CLI commands#
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.
$ cloud-init --help
Example output:
usage: cloud-init [-h] [--version] [--file FILES] [--debug] [--force]
{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.
--file FILES, -f FILES
Use additional yaml configuration files.
--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,features,analyze,devel,collect-logs,clean,status,schema}
init Initialize cloud-init and perform initial modules.
modules Activate modules using a given configuration key.
single Run a single module.
query Query standardized instance metadata 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 initialisation, kernel finish initialisation, 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
touninitialized\n
on 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 ]: Optionally remove all
cloud-init
generated config files. Argument ssh_config cleans config files for ssh daemon. Argument network removes all generated config files for network. 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 versiondmesg
outputjournalctl
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 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.
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
Example output:
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 Module reference
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
ormodules:final
cloud-init
stages. See Boot stages for more info.
query#
Query standardised 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 standardised 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 standardised metadata from clouds:
$ cloud-init query v1.cloud_name
Example output:
aws # or openstack, azure, gce etc.
Any standardised 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 metadata on EC2, e.g.:
$ cloud-init query ds.meta_data.public_ipv4
Note
The standardised instance data keys under v# are guaranteed not to change behaviour or format. If using top-level convenience aliases for any standardised 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``|``once-per-instance``|``once
).--report: Enable reporting.
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.--format [yaml|json|tabular]: Machine-readable JSON or YAML detailed output.
The status command can be used simply as follows:
$ cloud-init status
Which shows whether cloud-init
is currently running, done, disabled, or in
error, as in this example output:
status: running
The --long option, shown below, provides a more verbose output.
$ cloud-init status --long
Example output when cloud-init
is running:
status: running
time: Fri, 26 Jan 2018 21:39:43 +0000
detail:
Running in stage: init-local
Example output when cloud-init
is done:
status: done
boot_status_code: enabled-by-generator
last_update: Tue, 16 Aug 2022 19:12:58 +0000
detail:
DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net]
The detailed output can be shown in machine-readable JSON or YAML with the format option, for example:
$ cloud-init status --format=json
Which would produce the following example output:
{
"boot_status_code": "enabled-by-generator",
"datasource": "nocloud",
"detail": "DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net]",
"errors": [],
"last_update": "Tue, 16 Aug 2022 19:12:58 +0000",
"status": "done"
}