Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 2. Introduction to cloud-init


The cloud-init utility automates the initialization and configuration of virtual machines (VM) during the first boot. You can configure cloud-init to set hostnames, configure network interfaces, install packages, run scripts, and change default VM actions.

2.1. Overview of the cloud-init configuration

The cloud-init utility uses YAML-formatted configuration files to apply user-defined tasks to instances. When an instance boots, the cloud-init service initiates and executes the instructions from the YAML file. These tasks complete during the first boot or on subsequent boots of a virtual machine (VM), depending on the configuration.

To define the specific tasks, configure the /etc/cloud/cloud.cfg file and add directives under the /etc/cloud/cloud.cfg.d/ directory.

  • The cloud.cfg file includes directives for various system configurations, such as user access, authentication, and system information. This file also includes default and optional modules for cloud-init. The default module groups are as follows:

    • cloud_init_modules
    • cloud_config_modules
    • cloud_final_modules
  • You can include additional directives for cloud-init in the cloud.cfg.d directory.
  • While adding directives to the cloud.cfg.d directory, add them to a custom file named *.cfg, and always include #cloud-config at the top of the file.

For details, refer to an example file of cloud.cfg. See an example of cloud.cfg file.

2.2. Datasource types of cloud-init

Datasources are the sources of configuration data for cloud-init in the form of user data, metadata, and optionally vendor data. Metadata has the configuration drive created by certified cloud service provider. cloud-init automatically identifies the existing datasource, or you can configure a custom datasource directive.

# grep -i "vendor data" /var/log/cloud-init.log

For datasources, there are three types of configuration data: user data, metadata, and vendor data.

  • User data includes directives specified in the cloud.cfg file and the cloud.cfg.d directory. For example, user data can include files to run, packages to install, and shell scripts. Refer to the cloud-init Documentation section User-Data Formats for information about the types of user data that cloud-init allows.
  • 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 CCSP determines where your instance can find user data and metadata. After adding user data and metadata to an HTTP service. In this case, when cloud-init runs, it consumes user data and metadata 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-init acts 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.

By default, cloud-init automatically identifies the existing datasource. cloud-init attempts to identify the cloud platform by using the script ds-identify. The script runs on the first boot of an instance. Adding a custom 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. After cloud-init runs, you can view a log file (run/cloud-init/ds-identify.log) that provides detailed information about the platform. For details on datasource_list, see custom datasources.

For details on configuring datasources for certified cloud service provider, see:

2.3. Boot stages of cloud-init

During system boot, the cloud-init utility runs through five stages that specify whether cloud-init runs and where it finds its datasources, among other tasks. Each stage also belongs to a module execution phase, which controls what modules to run.

  1. Detect stage: By using the systemd service, this stage determines whether to run cloud-init utility at the time of boot. The ds-identify tool detects whether or not to run cloud-init in the absence of a valid platform.

    This stage belongs to the Initialization phase and does not run any modules. Instead, it identifies the datasource for cloud-init configuration.

  2. Local stage: cloud-init searches local data sources and applies network configuration, including the DHCP-based fallback mechanism.

    This stage belongs to the Initialization phase and does not run any modules.

  3. Network stage: cloud-init processes user data by running modules listed under cloud_init_modules in the /etc/cloud/cloud.cfg file. You can add, remove, enable, or disable modules in the cloud_init_modules section.

    This stage belongs to the Networking module execution stage.

  4. Config stage: cloud-init runs modules listed under cloud_config_modules section in the /etc/cloud/cloud.cfg file. You can add, remove, enable, or disable modules in the cloud_config_modules section.

    This stage belongs to the Configuration module execution phase.

  5. Final stage: cloud-init runs modules and configurations included in the cloud_final_modules section of the /etc/cloud/cloud.cfg file. It can include the installation of specific packages, and triggering configuration management plugins and user-defined scripts. You can add, remove, enable, or disable modules in the cloud_final_modules section.

    This stage is equivalent to the Finalization module execution phase.

During the first boot of VM, when the cloud-init service initiates, all the configured modules run in their phases. At the next boot, whether a module runs within a phase depends on the module frequency of that module. Module frequency sets in the cloud-init configuration, and determines whether a module runs every time cloud-init runs on the instance, or only the first time cloud-init runs, even if the instance ID changes.

Note

An instance ID uniquely identifies an instance. When an instance ID changes, cloud-init treats the instance as a new instance. For details, see Schema definition for module creation.

The possible module frequency values are as follows:

  • PER_INSTANCE means that the module runs on the first boot of an instance. For example, if you clone an instance or create a new instance from a saved image, the modules designated according to instance run again.
  • ONCE means 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_ALWAYS means the module runs on every boot.
Note

You can override a module’s frequency when you configure the module or by using the command line.

2.4. Files and directories significant for cloud-init

Red Hat supports the cloud-init utility, cloud-init modules, and default directories and files. You can use these directories and files to configure cloud-init, examine log files, find templates, and review configuration details after cloud-init completes execution. Depending on your requirement and datasource, there can be additional files and directories important to your configuration.

Expand
Table 2.1. cloud-init directories and files
Directory or FileDescription

/etc/cloud/cloud.cfg

The cloud.cfg file includes the basic cloud-init configuration and lets you know in what phase each module runs.

/etc/cloud/cloud.cfg.d

The cloud.cfg.d directory is where you can add additional directives for cloud-init.

/var/lib/cloud

When cloud-init runs, it creates a directory layout under /var/lib/cloud. The layout includes directories and files that give specifics on your instance configuration.

/usr/share/doc/cloud-init/examples

The examples directory includes multiple examples. You can use them to help model your own directives.

/etc/cloud/templates

This directory includes templates that you can enable in cloud-init for certain scenarios. The templates provide direction for enabling.

/var/log/cloud-init.log

The cloud-init.log file provides log information helpful for debugging.

/run/cloud-init

The /run/cloud-init directory includes logged information about your datasource and the ds-identify script.

The default cloud.cfg file

To list and use modules included in the basic configuration for cloud-init, use the /etc/cloud/cloud.cfg file. You can configure or remove modules based on your requirements:

  • To perform actions during one of the cloud-init phases, you must configure each module individually and list them in the cloud.cfg file. Modules run in the order given in cloud.cfg. You typically do not change this order. However, you can add additional modules to cloud.cfg, if Red Hat supports the modules that you want to add.
  • The cloud.cfg directives can be overridden by user data. When running cloud-init manually, you can override cloud.cfg with command-line options.
  • Each module includes its own configuration options, where you can add specific information.
  • To ensure optimal functionality of the configuration, use module names with underscores (_) rather than dashes (-).
  • The default contents of the file for Red Hat Enterprise Linux (RHEL) are as follows:

    users:
     - default
    
    disable_root: true
    resize_rootfs_tmp: /dev
    ssh_pwauth:   false
    
    mount_default_fields: [~, ~, 'auto', 'defaults,nofail,x-systemd.requires=cloud-init.service', '0', '2']
    ssh_deletekeys:   true
    ssh_genkeytypes: ['rsa', 'ecdsa', 'ed25519']
    syslog_fix_perms: ~
    disable_vmware_customization: false
    
    cloud_init_modules:
      - migrator
      - seed_random
      - bootcmd
      - write_files
      - growpart
      - resizefs
      - disk_setup
      - mounts
      - set_hostname
      - update_hostname
      - update_etc_hosts
      - ca_certs
      - rsyslog
      - users_groups
      - ssh
    
    cloud_config_modules:
      - ssh_import_id
      - locale
      - set_passwords
      - rh_subscription
      - spacewalk
      - yum_add_repo
      - ntp
      - timezone
      - disable_ec2_metadata
      - runcmd
    
    cloud_final_modules:
      - package_update_upgrade_install
      - write_files_deferred
      - puppet
      - chef
      - ansible
      - mcollective
      - salt_minion
      - reset_rmc
      - rightscale_userdata
      - scripts_vendor
      - scripts_per_once
      - scripts_per_boot
      - scripts_per_instance
      - scripts_user
      - ssh_authkey_fingerprints
      - keys_to_console
      - install_hotplug
      - phone_home
      - final_message
      - power_state_change
    
    system_info:
      default_user:
        name: cloud-user
        lock_passwd: true
        gecos: Cloud User
        groups: [adm, systemd-journal]
        sudo: ["ALL=(ALL) NOPASSWD:ALL"]
        shell: /bin/bash
       distro: rhel
       network:
        renderers: ['sysconfig', 'eni', 'netplan', 'network-manager', 'networkd']
      paths:
        cloud_dir: /var/lib/cloud
        templates_dir: /etc/cloud/templates
      ssh_svcname: sshd
    
    # vim:syntax=yaml
  • users specifies the default user for the system. For more information, see Users and Groups.
  • disable_root enables or disables root login. For more information, see Authorized Keys.
  • ssh_pwauth specifies whether ssh is configured to accept password authentication. For more information, see Set Passwords.
  • mount_default_fields configures mount points. It must be a list containing six values. For more information, see Mounts.
  • ssh_deletekeys specifies whether to remove default host SSH keys. For more information, see Host Keys.
  • ssh_genkeytypes specifies key types to generate. For more information, see Host Keys.
  • syslog_fix_perms configures cloud-init to log all boot stages to its log file. For more information, see the cloud-config.txt file in the usr/share/doc/cloud-init/examples directory.
  • disable_vmware_customization enables or disables VMware vSphere customization.
  • cloud_init_modules: The modules in this section are services that run when the cloud-init service starts, early in the boot process.
  • cloud_config_modules: These modules run during cloud-init configuration, after initial boot.
  • cloud_final_modules: These modules run in the final phase of cloud-init, after the configuration finishes.
  • default_user specifies details about the default user. For more information. see Users and Groups.
  • distro: specifies the distribution.
  • cloud_dir specifies the main directory that has cloud-init-specific subdirectories. For more information, see Directory layout.
  • templates_dir specifies the location of the templates.
  • ssh_svcname is the name of the SSH service.
The default 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.
Note

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.

Refer to User-Data Formats for details on how to add a user script as *.cfg file.

The default 05_logging.cfg file
To set logging information for cloud-init, use the 05_logging.cfg file located in the /etc/cloud/cloud.cfg.d directory. This directory contains various cloud-init directives that you can add.

By default, cloud-init uses the logging configuration in the 05_logging.cfg file for Red Hat Enterprise Linux (RHEL):

## 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'}
The /var/lib/cloud directory layout
When cloud-init initiates, it creates a directory layout with instance details and cloud-init configuration. This 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.once
Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2026 Red Hat
Nach oben