Cloud-init support
Below is a reference of all keys available in the cloud-init style files.
stages:
# "network" is the stage where network is expected to be up
# It is called internally when network is available from
# the cos-setup-network unit.
network:
# Here there are a list of
# steps to be run in the network stage
- name: "Some setup happening"
files:
- path: /tmp/foo
content: |
test
permissions: 0777
owner: 1000
group: 100
commands:
- echo "test"
modules:
- nvidia
environment:
FOO: "bar"
systctl:
debug.exception-trace: "0"
hostname: "foo"
systemctl:
enable:
- foo
disable:
- bar
start:
- baz
mask:
- foobar
authorized_keys:
user:
- "github:mudler"
- "ssh-rsa ...."
dns:
path: /etc/resolv.conf
nameservers:
- 8.8.8.8
ensure_entities:
- path: /etc/passwd
entity: |
kind: "user"
username: "foo"
password: "pass"
uid: 0
gid: 0
info: "Foo!"
homedir: "/home/foo"
shell: "/bin/bash"
delete_entities:
- path: /etc/passwd
entity: |
kind: "user"
username: "foo"
password: "pass"
uid: 0
gid: 0
info: "Foo!"
homedir: "/home/foo"
shell: "/bin/bash"
datasource:
providers:
- "aws"
- "digitalocean"
path: "/etc/cloud-data"
The default cloud-config format is split into stages (initramfs, boot, network, initramfs, reconcile, called generically STAGE_ID below) see also stages that are emitted internally during the various phases by calling cos-setup STAGE_ID.
steps (STEP_NAME below) defined for each stage are executed in order.
Each cloud-config file is loaded and executed only at the apprioriate stage, this allows further components to emit their own stages at the desired time.
The cloud-init tool can be also run standalone, this helps debugging locally and also during development, you can find separate releases here, or just run it with docker:
cat <<EOF | docker run -i --rm quay.io/costoolkit/releases-green:cos-recovery-0.6.0 yip -s test -
stages:
test:
- commands:
- echo "test"
EOF
Note: Each cloud-init option can be either run in dot notation ( e.g. stages.network[0].authorized_keys.user=github:user ) in the boot args or either can supply a cloud-init URL at boot with the cos.setup=$URL parameter.
Using templates
With Cloud Init support, templates can be used to allow dynamic configuration. More information about templates can be found here and also here for sprig functions.
Compatibility with Cloud Init format
A subset of the official cloud-config spec is implemented.
If a yaml file starts with #cloud-config it is parsed as a standard cloud-init and automatically associated it to the boot stage. For example:
#cloud-config
growpart:
mode: auto
devices: ['/']
users:
- name: "bar"
passwd: "foo"
lock_passwd: true
uid: "1002"
groups: "users"
ssh_authorized_keys:
- faaapploo
ssh_authorized_keys:
- asdd
runcmd:
- foo
hostname: "bar"
write_files:
- encoding: b64
content: CiMgVGhpcyBmaWxlIGNvbnRyb2xzIHRoZSBzdGF0ZSBvZiBTRUxpbnV4
path: /foo/bar
permissions: "0644"
owner: "bar"
Is executed at boot, by using the standard cloud-config format.
stages.STAGE_ID.STEP_NAME.name
A description of the stage step. Used only when printing output to console.
stages.STAGE_ID.STEP_NAME.files
A list of files to write to disk.
stages:
default:
- files:
- path: /tmp/bar
content: |
#!/bin/sh
echo "test"
permissions: 0777
owner: 1000
group: 100
stages.STAGE_ID.STEP_NAME.directories
A list of directories to be created on disk. Runs before files.
stages:
default:
- name: "Setup folders"
directories:
- path: "/etc/foo"
permissions: 0600
owner: 0
group: 0
stages.STAGE_ID.STEP_NAME.dns
A way to configure the /etc/resolv.conf file.
stages:
default:
- name: "Setup dns"
dns:
nameservers:
- 8.8.8.8
- 1.1.1.1
search:
- foo.bar
options:
- ..
path: "/etc/resolv.conf.bak"
stages.STAGE_ID.STEP_NAME.hostname
A string representing the machine hostname. It sets it in the running system, updates /etc/hostname and adds the new hostname to /etc/hosts.
Templates can be used to allow dynamic configuration. For example in mass-install scenario it could be needed (and easier) to specify hostnames for multiple machines from a single cloud-init config file.
stages:
default:
- name: "Setup hostname"
hostname: "node-{{ trunc 4 .MachineID }}"
stages.STAGE_ID.STEP_NAME.sysctl
Kernel configuration. It sets /proc/sys/<key> accordingly, similarly to sysctl.
stages:
default:
- name: "Setup exception trace"
systctl:
debug.exception-trace: "0"
stages.STAGE_ID.STEP_NAME.authorized_keys
A list of SSH authorized keys that should be added for each user. SSH keys can be obtained from GitHub user accounts by using the format github:${USERNAME}, similarly for Gitlab with gitlab:${USERNAME}.
stages:
default:
- name: "Setup exception trace"
authorized_keys:
mudler:
- github:mudler
- ssh-rsa: ...
stages.STAGE_ID.STEP_NAME.node
If defined, the node hostname where this stage has to run, otherwise it skips the execution. The node can be also a regexp in the Golang format.
stages:
default:
- name: "Setup logging"
node: "bastion"
stages.STAGE_ID.STEP_NAME.users
A map of users and user info to set. Passwords can be also encrypted.
The users parameter adds or modifies the specified list of users. Each user is an object which consists of the following fields. Each field is optional and of type string unless otherwise noted.
In case the user is already existing, the entry is ignored.
- name: Required. Login name of user
- gecos: GECOS comment of user
- passwd: Hash of the password to use for this user. Unencrypted strings are supported too.
- homedir: User’s home directory. Defaults to /home/name
- no-create-home: Boolean. Skip home directory creation.
- primary-group: Default group for the user. Defaults to a new group created named after the user.
- groups: Add user to these additional groups
- no-user-group: Boolean. Skip default group creation.
- ssh-authorized-keys: List of public SSH keys to authorize for this user
- system: Create the user as a system user. No home directory will be created.
- no-log-init: Boolean. Skip initialization of lastlog and faillog databases.
- shell: User’s login shell.
stages:
default:
- name: "Setup users"
users:
bastion:
passwd: "strongpassword"
homedir: "/home/foo
stages.STAGE_ID.STEP_NAME.ensure_entities
A user or a group in the entity format to be configured in the system
stages:
default:
- name: "Setup users"
ensure_entities:
- path: /etc/passwd
entity: |
kind: "user"
username: "foo"
password: "x"
uid: 0
gid: 0
info: "Foo!"
homedir: "/home/foo"
shell: "/bin/bash"
stages.STAGE_ID.STEP_NAME.delete_entities
A user or a group in the entity format to be pruned from the system
stages:
default:
- name: "Setup users"
delete_entities:
- path: /etc/passwd
entity: |
kind: "user"
username: "foo"
password: "x"
uid: 0
gid: 0
info: "Foo!"
homedir: "/home/foo"
shell: "/bin/bash"
stages.STAGE_ID.STEP_NAME.modules
A list of kernel modules to load.
stages:
default:
- name: "Setup users"
modules:
- nvidia
stages.STAGE_ID.STEP_NAME.systemctl
A list of systemd services to enable, disable, mask or start.
stages:
default:
- name: "Setup users"
systemctl:
enable:
- systemd-timesyncd
- cronie
mask:
- purge-kernels
disable:
- crond
start:
- cronie
stages.STAGE_ID.STEP_NAME.environment
A map of variables to write in /etc/environment, or otherwise specified in environment_file
stages:
default:
- name: "Setup users"
environment:
FOO: "bar"
stages.STAGE_ID.STEP_NAME.environment_file
A string to specify where to set the environment file
stages:
default:
- name: "Setup users"
environment_file: "/home/user/.envrc"
environment:
FOO: "bar"
stages.STAGE_ID.STEP_NAME.timesyncd
Sets the systemd-timesyncd daemon file (/etc/system/timesyncd.conf) file accordingly. The documentation for timesyncd and all the options can be found here.
stages:
default:
- name: "Setup NTP"
systemctl:
enable:
- systemd-timesyncd
timesyncd:
NTP: "0.pool.org foo.pool.org"
FallbackNTP: ""
...
stages.STAGE_ID.STEP_NAME.commands
A list of arbitrary commands to run after file writes and directory creation.
stages:
default:
- name: "Setup something"
commands:
- echo 1 > /bar
stages.STAGE_ID.STEP_NAME.datasource
Sets to fetch user data from the specified cloud providers. It populates
provider specific data into /run/config folder and the custom user data
is stored into the provided path.
stages:
default:
- name: "Fetch cloud provider's user data"
datasource:
providers:
- "aws"
- "digitalocean"
path: "/etc/cloud-data"
stages.STAGE_ID.STEP_NAME.layout
Sets additional partitions on disk free space, if any, and/or expands the last
partition. All sizes are expressed in MiB only and default value of size: 0
means all available free space in disk. This plugin is useful to be used in
oem images where the default partitions might not suit the actual disk geometry.
stages:
default:
- name: "Repart disk"
layout:
device:
# It will partition a device including the given filesystem label
# or partition label (filesystem label matches first) or the device
# provided in 'path'. The label check has precedence over path when
# both are provided.
label: "COS_RECOVERY"
path: "/dev/sda"
# Only last partition can be expanded and it happens before any other
# partition is added. size: 0 means all available free space
expand_partition:
size: 4096
add_partitions:
- fsLabel: "COS_STATE"
size: 8192
# No partition label is applied if omitted
pLabel: "state"
- fsLabel: "COS_PERSISTENT"
# default filesystem is ext2 if omitted
filesystem: "ext4"
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.