aports/community/cloud-init

After the cloud-init package is installed you will need to run the
"setup-cloud-init" command to prepare the OS for cloud-init use.

This command will enable cloud-init's init.d services so that they are run
upon future boots/reboots.


** IMPORTANT **
---------------

To avoid the Alpine package having a large number of dependencies that in
many cases would be unnecessary the package only has a general set of
dependencies defined that are common for the majority of use cases.

When creating an Alpine OS image that makes use of cloud-init you should
read the rest of this document, set a DataSources list to only enable
whichever DataSource(s) you require, and install any additionally required
Alpine package dependings on the filesystem type, DataSource(s), etc in use.
Information related to this is contained in the rest of this document.



Customising the enabled Data Sources list
-----------------------------------------

Whenever cloud-init runs on first boot it determines which DataSource is to
be used for performing machine configuration, it does so by reading the
"datasource_list" definition in the /etc/cloud/cloud.cfg file.

By default "datasource_list" is not set and so cloud-init defaults to
enabling all DataSources. If you do NOT set a "datasource_list" then you
should also install *all* the additional Alpine packages required by the
full set of DataSources - these are detailed below - to avoid cloud-init
errors/warnings.

If you are creating a cloud-init enabled Alpine image for a specific
environment, or a known set of environments, then it would make sense to
add a "datasource_list" value to only list whichever DataSource is
required/expected as this potentially result in (slightly) faster first boot
times as each individual enabled DataSource would not have to be checked in
sequence until the required one is reached.

For example if creating an Alpine image only for use with AWS then adding
the following setting to /etc/cloud/cloud.cfg would make sense:

  datasource_list: ['Ec2', 'None']

whereas if the image was intended to be used for either of AWS, Azure, or
Google Cloud then:

  datasource_list: ['Ec2', 'Azure', 'GCE', 'None']

and for an image to only be used with ISO or disk configuration files:

  datasource_list: ['NoCloud', 'None']


Additional Alpine packages required by specific DataSources
-----------------------------------------------------------

  Azure                           dhclient
  CloudSigma & SmartOS/Joyent     py3-pyserial
  Ec2                             dhclient, eudev
  GCE                             dhclient
  Hetzner                         dhclient
  MAAS                            py3-oauthlib
  NWCS                            dhclient
  OpenStack                       eudev
  Oracle                          dhclient
  Scaleway                        dhclient
  UpCloud                         dhclient
  VMware                          py3-netifaces
  Vultr                           dhclient


Additional Alpine packages you may want or need to manually install
-------------------------------------------------------------------

  doas

    Alpine v3.15+, see the section "Sudo & Doas" below.

  mdevd or eudev

    see the section "mdev / mdevd / eudev" below.

  mount (Alpine Edge & v3.17+) or util-linux-misc (Alpine v3.15 & v3.16)
  or util-linux (Alpine <= v3.14)

    see the section "Using ISO images for cloud-init configuration (i.e.
    with NoCloud/ConfigDrive)" below.

  openssh-server or openssh-server-pam

    see the section "Unable to SSH in as user(s) as the account(s) is/are
    locked" below.

  sudo

    see the section "Sudo & Doas" below.

Also please read the section "Missing dependencies" below for further
information.


mdev / mdevd / eudev
--------------------

As of Alpine release v3.17 (and Edge from mid-Nov 2022 onwards) the Alpine
cloud-init package can be used together with either eudev (aka udev), mdev,
or mdevd.

Due to this change the cloud-init package from Alpine v3.17 onwards no longer
declares a dependency on the eudev package - you will need to manually install
either eudev or mdevd to your Alpine disk image if required. You may also need
to run "setup-devd mdevd" or "setup-devd udev" accordingly to enable those
instead of mdev.

Upstream cloud-init is only designed and tested to work with udev and
therefore some cloud-init functionality may not work when either mdev or mdevd
are used instead. This document will, over time, detail any known mdev or
mdevd incompatible cloud-init modules and/or Data Sources.


Sudo & Doas
-----------

Cloud-init has always had support for 'sudo' when adding users (via
user-data). As Alpine has now moved towards preferring the use of 'doas'
rather than 'sudo' support for 'doas' has been added to the cc_users_groups
module.

As a result, the Alpine cloud-init package from Alpine v3.15 onwards no
longer declares a dependency on sudo - you must ensure to install either the
'doas' or 'sudo' package (or indeed both), depending on which you wish to use,
in order to be able to create users that can run commands as a privileged
user.


Doas
----

The cloud-init support for Doas has not (yet) been upstreamed, it only
exists in the Alpine cloud-init package. This functionality performs some
basic sanity checks of per-user Doas rules - it double-checks that the user
referred to in any such rules corresponds to the user the rule(s) is/are
defined for - if not then an error appears during 1st boot and no Doas rules
are added for that user.

It is recommended that you set up a Doas rule: "permit persist :wheel" so
that all members of group 'wheel' can have root access. The default
/etc/doas.d/doas.conf file has such a rule but it is commented out.

The cloud-init global configuration file /etc/cloud/cloud.cfg defines the
default 'alpine' user to be created upon 1st boot with a Doas rule giving
password-less root access - as the 'alpine' user is locked for password
access, both local and remote, and so only SSH key-based access is available
then obviously password-based Doas access would not work.

To setup Doas rules for additional users, both existing and new, in the
user-data add a 'doas' entry to define one or more rules to be setup for
each user, for example:

  users:
    - default
    - name: tester
      doas: ["permit tester as root"]

When cloud-init runs on 1st boot it creates the file
/etc/doas.d/cloud-init.conf containing all the per-user rules specified in
user-data, as well as the rule for the default 'alpine' user.

NOTE: if you specify a "users:" section in user-data you MUST specify a
"default" entry in addition to any other entries, otherwise the default
'alpine' user will NOT be created.


NTP
---

It is recommended that you enable a NTP client on the machine. Cloud-init
supports both Chrony (fully featured) and Busybox's NTP client (a minimal
implementation).

Chrony is the default NTP client in cloud-init for Alpine Linux.


To use Chrony as the NTP client:

  Install the chrony package and enable the chrony init.d service

    # apk add chrony
    # rc-update add chronyd default

  Specify a ntp section in your cloud-init User Data like so:

    ntp:
      pool:
        - 0.uk.pool.ntp.org
        - 1.uk.pool.ntp.org

  If you do not specify any pool or servers then 0.pool.ntp.org ->
  3.pool.ntp.org will be used.

  The file /etc/cloud/templates/chrony.conf.alpine.tmpl is used by cloud-init
  as a template to create the configuration file /etc/chrony/chrony.conf.


To use Busybox as the NTP client:


  Edit the /etc/conf.d/ntpd file and change the line:

    NTPD_OPTS="-N -p pool.ntp.org"

  so that it is instead:

    NTPD_OPTS="-N"

  This changes the NTP client from using the hardcoded NTP server
  "pool.ntp.org" to instead use the /etc/ntp.conf file which will be
  generated by cloud-init upon first boot.

  Enable the ntp init.d service:

    # rc-update add ntpd default

  Specify a ntp section in your cloud-init User Data like so:

    ntp:
      ntp_client: ntp
      servers:
        - 192.168.0.1
        - 192.168.0.2

  If you do not specify any servers then 0.pool.ntp.org -> 3.pool.ntp.org
  will be used.

  The file /etc/cloud/templates/ntp.conf.alpine.tmpl is used by cloud-init
  as a template to create the configuration file /etc/ntp.conf.



Network interface hotplugging
-----------------------------

Version 21.3 of cloud-init has added some support for network interface
hotplugging, that is the addition or removal of additional network
interfaces on an already running machine.

A simple daemon, cloud-init-hotplugd, if enabled runs at boot time that
listens for udev hotplug events and triggers cloud-init to react to them.

This daemon, via its init.d script, is *not* at present enabled by the
setup-cloud-init script as hotplug is currently *only* supported by the
'ConfigDrive', 'Ec2', and 'OpenStack' DataSources.

In order to make use of network hotplug you will need to do the following
*three* things:

  - install and enable the Alpine "eudev" package for managing devices.

  - add the /etc/init.d/cloud-init-hotplugd script to the "default"
    run-level, i.e.

      rc-update add cloud-init-hotplugd default

  - enable hotplug for the relevant DataSource by adding the following to
    either the /etc/cloud.cfg file or else to the supplied user-data:

      updates:
        network:
          when: ['boot','hotplug']


Limitations
===========

Unable to resize LVM or LUKS rootfs partitions and filesystems on them
----------------------------------------------------------------------

cloud-init's cc_growpart module, if enabled, attempts to resize the root
partition. If however the rootfs is on a /dev/mapper/ devices (whether LVM,
or LUKS, or LVM-on-LUKS, or LUKS-on-LVM, cc_growpart will be unable to
resize the partition - this is due to a difference in behaviour between mdev
(always used by Alpine's initramfs **even if eudev is used by the rest of
the OS once the rootfs is mounted**) and eudev.

When the initramfs' init runs it will trigger mdev to create a /dev/mapper/
entry, if required, for the rootfs. With mdev this entry is an actual file,
whereas eudev would create it as a softlink to the underlying /dev/dm-*
device. Cloud-init's cc_growpart attempts to determine the device that
provides the rootfs and, due to this mdev limitation, believes this is
/dev/mapper/<whatever> rather that the actual /dev/dm-<whatever> device. The
/growpart utility can resize /dev/dm-*

This issues affects partition growing/fs resizing regardless of whether
udev, mdev, or mdevd is enabled in the Alpine disk image - Alpine's
initramfs' init *always* runs mdev regardless.

As a workaround, in user-data provided to the VM the runcmd module can be
used to perform any resizing as follows:

For a LUKS-encrypted rootfs (assuming it is on a LUKS partition labelled
"lukspart" and is device /dev/sda2):

  runcmd:
    - growpart /dev/sda2
    - cryptsetup resize lukspart
    - resize2fs /dev/mapper/lukspart

For a LVM-based rootfs (assuming it is on a LVM VG called "rootfs" in VG
"vg0" with /dev/sda2 being the partition LVM is using):

  runcmd:
    - growpart /dev/sda2
    - lvextend -l +100%FREE /dev/mapper/vg0-rootfs
    - resize2fs /dev/mapper/vg0-rootfs



Known Issues
============


Unable to SSH in as user(s) as the account(s) is/are locked
-----------------------------------------------------------

Issue: By default cloud-init will ensure that any user accounts have their
password locked. The OpenSSH sshd daemon has logic that, when PAM is not
enabled, for accounts with locked passwords it *also* decides to refuse
key-based SSH logins.

Solution: install the openssh-server-pam package (rather than
openssh-server) and edit /etc/ssh/sshd_config to ensure that it defines
"UsePAM yes".

In the future this package may add "openssh-server-pam" as a dependency but
as it is possible some individuals may wish to use cloud-init without any
SSH daemon installed that decision is unclear.


Missing dependencies
--------------------

The cloud-init package declares dependencies for only commonly used
cloud-init modules - if deps for all supported modules were defined then the
dependency list would be quite large.

As a result when building cloud-init based disk images you may need to
manually install additional packages required by some cloud-init modules.

The following modules should work, in general, with the defined dependencies:

  cc_apk_configure
  cc_bootcmd
  cc_ca_certs
  cc_disable_ec2_metadata
  cc_disk_setup
  cc_final_message
  cc_growpart
  cc_key_to_console
  cc_locale
  cc_migrator
  cc_mount
  cc_package_update_upgrade_install
  cc_phone_home
  cc_power_state_change
  cc_resizefs
  cc_resolv_conf
  cc_rsyslog
  cc_runcmd
  cc_scripts_per_boot
  cc_scripts_per_instance
  cc_scripts_per_once
  cc_scripts_user
  cc_scripts_vendor
  cc_seed_random
  cc_set_hostname
  cc_set_passwords
  cc_ssh
  cc_ssh_authkey_fingerprints
  cc_timezone
  cc_update_etc_hosts
  cc_update_hostname
  cc_users_groups
  cc_write_files

If you want to delete existing partitions using cc_disk_setup then you will
need to install the Alpine "wipefs" package.

If you want to create/resize filesystems using cc_disk_setup and/or
cc_resizefs then you will need to install the relevant package(s) containing
the appropriate tools:

  BTRFS:        btrfs-progs
  EXT2/3/4:     e2fsprogs-extra
  F2FS:         f2fs-tools
  LUKS:         cryptsetup and device-mapper
  LVM:          lvm2 and device-mapper
  XFS:          xfsprogs and xfsprogs-extra
  ZFS:          zfs

Cloud-init assumes the use of dhclient for DHCP purposes. However other DHCP
clients do also work, in part, with cloud-init. Therefore "dhclient" has not
been set as a hard dependancy for the Alpine package.

However if you are using a DataSource (i.e. AWS Ec2, Azure, GCE, Hetzner,
NWCS, OpenStack, Oracle, Scaleway, UpCloud, and Vultr) that needs to set up a
Ephemeral (temporary) DHCPv4 connection in order to talk to a Metadata Server
(to retrieve metadata, network configuration, and user-data information from)
then these DataSources expect "dhclient" to be installed and will try and
execute it directly and therefore retrieving information from the metadata
server will fail if dhclient is not installed).


cc_ca_certs module
------------------

The "remove-defaults" option of the cloud-init cc_ca_certs module does not
currently work correctly. This option will delete certificates installed by
the Alpine ca-certificates package as expected. However the certificates
provided by the ca-certificates-bundle package, which is always automatically
installed in an Alpine system due to it being a dependency of a base package,
are not deleted.


Using ISO images for cloud-init configuration (i.e. with NoCloud/ConfigDrive)
-----------------------------------------------------------------------------

The "mount" command in Alpine is provided by the "busybox" package by default.

The "mount" package (Alpine v3.17+), "util-linux-misc" package (Alpine v3.15
& v3.16), or "util-linux" package (Alpine <= v3.14) provides an alternative,
full featured, version of the "mount" command.

Cloud-init makes use of the mount command's "-t auto" option to mount a
filesystem containing cloud-init configuration data (detected by searching
for a filesystem with the label "cidata"). Busybox's mount command behaves
differently to that of util-linux's when the "-t auto" option is used,
specifically if the kernel module for the required filesystem is not already
loaded the util-linux mount command will trigger it to be loaded and so the
mount will succeed. However Busybox's mount will not normally trigger a kernel
module load and the mount will fail!

When this problem occurs a message such as the following will be displayed on
the console during boot:

  util.py[WARNING]: Failed to mount /dev/vdb when looking for data

If cloud-init debugging is enabled then the file /var/log/cloud-init.log will
also contain the following entries:

  subp.py[DEBUG]: Running command ['mount', '-o', 'ro', '-t', 'auto',
  '/dev/vdb', '/run/cloud-init/tmp/tmpAbCdEf'] with allowed return codes [0]
  (shell=False, capture=True)
  util.py[DEBUG]: Failed mount of '/dev/vdb' as 'auto': Unexpected error
  while running command.
  Command: ['mount', '-o', 'ro', '-t', 'auto', '/dev/vdb',
  '/run/cloud-init/tmp/tmpAbCdEf']
  Exit code: 255
  Reason: -
  Stdout:
  Stderr: mount: mounting /dev/vdb on /run/cloud-init/tmp/tmpAbCdEf failed:
  invalid argument

There are 2 possible solutions to this issue, either:

(1) Install the mount (Edge and v3.17+) / util-linux-misc (v3.15 & v3.16) /
    util-linux (<= v.3.14) package in the Alpine image used with cloud-init.

or:

(2) Create (or modify) the file /etc/filesystems and ensure it has a line
    present with the name of the required kernel module for the relevant
    filesystem i.e. "iso9660". This will ensure that Busybox's mount will
    trigger the loading of this kernel module.