Chapter 1. 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.
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 on 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 on
- Sign up for a Red Hat Customer Portal account.
1.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
You define the tasks by configuring the
/etc/cloud/cloud.cfg file and adding directives under 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 the
cloud-initinitialization phase, the configuration phase, and the final phase. Within the
cloud.cfgfile, modules for the three phases are listed under
cloud.cfg.ddirectory is where you can add additional directives for
cloud-init. When you add directives to the
cloud.cfg.ddirectory, you typically add them to a file named
*.cfg, and you always include
#cloud-configat the top of the file.
1.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:
cloud-initgenerator stage, through the
systemdservice, determines whether to run
cloud-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 under
cloud.cfgfile. You can enable, disable, or add modules to the
During the config stage,
cloud-initruns the modules listed under
cloud.cfgfile. You can enable, disable, or add modules to the
During the final stage,
cloud-initcan run what you have included under
cloud.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 the
The five boot stages are described in the
cloud-init Documentation section Boot Stages.
1.3. cloud-init modules execute in phases
cloud-init runs, it executes the modules within
cloud.cfg in order within three phases:
The network phase (
The configuration phase (
The final phase (
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.
1.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 the
cloud.cfg.ddirectory, for example, user data can include files to run, packages to install, and shell scripts. Refer to the
cloud-initDocumentation section User-Data Formats for information on the types of user data that
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 on vendor data.
1.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:
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']
cloud-init runs, you can view a log file (
run/cloud-init/ds-identify.log) that provides detailed information about the platform.