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. It also enables eudev's init.d services as udev is
used by cloud-init for both disk configuration and network card persistent
naming.


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.



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


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 some packages required by some cloud-init modules.

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

	cc_bootcmd
	cc_ca_certs
	cc_debug
	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 create/resize filesystems other than ext2/3/4 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
	F2FS:	f2fs-tools
	LVM:	lvm2
	XFS:	xfsprogs and xfsprogs-extra
	ZFS:	zfs


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

With the removal of the util-linux dependency from the Alpine cloud-init
package the "mount" command provided by Busybox will be used instead.

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 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 util-linux package into the Alpine image used with
cloud-init.

or:

(2) Create (or modify) the file /etc/filesystem 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.


CloudSigma and SmartOS data sources
-----------------------------------

If you are using either the CloudSigma or SmartOS/Joyent Cloud data sources
then you will need to install the Alpine py3-serial package. This was removed
as a cloud-init (hard) dependency as it is only used by these two uncommon
Data Sources.


MAAS data source
----------------

If you are using the MAAS data source then you will need to install the
Alpine py3-oauthlib package. This was removed as a cloud-init (hard)
dependency as it is only used by the MAAS Data Source.