How to use Cloud-Init to configure your server at first boot

Cloud-Init Overview

Cloud-init is a package that contains utilities for early initialization of cloud instances. It enables automatic configuration of cloud instances as it boots into the cloud, turning it from a generic Ubuntu image into a configured server in a few seconds, quickly and easily

The cloud-init program that is available on recent distributions (Ubuntu, Fedora, Debian) is able to consume and execute data from the user-data field of the Scaleway service. This process behaves differently depending on the format of the information it finds. One of the most popular formats for scripts within user-data is the cloud-config file format.

Cloud-config files are special scripts designed to be run by the cloud-init process. These are generally used for initial configuration on the very first boot of a server.

Scaleway Cloud-Init Enabled Images

Note: Debian Jessie has dependancy limitation issues that make cloud-init unavailable. Cloud-init is currently not available for Start1-XS offers.

Cloud-init is now natively enabled for the following distributions:

User data

User data is the mechanism by which a user can pass information contained in a local file to an instance at launch time. The typical use case is to pass something like a shell script or a configuration file as user data.

Cloud-init supports different input formats for user-data:

Provisioning your Instance with Cloud-Init

You can download the latest version of the Scaleway CLI tools, directly from Github.

Cloud-init is the perfect tool to provision a new instance. You can provide provisionning instructions to cloud-init using the cloud-init key of the user_data facility.

In order for the user_data to be effective, it has to be added prior to starting the instance since cloud-init gets activated early in the first phases of the boot process.

• Image ID refers to the image identification number of your server. To retrieve your image ID, launch the scw images command.
• Server ID refers to the unique identification string of your server. It will be displayed when you create your server. You can also recover it from the list of your servers, by typing scw ps.

1 . Create your instance

$ scw create --commercial-type=START1-S --name=myvm {image Id}
{server Id}

2 . Use the scw _userdata command to provide your newly created instance

$ scw _userdata {server Id} cloud-init=@/path/to/cloud-config-file
cloud-init

3 . Start your instance

$ scw start {server Id}

Using Cloud-Init with Scaleway Console

Cloud init user_data can be provided directly from the Scaleway console. When creating a server, expand the Advanced settings tab to display the cloud init section.

Using Cloud-Init with Scaleway API

You need to generate an API key to authenticate before you can use the API. For more information, refer to the Scaleway API documentation.

curl -X PATCH -d '<cloud-init-data>' -H 'Content-Type: text/plain' -H "X-Auth-Token: $SECRET_KEY" https://cp-<region>.scaleway.com/servers/<server_id>/user_data/cloud-init

Cloud-Init CLI Interface

The command line documentation is accessible on any cloud-init installed system:

% cloud-init --help
usage: cloud-init [-h] [--version] [--file FILES]

                  [--debug] [--force]
                  {init,modules,single,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
                  ...

optional arguments:
  -h, --help            show this help message and exit
  --version, -v         show program's version number and exit
  --file FILES, -f FILES
                        additional yaml configuration files to use
  --debug, -d           show additional pre-action logging (default: False)
  --force               force running even if no datasource is found (use at
                        your own risk)

Subcommands:
  {init,modules,single,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
    init                initializes cloud-init and performs initial modules
    modules             activates modules using a given configuration key
    single              run a single module
    dhclient-hook       run the dhclient hookto record network info
    features            list defined features
    analyze             Devel tool: Analyze cloud-init logs and data
    devel               Run development tools
    collect-logs        Collect and tar all cloud-init debug info
    clean               Remove logs and artifacts so cloud-init can re-run.
    status              Report cloud-init status or wait on completion.

Troubleshooting Cloud-Init

You can test and debug your cloud-config script without having to reboot your instance. The normal sequence of execution of cloud-init during the boot of the instance is as follows:

1. cloud-init init --local
2. cloud-init init
3. cloud-init modules --mode=config
4. cloud-init modules --mode=final

A typical debugging session could be:

$ scw create --commercial-type=START1-S --name=myvm {image Id}
{server Id}

$ scw start {server Id}

Login to your instance and issue the following commands to reset cloud-init which has already run once:

$ cloud-init clean
$ rm -f /var/log/cloud*

On the system where you launched the instance add the cloud-init user_data:

$ cat my-user-data
#cloud-config
final_message: "Scaleway is happy to welcome you to a cloud-init enabled instance"
runcmd:
  - [ cloud-init, status]

$ scw _userdata {server Id} cloud-init=@/path/to/cloud-config-file
cloud-init

Back on the instance you started, launch:

$ cloud-init clean
$ rm -f /var/log/cloud*
$ cloud-init init --local
Cloud-init v. 18.2 running 'init-local' at Fri, 29 Jun 2018 07:29:58 +0000. Up 551.27 seconds.
$ cloud-init init
Cloud-init v. 18.2 running 'init' at Fri, 29 Jun 2018 07:30:02 +0000. Up 555.57 seconds.
ci-info: ++++++++++++++++++++++++++++++++++++++++Net device info++++++++++++++++++++++++++++++++++++++++
ci-info: +--------+------+------------------------------+-----------------+--------+-------------------+
ci-info: | Device |  Up  |           Address            |       Mask      | Scope  |     Hw-Address    |
ci-info: +--------+------+------------------------------+-----------------+--------+-------------------+
ci-info: |  ens2  | True |        10.15.121.133         | 255.255.255.254 | global | de:1a:20:20:20:03 |
...
$ cloud-init modules --mode=config
Cloud-init v. 18.2 running 'modules:config' at Fri, 29 Jun 2018 07:30:11 +0000. Up 564.70 seconds.
$ cloud-init modules --mode=final
Cloud-init v. 18.2 running 'modules:final' at Fri, 29 Jun 2018 07:30:16 +0000. Up 569.64 seconds.
status: running
Scaleway is happy to welcome you to a cloud-init enabled instance

Cloud-Init Logs Location

Once the VM has been provisioned, cloud-init will run through all the modules and script defined in --custom-data in order to configure the VM. If you need to troubleshoot any errors or omissions from the configuration, you need to search for the module name (disk_setup or runcmd for example) in the cloud-init log - located in /var/log/cloud-init.logs.

For detailed information on Cloud-init, refer to the official cloud-init documentation.