Modules ¶

Table of Contents

APK Configure ¶

Summary: Configure apk repositories file

This module handles configuration of the /etc/apk/repositories file.

Note

To ensure that apk configuration is valid yaml, any strings containing special characters, especially : should be quoted.

Internal name: cc_apk_configure

Module frequency: once-per-instance

Supported distros: alpine

Config schema:: apk_repos: (object)

preserve_repositories: (boolean) By default, cloud-init will generate a new repositories file /etc/apk/repositories based on any valid configuration settings specified within a apk_repos section of cloud config. To disable this behavior and preserve the repositories file from the pristine image, set preserve_repositories to true.

The preserve_repositories option overrides all other config keys that would alter /etc/apk/repositories.

alpine_repo: (object/null)

base_url: (string) The base URL of an Alpine repository, or mirror, to download official packages from. If not specified then it defaults to https://alpine.global.ssl.fastly.net/alpine

community_enabled: (boolean) Whether to add the Community repo to the repositories file. By default the Community repo is not included.

testing_enabled: (boolean) Whether to add the Testing repo to the repositories file. By default the Testing repo is not included. It is only recommended to use the Testing repo on a machine running the Edge version of Alpine as packages installed from Testing may have dependancies that conflict with those in non-Edge Main or Community repos.”

version: (string) The Alpine version to use (e.g. v3.12 or edge)

local_repo_base_url: (string) The base URL of an Alpine repository containing unofficial packages

Examples:

# Keep the existing /etc/apk/repositories file unaltered.
apk_repos:
    preserve_repositories: true

# --- Example2 ---
# Create repositories file for Alpine v3.12 main and community
# using default mirror site.
apk_repos:
    alpine_repo:
        community_enabled: true
        version: 'v3.12'

# --- Example3 ---
# Create repositories file for Alpine Edge main, community, and
# testing using a specified mirror site and also a local repo.
apk_repos:
    alpine_repo:
        base_url: 'https://some-alpine-mirror/alpine'
        community_enabled: true
        testing_enabled: true
        version: 'edge'
    local_repo_base_url: 'https://my-local-server/local-alpine'

This module handles both configuration of apt options and adding source lists. There are configuration options such as apt_get_wrapper and apt_get_command that control how cloud-init invokes apt-get. These configuration options are handled on a per-distro basis, so consult documentation for cloud-init’s distro support for instructions on using these config options.

Note

To ensure that apt configuration is valid yaml, any strings containing special characters, especially : should be quoted.

Note

For more information about apt configuration, see the Additional apt configuration example.

Internal name: cc_apt_configure

Module frequency: once-per-instance

Supported distros: ubuntu, debian

Config schema:

apt: (object)

preserve_sources_list: (boolean) By default, cloud-init will generate a new sources list in /etc/apt/sources.list.d based on any changes specified in cloud config. To disable this behavior and preserve the sources list from the pristine image, set preserve_sources_list to true.

The preserve_sources_list option overrides all other config keys that would alter sources.list or sources.list.d, except for additional sources to be added to sources.list.d.

disable_suites: (array of string) Entries in the sources list can be disabled using disable_suites, which takes a list of suites to be disabled. If the string $RELEASE is present in a suite in the disable_suites list, it will be replaced with the release name. If a suite specified in disable_suites is not present in sources.list it will be ignored. For convenience, several aliases are provided for disable_suites:

updates => $RELEASE-updates

backports => $RELEASE-backports

security => $RELEASE-security

proposed => $RELEASE-proposed

release => $RELEASE.

When a suite is disabled using disable_suites, its entry in sources.list is not deleted; it is just commented out.

primary: (array) The primary and security archive mirrors can be specified using the primary and security keys, respectively. Both the primary and security keys take a list of configs, allowing mirrors to be specified on a per-architecture basis. Each config is a dictionary which must have an entry for arches, specifying which architectures that config entry is for. The keyword default applies to any architecture not explicitly listed. The mirror url can be specified with the uri key, or a list of mirrors to check can be provided in order, with the first mirror that can be resolved being selected. This allows the same configuration to be used in different environment, with different hosts used for a local apt mirror. If no mirror is provided by uri or search, search_dns may be used to search for dns names in the format <distro>-mirror in each of the following:

fqdn of this host per cloud metadata,

localdomain,

domains listed in /etc/resolv.conf.

If there is a dns entry for <distro>-mirror, then it is assumed that there is a distro mirror at http://<distro>-mirror.<domain>/<distro>. If the primary key is defined, but not the security key, then then configuration for primary is also used for security. If search_dns is used for the security key, the search pattern will be <distro>-security-mirror.

Each mirror may also specify a key to import via any of the following optional keys:

keyid: a key to import via shortid or fingerprint.

key: a raw PGP key.

keyserver: alternate keyserver to pull keyid key from.

If no mirrors are specified, or all lookups fail, then default mirrors defined in the datasource are used. If none are present in the datasource either the following defaults are used:

primary => http://archive.ubuntu.com/ubuntu.

security => http://security.ubuntu.com/ubuntu

security: (array) Please refer to the primary config documentation

add_apt_repo_match: (string) All source entries in apt-sources that match regex in add_apt_repo_match will be added to the system using add-apt-repository. If add_apt_repo_match is not specified, it defaults to ^[\w-]+:\w

debconf_selections: (object of string) Debconf additional configurations can be specified as a dictionary under the debconf_selections config key, with each key in the dict representing a different set of configurations. The value of each key must be a string containing all the debconf configurations that must be applied. We will bundle all of the values and pass them to debconf-set-selections. Therefore, each value line must be a valid entry for debconf-set-selections, meaning that they must possess for distinct fields:

pkgname question type answer

Where:

pkgname is the name of the package.

question the name of the questions.

type is the type of question.

answer is the value used to ansert the question.

For example: ippackage ippackage/ip string 127.0.01

sources_list: (string) Specifies a custom template for rendering sources.list . If no sources_list template is given, cloud-init will use sane default. Within this template, the following strings will be replaced with the appropriate values:

$MIRROR

$RELEASE

$PRIMARY

$SECURITY

conf: (string) Specify configuration for apt, such as proxy configuration. This configuration is specified as a string. For multiline apt configuration, make sure to follow yaml syntax.

https_proxy: (string) More convenient way to specify https apt proxy. https proxy url is specified in the format https://[[user][:pass]@]host[:port]/.

http_proxy: (string) More convenient way to specify http apt proxy. http proxy url is specified in the format http://[[user][:pass]@]host[:port]/.

proxy: (string) Alias for defining a http apt proxy.

ftp_proxy: (string) More convenient way to specify ftp apt proxy. ftp proxy url is specified in the format ftp://[[user][:pass]@]host[:port]/.

sources: (object of string) Source list entries can be specified as a dictionary under the sources config key, with each key in the dict representing a different source file. The key of each source entry will be used as an id that can be referenced in other config entries, as well as the filename for the source’s configuration under /etc/apt/sources.list.d. If the name does not end with .list, it will be appended. If there is no configuration for a key in sources, no file will be written, but the key may still be referred to as an id in other sources entries.

Each entry under sources is a dictionary which may contain any of the following optional keys:

source: a sources.list entry (some variable replacements apply).

keyid: a key to import via shortid or fingerprint.

key: a raw PGP key.

keyserver: alternate keyserver to pull keyid key from.

The source key supports variable replacements for the following strings:

$MIRROR

$PRIMARY

$SECURITY

$RELEASE

Examples:

apt:
  preserve_sources_list: false
  disable_suites:
    - $RELEASE-updates
    - backports
    - $RELEASE
    - mysuite
  primary:
    - arches:
        - amd64
        - i386
        - default
      uri: 'http://us.archive.ubuntu.com/ubuntu'
      search:
        - 'http://cool.but-sometimes-unreachable.com/ubuntu'
        - 'http://us.archive.ubuntu.com/ubuntu'
      search_dns: <true/false>
    - arches:
        - s390x
        - arm64
      uri: 'http://archive-to-use-for-arm64.example.com/ubuntu'
  security:
    - arches:
        - default
      search_dns: true
  sources_list: |
      deb $MIRROR $RELEASE main restricted
      deb-src $MIRROR $RELEASE main restricted
      deb $PRIMARY $RELEASE universe restricted
      deb $SECURITY $RELEASE-security multiverse
  debconf_selections:
      set1: the-package the-package/some-flag boolean true
  conf: |
      APT {
          Get {
              Assume-Yes 'true';
              Fix-Broken 'true';
          }
      }
  proxy: 'http://[[user][:pass]@]host[:port]/'
  http_proxy: 'http://[[user][:pass]@]host[:port]/'
  ftp_proxy: 'ftp://[[user][:pass]@]host[:port]/'
  https_proxy: 'https://[[user][:pass]@]host[:port]/'
  sources:
      source1:
          keyid: 'keyid'
          keyserver: 'keyserverurl'
          source: 'deb http://<url>/ xenial main'
      source2:
          source: 'ppa:<ppa-name>'
      source3:
          source: 'deb $MIRROR $RELEASE multiverse'
          key: |
              ------BEGIN PGP PUBLIC KEY BLOCK-------
              <key data>
              ------END PGP PUBLIC KEY BLOCK-------

Apt Pipelining ¶

Summary: configure apt pipelining

This module configures apt’s Acquite::http::Pipeline-Depth option, which controls how apt handles HTTP pipelining. It may be useful for pipelining to be disabled, because some web servers, such as S3 do not pipeline properly (LP: #948461). The apt_pipelining config key may be set to false to disable pipelining altogether. This is the default behavior. If it is set to none, unchanged, or os, no change will be made to apt configuration and the default setting for the distro will be used. The pipeline depth can also be manually specified by setting apt_pipelining to a number. However, this is not recommended.

Internal name: cc_apt_pipelining

Module frequency: per instance

Supported distros: ubuntu, debian

Config keys::: apt_pipelining: <false/none/unchanged/os/number>

Bootcmd ¶

Summary: Run arbitrary commands early in the boot process

This module runs arbitrary commands very early in the boot process, only slightly after a boothook would run. This is very similar to a boothook, but more user friendly. The environment variable INSTANCE_ID will be set to the current instance id for all run commands. Commands can be specified either as lists or strings. For invocation details, see runcmd.

Note

bootcmd should only be used for things that could not be done later in the boot process.

Note

when writing files, do not use /tmp dir as it races with systemd-tmpfiles-clean LP: #1707222. Use /run/somedir instead.

Internal name: cc_bootcmd

Module frequency: always

Supported distros: all

Config schema:: bootcmd: (array of (array of string)/(string))

Examples:

bootcmd:
    - echo 192.168.1.130 us.archive.ubuntu.com > /etc/hosts
    - [ cloud-init-per, once, mymkfs, mkfs, /dev/vdb ]

Byobu ¶

Summary: enable/disable byobu system wide and for default user

This module controls whether byobu is enabled or disabled system wide and for the default system user. If byobu is to be enabled, this module will ensure it is installed. Likewise, if it is to be disabled, it will be removed if installed.

Valid configuration options for this module are:

enable-system: enable byobu system wide

enable-user: enable byobu for the default user

disable-system: disable byobu system wide

disable-user: disable byobu for the default user

enable: enable byobu both system wide and for default user

disable: disable byobu for all users

user: alias for enable-user

system: alias for enable-system

Internal name: cc_byobu

Module frequency: per instance

Supported distros: ubuntu, debian

Config keys:

byobu_by_default: <user/system>

CA Certs ¶

Summary: add ca certificates

This module adds CA certificates to /etc/ca-certificates.conf and updates the ssl cert cache using update-ca-certificates. The default certificates can be removed from the system with the configuration option remove-defaults.

Note

certificates must be specified using valid yaml. in order to specify a multiline certificate, the yaml multiline list syntax must be used

Note

For Alpine Linux the “remove-defaults” functionality works if the ca-certificates package is installed but not if the ca-certificates-bundle package is installed.

Internal name: cc_ca_certs

Module frequency: per instance

Supported distros: alpine, debian, ubuntu, rhel

Config keys:

ca-certs:
    remove-defaults: <true/false>
    trusted:
        - <single line cert>
        - |
          -----BEGIN CERTIFICATE-----
          YOUR-ORGS-TRUSTED-CA-CERT-HERE
          -----END CERTIFICATE-----

Chef ¶

Summary: module that configures, starts and installs chef

This module enables chef to be installed (from packages, gems, or from omnibus). Before this occurs, chef configuration is written to disk (validation.pem, client.pem, firstboot.json, client.rb), and required directories are created (/etc/chef and /var/log/chef and so-on). If configured, chef will be installed and started in either daemon or non-daemon mode. If run in non-daemon mode, post run actions are executed to do finishing activities such as removing validation.pem.

Internal name: cc_chef

Module frequency: always

Supported distros: all

Config schema:

chef: (object)

directories: (array of string) Create the necessary directories for chef to run. By default, it creates the following directories:

/etc/chef

/var/log/chef

/var/lib/chef

/var/cache/chef

/var/backups/chef

/var/run/chef

validation_cert: (string) Optional string to be written to file validation_key. Special value system means set use existing file.

validation_key: (string) Optional path for validation_cert. default to /etc/chef/validation.pem.

firstboot_path: (string) Path to write run_list and initial_attributes keys that should also be present in this configuration, defaults to /etc/chef/firstboot.json.

exec: (boolean) define if we should run or not run chef (defaults to false, unless a gem installed is requested where this will then default to true).

client_key: (string) Optional path for client_cert. default to /etc/chef/client.pem.

encrypted_data_bag_secret: (string) Specifies the location of the secret key used by chef to encrypt data items. By default, this path is set to None, meaning that chef will have to look at the path /etc/chef/encrypted_data_bag_secret for it.

environment: (string) Specifies which environment chef will use. By default, it will use the _default configuration.

file_backup_path: (string) Specifies the location in which backup files are stored. By default, it uses the /var/backups/chef location.

file_cache_path: (string) Specifies the location in which chef cache files will be saved. By default, it uses the /var/cache/chef location.

json_attribs: (string) Specifies the location in which some chef json data is stored. By default, it uses the /etc/chef/firstboot.json location.

log_level: (string) Defines the level of logging to be stored in the log file. By default this value is set to :info.

log_location: (string) Specifies the location of the chef lof file. By default, the location is specified at /var/log/chef/client.log.

node_name: (string) The name of the node to run. By default, we will use th instance id as the node name.

omnibus_url: (string) Omnibus URL if chef should be installed through Omnibus. By default, it uses the https://www.chef.io/chef/install.sh.

omnibus_url_retries: (integer) The number of retries that will be attempted to reach the Omnibus URL

omnibus_version: (string) Optional version string to require for omnibus install.

pid_file: (string) The location in which a process identification number (pid) is saved. By default, it saves in the /var/run/chef/client.pid location.

server_url: (string) The URL for the chef server

show_time: (boolean) Show time in chef logs

ssl_verify_mode: (string) Set the verify mode for HTTPS requests. We can have two possible values for this parameter:

:verify_none: No validation of SSL certificates.

:verify_peer: Validate all SSL certificates.

By default, the parameter is set as :verify_none.

validation_name: (string) The name of the chef-validator key that Chef Infra Client uses to access the Chef Infra Server during the initial Chef Infra Client run.

force_install: (boolean) If set to True, forces chef installation, even if it is already installed.

initial_attributes: (object of string) Specify a list of initial attributes used by the cookbooks.

install_type: (string) The type of installation for chef. It can be one of the following values:

packages

gems

omnibus

run_list: (array of string) A run list for a first boot json.

chef_license: (string) string that indicates if user accepts or not license related to some of chef products

Examples:

chef:
  directories:
    - /etc/chef
    - /var/log/chef
  validation_cert: system
  install_type: omnibus
  initial_attributes:
    apache:
      prefork:
        maxclients: 100
      keepalive: off
  run_list:
    - recipe[apache2]
    - role[db]
  encrypted_data_bag_secret: /etc/chef/encrypted_data_bag_secret
  environment: _default
  log_level: :auto
  omnibus_url_retries: 2
  server_url: https://chef.yourorg.com:4000
  ssl_verify_mode: :verify_peer
  validation_name: yourorg-validator

Debug ¶

Summary: helper to debug cloud-init internal datastructures.

This module will enable for outputting various internal information that cloud-init sources provide to either a file or to the output console/log location that this cloud-init has been configured with when running.

Note

Log configurations are not output.

Internal name: cc_debug

Module frequency: per instance

Supported distros: all

Config keys:

debug:
   verbose: true/false (defaulting to true)
   output: (location to write output, defaulting to console + log)

Disable EC2 Metadata ¶

Summary: disable aws ec2 metadata

This module can disable the ec2 datasource by rejecting the route to 169.254.169.254, the usual route to the datasource. This module is disabled by default.

Internal name: cc_disable_ec2_metadata

Module frequency: per always

Supported distros: all

Config keys:

disable_ec2_metadata: <true/false>

Disk Setup ¶

Summary: configure partitions and filesystems

This module is able to configure simple partition tables and filesystems.

Note

for more detail about configuration options for disk setup, see the disk setup example

For convenience, aliases can be specified for disks using the device_aliases config key, which takes a dictionary of alias: path mappings. There are automatic aliases for swap and ephemeral<X>, where swap will always refer to the active swap partition and ephemeral<X> will refer to the block device of the ephemeral image.

Disk partitioning is done using the disk_setup directive. This config directive accepts a dictionary where each key is either a path to a block device or an alias specified in device_aliases, and each value is the configuration options for the device. The table_type option specifies the partition table type, either mbr or gpt. The layout option specifies how partitions on the device are to be arranged. If layout is set to true, a single partition using all the space on the device will be created. If set to false, no partitions will be created. Partitions can be specified by providing a list to layout, where each entry in the list is either a size or a list containing a size and the numerical value for a partition type. The size for partitions is specified in percentage of disk space, not in bytes (e.g. a size of 33 would take up 1/3 of the disk space). The overwrite option controls whether this module tries to be safe about writing partition tables or not. If overwrite: false is set, the device will be checked for a partition table and for a file system and if either is found, the operation will be skipped. If overwrite: true is set, no checks will be performed.

Note

Using overwrite: true is dangerous and can lead to data loss, so double check that the correct device has been specified if using this option.

File system configuration is done using the fs_setup directive. This config directive accepts a list of filesystem configs. The device to create the filesystem on may be specified either as a path or as an alias in the format <alias name>.<y> where <y> denotes the partition number on the device. The partition can also be specified by setting partition to the desired partition number. The partition option may also be set to auto, in which this module will search for the existance of a filesystem matching the label, type and device of the fs_setup entry and will skip creating the filesystem if one is found. The partition option may also be set to any, in which case any file system that matches type and device will cause this module to skip filesystem creation for the fs_setup entry, regardless of label matching or not. To write a filesystem directly to a device, use partition: none. A label can be specified for the filesystem using label, and the filesystem type can be specified using filesystem.

Note

If specifying device using the <device name>.<partition number> format, the value of partition will be overwritten.

Note

Using overwrite: true for filesystems is dangerous and can lead to data loss, so double check the entry in fs_setup.

Note

replace_fs is ignored unless partition is auto or any.

Internal name: cc_disk_setup

Module frequency: per instance

Supported distros: all

Config keys:

device_aliases:
    <alias name>: <device path>
disk_setup:
    <alias name/path>:
        table_type: <'mbr'/'gpt'>
        layout:
            - [33,82]
            - 66
        overwrite: <true/false>
fs_setup:
    - label: <label>
      filesystem: <filesystem type>
      device: <device>
      partition: <"auto"/"any"/"none"/<partition number>>
      overwrite: <true/false>
      replace_fs: <filesystem type>

Emit Upstart ¶

Summary: emit upstart configuration

Emit upstart configuration for cloud-init modules on upstart based systems. No user configuration should be required.

Internal name: cc_emit_upstart

Module frequency: per always

Supported distros: ubuntu, debian

Fan ¶

Summary: configure ubuntu fan networking

This module installs, configures and starts the ubuntu fan network system. For more information about Ubuntu Fan, see: https://wiki.ubuntu.com/FanNetworking.

If cloud-init sees a fan entry in cloud-config it will:

write config_path with the contents of the config key

install the package ubuntu-fan if it is not installed

ensure the service is started (or restarted if was previously running)

Internal name: cc_fan

Module frequency: per instance

Supported distros: ubuntu

Config keys:

fan:
    config: |
        # fan 240
        10.0.0.0/8 eth0/16 dhcp
        10.0.0.0/8 eth1/16 dhcp off
        # fan 241
        241.0.0.0/8 eth0/16 dhcp
    config_path: /etc/network/fan

Final Message ¶

Summary: output final message when cloud-init has finished

This module configures the final message that cloud-init writes. The message is specified as a jinja template with the following variables set:

version: cloud-init version

timestamp: time at cloud-init finish

datasource: cloud-init data source

uptime: system uptime

Internal name: cc_final_message

Module frequency: per always

Supported distros: all

Config keys:

final_message: <message>

Foo ¶

Summary: example module

Example to show module structure. Does not do anything.

Internal name: cc_foo

Module frequency: per instance

Supported distros: all

Growpart ¶

Summary: grow partitions

Growpart resizes partitions to fill the available disk space. This is useful for cloud instances with a larger amount of disk space available than the pristine image uses, as it allows the instance to automatically make use of the extra space.

The devices on which to run growpart are specified as a list under the devices key. Each entry in the devices list can be either the path to the device’s mountpoint in the filesystem or a path to the block device in /dev.

The utility to use for resizing can be selected using the mode config key. If the mode key is set to auto, then any available utility (either growpart or BSD gpart) will be used. If neither utility is available, no error will be raised. If mode is set to growpart, then the growpart utility will be used. If this utility is not available on the system, this will result in an error. If mode is set to off or false, then cc_growpart will take no action.

There is some functionality overlap between this module and the growroot functionality of cloud-initramfs-tools. However, there are some situations where one tool is able to function and the other is not. The default configuration for both should work for most cloud instances. To explicitly prevent cloud-initramfs-tools from running growroot, the file /etc/growroot-disabled can be created. By default, both growroot and cc_growpart will check for the existence of this file and will not run if it is present. However, this file can be ignored for cc_growpart by setting ignore_growroot_disabled to true. For more information on cloud-initramfs-tools see: https://launchpad.net/cloud-initramfs-tools

Growpart is enabled by default on the root partition. The default config for growpart is:

growpart:
    mode: auto
    devices: ["/"]
    ignore_growroot_disabled: false

Internal name: cc_growpart

Module frequency: per always

Supported distros: all

Config keys:

growpart:
    mode: <auto/growpart/off/false>
    devices:
        - "/"
        - "/dev/vdb1"
    ignore_growroot_disabled: <true/false>

Grub Dpkg ¶

Summary: configure grub debconf installation device

Configure which device is used as the target for grub installation. This module should work correctly by default without any user configuration. It can be enabled/disabled using the enabled config key in the grub_dpkg config dict. The global config key grub-dpkg is an alias for grub_dpkg. If no installation device is specified this module will execute grub-probe to determine which disk the /boot directory is associated with.

The value which is placed into the debconf database is in the format which the grub postinstall script expects. Normally, this is a /dev/disk/by-id/ value, but we do fallback to the plain disk name if a by-id name is not present.

If this module is executed inside a container, then the debconf database is seeded with empty values, and install_devices_empty is set to true.

Internal name: cc_grub_dpkg

Module frequency: per instance

Supported distros: ubuntu, debian

Config keys:

grub_dpkg:
    enabled: <true/false>
    grub-pc/install_devices: <devices>
    grub-pc/install_devices_empty: <devices>
grub-dpkg: (alias for grub_dpkg)

Keys to Console ¶

Summary: control which SSH host keys may be written to console

For security reasons it may be desirable not to write SSH host keys and their fingerprints to the console. To avoid either being written to the console the emit_keys_to_console config key under the main ssh config key can be used. To avoid the fingerprint of types of SSH host keys being written to console the ssh_fp_console_blacklist config key can be used. By default all types of keys will have their fingerprints written to console. To avoid host keys of a key type being written to console the ssh_key_console_blacklist config key can be used. By default ssh-dss host keys are not written to console.

Internal name: cc_keys_to_console

Module frequency: per instance

Supported distros: all

Config keys:

ssh:
  emit_keys_to_console: false

ssh_fp_console_blacklist: <list of key types>
ssh_key_console_blacklist: <list of key types>

Landscape ¶

Summary: install and configure landscape client

This module installs and configures landscape-client. The landscape client will only be installed if the key landscape is present in config. Landscape client configuration is given under the client key under the main landscape config key. The config parameters are not interpreted by cloud-init, but rather are converted into a ConfigObj formatted file and written out to /etc/landscape/client.conf.

The following default client config is provided, but can be overridden:

landscape:
    client:
        log_level: "info"
        url: "https://landscape.canonical.com/message-system"
        ping_url: "http://landscape.canoncial.com/ping"
        data_path: "/var/lib/landscape/client"

Note

see landscape documentation for client config keys

Note

if tags is defined, its contents should be a string delimited with , rather than a list

Internal name: cc_landscape

Module frequency: per instance

Supported distros: ubuntu

Config keys:

landscape:
    client:
        url: "https://landscape.canonical.com/message-system"
        ping_url: "http://landscape.canonical.com/ping"
        data_path: "/var/lib/landscape/client"
        http_proxy: "http://my.proxy.com/foobar"
        https_proxy: "https://my.proxy.com/foobar"
        tags: "server,cloud"
        computer_title: "footitle"
        registration_key: "fookey"
        account_name: "fooaccount"

Locale ¶

Summary: Set system locale

Configure the system locale and apply it system wide. By default use the locale specified by the datasource.

Internal name: cc_locale

Module frequency: once-per-instance

Supported distros: all

Config schema:

locale: (string) The locale to set as the system’s locale (e.g. ar_PS)

locale_configfile: (string) The file in which to write the locale configuration (defaults to the distro’s default location)

Examples:

# Set the locale to ar_AE
locale: ar_AE

# --- Example2 ---
# Set the locale to fr_CA in /etc/alternate_path/locale
locale: fr_CA
locale_configfile: /etc/alternate_path/locale

LXD ¶

Summary: configure lxd with lxd init and optionally lxd-bridge

This module configures lxd with user specified options using lxd init. If lxd is not present on the system but lxd configuration is provided, then lxd will be installed. If the selected storage backend is zfs, then zfs will be installed if missing. If network bridge configuration is provided, then lxd-bridge will be configured accordingly.

Internal name: cc_lxd

Module frequency: per instance

Supported distros: ubuntu

Config keys:

lxd:
    init:
        network_address: <ip addr>
        network_port: <port>
        storage_backend: <zfs/dir>
        storage_create_device: <dev>
        storage_create_loop: <size>
        storage_pool: <name>
        trust_password: <password>
    bridge:
        mode: <new, existing or none>
        name: <name>
        ipv4_address: <ip addr>
        ipv4_netmask: <cidr>
        ipv4_dhcp_first: <ip addr>
        ipv4_dhcp_last: <ip addr>
        ipv4_dhcp_leases: <size>
        ipv4_nat: <bool>
        ipv6_address: <ip addr>
        ipv6_netmask: <cidr>
        ipv6_nat: <bool>
        domain: <domain>

Mcollective ¶

Summary: install, configure and start mcollective

This module installs, configures and starts mcollective. If the mcollective key is present in config, then mcollective will be installed and started.

Configuration for mcollective can be specified in the conf key under mcollective. Each config value consists of a key value pair and will be written to /etc/mcollective/server.cfg. The public-cert and private-cert keys, if present in conf may be used to specify the public and private certificates for mcollective. Their values will be written to /etc/mcollective/ssl/server-public.pem and /etc/mcollective/ssl/server-private.pem.

Note

The ec2 metadata service is readable by non-root users. If security is a concern, use include-once and ssl urls.

Internal name: cc_mcollective

Module frequency: per instance

Supported distros: all

Config keys:

mcollective:
    conf:
        <key>: <value>
        public-cert: |
            -------BEGIN CERTIFICATE--------
            <cert data>
            -------END CERTIFICATE--------
        private-cert: |
            -------BEGIN CERTIFICATE--------
            <cert data>
            -------END CERTIFICATE--------

Migrator ¶

Summary: migrate old versions of cloud-init data to new

This module handles moving old versions of cloud-init data to newer ones. Currently, it only handles renaming cloud-init’s per-frequency semaphore files to canonicalized name and renaming legacy semaphore names to newer ones. This module is enabled by default, but can be disabled by specifying migrate: false in config.

Internal name: cc_migrator

Module frequency: per always

Supported distros: all

Config keys:

migrate: <true/false>

Mounts ¶

Summary: configure mount points and swap files

This module can add or remove mountpoints from /etc/fstab as well as configure swap. The mounts config key takes a list of fstab entries to add. Each entry is specified as a list of [ fs_spec, fs_file, fs_vfstype, fs_mntops, fs-freq, fs_passno ]. For more information on these options, consult the manual for /etc/fstab. When specifying the fs_spec, if the device name starts with one of xvd, sd, hd, or vd, the leading /dev may be omitted.

In order to remove a previously listed mount, an entry can be added to the mounts list containing fs_spec for the device to be removed but no mountpoint (i.e. [ sda1 ] or [ sda1, null ]).

The mount_default_fields config key allows default options to be specified for the values in a mounts entry that are not specified, aside from the fs_spec and the fs_file. If specified, this must be a list containing 6 values. It defaults to:

mount_default_fields: [none, none, "auto", "defaults,nobootwait", "0", "2"]

On a systemd booted system that default is the mostly equivalent:

mount_default_fields: [none, none, "auto",
   "defaults,nofail,x-systemd.requires=cloud-init.service", "0", "2"]

Note that nobootwait is an upstart specific boot option that somewhat equates to the more standard nofail.

Swap files can be configured by setting the path to the swap file to create with filename, the size of the swap file with size maximum size of the swap file if using an size: auto with maxsize. By default no swap file is created.

Internal name: cc_mounts

Module frequency: per instance

Supported distros: all

Config keys:

mounts:
    - [ /dev/ephemeral0, /mnt, auto, "defaults,noexec" ]
    - [ sdc, /opt/data ]
    - [ xvdh, /opt/data, "auto", "defaults,nofail", "0", "0" ]
mount_default_fields: [None, None, "auto", "defaults,nofail", "0", "2"]
swap:
    filename: <file>
    size: <"auto"/size in bytes>
    maxsize: <size in bytes>

NTP ¶

Summary: enable and configure ntp

Handle ntp configuration. If ntp is not installed on the system and ntp configuration is specified, ntp will be installed. If there is a default ntp config file in the image or one is present in the distro’s ntp package, it will be copied to a file with .dist appended to the filename before any changes are made. A list of ntp pools and ntp servers can be provided under the ntp config key. If no ntp servers or pools are provided, 4 pools will be used in the format {0-3}.{distro}.pool.ntp.org.

Internal name: cc_ntp

Module frequency: once-per-instance

Supported distros: almalinux, alpine, centos, debian, eurolinux, fedora, opensuse, photon, rhel, rocky, sles, ubuntu, virtuozzo

Config schema:: ntp: (object/null)

pools: (array of string) List of ntp pools. If both pools and servers are empty, 4 default pool servers will be provided of the format {0-3}.{distro}.pool.ntp.org. NOTE: for Alpine Linux when using the Busybox NTP client this setting will be ignored due to the limited functionality of Busybox’s ntpd.

servers: (array of string) List of ntp servers. If both pools and servers are empty, 4 default pool servers will be provided with the format {0-3}.{distro}.pool.ntp.org.

ntp_client: (string) Name of an NTP client to use to configure system NTP. When unprovided or ‘auto’ the default client preferred by the distribution will be used. The following built-in client names can be used to override existing configuration defaults: chrony, ntp, ntpdate, systemd-timesyncd.

enabled: (boolean) Attempt to enable ntp clients if set to True. If set to False, ntp client will not be configured or installed

config: (object) Configuration settings or overrides for the ntp_client specified.

confpath: (string) The path to where the ntp_client configuration is written.

check_exe: (string) The executable name for the ntp_client. For example, ntp service check_exe is ‘ntpd’ because it runs the ntpd binary.

packages: (array of string) List of packages needed to be installed for the selected ntp_client.

service_name: (string) The systemd or sysvinit service name used to start and stop the ntp_client service.

template: (string) Inline template allowing users to define their own ntp_client configuration template. The value must start with ‘## template:jinja’ to enable use of templating support.

Examples:

# Override ntp with chrony configuration on Ubuntu
ntp:
  enabled: true
  ntp_client: chrony  # Uses cloud-init default chrony configuration

# --- Example2 ---
# Provide a custom ntp client configuration
ntp:
  enabled: true
  ntp_client: myntpclient
  config:
     confpath: /etc/myntpclient/myntpclient.conf
     check_exe: myntpclientd
     packages:
       - myntpclient
     service_name: myntpclient
     template: |
         ## template:jinja
         # My NTP Client config
         {% if pools -%}# pools{% endif %}
         {% for pool in pools -%}
         pool {{pool}} iburst
         {% endfor %}
         {%- if servers %}# servers
         {% endif %}
         {% for server in servers -%}
         server {{server}} iburst
         {% endfor %}
  pools: [0.int.pool.ntp.org, 1.int.pool.ntp.org, ntp.myorg.org]
  servers:
    - ntp.server.local
    - ntp.ubuntu.com
    - 192.168.23.2

Package Update Upgrade Install ¶

Summary: update, upgrade, and install packages

This module allows packages to be updated, upgraded or installed during boot. If any packages are to be installed or an upgrade is to be performed then the package cache will be updated first. If a package installation or upgrade requires a reboot, then a reboot can be performed if package_reboot_if_required is specified. A list of packages to install can be provided. Each entry in the list can be either a package name or a list with two entries, the first being the package name and the second being the specific package version to install.

Internal name: cc_package_update_upgrade_install

Module frequency: per instance

Supported distros: all

Config keys:

packages:
    - pwgen
    - pastebinit
    - [libpython2.7, 2.7.3-0ubuntu3.1]
package_update: <true/false>
package_upgrade: <true/false>
package_reboot_if_required: <true/false>

apt_update: (alias for package_update)
apt_upgrade: (alias for package_upgrade)
apt_reboot_if_required: (alias for package_reboot_if_required)

Phone Home ¶

Summary: post data to url

This module can be used to post data to a remote host after boot is complete. If the post url contains the string $INSTANCE_ID it will be replaced with the id of the current instance. Either all data can be posted or a list of keys to post. Available keys are:

pub_key_dsa

pub_key_rsa

pub_key_ecdsa

pub_key_ed25519

instance_id

hostname

fdqn

Internal name: cc_phone_home

Module frequency: per instance

Supported distros: all

Config keys:

phone_home:
    url: http://example.com/$INSTANCE_ID/
    post:
        - pub_key_dsa
        - instance_id
        - fqdn
    tries: 10

Power State Change ¶

Summary: change power state

This module handles shutdown/reboot after all config modules have been run. By default it will take no action, and the system will keep running unless a package installation/upgrade requires a system reboot (e.g. installing a new kernel) and package_reboot_if_required is true. The power_state config key accepts a dict of options. If mode is any value other than poweroff, halt, or reboot, then no action will be taken.

The system can be shutdown before cloud-init has finished using the timeout option. The delay key specifies a duration to be added onto any shutdown command used. Therefore, if a 5 minute delay and a 120 second shutdown are specified, the maximum amount of time between cloud-init starting and the system shutting down is 7 minutes, and the minimum amount of time is 5 minutes. The delay key must have an argument in either the form '+5' for 5 minutes or now for immediate shutdown.

Optionally, a command can be run to determine whether or not the system should shut down. The command to be run should be specified in the condition key. For command formatting, see the documentation for cc_runcmd. The specified shutdown behavior will only take place if the condition key is omitted or the command specified by the condition key returns 0.

Note

With Alpine Linux any message value specified is ignored as Alpine’s halt, poweroff, and reboot commands do not support broadcasting a message.

Internal name: cc_power_state_change

Module frequency: per instance

Supported distros: all

Config keys:

power_state:
    delay: <now/'+minutes'>
    mode: <poweroff/halt/reboot>
    message: <shutdown message>
    timeout: <seconds>
    condition: <true/false/command>

Puppet ¶

Summary: install, configure and start puppet

This module handles puppet installation and configuration. If the puppet key does not exist in global configuration, no action will be taken. If a config entry for puppet is present, then by default the latest version of puppet will be installed. If install is set to false, puppet will not be installed. However, this will result in an error if puppet is not already present on the system. The version of puppet to be installed can be specified under version, and defaults to none, which selects the latest version in the repos. If the puppet config key exists in the config archive, this module will attempt to start puppet even if no installation was performed.

The module also provides keys for configuring the new puppet 4 paths and installing the puppet package from the puppetlabs repositories: https://docs.puppet.com/puppet/4.2/reference/whered_it_go.html The keys are package_name, conf_file, ssl_dir and csr_attributes_path. If unset, their values will default to ones that work with puppet 3.x and with distributions that ship modified puppet 4.x that uses the old paths.

Agent packages from the puppetlabs repositories can be installed by setting install_type to aio. Based on this setting, the default config/SSL/CSR paths will be adjusted accordingly. To maintain backwards compatibility this setting defaults to packages which will install puppet from the distro packages.

If installing aio packages, collection can also be set to one of puppet (rolling release), puppet6, puppet7 (or their nightly counterparts) in order to install specific release streams. By default, the puppetlabs repository will be purged after installation finishes; set cleanup to false to prevent this. AIO packages are installed through a shell script which is downloaded on the machine and then executed; the path to this script can be overridden using the aio_install_url key.

Puppet configuration can be specified under the conf key. The configuration is specified as a dictionary containing high-level <section> keys and lists of <key>=<value> pairs within each section. Each section name and <key>=<value> pair is written directly to puppet.conf. As such, section names should be one of: main, server, agent or user and keys should be valid puppet configuration options. The certname key supports string substitutions for %i and %f, corresponding to the instance id and fqdn of the machine respectively. If ca_cert is present, it will not be written to puppet.conf, but instead will be used as the puppetserver certificate. It should be specified in pem format as a multi-line string (using the | yaml notation).

Additionally it’s possible to create a csr_attributes.yaml file for CSR attributes and certificate extension requests. See https://puppet.com/docs/puppet/latest/config_file_csr_attributes.html

The puppet service will be automatically enabled after installation. A manual run can also be triggered by setting exec to true, and additional arguments can be passed to puppet agent via the exec_args key (by default the agent will execute with the --test flag).

Internal name: cc_puppet

Module frequency: per instance

Supported distros: all

Config keys:

puppet:
    install: <true/false>
    version: <version>
    collection: <aio collection>
    install_type: <packages/aio>
    aio_install_url: 'https://git.io/JBhoQ'
    cleanup: <true/false>
    conf_file: '/etc/puppet/puppet.conf'
    ssl_dir: '/var/lib/puppet/ssl'
    csr_attributes_path: '/etc/puppet/csr_attributes.yaml'
    package_name: 'puppet'
    exec: <true/false>
    exec_args: ['--test']
    conf:
        agent:
            server: "puppetserver.example.org"
            certname: "%i.%f"
            ca_cert: |
                -------BEGIN CERTIFICATE-------
                <cert data>
                -------END CERTIFICATE-------
    csr_attributes:
        custom_attributes:
            1.2.840.113549.1.9.7: 342thbjkt82094y0uthhor289jnqthpc2290
        extension_requests:
            pp_uuid: ED803750-E3C7-44F5-BB08-41A04433FE2E
            pp_image_name: my_ami_image
            pp_preshared_key: 342thbjkt82094y0uthhor289jnqthpc2290

Resizefs ¶

Summary: Resize filesystem

Resize a filesystem to use all avaliable space on partition. This module is useful along with cc_growpart and will ensure that if the root partition has been resized the root filesystem will be resized along with it. By default, cc_resizefs will resize the root partition and will block the boot process while the resize command is running. Optionally, the resize operation can be performed in the background while cloud-init continues running modules. This can be enabled by setting resize_rootfs to true. This module can be disabled altogether by setting resize_rootfs to false.

Internal name: cc_resizefs

Module frequency: always

Supported distros: all

Config schema:: resize_rootfs: (true/false/noblock) Whether to resize the root partition. Default: ‘true’

Examples:

resize_rootfs: false  # disable root filesystem resize operation

Resolv Conf ¶

Summary: configure resolv.conf

This module is intended to manage resolv.conf in environments where early configuration of resolv.conf is necessary for further bootstrapping and/or where configuration management such as puppet or chef own dns configuration. As Debian/Ubuntu will, by default, utilize resolvconf, and similarly Red Hat will use sysconfig, this module is likely to be of little use unless those are configured correctly.

Note

For Red Hat with sysconfig, be sure to set PEERDNS=no for all DHCP enabled NICs.

Note

And, in Ubuntu/Debian it is recommended that DNS be configured via the standard /etc/network/interfaces configuration file.

Internal name: cc_resolv_conf

Module frequency: per instance

Supported distros: alpine, fedora, photon, rhel, sles

Config keys:

manage_resolv_conf: <true/false>
resolv_conf:
    nameservers: ['8.8.4.4', '8.8.8.8']
    searchdomains:
        - foo.example.com
        - bar.example.com
    domain: example.com
    options:
        rotate: <true/false>
        timeout: 1

Red Hat Subscription ¶

Summary: register red hat enterprise linux based system

Register a Red Hat system either by username and password or activation and org. Following a sucessful registration, you can auto-attach subscriptions, set the service level, add subscriptions based on pool id, enable/disable yum repositories based on repo id, and alter the rhsm_baseurl and server-hostname in /etc/rhsm/rhs.conf. For more details, see the Register Red Hat Subscription example config.

Internal name: cc_rh_subscription

Module frequency: per instance

Supported distros: rhel, fedora

Config keys:

rh_subscription:
    username: <username>
    password: <password>
    activation-key: <activation key>
    org: <org number>
    auto-attach: <true/false>
    service-level: <service level>
    add-pool: <list of pool ids>
    enable-repo: <list of yum repo ids>
    disable-repo: <list of yum repo ids>
    rhsm-baseurl: <url>
    server-hostname: <hostname>

Rightscale Userdata ¶

Summary: support rightscale configuration hooks

This module adds support for RightScale configuration hooks to cloud-init. RightScale adds a entry in the format CLOUD_INIT_REMOTE_HOOK=http://... to ec2 user-data. This module checks for this line in the raw userdata and retrieves any scripts linked by the RightScale user data and places them in the user scripts configuration directory, to be run later by cc_scripts_user.

Note

the CLOUD_INIT_REMOTE_HOOK config variable is present in the raw ec2 user data only, not in any cloud-config parts

Internal name: cc_rightscale_userdata

Module frequency: per instance

Supported distros: all

Config keys:

CLOUD_INIT_REMOTE_HOOK=<url>

Rsyslog ¶

Summary: configure system loggig via rsyslog

This module configures remote system logging using rsyslog.

The rsyslog config file to write to can be specified in config_filename, which defaults to 20-cloud-config.conf. The rsyslog config directory to write config files to may be specified in config_dir, which defaults to /etc/rsyslog.d.

A list of configurations for rsyslog can be specified under the configs key in the rsyslog config. Each entry in configs is either a string or a dictionary. Each config entry contains a configuration string and a file to write it to. For config entries that are a dictionary, filename sets the target filename and content specifies the config string to write. For config entries that are only a string, the string is used as the config string to write. If the filename to write the config to is not specified, the value of the config_filename key is used. A file with the selected filename will be written inside the directory specified by config_dir.

The command to use to reload the rsyslog service after the config has been updated can be specified in service_reload_command. If this is set to auto, then an appropriate command for the distro will be used. This is the default behavior. To manually set the command, use a list of command args (e.g. [systemctl, restart, rsyslog]).

Configuration for remote servers can be specified in configs, but for convenience it can be specified as key value pairs in remotes. Each key is the name for an rsyslog remote entry. Each value holds the contents of the remote config for rsyslog. The config consists of the following parts:

filter for log messages (defaults to *.*)

optional leading @ or @@, indicating udp and tcp respectively (defaults to @, for udp)

ipv4 or ipv6 hostname or address. ipv6 addresses must be in [::1] format, (e.g. @[fd00::1]:514)

optional port number (defaults to 514)

This module will provide sane defaults for any part of the remote entry that is not specified, so in most cases remote hosts can be specified just using <name>: <address>.

For backwards compatibility, this module still supports legacy names for the config entries. Legacy to new mappings are as follows:

rsyslog -> rsyslog/configs

rsyslog_filename -> rsyslog/config_filename

rsyslog_dir -> rsyslog/config_dir

Note

The legacy config format does not support specifying service_reload_command.

Internal name: cc_rsyslog

Module frequency: per instance

Supported distros: all

Config keys:

rsyslog:
    config_dir: config_dir
    config_filename: config_filename
    configs:
        - "*.* @@192.158.1.1"
        - content: "*.*   @@192.0.2.1:10514"
          filename: 01-example.conf
        - content: |
            *.*   @@syslogd.example.com
    remotes:
        maas: "192.168.1.1"
        juju: "10.0.4.1"
    service_reload_command: [your, syslog, restart, command]

Legacy config keys:

rsyslog:
    - "*.* @@192.158.1.1"
rsyslog_dir: /etc/rsyslog-config.d/
rsyslog_filename: 99-local.conf

Runcmd ¶

Summary: Run arbitrary commands

Run arbitrary commands at a rc.local like level with output to the console. Each item can be either a list or a string. If the item is a list, it will be properly executed as if passed to execve() (with the first arg as the command). If the item is a string, it will be written to a file and interpreted using sh.

Note

all commands must be proper yaml, so you have to quote any characters yaml would eat (‘:’ can be problematic)

Note

when writing files, do not use /tmp dir as it races with systemd-tmpfiles-clean LP: #1707222. Use /run/somedir instead.

Internal name: cc_runcmd

Module frequency: once-per-instance

Supported distros: all

Config schema:: runcmd: (array of (array of string)/(string))

Examples:

runcmd:
    - [ ls, -l, / ]
    - [ sh, -xc, "echo $(date) ': hello world!'" ]
    - [ sh, -c, echo "=========hello world'=========" ]
    - ls -l /root
    - [ wget, "http://example.org", -O, /tmp/index.html ]

Salt Minion ¶

Summary: set up and run salt minion

This module installs, configures and starts salt minion. If the salt_minion key is present in the config parts, then salt minion will be installed and started. Configuration for salt minion can be specified in the conf key under salt_minion. Any conf values present there will be assigned in /etc/salt/minion. The public and private keys to use for salt minion can be specified with public_key and private_key respectively. Optionally if you have a custom package name, service name or config directory you can specify them with pkg_name, service_name and config_dir.

Internal name: cc_salt_minion

Module frequency: per instance

Supported distros: all

Config keys:

salt_minion:
    pkg_name: 'salt-minion'
    service_name: 'salt-minion'
    config_dir: '/etc/salt'
    conf:
        master: salt.example.com
    grains:
        role:
            - web
    public_key: |
        ------BEGIN PUBLIC KEY-------
        <key data>
        ------END PUBLIC KEY-------
    private_key: |
        ------BEGIN PRIVATE KEY------
        <key data>
        ------END PRIVATE KEY-------

Scripts Per Boot ¶

Summary: run per boot scripts

Any scripts in the scripts/per-boot directory on the datasource will be run every time the system boots. Scripts will be run in alphabetical order. This module does not accept any config keys.

Internal name: cc_scripts_per_boot

Module frequency: per always

Supported distros: all

Scripts Per Instance ¶

Summary: run per instance scripts

Any scripts in the scripts/per-instance directory on the datasource will be run when a new instance is first booted. Scripts will be run in alphabetical order. This module does not accept any config keys.

Some cloud platforms change instance-id if a significant change was made to the system. As a result per-instance scripts will run again.

Internal name: cc_scripts_per_instance

Module frequency: per instance

Supported distros: all

Scripts Per Once ¶

Summary: run one time scripts

Any scripts in the scripts/per-once directory on the datasource will be run only once. Changes to the instance will not force a re-run. The only way to re-run these scripts is to run the clean subcommand and reboot. Scripts will be run in alphabetical order. This module does not accept any config keys.

Internal name: cc_scripts_per_once

Module frequency: per once

Supported distros: all

Scripts User ¶

Summary: run user scripts

This module runs all user scripts. User scripts are not specified in the scripts directory in the datasource, but rather are present in the scripts dir in the instance configuration. Any cloud-config parts with a #! will be treated as a script and run. Scripts specified as cloud-config parts will be run in the order they are specified in the configuration. This module does not accept any config keys.

Internal name: cc_scripts_user

Module frequency: per instance

Supported distros: all

Scripts Vendor ¶

Summary: run vendor scripts

Any scripts in the scripts/vendor directory in the datasource will be run when a new instance is first booted. Scripts will be run in alphabetical order. Vendor scripts can be run with an optional prefix specified in the prefix entry under the vendor_data config key.

Internal name: cc_scripts_vendor

Module frequency: per instance

Supported distros: all

Config keys:

vendor_data:
    prefix: <vendor data prefix>

Seed Random ¶

Summary: provide random seed data

Since all cloud instances started from the same image will produce very similar data when they are first booted, as they are all starting with the same seed for the kernel’s entropy keyring. To avoid this, random seed data can be provided to the instance either as a string or by specifying a command to run to generate the data.

Configuration for this module is under the random_seed config key. The file key specifies the path to write the data to, defaulting to /dev/urandom. Data can be passed in directly with data, and may optionally be specified in encoded form, with the encoding specified in encoding.

If the cloud provides its own random seed data, it will be appended to data before it is written to file.

Note

when using a multiline value for data or specifying binary data, be sure to follow yaml syntax and use the | and !binary yaml format specifiers when appropriate

If the command key is specified, the given command will be executed. This will happen after file has been populated. That command’s environment will contain the value of the file key as RANDOM_SEED_FILE. If a command is specified that cannot be run, no error will be reported unless command_required is set to true.

For example, to use pollinate to gather data from a remote entropy server and write it to /dev/urandom, the following could be used:

random_seed:
    file: /dev/urandom
    command: ["pollinate", "--server=http://local.polinate.server"]
    command_required: true

Internal name: cc_seed_random

Module frequency: per instance

Supported distros: all

Config keys:

random_seed:
    file: <file>
    data: <random string>
    encoding: <raw/base64/b64/gzip/gz>
    command: [<cmd name>, <arg1>, <arg2>...]
    command_required: <true/false>

Set Hostname ¶

Summary: set hostname and fqdn

This module handles setting the system hostname and fqdn. If preserve_hostname is set, then the hostname will not be altered.

A hostname and fqdn can be provided by specifying a full domain name under the fqdn key. Alternatively, a hostname can be specified using the hostname key, and the fqdn of the cloud wil be used. If a fqdn specified with the hostname key, it will be handled properly, although it is better to use the fqdn config key. If both fqdn and hostname are set, it is distro dependent whether hostname or fqdn is used, unless the prefer_fqdn_over_hostname option is true and fqdn is set it will force the use of FQDN in all distros, and if false then it will force the hostname use.

This module will run in the init-local stage before networking is configured if the hostname is set by metadata or user data on the local system.

This will occur on datasources like nocloud and ovf where metadata and user data are available locally. This ensures that the desired hostname is applied before any DHCP requests are preformed on these platforms where dynamic DNS is based on initial hostname.

Internal name: cc_set_hostname

Module frequency: per always

Supported distros: all

Config keys:

preserve_hostname: <true/false>
prefer_fqdn_over_hostname: <true/false>
fqdn: <fqdn>
hostname: <fqdn/hostname>

Set Passwords ¶

Summary: Set user passwords and enable/disable SSH password authentication

This module consumes three top-level config keys: ssh_pwauth, chpasswd and password.

The ssh_pwauth config key determines whether or not sshd will be configured to accept password authentication. True values will enable password auth, false values will disable password auth, and the literal string unchanged will leave it unchanged. Setting no value will also leave the current setting on-disk unchanged.

The chpasswd config key accepts a dictionary containing either or both of expire and list.

If the list key is provided, it should contain a list of username:password pairs. This can be either a YAML list (of strings), or a multi-line string with one pair per line. Each user will have the corresponding password set. A password can be randomly generated by specifying RANDOM or R as a user’s password. A hashed password, created by a tool like mkpasswd, can be specified; a regex (r'\$(1|2a|2y|5|6)(\$.+){2}') is used to determine if a password value should be treated as a hash.

Note

The users specified must already exist on the system. Users will have been created by the cc_users_groups module at this point.

By default, all users on the system will have their passwords expired (meaning that they will have to be reset the next time the user logs in). To disable this behaviour, set expire under chpasswd to a false value.

If a list of user/password pairs is not specified under chpasswd, then the value of the password config key will be used to set the default user’s password.

Internal name: cc_set_passwords

Module frequency: per instance

Supported distros: all

Config keys:

ssh_pwauth: <yes/no/unchanged>

password: password1
chpasswd:
    expire: <true/false>

chpasswd:
    list: |
        user1:password1
        user2:RANDOM
        user3:password3
        user4:R

##
# or as yaml list
##
chpasswd:
    list:
        - user1:password1
        - user2:RANDOM
        - user3:password3
        - user4:R
        - user4:$6$rL..$ej...

Snap ¶

Summary: Install, configure and manage snapd and snap packages

This module provides a simple configuration namespace in cloud-init to both setup snapd and install snaps.

Note

Both assertions and commands values can be either a dictionary or a list. If these configs are provided as a dictionary, the keys are only used to order the execution of the assertions or commands and the dictionary is merged with any vendor-data snap configuration provided. If a list is provided by the user instead of a dict, any vendor-data snap configuration is ignored.

The assertions configuration option is a dictionary or list of properly-signed snap assertions which will run before any snap commands. They will be added to snapd’s assertion database by invoking snap ack <aggregate_assertion_file>.

Snap commands is a dictionary or list of individual snap commands to run on the target system. These commands can be used to create snap users, install snaps and provide snap configuration.

Note

If ‘side-loading’ private/unpublished snaps on an instance, it is best to create a snap seed directory and seed.yaml manifest in /var/lib/snapd/seed/ which snapd automatically installs on startup.

Development only: The squashfuse_in_container boolean can be set true to install squashfuse package when in a container to enable snap installs. Default is false.

Internal name: cc_snap

Module frequency: once-per-instance

Supported distros: ubuntu

Config schema:: snap: (object)

assertions: (object/array of string)

commands: (object/array of (array of string)/(string))

squashfuse_in_container: (boolean)

Examples:

snap:
    assertions:
      00: |
        signed_assertion_blob_here
      02: |
        signed_assertion_blob_here
    commands:
      00: snap create-user --sudoer --known <snap-user>@mydomain.com
      01: snap install canonical-livepatch
      02: canonical-livepatch enable <AUTH_TOKEN>

# --- Example2 ---
# LXC-based containers require squashfuse before snaps can be installed
snap:
    commands:
        00: apt-get install squashfuse -y
        11: snap install emoj


# --- Example3 ---
# Convenience: the snap command can be omitted when specifying commands
# as a list and 'snap' will automatically be prepended.
# The following commands are equivalent:
snap:
    commands:
        00: ['install', 'vlc']
        01: ['snap', 'install', 'vlc']
        02: snap install vlc
        03: 'snap install vlc'

# --- Example4 ---
# You can use a list of commands
snap:
    commands:
        - ['install', 'vlc']
        - ['snap', 'install', 'vlc']
        - snap install vlc
        - 'snap install vlc'

# --- Example5 ---
# You can use a list of assertions
snap:
    assertions:
        - signed_assertion_blob_here
        - |
            signed_assertion_blob_here

Spacewalk ¶

Summary: install and configure spacewalk

This module installs spacewalk and applies basic configuration. If the spacewalk config key is present spacewalk will be installed. The server to connect to after installation must be provided in the server in spacewalk configuration. A proxy to connect through and a activation key may optionally be specified.

For more information about spacewalk see: https://fedorahosted.org/spacewalk/

Internal name: cc_spacewalk

Module frequency: per instance

Supported distros: redhat, fedora

Config keys:

spacewalk:
   server: <url>
   proxy: <proxy host>
   activation_key: <key>

SSH ¶

Summary: configure SSH and SSH keys (host and authorized)

This module handles most configuration for SSH and both host and authorized SSH keys.

Authorized Keys ¶

Authorized keys are a list of public SSH keys that are allowed to connect to a a user account on a system. They are stored in .ssh/authorized_keys in that account’s home directory. Authorized keys for the default user defined in users can be specified using ssh_authorized_keys. Keys should be specified as a list of public keys.

Note

see the cc_set_passwords module documentation to enable/disable SSH password authentication

Root login can be enabled/disabled using the disable_root config key. Root login options can be manually specified with disable_root_opts. If disable_root_opts is specified and contains the string $USER, it will be replaced with the username of the default user. By default, root login is disabled, and root login opts are set to:

no-port-forwarding,no-agent-forwarding,no-X11-forwarding

Supported public key types for the ssh_authorized_keys are:

dsa

rsa

ecdsa

ed25519

ecdsa-sha2-nistp256-cert-v01@openssh.com

ecdsa-sha2-nistp256

ecdsa-sha2-nistp384-cert-v01@openssh.com

ecdsa-sha2-nistp384

ecdsa-sha2-nistp521-cert-v01@openssh.com

ecdsa-sha2-nistp521

sk-ecdsa-sha2-nistp256-cert-v01@openssh.com

sk-ecdsa-sha2-nistp256@openssh.com

sk-ssh-ed25519-cert-v01@openssh.com

sk-ssh-ed25519@openssh.com

ssh-dss-cert-v01@openssh.com

ssh-dss

ssh-ed25519-cert-v01@openssh.com

ssh-ed25519

ssh-rsa-cert-v01@openssh.com

ssh-rsa

ssh-xmss-cert-v01@openssh.com

ssh-xmss@openssh.com

Note

this list has been filtered out from the supported keytypes of OpenSSH source, where the sigonly keys are removed. Please see ssh_util for more information.

dsa, rsa, ecdsa and ed25519 are added for legacy, as they are valid public keys in some old distros. They can possibly be removed in the future when support for the older distros are dropped

Host Keys ¶

Host keys are for authenticating a specific instance. Many images have default host SSH keys, which can be removed using ssh_deletekeys. This prevents re-use of a private host key from an image on multiple machines. Since removing default host keys is usually the desired behavior this option is enabled by default.

Host keys can be added using the ssh_keys configuration key. The argument to this config key should be a dictionary entries for the public and private keys of each desired key type. Entries in the ssh_keys config dict should have keys in the format <key type>_private, <key type>_public, and, optionally, <key type>_certificate, e.g. rsa_private: <key>, rsa_public: <key>, and rsa_certificate: <key>. See below for supported key types. Not all key types have to be specified, ones left unspecified will not be used. If this config option is used, then no keys will be generated.

Note

when specifying private host keys in cloud-config, care should be taken to ensure that the communication between the data source and the instance is secure

Note

to specify multiline private host keys and certificates, use yaml multiline syntax

If no host keys are specified using ssh_keys, then keys will be generated using ssh-keygen. By default one public/private pair of each supported host key type will be generated. The key types to generate can be specified using the ssh_genkeytypes config flag, which accepts a list of host key types to use. For each host key type for which this module has been instructed to create a keypair, if a key of the same type is already present on the system (i.e. if ssh_deletekeys was false), no key will be generated.

Supported host key types for the ssh_keys and the ssh_genkeytypes config flags are:

rsa

dsa

ecdsa

ed25519

Internal name: cc_ssh

Module frequency: per instance

Supported distros: all

Config keys:

ssh_deletekeys: <true/false>
ssh_keys:
    rsa_private: |
        -----BEGIN RSA PRIVATE KEY-----
        MIIBxwIBAAJhAKD0YSHy73nUgysO13XsJmd4fHiFyQ+00R7VVu2iV9Qco
        ...
        -----END RSA PRIVATE KEY-----
    rsa_public: ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAGEAoPRhIfLvedSDKw7Xd ...
    rsa_certificate: |
        [email protected] AAAAIHNzaC1lZDI1NTE5LWNlcnQt ...
    dsa_private: |
        -----BEGIN DSA PRIVATE KEY-----
        MIIBxwIBAAJhAKD0YSHy73nUgysO13XsJmd4fHiFyQ+00R7VVu2iV9Qco
        ...
        -----END DSA PRIVATE KEY-----
    dsa_public: ssh-dsa AAAAB3NzaC1yc2EAAAABIwAAAGEAoPRhIfLvedSDKw7Xd ...
    dsa_certificate: |
        [email protected] AAAAIHNzaC1lZDI1NTE5LWNlcnQt ...

ssh_genkeytypes: <key type>
disable_root: <true/false>
disable_root_opts: <disable root options string>
ssh_authorized_keys:
    - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAGEA3FSyQwBI6Z+nCSjUU ...
    - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA3I7VUf2l5gSn5uavROsc5HRDpZ ...
allow_public_ssh_keys: <true/false>
ssh_publish_hostkeys:
    enabled: <true/false> (Defaults to true)
    blacklist: <list of key types> (Defaults to [dsa])

SSH Authkey Fingerprints ¶

Summary: log fingerprints of user SSH keys

Write fingerprints of authorized keys for each user to log. This is enabled by default, but can be disabled using no_ssh_fingerprints. The hash type for the keys can be specified, but defaults to sha256.

Internal name: cc_ssh_authkey_fingerprints

Module frequency: per instance

Supported distros: all

Config keys:

no_ssh_fingerprints: <true/false>
authkey_hash: <hash type>

SSH Import Id ¶

Summary: import SSH id

This module imports SSH keys from either a public keyserver, usually launchpad or github using ssh-import-id. Keys are referenced by the username they are associated with on the keyserver. The keyserver can be specified by prepending either lp: for launchpad or gh: for github to the username.

Internal name: cc_ssh_import_id

Module frequency: per instance

Supported distros: ubuntu, debian

Config keys:

ssh_import_id:
    - user
    - gh:user
    - lp:user

Timezone ¶

Summary: set system timezone

Set the system timezone. If any args are passed to the module then the first will be used for the timezone. Otherwise, the module will attempt to retrieve the timezone from cloud config.

Internal name: cc_timezone

Module frequency: per instance

Supported distros: all

Config keys:

timezone: <timezone>

Ubuntu Advantage ¶

Summary: Configure Ubuntu Advantage support services

Attach machine to an existing Ubuntu Advantage support contract and enable or disable support services such as Livepatch, ESM, FIPS and FIPS Updates. When attaching a machine to Ubuntu Advantage, one can also specify services to enable. When the ‘enable’ list is present, any named service will be enabled and all absent services will remain disabled.

Note that when enabling FIPS or FIPS updates you will need to schedule a reboot to ensure the machine is running the FIPS-compliant kernel. See Power State Change for information on how to configure cloud-init to perform this reboot.

Internal name: cc_ubuntu_advantage

Module frequency: once-per-instance

Supported distros: ubuntu

Config schema:: ubuntu_advantage: (object)

enable: (array of string)

token: (string) A contract token obtained from https://ubuntu.com/advantage.

Examples:

# Attach the machine to an Ubuntu Advantage support contract with a
# UA contract token obtained from https://ubuntu.com/advantage.
ubuntu_advantage:
  token: <ua_contract_token>

# --- Example2 ---
# Attach the machine to an Ubuntu Advantage support contract enabling
# only fips and esm services. Services will only be enabled if
# the environment supports said service. Otherwise warnings will
# be logged for incompatible services specified.
ubuntu-advantage:
  token: <ua_contract_token>
  enable:
  - fips
  - esm

# --- Example3 ---
# Attach the machine to an Ubuntu Advantage support contract and enable
# the FIPS service.  Perform a reboot once cloud-init has
# completed.
power_state:
  mode: reboot
ubuntu-advantage:
  token: <ua_contract_token>
  enable:
  - fips

Ubuntu Drivers ¶

Summary: Interact with third party drivers in Ubuntu.

This module interacts with the ‘ubuntu-drivers’ command to install third party driver packages.

Internal name: cc_ubuntu_drivers

Module frequency: once-per-instance

Supported distros: ubuntu

Config schema:: drivers: (object)

nvidia: (object)

license-accepted: (boolean) Do you accept the NVIDIA driver license?

version: (string) The version of the driver to install (e.g. “390”, “410”). Defaults to the latest version.

Examples:

drivers:
  nvidia:
    license-accepted: true

Update Etc Hosts ¶

Summary: update /etc/hosts

This module will update the contents of /etc/hosts based on the hostname/fqdn specified in config. Management of /etc/hosts is controlled using manage_etc_hosts. If this is set to false, cloud-init will not manage /etc/hosts at all. This is the default behavior.

If set to true or template, cloud-init will generate /etc/hosts using the template located in /etc/cloud/templates/hosts.tmpl. In the /etc/cloud/templates/hosts.tmpl template, the strings $hostname and $fqdn will be replaced with the hostname and fqdn respectively.

If manage_etc_hosts is set to localhost, then cloud-init will not rewrite /etc/hosts entirely, but rather will ensure that a entry for the fqdn with a distribution dependent ip is present in /etc/hosts (i.e. ping <hostname> will ping 127.0.0.1 or 127.0.1.1 or other ip).

Note

if manage_etc_hosts is set true or template, the contents of /etc/hosts will be updated every boot. to make any changes to /etc/hosts persistant they must be made in /etc/cloud/templates/hosts.tmpl

Note

for instructions on specifying hostname and fqdn, see documentation for cc_set_hostname

Internal name: cc_update_etc_hosts

Module frequency: per always

Supported distros: all

Config keys:

manage_etc_hosts: <true/"template"/false/"localhost">
fqdn: <fqdn>
hostname: <fqdn/hostname>

Update Hostname ¶

Summary: update hostname and fqdn

This module will update the system hostname and fqdn. If preserve_hostname is set, then the hostname will not be altered.

Note

for instructions on specifying hostname and fqdn, see documentation for cc_set_hostname

Internal name: cc_update_hostname

Module frequency: per always

Supported distros: all

Config keys:

preserve_hostname: <true/false>
prefer_fqdn_over_hostname: <true/false>
fqdn: <fqdn>
hostname: <fqdn/hostname>

Users and Groups ¶

Summary: configure users and groups

This module configures users and groups. For more detailed information on user options, see the Including users and groups config example.

Groups to add to the system can be specified as a list under the groups key. Each entry in the list should either contain a the group name as a string, or a dictionary with the group name as the key and a list of users who should be members of the group as the value. Note: Groups are added before users, so any users in a group list must already exist on the system.

The users config key takes a list of users to configure. The first entry in this list is used as the default user for the system. To preserve the standard default user for the distro, the string default may be used as the first entry of the users list. Each entry in the users list, other than a default entry, should be a dictionary of options for the user. Supported config keys for an entry in users are as follows:

name: The user’s login name

expiredate: Optional. Date on which the user’s account will be disabled. Default: none

gecos: Optional. Comment about the user, usually a comma-separated string of real name and contact information. Default: none

groups: Optional. Additional groups to add the user to. Default: none

homedir: Optional. Home dir for user. Default is /home/<username>

inactive: Optional. Number of days after a password expires until the account is permanently disabled. Default: none

lock_passwd: Optional. Disable password login. Default: true

no_create_home: Optional. Do not create home directory. Default: false

no_log_init: Optional. Do not initialize lastlog and faillog for user. Default: false

no_user_group: Optional. Do not create group named after user. Default: false

passwd: Hash of user password

primary_group: Optional. Primary group for user. Default to new group named after user.

selinux_user: Optional. SELinux user for user’s login. Default to default SELinux user.

shell: Optional. The user’s login shell. The default is to set no shell, which results in a system-specific default being used.

snapuser: Optional. Specify an email address to create the user as a Snappy user through snap create-user. If an Ubuntu SSO account is associated with the address, username and SSH keys will be requested from there. Default: none

ssh_authorized_keys: Optional. List of SSH keys to add to user’s authkeys file. Default: none. This key can not be combined with ssh_redirect_user.

ssh_import_id: Optional. SSH id to import for user. Default: none. This key can not be combined with ssh_redirect_user.

ssh_redirect_user: Optional. Boolean set to true to disable SSH logins for this user. When specified, all cloud meta-data public SSH keys will be set up in a disabled state for this username. Any SSH login as this username will timeout and prompt with a message to login instead as the configured <default_username> for this instance. Default: false. This key can not be combined with ssh_import_id or ssh_authorized_keys.

sudo: Optional. Sudo rule to use, list of sudo rules to use or False. Default: none. An absence of sudo key, or a value of none or false will result in no sudo rules being written for the user.

system: Optional. Create user as system user with no home directory. Default: false

uid: Optional. The user’s ID. Default: The next available value.

Note

Specifying a hash of a user’s password with passwd is a security risk if the cloud-config can be intercepted. SSH authentication is preferred.

Note

If specifying a sudo rule for a user, ensure that the syntax for the rule is valid, as it is not checked by cloud-init.

Note

Most of these configuration options will not be honored if the user already exists. The following options are the exceptions; they are applied to already-existing users: plain_text_passwd, hashed_passwd, lock_passwd, sudo, ssh_authorized_keys, ssh_redirect_user.

Internal name: cc_users_groups

Module frequency: per instance

Supported distros: all

Config keys:

groups:
    - <group>: [<user>, <user>]
    - <group>

users:
    - default
    # User explicitly omitted from sudo permission; also default behavior.
    - name: <some_restricted_user>
      sudo: false
    - name: <username>
      expiredate: '<date>'
      gecos: <comment>
      groups: <additional groups>
      homedir: <home directory>
      inactive: '<number of days>'
      lock_passwd: <true/false>
      no_create_home: <true/false>
      no_log_init: <true/false>
      no_user_group: <true/false>
      passwd: <password>
      primary_group: <primary group>
      selinux_user: <selinux username>
      shell: <shell path>
      snapuser: <email>
      ssh_redirect_user: <true/false>
      ssh_authorized_keys:
          - <key>
          - <key>
      ssh_import_id: <id>
      sudo: <sudo config>
      system: <true/false>
      uid: <user id>

Write Files ¶

Summary: write arbitrary files

Write out arbitrary content to files, optionally setting permissions. Parent folders in the path are created if absent. Content can be specified in plain text or binary. Data encoded with either base64 or binary gzip data can be specified and will be decoded before being written. For empty file creation, content can be omitted.

Note

if multiline data is provided, care should be taken to ensure that it follows yaml formatting standards. to specify binary data, use the yaml option !!binary

Note

Do not write files under /tmp during boot because of a race with systemd-tmpfiles-clean that can cause temp files to get cleaned during the early boot process. Use /run/somedir instead to avoid race LP:1707222.

Internal name: cc_write_files

Module frequency: once-per-instance

Supported distros: all

Config schema:: write_files: (array of object)

Each item in write_files list supports the following keys:

path: (string) Path of the file to which content is decoded and written

content: (string) Optional content to write to the provided path. When content is present and encoding is not ‘text/plain’, decode the content prior to writing. Default: ‘’

owner: (string) Optional owner:group to chown on the file. Default: root:root

permissions: (string) Optional file permissions to set on path represented as an octal string ‘0###’. Default: ‘0644’

encoding: (string) Optional encoding type of the content. Default is text/plain and no content decoding is performed. Supported encoding types are: gz, gzip, gz+base64, gzip+base64, gz+b64, gzip+b64, b64, base64.

append: (boolean) Whether to append content to existing file if path exists. Default: false.

Examples:

# Write out base64 encoded content to /etc/sysconfig/selinux
write_files:
- encoding: b64
  content: CiMgVGhpcyBmaWxlIGNvbnRyb2xzIHRoZSBzdGF0ZSBvZiBTRUxpbnV4...
  owner: root:root
  path: /etc/sysconfig/selinux
  permissions: '0644'

# --- Example2 ---
# Appending content to an existing file
write_files:
- content: |
    15 * * * * root ship_logs
  path: /etc/crontab
  append: true

# --- Example3 ---
# Provide gziped binary content
write_files:
- encoding: gzip
  content: !!binary |
      H4sIAIDb/U8C/1NW1E/KzNMvzuBKTc7IV8hIzcnJVyjPL8pJ4QIA6N+MVxsAAAA=
  path: /usr/bin/hello
  permissions: '0755'

# --- Example4 ---
# Create an empty file on the system
write_files:
- path: /root/CLOUD_INIT_WAS_HERE

Yum Add Repo ¶

Summary: add yum repository configuration to the system

Add yum repository configuration to /etc/yum.repos.d. Configuration files are named based on the dictionary key under the yum_repos they are specified with. If a config file already exists with the same name as a config entry, the config entry will be skipped.

Internal name: cc_yum_add_repo

Module frequency: per always

Supported distros: almalinux, centos, eurolinux, fedora, photon, rhel,: rocky, virtuozzo

Config keys:

yum_repos:
    <repo-name>:
        baseurl: <repo url>
        name: <repo name>
        enabled: <true/false>
        # any repository configuration options (see man yum.conf)