Configuring and managing cloud-init for RHEL 9
Using cloud-init to automate the initialization of cloud instances
Abstract
- How cloud-init works
- How to use cloud-init to initiate cloud instances
- What uses of cloud-init Red Hat supports
Making open source more inclusive
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
Providing feedback on Red Hat documentation
We appreciate your feedback on our documentation. Let us know how we can improve it.
Submitting comments on specific passages
- View the documentation in the Multi-page HTML format and ensure that you see the Feedback button in the upper right corner after the page fully loads.
- Use your cursor to highlight the part of the text that you want to comment on.
- Click the Add Feedback button that appears near the highlighted text.
- Add your feedback and click Submit.
Submitting feedback through Jira (account required)
- Log in to the Jira website.
- Click Create in the top navigation bar
- Enter a descriptive title in the Summary field.
- Enter your suggestion for improvement in the Description field. Include links to the relevant parts of the documentation.
- Click Create at the bottom of the dialogue.
Chapter 1. Introducing RHEL on public cloud platforms
Public cloud platforms provide computing resources as a service. Instead of using on-premises hardware, you can run your IT workloads, including Red Hat Enterprise Linux (RHEL) systems, as public cloud instances.
To learn more about RHEL on public cloud platforms, see:
1.1. Benefits of using RHEL in a public cloud
RHEL as a cloud instance located on a public cloud platform has the following benefits over RHEL on-premises physical systems or virtual machines (VMs):
Flexible and fine-grained allocation of resources
A cloud instance of RHEL runs as a VM on a cloud platform, which typically means a cluster of remote servers maintained by the provider of the cloud service. Therefore, allocating hardware resources to the instance, such as a specific type of CPU or storage, happens on the software level and is easily customizable.
In comparison to a local RHEL system, you are also not limited by the capabilities of your physical host. Instead, you can choose from a variety of features, based on selection offered by the cloud provider.
Space and cost efficiency
You do not need to own any on-premises servers to host your cloud workloads. This avoids the space, power, and maintenance requirements associated with physical hardware.
Instead, on public cloud platforms, you pay the cloud provider directly for using a cloud instance. The cost is typically based on the hardware allocated to the instance and the time you spend using it. Therefore, you can optimize your costs based on your requirements.
Software-controlled configurations
The entire configuration of a cloud instance is saved as data on the cloud platform, and is controlled by software. Therefore, you can easily create, remove, clone, or migrate the instance. A cloud instance is also operated remotely in a cloud provider console and is connected to remote storage by default.
In addition, you can back up the current state of a cloud instance as a snapshot at any time. Afterwards, you can load the snapshot to restore the instance to the saved state.
Separation from the host and software compatibility
Similarly to a local VM, the RHEL guest operating system on a cloud instance runs on a virtualized kernel. This kernel is separate from the host operating system and from the client system that you use to connect to the instance.
Therefore, any operating system can be installed on the cloud instance. This means that on a RHEL public cloud instance, you can run RHEL-specific applications that cannot be used on your local operating system.
In addition, even if the operating system of the instance becomes unstable or is compromised, your client system is not affected in any way.
1.2. Public cloud use cases for RHEL
Deploying on a public cloud provides many benefits, but might not be the most efficient solution in every scenario. If you are evaluating whether to migrate your RHEL deployments to the public cloud, consider whether your use case will benefit from the advantages of the public cloud.
Beneficial use cases
Deploying public cloud instances is very effective for flexibly increasing and decreasing the active computing power of your deployments, also known as scaling up and scaling down. Therefore, using RHEL on public cloud is recommended in the following scenarios:
- Clusters with high peak workloads and low general performance requirements. Scaling up and down based on your demands can be highly efficient in terms of resource costs.
- Quickly setting up or expanding your clusters. This avoids high upfront costs of setting up local servers.
- Cloud instances are not affected by what happens in your local environment. Therefore, you can use them for backup and disaster recovery.
Potentially problematic use cases
- You are running an existing environment that cannot be adjusted. Customizing a cloud instance to fit the specific needs of an existing deployment may not be cost-effective in comparison with your current host platform.
- You are operating with a hard limit on your budget. Maintaining your deployment in a local data center typically provides less flexibility but more control over the maximum resource costs than the public cloud does.
Next steps
Additional resources
1.3. Frequent concerns when migrating to a public cloud
Moving your RHEL workloads from a local environment to a public cloud platform might raise concerns about the changes involved. The following are the most commonly asked questions.
Will my RHEL work differently as a cloud instance than as a local virtual machine?
In most respects, RHEL instances on a public cloud platform work the same as RHEL virtual machines on a local host, such as an on-premises server. Notable exceptions include:
- Instead of private orchestration interfaces, public cloud instances use provider-specific console interfaces for managing your cloud resources.
- Certain features, such as nested virtualization, may not work correctly. If a specific feature is critical for your deployment, check the feature’s compatibility in advance with your chosen public cloud provider.
Will my data stay safe in a public cloud as opposed to a local server?
The data in your RHEL cloud instances is in your ownership, and your public cloud provider does not have any access to it. In addition, major cloud providers support data encryption in transit, which improves the security of data when migrating your virtual machines to the public cloud.
The general security of your RHEL public cloud instances is managed as follows:
- Your public cloud provider is responsible for the security of the cloud hypervisor
- Red Hat provides the security features of the RHEL guest operating systems in your instances
- You manage the specific security settings and practices in your cloud infrastructure
What effect does my geographic region have on the functionality of RHEL public cloud instances?
You can use RHEL instances on a public cloud platform regardless of your geographical location. Therefore, you can run your instances in the same region as your on-premises server.
However, hosting your instances in a physically distant region might cause high latency when operating them. In addition, depending on the public cloud provider, certain regions may provide additional features or be more cost-efficient. Before creating your RHEL instances, review the properties of the hosting regions available for your chosen cloud provider.
1.4. Obtaining RHEL for public cloud deployments
To deploy a RHEL system in a public cloud environment:
Select the optimal cloud provider for your use case, based on your requirements and the current offer on the market.
The cloud providers currently certified for running RHEL instances are:
- For more information, see Deploying RHEL 9 on Amazon Web Services.
- For more information, see Deploying RHEL 9 on Google Cloud Platform.
- For more information, see Deploying RHEL 9 on Microsoft Azure.
- Create a RHEL cloud instance on your chosen cloud platform. For more information, see Methods for creating RHEL cloud instances.
- To keep your RHEL deployment up-to-date, use Red Hat Update Infrastructure (RHUI).
Additional resources
1.5. Methods for creating RHEL cloud instances
To deploy a RHEL instance on a public cloud platform, you can use one of the following methods:
| Create a system image of RHEL and import it to the cloud platform.
|
| Purchase a RHEL instance directly from the cloud provider marketplace.
|
Additional resources
Chapter 2. Introduction to cloud-init
cloud-init is a software package that automates the initialization of cloud instances during system boot. You can configure cloud-init to perform a variety of tasks. Some sample tasks that cloud-init can perform include:
- Configuring a host name
- Installing packages on an instance
- Running scripts
- Suppressing default virtual machine (VM) behavior
Where you obtain your image for configuring cloud-init depends on how you intend to use it.
-
The
cloud-initpackage is installed on KVM Guest Images that you download from the Red Hat Customer Portal. When you launch an instance,cloud-initis enabled. KVM Guest Images that you download from the Red Hat Customer Portal are intended for use with Red Hat Virtualization (RHV), the Red Hat OpenStack Platform (RHOSP), and Red Hat OpenShift Virtualization. -
You can also download a RHEL ISO image from the Red Hat Customer Portal to create your own custom guest image. In this case, you need to install the
cloud-initpackage on your guest image yourself. -
If you plan to use an image with a cloud provider (for example, AWS or Azure), use Red Hat Image Builder to create the image. Image Builder images are customized for use for specific cloud providers. The image types AMI, VHD, and qcow2 include
cloud-initalready installed. Refer to Composing a Customized RHEL System Image for information about Image Builder.
Most cloud platforms support cloud-init, though configuration procedures and supported options vary. Alternatively, you can configure cloud-init for a NoCloud environment.
You can configure cloud-init on one VM and then use that VM as a template for additional VMs or clusters of VMs.
Specific Red Hat products (for example, Red Hat Virtualization) have documented procedures for configuring cloud-init for use with those products.
This document refers to the cloud-init documentation in a number of places. Refer to the referenced cloud-init documentation for complete information about cloud-init.
Prerequisites
- Sign up for a Red Hat Customer Portal account.
2.1. cloud-init configuration
cloud-init uses YAML-formatted file instructions to perform tasks. You decide the initial configuration you want cloud-init to perform by providing instructions within the YAML files. When an instance boots, the cloud-init service starts and searches for and executes the instructions. Tasks complete during the first boot or on subsequent boots of your VM, based on your cloud-init configuration.
You define the tasks by configuring the /etc/cloud/cloud.cfg file and adding directives under the /etc/cloud/cloud.cfg.d/ directory.
The
cloud.cfgfile includes directives, such as those for user access and authentication and system information.The file also includes default and optional modules for
cloud-init. The modules are executed in order within three phases that include thecloud-initinitialization phase, the configuration phase, and the final phase. Within thecloud.cfgfile, modules for the three phases are listed undercloud_init_modules,cloud_config_modules, andcloud_final_modules, respectively.-
The
cloud.cfg.ddirectory is where you can add additional directives forcloud-init. When you add directives to thecloud.cfg.ddirectory, you typically add them to a file named*.cfg, and you always include#cloud-configat the top of the file.
2.2. cloud-init operates in stages
cloud-init operates in five stages during a system boot. Those stages determine whether cloud-init runs and where it finds its datasources, among other tasks. The stages are as follows:
-
The
cloud-initgenerator stage, through thesystemdservice, determines whether to runcloud-initupon the boot. -
During the local stage,
cloud-initfinds local datasources and applies network configuration. -
During the network stage,
cloud-initprocesses user data and runs the modules listed undercloud_init_modulesin yourcloud.cfgfile. You can enable, disable, or add modules to thecloud_init_modulessection. -
During the config stage,
cloud-initruns the modules listed undercloud_config_modulesin yourcloud.cfgfile. You can enable, disable, or add modules to thecloud_config_modulessection. -
During the final stage,
cloud-initcan run what you have included undercloud_final_modulesin yourcloud.cfgfile. You can include package installations that you would typically run after a system boots and can also include configuration management plug-ins and user scripts. You can enable, disable, or add modules to thecloud_final_modulessection.
The five boot stages are described in the cloud-init Documentation section Boot Stages.
2.3. cloud-init modules execute in phases
When cloud-init runs, it executes the modules within cloud.cfg in order within three phases:
-
The network phase (
cloud_init_modules) -
The configuration phase (
cloud_config_modules) -
The final phase (
cloud_final_modules)
When cloud-init runs for the first time on a VM, all the modules you have configured run in their respective phases. On a subsequent running of cloud-init, whether a module runs within a phase depends on the module frequency of the individual module. Some modules run every time cloud-init runs; some modules only run the first time cloud-init runs, even if the instance ID changes.
An instance ID uniquely identifies an instance. When an instance ID changes, cloud-init treats the instance as a new instance.
The possible module frequency values are as follows:
-
Per instancemeans that the module runs on first boot of an instance. For example, if you clone an instance or create a new instance from a saved image, the modules designated as per instance run again. -
Per oncemeans that the module runs only once. For example, if you clone an instance or create a new instance from a saved image, the modules designated per once do not run again on those instances. -
Per alwaysmeans the module runs on every boot.
You can override a module’s frequency when you configure the module or by using the command line.
2.4. cloud-init acts upon user data, metadata, and vendor data
cloud-init consumes and acts upon user data, metadata, and vendor data.
-
User data includes directives you specify in the
cloud.cfgfile and in thecloud.cfg.ddirectory, for example, user data can include files to run, packages to install, and shell scripts. Refer to thecloud-initDocumentation section User-Data Formats for information about the types of user data thatcloud-initallows. -
Metadata includes data associated with a specific datasource, for example, metadata can include a server name and instance ID. If you are using a specific cloud platform, the platform determines where your instances find user data and metadata. Your platform may require that you add metadata and user data to an HTTP service; in this case, when
cloud-initruns it consumes metadata and user data from the HTTP service. Vendor data is optionally provided by the organization (for example, a cloud provider) and includes information that can customize the image to better fit the environment where the image runs.
cloud-initacts upon optional vendor data and user data after it reads any metadata and initializes the system. By default, vendor data runs on the first boot. You can disable vendor data execution.Refer to the
cloud-initDocumentation section Instance Metadata for a description of metadata; Datasources for a list of datasources; and Vendor Data for more information about vendor data.
2.5. cloud-init identifies the cloud platform
cloud-init attempts to identify the cloud platform using the script ds-identify. The script runs on the first boot of an instance.
Adding a datasource directive can save time when cloud-init runs. You would add the directive in the /etc/cloud/cloud.cfg file or in the /etc/cloud/cloud.cfg.d directory. For example:
datasource_list:[Ec2]
Beyond adding the directive for your cloud platform, you can further configure cloud-init by adding additional configuration details, such as metadata URLs.
datasource_list: [Ec2]
datasource:
Ec2:
metadata_urls: ['http://169.254.169.254']
After cloud-init runs, you can view a log file (run/cloud-init/ds-identify.log) that provides detailed information about the platform.
Additional resources
2.6. Additional resources
Chapter 3. Red Hat support for cloud-init
This chapter covers Red Hat support for cloud-init. It includes information about Red Hat products that use cloud-init, cloud-init modules that Red Hat supports, and default directories and files.
3.1. cloud-init significant directories and files
The following table includes important directories and files. Review these directories and files; they allow you to perform tasks like:
-
Configuring
cloud-init -
Finding information about your configuration after
cloud-inithas run - Examining log files
- Finding templates
Depending on your scenario and datasource, there can be additional files and directories important to your configuration.
Table 3.1. cloud-init directories and files
| Directory or File | Description |
|---|---|
|
|
The |
|
|
The |
|
|
When |
|
|
The |
|
|
This directory includes templates that you can enable in |
|
|
The |
|
|
The |
3.2. Red Hat products that use cloud-init
You can use cloud-init with the following Red Hat products.
-
Red Hat Virtualization. Once you install
cloud-initon a VM, you can create a template and leveragecloud-initfunctions for all VMs created from that template. Refer to Using Cloud-Init to Automate the Configuration of Virtual Machines for information about usingcloud-initwith VMs. -
Red Hat OpenStack Platform. You can use
cloud-initto help configure images for OpenStack. Refer to the Instances and Images Guide for more information. -
Red Hat CloudForms. You can use
cloud-initto provision VMs for Red Hat CloudForms. Refer to Customization Templates for Virtual Machine and Instance Provisioning for more information. -
Red Hat Satellite. You can use
cloud-initwith Red Hat Satellite. Refer to Preparing Cloud-init Images in Red Hat Virtualization for more information. -
Red Hat OpenShift. You can use
cloud-initwhen you create VMs for OpenShift. Refer to Creating Virtual Machines for more information.
3.3. Red Hat supports these cloud-init modules
Red Hat supports most cloud-init modules. Individual modules can contain multiple configuration options. The following table lists all of the cloud-init modules that Red Hat currently supports and provides a brief description and the default module frequency. Refer to Modules in the cloud-init Documentation section for complete descriptions and options for these modules.
Table 3.2. Supported cloud-init modules
| cloud-init Module | Description | Default Module Frequency |
|---|---|---|
| bootcmd | Runs commands early in the boot process | per always |
| ca_certs | Adds CA certificates | per instance |
| debug | Enables or disables output of internal information to assist with debugging | per instance |
| disable_ec2_metadata | Enables or disables the AWS EC2 metadata | per always |
| disk_setup | Configures simple partition tables and file systems | per instance |
| final_message |
Specifies the output message once | per always |
| foo | Example shows module structure (Module does nothing) | per instance |
| growpart | Resizes partitions to fill the available disk space | per always |
| keys_to_console | Allows controls of fingerprints and keys that can be written to the console | per instance |
| landscape | Installs and configures a landscape client | per instance |
| locale | Configures the system locale and applies it system-wide | per instance |
| mcollective |
Installs, configures, and starts | per instance |
| migrator |
Moves old versions of | per always |
| mounts | Configures mount points and swap files | per instance |
| phone_home | Posts data to a remote host after boot completes | per instance |
| power_state_change | Completes shutdown and reboot after all configuration modules have run | per instance |
| puppet | Installs and configures puppet | per instance |
| resizefs | Resizes a file system to use all available space on a partition | per always |
| resolv_conf |
Configures | per instance |
| rh_subscription | Registers a Red Hat Enterprise Linux system | per instance |
| rightscale_userdata |
Adds support for RightScale configuration hooks to | per instance |
| rsyslog |
Configures remote system logging using | per instance |
| runcmd | Runs arbitrary commands | per instance |
| salt_minion |
Installs, configures, and starts | per instance |
| scripts_per_boot | Runs per boot scripts | per always |
| scripts_per_instance | Runs per instance scripts | per instance |
| scripts_per_once | Runs scripts once | per once |
| scripts_user | Runs user scripts | per instance |
| scripts_vendor | Runs vendor scripts | per instance |
| seed_random | Provides random seed data | per instance |
| set_hostname | Sets host name and fully qualified domain name (FQDN) | per always |
| set_passwords | Sets user passwords and enables or disables SSH password authentication | per instance |
| ssh_authkey_fingerprints | Logs fingerprints of user SSH keys | per instance |
| ssh_import_id | Imports SSH keys | per instance |
| ssh | Configures SSH, and host and authorized SSH keys | per instance |
| timezone | Sets the system time zone | per instance |
| update_etc_hosts |
Updates | per always |
| update_hostname | Updates host name and FQDN | per always |
| users_groups | Configures users and groups | per instance |
| write_files | Writes arbitrary files | per instance |
| yum_add_repo | Adds dnf repository configuration to the system | per always |
The following table lists modules that Red Hat does not currently support.
Table 3.3. Modules not supported
| Module |
|---|
| apt_configure |
| apt_pipeline |
| byobu |
| chef |
| emit_upstart |
| grub_dpkg |
| ubuntu_init_switch |
3.4. The default cloud.cfg file
The /etc/cloud/cloud.cfg file lists the modules comprising the basic configuration for cloud-init.
The modules in the file are the default modules for cloud-init. You can configure the modules for your environment or remove modules you do not need. Modules that are included in cloud.cfg do not necessarily do anything by being listed in the file. You need to configure them individually if you want them to perform actions during one of the cloud-init phases.
The cloud.cfg file provides the chronology for running individual modules. You can add additional modules to cloud.cfg as long as Red Hat supports the modules you want to add.
The default contents of the file for Red Hat Enterprise Linux (RHEL) are as follows:
-
Modules run in the order given in
cloud.cfg. You typically do not change this order. -
The
cloud.cfgdirectives can be overridden by user data. -
When running
cloud-initmanually, you can overridecloud.cfgwith command line options. - Each module includes its own configuration options, where you can add specific information.
users: 1 - default disable_root: 1 2 ssh_pwauth: 0 3 mount_default_fields: [~, ~, 'auto', 'defaults,nofail,x-systemd.requires=cloud-init.service', '0', '2'] 4 ssh_deletekeys: 1 5 ssh_genkeytypes: ['rsa', 'ecdsa', 'ed25519'] 6 syslog_fix_perms: ~ 7 disable_vmware_customization: false 8 cloud_init_modules: 9 - disk_setup - migrator - bootcmd - write-files - growpart - resizefs - set_hostname - update_hostname - update_etc_hosts - rsyslog - users-groups - ssh cloud_config_modules: 10 - mounts - locale - set-passwords - rh_subscription - dnf-add-repo - package-update-upgrade-install - timezone - puppet - chef - salt-minion - mcollective - disable-ec2-metadata - runcmd cloud_final_modules: 11 - rightscale_userdata - scripts-per-once - scripts-per-boot - scripts-per-instance - scripts-user - ssh-authkey-fingerprints - keys-to-console - phone-home - final-message - power-state-change system_info: default_user: 12 name: cloud-user lock_passwd: true gecos: Cloud User groups: [adm, systemd-journal] sudo: ["ALL=(ALL) NOPASSWD:ALL"] shell: /bin/bash distro: rhel 13 paths: cloud_dir: /var/lib/cloud 14 templates_dir: /etc/cloud/templates 15 ssh_svcname: sshd 16 # vim:syntax=yaml
- 1
- Specifies the default user for the system. Refer to Users and Groups for more information.
- 2
- Enables or disables root login. Refer to Authorized Keys for more information.
- 3
- Specifies whether
sshis configured to accept password authentication. Refer to Set Passwords for more information. - 4
- Configures mount points; must be a list containing six values. Refer to Mounts for more information.
- 5
- Specifies whether to remove default host SSH keys. Refer to Host Keys for more information.
- 6
- Specifies key types to generate. Refer to Host Keys for more information. Note that for RHEL 8.4 and earlier, the default value of this line is
~. - 7
cloud-initruns at multiple stages of boot. Set this option so thatcloud-initcan log all stages to its log file. Find more information about this option in thecloud-config.txtfile in theusr/share/doc/cloud-init/examplesdirectory.- 8
- Enables or disables VMware vSphere customization
- 9
- The modules in this section are services that run when the
cloud-initservice starts, early in the boot process. - 10
- These modules run during
cloud-initconfiguration, after initial boot. - 11
- These modules run in the final phase of
cloud-init, after the configuration finishes. - 12
- Specifies details about the default user. Refer to Users and Groups for more information.
- 13
- Specifies the distribution
- 14
- Specifies the main directory that contains
cloud-init-specific subdirectories. Refer to Directory layout for more information. - 15
- Specifies where templates reside
- 16
- The name of the SSH service
Additional resources
3.5. The cloud.cfg.d directory
cloud-init acts upon directives that you provide and configure. Typically, those directives are included in the cloud.cfg.d directory.
While you can configure modules by adding user data directives within the cloud.cfg file, as a best practice consider leaving cloud.cfg unmodified. Add your directives to the /etc/cloud/cloud.cfg.d directory. Adding directives to this directory can make future modifications and upgrades easier.
There are multiple ways to add directives. You can include directives in a file named *.cfg, which includes the heading #cloud-config. Typically, the directory would contain multiple *cfg files. There are other options for adding directives, for example, you can add a user data script. Refer to User-Data Formats for more information.
Additional resources
3.6. The default 05_logging.cfg file
The 05_logging.cfg file sets logging information for cloud-init. The /etc/cloud/cloud.cfg.d directory includes this file, along with other cloud-init directives that you add.
cloud-init uses the logging configuration in 05_logging.cfg by default. The default contents of the file for Red Hat Enterprise Linux (RHEL) are as follows:
## This yaml formatted config file handles setting
## logger information. The values that are necessary to be set
## are seen at the bottom. The top '_log' are only used to remove
## redundancy in a syslog and fallback-to-file case.
##
## The 'log_cfgs' entry defines a list of logger configs
## Each entry in the list is tried, and the first one that
## works is used. If a log_cfg list entry is an array, it will
## be joined with '\n'.
_log:
- &log_base |
[loggers]
keys=root,cloudinit
[handlers]
keys=consoleHandler,cloudLogHandler
[formatters]
keys=simpleFormatter,arg0Formatter
[logger_root]
level=DEBUG
handlers=consoleHandler,cloudLogHandler
[logger_cloudinit]
level=DEBUG
qualname=cloudinit
handlers=
propagate=1
[handler_consoleHandler]
class=StreamHandler
level=WARNING
formatter=arg0Formatter
args=(sys.stderr,)
[formatter_arg0Formatter]
format=%(asctime)s - %(filename)s[%(levelname)s]: %(message)s
[formatter_simpleFormatter]
format=[CLOUDINIT] %(filename)s[%(levelname)s]: %(message)s
- &log_file |
[handler_cloudLogHandler]
class=FileHandler
level=DEBUG
formatter=arg0Formatter
args=('/var/log/cloud-init.log',)
- &log_syslog |
[handler_cloudLogHandler]
class=handlers.SysLogHandler
level=DEBUG
formatter=simpleFormatter
args=("/dev/log", handlers.SysLogHandler.LOG_USER)
log_cfgs:
# Array entries in this list will be joined into a string
# that defines the configuration.
#
# If you want logs to go to syslog, uncomment the following line.
# - [ *log_base, *log_syslog ]
#
# The default behavior is to just log to a file.
# This mechanism that does not depend on a system service to operate.
- [ *log_base, *log_file ]
# A file path can also be used.
# - /etc/log.conf
# This tells cloud-init to redirect its stdout and stderr to
# 'tee -a /var/log/cloud-init-output.log' so the user can see output
# there without needing to look on the console.
output: {all: '| tee -a /var/log/cloud-init-output.log'}Additional resources
3.7. The cloud-init /var/lib/cloud directory layout
When cloud-init first runs, it creates a directory layout that includes information about your instance and cloud-init configuration.
The directory can include optional directories, such as /scripts/vendor.
The following is a sample directory layout for cloud-init.
/var/lib/cloud/
- data/
- instance-id
- previous-instance-id
- previous-datasource
- previous-hostname
- result.json
- set-hostname
- status.json
- handlers/
- instance
- boot-finished
- cloud-config.txt
- datasource
- handlers/
- obj.pkl
- scripts/
- sem/
- user-data.txt
- user-data.txt.i
- vendor-data.txt
- vendor-data.txt.i
- instances/
f111ee00-0a4a-4eea-9c17-3fa164739c55/
- boot-finished
- cloud-config.txt
- datasource
- handlers/
- obj.pkl
- scripts/
- sem/
- user-data.txt
- user-data.txt.i
- vendor-data.txt
- vendor-data.txt.i
- scripts/
- per-boot/
- per-instance/
- per-once/
- vendor/
- seed/
- sem/
- config_scripts_per_once.onceAdditional resources
Chapter 4. Configuring cloud-init
This chapter includes examples of the most common configuration tasks for cloud-init.
Your cloud-init configuration can require that you add directives to the cloud.cfg file and the cloud.cfg.d directory. Alternatively, your specific data source might require that you add directives to files, such as a user data file and a metadata file. A data source might require that you upload your directives to an HTTP server. Check the requirements of your data source and add directives accordingly.
4.1. Creating a virtual machine that includes cloud-init for a NoCloud datasource
To create a new virtual machine (VM) that includes cloud-init, see the following procedure. In this procedure, you create a meta-data and user-data file.
-
Your
meta-datafile includes instance details. -
Your
user-datafile includes information to create a user and grant access.
Then, you include these files in a new ISO image, and you attach the ISO file to a new VM you create from a KVM Guest Image. In this scenario, the datasource is NoCloud.
Procedure
Create a directory named
cloudinitisoand move into it.$ mkdir cloudinitiso $ cd cloudinitiso
Create a file named
meta-data. Add the following information to the file.instance-id: citest local-hostname: citest-1
Create a file named
user-data. Include the following information in the file.#cloud-config password: cilogon chpasswd: {expire: False} ssh_pwauth: True ssh_authorized_keys: - ssh-rsa AAA...fhHQ== sample@redhat.comNoteThe final line of the
user-datafile references an SSH public key. Find your SSH public keys in~/.ssh/id_rsa.pub. When trying this sample procedure, modify the line to include one of your public keys.Use the
genisoimagecommand to create an ISO image that includesuser-dataandmeta-data.# genisoimage -output ciiso.iso -volid cidata -joliet -rock user-data meta-data I: -input-charset not specified, using utf-8 (detected in locale settings) Total translation table size: 0 Total rockridge attributes bytes: 331 Total directory bytes: 0 Path table size(bytes): 10 Max brk space used 0 183 extents written (0 MB)-
Download a KVM Guest Image from the Red Hat Customer Portal to the
/var/lib/libvirt/imagesdirectory. Create a new VM from the KVM Guest Image using the
virt-installcommand. Include the ISO image you created as an attachment to the image.virt-install \ --memory 4096 \ --vcpus 4 \ --name mytestcivm \ --disk /var/lib/libvirt/images/rhel-8.1-x86_64-kvm.qcow2,device=disk,bus=virtio,format=qcow2 \ --disk /home/sample/cloudinitiso/ciiso.iso,device=cdrom \ --os-type Linux \ --os-variant rhel9.0 \ --virt-type kvm \ --graphics none \ --importLog on to your image as
cloud-user. Your password iscilogon.citest-1 login: cloud-user Password: [cloud-user@citest-1 ~]$
Verification
Check the
cloud-initstatus to see that it has completed its tasks.[cloud-user@citest-1 instance]$ cloud-init status status: donecloud-initcreates thecloud-initdirectory layout under/var/lib/cloudwhen it runs, and it updates or changes certain directory contents based upon the directives you have specified.For example, you can confirm that the datasource is
NoCloudby checking the datasource file.$ cd /var/lib/cloud/instance $ cat datasource DataSourceNoCloud: DataSourceNoCloud [seed=/dev/sr0][dsmode=net]
cloud-initcopies user-data into/var/lib/cloud/instance/user-data.txt.$cat user-data.txt #cloud-config password: cilogon chpasswd: {expire: False} ssh_pwauth: True ssh_authorized_keys: - ssh-rsa AAA...fhHQ== sample@redhat.comThese are samples. The
cloud-initdirectory layout includes much more information.
For OpenStack, the Creating and managing instances includes information for configuring an instance using cloud-init. See Creating a customized instance for specific procedures.
Additional resources
4.2. Expiring a cloud user password with cloud-init
You can force cloud-user to change the cloud-user password at the first login. Perform the following procedure to expire a password.
Procedure
Depending upon the requirements of your datasource, open your user-data file for editing, or otherwise add the following directive to the
cloud.cfg.ddirectory.NoteAll user directives include
#cloud-configat the top of the file so thatcloud-initrecognizes the file as containing user directives. When you include directives in thecloud.cfg.ddirectory, name the file*.cfg, and always include#cloud-configat the top of the file.Change the line
chpasswd: {expire: False}tochpasswd: {expire: True}.#cloud-config password: mypassword chpasswd: {expire: True} ssh_pwauth: True ssh_authorized_keys: - ssh-rsa AAA...SDvz user1@yourdomain.com - ssh-rsa AAB...QTuo user2@yourdomain.comThis works to expire the password because
passwordandchpasswdoperate on the default user unless you indicate otherwise.NoteThis is a global setting. When you set
chpasswdtoTrue, all users you create need to change their passwords when they log in.
4.3. Changing a default user name with cloud-init
You can change the default user name to something other than cloud-user.
Procedure
Depending upon the requirements of your datasource, open your user-data file for editing, or otherwise add the following directive to the
cloud.cfg.ddirectory.NoteAll user directives include
#cloud-configat the top of the file so thatcloud-initrecognizes the file as containing user directives. When you include directives in thecloud.cfg.ddirectory, name the file*.cfg, and always include#cloud-configat the top of the file.Add the line
user: <username>, replacing <username> with the new default user name.#cloud-config user: username password: mypassword chpasswd: {expire: False} ssh_pwauth: True ssh_authorized_keys: - ssh-rsa AAA...SDvz user1@yourdomain.com - ssh-rsa AAB...QTuo user2@yourdomain.com
4.4. Setting a root password with cloud-init
To set the root password, create a user list.
Procedure
Depending upon the requirements of your datasource, open your user-data file for editing, or otherwise add the following directive to the
cloud.cfg.ddirectory.NoteAll user directives include
#cloud-configat the top of the file so thatcloud-initrecognizes the file as containing user directives. When you include directives in thecloud.cfg.ddirectory, name the file*.cfg, and always include#cloud-configat the top of the file.Create a user list in the
chpasswdsection of the file. The format is shown in the following sample.NoteWhite space is significant. Do not include white space before or after the colon in your user list. If you include white space, the password is set with a space in it.
#cloud-config ssh_pwauth: True ssh_authorized_keys: - ssh-rsa AAA...SDvz user1@yourdomain.com - ssh-rsa AAB...QTuo user2@yourdomain.com chpasswd: list: | root:myrootpassword cloud-user:mypassword expire: FalseNoteIf you use this method to set the user password, you must set all passwords in this section.
4.5. Managing Red Hat subscriptions with cloud-init
You can use the rh_subscription directive to register your system. Samples follow. For each subscription, you would edit your user data.
Procedure
The following example uses the auto-attach and service-level options.
Under
rh_subscription, add yourusernameandpassword, setauto-attachtoTrue, and setservice-leveltoself-support.rh_subscription: username: sample@redhat.com password: 'mypassword' auto-attach: True service-level: self-support
NoteThe
service-leveloption requires that you use theauto-attachoption.
The following example uses the activation-key and org options.
Under
rh_subscription, add youractivation keyandorgnumber and setauto-attachtoTrue.rh_subscription: activation-key: example_key org: 12345 auto-attach: True
The following example adds a subscription pool.
Under
rh_subscription, add yourusername,password, and pool number.rh_subscription: username: sample@redhat.com password: 'password' add-pool: XYZ01234567
NoteThis sample is the equivalent of the
subscription-manager attach --pool=XYZ01234567command.
The following example sets a server host name in the /etc/rhsm/rhsm.conf file.
Under
rh_subscription, add yourusername,password,server-hostname, and setauto-attachtoTrue.rh_subscription: username: sample@redhat.com password: 'password' server-hostname: test.example.com auto-attach: True
4.6. Adding users and user options with cloud-init
You create and describe users in a users section. You can modify the section to add more users to your initial system configuration, and you can set additional user options.
If you add the users section, you must also set the default user options in this section.
Procedure
Depending upon the requirements of your datasource, open your user-data file for editing, or otherwise add the following directive to the
cloud.cfg.ddirectory.NoteAll user directives include
#cloud-configat the top of the file so thatcloud-initrecognizes the file as containing user directives. When you include directives in thecloud.cfg.ddirectory, name the file*.cfg, and always include#cloud-configat the top of the file.Add or modify the
userssection to add users.-
If you want
cloud-userto be the default user created along with the other users you specify, ensure that you adddefaultas the first entry in the section. If it is not the first entry,cloud-useris not created. By default, users are labeled as
unconfined_uif there is not anselinux-uservalue.#cloud-config users: - default - name: user2 gecos: User N. Ame selinux-user: staff_u groups: users,wheel ssh_pwauth: True ssh_authorized_keys: - ssh-rsa AA..vz user@domain.com chpasswd: list: | root:password cloud-user:mypassword user2:mypassword2 expire: FalseNote-
The example places the user
user2into two groups,usersandwheel.
-
The example places the user
-
If you want
4.7. Running first boot commands with cloud-init
You can use the runcmd and bootcmd sections to execute commands during startup and initialization.
The bootcmd section executes early in the initialization process and by default runs on every boot. The runcmd section executes near the end of the process and is only executed during the first boot and initialization.
Procedure
Depending upon the requirements of your datasource, open your user-data file for editing, or otherwise add the following directive to the
cloud.cfg.ddirectory.NoteAll user directives include
#cloud-configat the top of the file so thatcloud-initrecognizes the file as containing user directives. When you include directives in thecloud.cfg.ddirectory, name the file*.cfg, and always include#cloud-configat the top of the file.Add the sections for
bootcmdandruncmd; include commands you wantcloud-initto execute.#cloud-config users: - default - name: user2 gecos: User N. Ame groups: users chpasswd: list: | root:password fedora:myfedpassword user2:mypassword2 expire: False bootcmd: - echo New MOTD >> /etc/motd runcmd: - echo New MOTD2 >> /etc/motd
4.8. Adding additional sudoers with cloud-init
You can configure a user as a sudoer by adding a sudo and groups entry to the users section.
Procedure
Depending upon the requirements of your datasource, open your user-data file for editing, or otherwise add the following directive to the
cloud.cfg.ddirectory.NoteAll user directives include
#cloud-configat the top of the file so thatcloud-initrecognizes the file as containing user directives. When you include directives in thecloud.cfg.ddirectory, name the file*.cfg, and always include#cloud-configat the top of the file.-
Add a
sudoentry and specify the user access. For example,sudo: ALL=(ALL) NOPASSWD:ALLallows a user unrestricted user access. Add a
groupsentry and specify the groups that include the user.#cloud-config users: - default - name: user2 gecos: User D. Two sudo: ["ALL=(ALL) NOPASSWD:ALL"] groups: wheel,adm,systemd-journal ssh_pwauth: True ssh_authorized_keys: - ssh-rsa AA...vz user@domain.com chpasswd: list: | root:password cloud-user:mypassword user2:mypassword2 expire: False
4.9. Setting up a static networking configuration with cloud-init
You can set up your network configuration with cloud-init by adding a network-interfaces section to your metadata.
Red Hat Enterprise Linux provides its default networking service through NetworkManager, which is a dynamic network control and configuration daemon that keeps network devices and connections up and active when they are available.
Your datasource might provide a network configuration. Refer to the cloud-init documentation section Network Configuration Sources for more information.
If you specify no network configuration for cloud-init and have not disabled network configuration, cloud-init tries to determine if any attached devices have a connection. If it finds a connected device, it generates a network configuration that issues a DHCP request on the interface. Refer to the cloud-init documentation section Fallback Network Configuration for more information.
Procedure
The following example adds a static networking configuration.
Depending upon the requirements of your datasource, open your user-data file for editing, or otherwise add the following directive to the
cloud.cfg.ddirectory.NoteAll user directives include
#cloud-configat the top of the file so thatcloud-initrecognizes the file as containing user directives. When you include directives in thecloud.cfg.ddirectory, name the file*.cfg, and always include#cloud-configat the top of the file.Add a
network-interfacessection.network: version: 1 config: - type: physical name: eth0 subnets: - type: static address: 192.168.1.10/24 gateway: 192.168.1.254
You can disable a network configuration by adding the following information to your metadata.
network config: disabled
Additional resources
4.10. Configuring only a root user with cloud-init
You can configure your user data so that you have a root user and no other users.
Procedure
Depending upon the requirements of your datasource, open your user-data file for editing, or otherwise add the following directive to the
cloud.cfg.ddirectory.NoteAll user directives include
#cloud-configat the top of the file so thatcloud-initrecognizes the file as containing user directives. When you include directives in thecloud.cfg.ddirectory, name the file*.cfg, and always include#cloud-configat the top of the file.Create an entry for the user
rootin theuserssection.The simple example that follows includes a
userssection with only thenameoption.users: - name: root chpasswd: list: | root:password expire: FalseOptionally, set up SSH keys for the root user.
users: - name: root ssh_pwauth: True ssh_authorized_keys: - ssh-rsa AA..vz user@domain.com
4.11. Setting up storage with container-storage-setup in cloud-init
You can set up storage by referencing the container-storage-setup utility within the write_files module.
Procedure
Depending upon the requirements of your datasource, open your user-data file for editing, or otherwise add the following directive to the
cloud.cfg.ddirectory.NoteAll user directives include
#cloud-configat the top of the file so thatcloud-initrecognizes the file as containing user directives. When you include directives in thecloud.cfg.ddirectory, name the file*.cfg, and always include#cloud-configat the top of the file.Add or modify the
write_filesmodule to include the path to thecontainer-storage-setuputility.The following example sets the size of the root logical volume to 6GB rather than the default 3GB.
write_files: - path: /etc/sysconfig/docker-storage-setup permissions: 0644 owner: root content: | ROOT_SIZE=6GNotePrior to RHEL 7.4, container-storage-setup was called docker-storage-setup. If you are using OverlayFS for storage, as of RHEL 7.4 you can now use that type of file system with SELinux in enforcing mode.
4.12. Changing the system locale with cloud-init
You can configure the system location with the locale module.
Procedure
-
Depending upon the requirements of your datasource, open your meta-data file for editing, or otherwise add the following directive to the
cloud.cfgfile or thecloud.cfg.ddirectory. -
Add the
localedirective, specifying the location. The following sample sets thelocaletoja_JP(Japan) withUTF-8encoding.
#cloud-config locale: ja_JP.UTF-8
Additional resources
4.13. cloud-init and shell scripts
You can add list values or string values to bootcmd or runcmd. You can also provide a shell script within your userdata.
-
If you use a list value for
bootcmdorruncmd, each list item is run in turn usingexecve. - If you use a string value, then the entire string is run as a shell script.
-
If you want to use
cloud-initto run a shell script, you can provide a shell script (complete with shebang (#!) ) instead of providingcloud-initwith a.yamlfile.
Refer to Run commands on first boot for examples of how to put shell scripts in bootcmd and runcmd.
4.14. Preventing cloud-init from updating config files
When you create or restore an instance from a backup image, the instance ID changes. The change in instance ID can cause cloud-init to update configuration files.
Perform the following procedure to ensure that cloud-init does not update certain configuration files when you create or restore from backup.
Procedure
-
Open the
/etc/cloud/cloud.cfgfile for editing. Comment out or remove the configuration that you do not want
cloud-initto update when you restore your instance.For example, to avoid updating the SSH key file, remove
-sshfrom thecloud_init_modulessection.cloud_init_modules: - disk_setup - migrator - bootcmd - write-files - growpart - resizefs - set_hostname - update_hostname - update_etc_hosts - rsyslog - users-groups # - ssh
Verification
You can check to see which configuration files cloud-init has updated. To do so, examine the /var/log/cloud/cloud-init.log file. Updated files are logged during instance startup with messages beginning with Writing to. For example:
2019-09-03 00:16:07,XXX - util.py[DEBUG]: Writing to /root/.ssh/authorized_keys - wb: [XXX] 554 bytes 2019-09-03 00:16:08,XXX - util.py[DEBUG]: Writing to /etc/ssh/sshd_config - wb: [XXX] 3905 bytes
4.15. Modifying a VM created from a KVM Guest Image after cloud-init has run
To modify your cloud-init configuration before rerunning cloud-init, use the following procedure. When you launch a VM that includes the cloud-init package installed and enabled, cloud-init runs in its default state on that initial boot of your VM.
Procedure
- Log in to your VM.
-
Add or change directives, for example, modify the
cloud.cfgfile in the/etc/clouddirectory or add directives to the/etc/cloud/cloud.cfg.ddirectory. Run the
cloud-init cleancommand to clean directories so thatcloud-initcan rerun. You can also run the following commands as root to clean the VM.`rm -Rf /var/lib/cloud/instances/*` `rm -Rf /var/lib/cloud/instance` `rm -Rf /var/lib/cloud/data/*`
NoteYou can save the cleaned image as a new image and use that image for multiple VMs. The new VMs run
cloud-initusing your updatedcloud-initconfiguration.Rerun
cloud-initor reboot the VM.cloud-initreruns, implementing the configuration changes you made.
4.16. Modifying a VM for a specific datasource after cloud-init has run
To modify your cloud-init configuration before rerunning cloud-init, see the following procedure. This procedure uses OpenStack as an example. Note that the exact steps you need to perform vary based on your datasource.
Procedure
-
Create and launch an instance for the OpenStack Platform. For information about creating instances for OpenStack, see Creating an instance. In this example, our virtual machine includes
cloud-init, which runs upon boot of the virtual machine. -
Add or change directives. For example, modify the
user-data.filefile that is stored on the OpenStack HTTP server. Clean the virtual machine. Run the following commands as root.
`rm -rf /etc/resolv.conf /run/cloud-init` `userdel -rf cloud-user` `hostnamectl set-hostname localhost.localdomain` `rm /etc/NetworkManager/conf.d/99-cloud-init.conf`
NoteYou can save the cleaned image as a new image and use that image for multiple virtual machines. The new virtual machines run
cloud-initusing your updatedcloud-initconfiguration.Rerun
cloud-initor reboot the virtual machine.Cloud-init reruns, implementing the configuration changes you made.
4.17. Troubleshooting cloud-init
You can troubleshoot your instance after cloud-init has run by examining your configuration and log files. Once you have identified the issue, you can rerun cloud-init on your instance.
You can run cloud-init from the command line using the cloud-init command. To view the command syntax, along with a description of the optional arguments and subcommands, run the cloud-init --help command. The basic syntax follows.
cloud-init [-h] [--version] [--file FILES] [--debug] [--force]
{init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
The procedure that follows offers ideas for identifying issues with cloud-init and samples for rerunning the program.
Procedure
Review the
cloud-initconfiguration files.-
Examine the
/etc/cloud/cloud.cfgconfiguration file. Check which modules are included undercloud_init_modules,cloud_config_modules, andcloud_final_modules. -
Check directives (
*.cfgfiles) in the/etc/cloud/cloud.cfg.ddirectory.
-
Examine the
Review the
/var/log/cloud-init.logand/var/log/cloud-init-output.logfiles for details on a specific issue. For example, if the issue was that the root partition was not automatically extended, check log messages forgrowpart. If the file system was not extended, check log messages forresizefs. For example:# grep resizefs /var/log/cloud-init.log
Notegrowpartdoes not support LVM. If your root partition is based in LVM, the root partition is not automatically extended upon first boot.Rerun
cloud-init. Sample scenarios follow. Run commands as root.Rerun
cloud-initwith only the init modules./usr/bin/cloud-init -d init
Rerun
cloud-initwith all modules in your configuration./usr/bin/cloud-init -d modules
Delete the
cloud-initcache and forcecloud-initto run after boot.rm -rf /var/lib/cloud/* && /usr/bin/cloud-init -d init
Run the following commands to clean directories and simulate a clean instance.
rm -Rf /var/lib/cloud/instances/* rm -Rf /var/lib/cloud/instance rm -Rf /var/lib/cloud/data/* reboot
Run the following commands to rerun
cloud-init.cloud-init init --local cloud-init init
Additional resources