cloud-init Documentation

cloud-init is an industry-standard, multi-distribution method for cross-platform cloud instance initialization. It works during the boot process to identify the cloud environment and automatically provision system aspects such as networking, storage, SSH keys, and packages.

For cloud users, it provides no-install first-boot configuration management. For cloud providers, it provides instance setup capabilities that can be integrated into cloud infrastructure.

cloud-init is a multi-distribution method for cross-platform cloud instance initialization. It works by identifying the cloud environment during boot and reading instance data to initialize the system.

Key data sources used for initialization include:

• Cloud metadata: Used to identify the cloud provider and configure network/storage.
• User data (optional): Custom configuration or scripts provided by the user.
• Vendor data (optional): Configuration provided by the cloud vendor.

It is supported across major public cloud providers, private cloud provisioning systems, and bare-metal installations.

cloud-init is an open source initialization tool designed to automate the configuration of cloud instances, VMs, and bare metal servers. It allows users to provide an initial configuration (a "to-do list") that is automatically applied during the system boot process, ensuring repeatable and consistent provisioning across fleets of machines.

Key capabilities include:

• Setting hostnames and configuring network interfaces.
• Creating user accounts and managing permissions.
• Installing software and running system updates.
• Executing custom scripts and injecting SSH keys.
• Integrating with configuration management tools like Puppet, Ansible, or Chef.

Datasources provide the configuration data required by cloud-init. They generally fall into two categories:

1. User-data: Configuration provided by the user, typically in the form of files, YAML, or shell scripts.
2. Meta-data: Configuration provided by the cloud platform, typically containing details like server name, instance ID, display name, and other cloud-specific metadata.

Any meta-data processed by cloud-init's datasources can be inspected via the instance data.

The CloudSigma datasource retrieves metadata and user-data from the CloudSigma cloud platform via a virtual serial port. A network adapter is NOT required for data transfer.

By default, the server name provided by CloudSigma is applied as the system hostname on the first boot.

The EC2 datasource allows cloud-init to retrieve instance user-data and instance-data from an EC2-compatible metadata service. This is commonly used in Amazon EC2 and clouds that emulate EC2 (such as Brightbox, E24Cloud, Outscale, Tilaa, and Zscale).

Metadata and user-data are typically accessed via a magic IP (usually 169.254.169.254) using HTTP GET requests. cloud-init automatically attempts to use the most recent supported API version to access features like Instance tags or secondary IP addresses.

Vendor-data is data provided by the entity launching an instance (e.g., a cloud provider) to customize the image for a specific environment. It follows the same rules as user-data with these specific behaviors:

• Execution Timing: By default, it only runs on the first boot.
• User Control: Users have ultimate control. They can disable the execution of vendor-data entirely or disable specific parts of multi-part input.
• Precedence: User-supplied cloud-config is merged over cloud-config provided via vendor-data.
• Safety Warning: Vendors should ensure vendor-data is safe, atomic, idempotent, and does not compromise the system, as users trust the vendor's data.

cloud-init searches for network configuration in order of increasing precedence. Each subsequent source overrides the previous one:

1. Datasource: Provided by the cloud provider (e.g., OpenStack Metadata Service).
2. System config: A network: entry in /etc/cloud/cloud.cfg.d/* files.
3. Kernel command line: Using ip= or network-config=<Base64 encoded YAML config string>.

Note: user-data cannot be used to change an instance's network configuration. If no configuration is found in the sources above, cloud-init will attempt to issue a DHCP request on the 'first' detected network interface.

CloudCIX provides metadata and user-data via an internal server accessible at http://169.254.169.254/v1.

• Metadata is available at the /metadata path.
• User-data is available at the /userdata path.

CloudCIX instances are identified by the DMI product name CloudCIX.

Part handlers are custom code implementations used to define configuration formats by modifying cloud-init's source code. They are used to either support new MIME types in multi-part user-data or to override existing handlers for currently supported MIME types.

Warning: Part handlers are not recommended for most users because the Part Handler API is not guaranteed to be stable.

Ubuntu uses Stable Release Updates (SRU) to backport new versions of cloud-init to existing Ubuntu releases. This process ensures that cloud-init updates on existing releases do not introduce breaking changes. Breaking changes are generally only permitted when transitioning between different Ubuntu series (e.g., from Focal to Jammy).

SRU support is provided for:

• The current active interim releases.
• The two most recent Long-Term Support (LTS) releases.