CLI Interface¶

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

$ cloud-init --help
  usage: /usr/bin/cloud-init [-h] [--version] [--file FILES] [--debug] [--force]
                          {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
                          ...

  optional arguments:
  -h, --help            show this help message and exit
  --version, -v         show program's version number and exit
  --file FILES, -f FILES
                          additional yaml configuration files to use
  --debug, -d           show additional pre-action logging (default: False)
  --force               force running even if no datasource is found (use at
                          your own risk)

  Subcommands:
  {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
      init                initializes cloud-init and performs initial modules
      modules             activates modules using a given configuration key
      single              run a single module
      query               Query standardized instance metadata from the command
                          line.
      dhclient-hook       Run the dhclient hook to record network info.
      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.

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 analyze.

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 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

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 with 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 or custom-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.

schema: a #cloud-config format and schema validator. It accepts a cloud-config yaml file and annotates potential schema errors locally without the need for deployment. Schema validation is work in progress and supports a subset of cloud-config modules.

hotplug-hook: respond to newly added system devices by retrieving updated system metadata and bringing up/down the corresponding device. This command is intended to be called via a systemd service and is not considered user-accessible except for debugging purposes.

features¶

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

$ cloud-init features
NETWORK_CONFIG_V1
NETWORK_CONFIG_V2

init¶

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 commandline, but is 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

modules¶

Generally run by OS init systems to execute modules:config and modules:final boot stages. This executes cloud config Modules configured to run in the init, config and final stages. 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 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.

query¶

Query standardized cloud instance metadata 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 metadata that cloud-init crawls when booting the instance. See Instance Metadata for more info.

--all: dump all available instance data as json which can be queried
--instance-data: optional path to a different instance-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
<varname>: a dot-delimited variable path into the instance-data.json object

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

$ cloud-init query --list-keys
_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

Below demonstrates how to query standardized metadata from clouds:

% cloud-init query v1.cloud_name
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
aws  # or openstack, azure, gce etc.

# Query datasource-specific metadata on EC2
% cloud-init query ds.meta_data.public_ipv4

Note

The standardized instance data keys under v# are guaranteed not to change behavior 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:

# 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

single¶

Attempt to run a single named cloud config module.

--name: the cloud-config module name to run
--frequency: optionally override the declared module frequency with one of (always|once-per-instance|once)

The following example re-runs the cc_set_hostname module ignoring the module default frequency of once-per-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 whether cloud-init is running, done, disabled or errored. Exits non-zero if an error is detected in cloud-init.

--long: detailed status information
--wait: block until cloud-init completes

Below are examples of output when cloud-init is running, showing status and the currently running modules, as well as when it is done.

$ cloud-init status
status: running

$ cloud-init status --long
status: running
time: Fri, 26 Jan 2018 21:39:43 +0000
detail:
Running in stage: init-local

$ cloud-init status
status: done

$ cloud-init status --long
status: done
time: Wed, 17 Jan 2018 20:41:59 +0000
detail:
DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net]