CLI commands - cloud-init 25.1.2 documentation (original) (raw)

Cloud-init ships multiple executables that are intended for user interaction.

cloud-init¶

For the latest list of subcommands and arguments use cloud-init’s--help option. This can be used against cloud-init itself, or on any of its subcommands.

Example output:

usage: cloud-init [-h] [--version] [--debug] [--force] [--all-stages] {init,modules,single,query,features,analyze,devel,collect-logs,clean,status,schema} ...

options: -h, --help show this help message and exit --version, -v Show program's version number and exit. --debug, -d Show additional pre-action logging (default: False). --force Force running even if no datasource is found (use at your own risk). --all-stages Run cloud-init's stages under a single process using a syncronization protocol. This is not intended for CLI usage.

Subcommands: {init,modules,single,query,features,analyze,devel,collect-logs,clean,status,schema} init DEPRECATED: Initialize cloud-init and perform initial modules. modules DEPRECATED: Activate modules using a given configuration key. single Manually run a single module. Useful for testing during development. query Query standardized instance-data from the command line. features List defined features. analyze Devel tool: Analyze cloud-init logs and data. devel Run development tools. collect-logs Collect and tar all cloud-init debug info. clean Remove logs and artifacts so cloud-init can re-run. status Report cloud-init status or wait on completion. schema Validate cloud-config files using jsonschema.

The rest of this document will give an overview of each of the subcommands.

analyze¶

Get detailed reports of where cloud-init spends its time during the boot process. For more complete reference see Performance.

Possible subcommands include:

• blame: report ordered by most costly operations.
• dump: machine-readable JSON dump of all cloud-init tracked events.
• show: show time-ordered report of the cost of operations during each boot stage.
• boot: show timestamps from kernel initialization, kernel finish initialization, and cloud-init start.

clean¶

Remove cloud-init artifacts from /var/lib/cloud and config files (best effort) to simulate a clean instance. On reboot, cloud-init will re-run all stages as it did on first boot.

• --logs: Optionally remove all cloud-init log files in/var/log/.
• --reboot: Reboot the system after removing artifacts.
• --machine-id: Set /etc/machine-id to uninitialized\non this image for systemd environments. On distributions without systemd, remove the file. Best practice when cloning a golden image, to ensure the next boot of that image auto-generates a unique machine ID.More details on machine-id.
• --configs [all | ssh_config | network | datasource ]: Optionally remove all cloud-init generated config files. Argument ssh_configcleans config files for ssh daemon. Argument network removes all generated config files for network. Argument datasource removes files and/or configs written by current datasource. all removes config files of all types.

collect-logs¶

Collect and tar cloud-init-generated logs, data files, and system information for triage. This subcommand is integrated with apport.

Logs collected include:

• /var/log/cloud-init.log
• /var/log/cloud-init-output.log
• /run/cloud-init
• /var/lib/cloud/instance/user-data.txt
• cloud-init package version
• dmesg output
• journalctl output

Note

Ubuntu users can file bugs using ubuntu-bug cloud-init to automatically attach these logs to a bug report.

devel¶

Collection of development tools under active development. These tools will likely be promoted to top-level subcommands when stable.

Do NOT rely on the output of these commands as they can and will change.

Current subcommands:

net-convert¶

Manually use cloud-init’s network format conversion. Useful for testing configuration or testing changes to the network conversion logic itself.

render¶

Use cloud-init’s jinja template render to process #cloud-config orcustom-scripts, injecting any variables from/run/cloud-init/instance-data.json. It accepts a user-data file containing the jinja template header ## template: jinja and renders that content with any instance-data.json variables present.

hotplug-hook¶

Hotplug related subcommands. This command is intended to be called via a systemd service and is not considered user-accessible except for debugging purposes.

query¶

Query if hotplug is enabled for a given subsystem.

handle¶

Respond to newly added system devices by retrieving updated system meta-data and bringing up/down the corresponding device.

enable¶

Enable hotplug for a given subsystem. This is a last resort command for administrators to enable hotplug in running instances. The recommended method is configuring Events and updates, if not enabled by default in the active datasource.

features¶

Print out each feature supported. If cloud-init does not have thefeatures subcommand, it also does not support any features described in this document.

Example output:

NETWORK_CONFIG_V1 NETWORK_CONFIG_V2

init (deprecated)¶

Generally run by OS init systems to execute cloud-init’s stages:init and init-local. See Boot stages for more info. Can be run on the command line, but is deprecated, because incomplete configuration can be applied when run later in boot. The boot stages are generally gated to run only once due to semaphores in/var/lib/cloud/instance/sem/ and /var/lib/cloud/sem.

• --local: Run init-local stage instead of init.
• --file : Use additional yaml configuration files.

modules (deprecated)¶

Generally run by OS init systems to execute modules:config andmodules:final boot stages. This executes cloud config Module referenceconfigured to run in the Init, Config and Final stages. Can be run on the command line, but this is not recommended and will generate a warning because incomplete configuration can be applied when run later in boot. The modules are declared to run in various boot stages in the file/etc/cloud/cloud.cfg under keys:

• cloud_init_modules
• cloud_config_modules
• cloud_final_modules

Can be run on the command line, but is deprecated, because incomplete configuration can be applied when run later in boot. Each module is gated to run only once due to semaphores in /var/lib/cloud/.

• --mode [init|config|final]: Run modules:init,modules:config or modules:final cloud-init stages. See Boot stages for more info.
• --file : Use additional yaml configuration files.

Warning

–mode init is deprecated in 24.1 and scheduled to be removed in 29.1. Use cloud-init init instead.

query¶

Query standardized instance-data crawled by cloud-init and stored in /run/cloud-init/instance-data.json. This is a convenience command-line interface to reference any cached configuration meta-data thatcloud-init crawls when booting the instance. See Instance-datafor more info.

• --all: Dump all available instance-data as JSON which can be queried.
• --instance-data: Optional path to a differentinstance-data.json file to source for queries.
• --list-keys: List available query keys from cached instance-data.
• --format: A string that will use jinja-template syntax to render a string replacing.
• : A dot-delimited variable path into theinstance-data.json object.

Below demonstrates how to list all top-level query keys that are standardized aliases:

$ cloud-init query --list-keys

Example output:

_beta_keys availability_zone base64_encoded_keys cloud_name ds instance_id local_hostname platform public_ssh_keys region sensitive_keys subplatform userdata v1 vendordata

Here are a few examples of how to query standardized meta-data from clouds:

$ cloud-init query v1.cloud_name

Example output:

aws # or openstack, azure, gce etc.

Any standardized instance-data under a <v#> key is aliased as a top-level key for convenience:

$ cloud-init query cloud_name

Example output:

aws # or openstack, azure, gce etc.

One can also query datasource-specific meta-data on EC2, e.g.:

$ cloud-init query ds.meta_data.public_ipv4

Note

The standardized instance data keys under v# are guaranteed not to change behaviour or format. If using top-level convenience aliases for any standardized instance data keys, the most value (highest v#) of that key name is what is reported as the top-level value. So these aliases act as a ‘latest’.

This data can then be formatted to generate custom strings or data. For example, we can generate a custom hostname FQDN based on instance-id, cloud and region:

$ cloud-init query --format 'custom-{{instance_id}}.{{region}}.{{v1.cloud_name}}.com'

custom-i-0e91f69987f37ec74.us-east-2.aws.com

schema¶

Validate cloud-config files using jsonschema.

• -h, --help: Show this help message and exit.
• -c CONFIG_FILE, --config-file CONFIG_FILE: Path of the cloud-config YAML file to validate.
• -t SCHEMA_TYPE, --schema-type SCHEMA_TYPE: The schema type to validate –config-file against. One of: cloud-config, network-config. Default: cloud-config.
• --system: Validate the system cloud-config user-data.
• -d DOCS [cc_module ...], --docs DOCS [cc_module ...]: Print schema module docs. Choices are: “all” or “space-delimited” cc_names.
• --annotate: Annotate existing cloud-config file with errors.

The following example checks a config file and annotates the config file with errors on stdout.

$ cloud-init schema -c ./config.yml --annotate

single¶

Attempt to run a single, named, cloud config module.

• --name: The cloud-config module name to run.
• --frequency: Module frequency for this run. One of (always``|``instance``|``once).
• --report: Enable reporting.
• --file : Use additional yaml configuration files.

The following example re-runs the cc_set_hostname module ignoring the module default frequency of instance:

$ cloud-init single --name set_hostname --frequency always

Note

Mileage may vary trying to re-run each cloud-config module, as some are not idempotent.

status¶

Report cloud-init’s current status.

Exits 1 if cloud-init crashes, 2 if cloud-init finishes but experienced recoverable errors, and 0 if cloud-init ran without error.

• --long: Detailed status information.
• --wait: Block until cloud-init completes.
• --format [yaml|json]: Machine-readable JSON or YAML detailed output.

The status command can be used simply as follows:

Which shows whether cloud-init is currently running, done, disabled, or in error. Note that the extended_status key in --long or --format jsoncontains more accurate and complete status information. Example output:

The --long option, shown below, provides a more verbose output.

$ cloud-init status --long

Example output when cloud-init is running:

status: running extended_status: running boot_status_code: enabled-by-generator last_update: Wed, 13 Mar 2024 18:46:26 +0000 detail: DataSourceLXD errors: [] recoverable_errors: {}

Example output when cloud-init is done:

status: done extended_status: done boot_status_code: enabled-by-generator last_update: Wed, 13 Mar 2024 18:46:26 +0000 detail: DataSourceLXD errors: [] recoverable_errors: {}

The detailed output can be shown in machine-readable JSON or YAML with theformat option, for example:

$ cloud-init status --format=json

Which would produce the following example output:

{ "boot_status_code": "enabled-by-generator", "datasource": "lxd", "detail": "DataSourceLXD", "errors": [], "extended_status": "done", "init": { "errors": [], "finished": 1710355584.3603137, "recoverable_errors": {}, "start": 1710355584.2216876 }, "init-local": { "errors": [], "finished": 1710355582.279756, "recoverable_errors": {}, "start": 1710355582.2255273 }, "last_update": "Wed, 13 Mar 2024 18:46:26 +0000", "modules-config": { "errors": [], "finished": 1710355585.5042186, "recoverable_errors": {}, "start": 1710355585.334438 }, "modules-final": { "errors": [], "finished": 1710355586.9038777, "recoverable_errors": {}, "start": 1710355586.8076844 }, "recoverable_errors": {}, "stage": null, "status": "done" }