Chapter 9: Cloud-Init Setup

From cOS Core version 13.00.08 onwards, the distributed KVM image is capable of providing Cloud-Init functionality for cOS Core instance initialization. cOS Core distributions for all virtual environments have Cloud-Init support enabled by default on startup. However, cOS Core will initialize with its default configuration if it is unable to retrieve the data for initialization from an external server.

[Note] Note: Cloud-Init is only available in virtual environments

The Cloud-Init feature will only function when cOS Core is running in any of the supported virtual environments. In addition, cOS Core initialization of an HA cluster is not supported with Cloud-Init.

External Cloud-Init Documentation

The full documentation for the Cloud-Init standard can be found at:

Typical Configuration Actions Performed Using Cloud Init

Below is an example list of some of the typical configuration actions that the administrator might use Cloud-Init for prior to deploying an instance:

Prerequisites for Cloud-Init Setup

The following prerequisites are required for the Cloud-Init process:

A Summary of Cloud-Init Instance Initialization

The following steps outline the process of Cloud-Init initialization for any cOS Core instance:

  1. When an instance is starting up for the first time, cOS Core will enable a DHCP client on all interfaces. This will continue to be enabled unless the initialization disables it or it is disabled later by the administrator.

  2. Any of the interfaces can then receive an IP address lease through DHCP. The lease must include a route to the IP address (the IP of the initialization HTTP server).

  3. cOS Core will attempt to connect to on the first interface that receives a suitable DHCP lease. cOS Core will make up to 6 attempts to reach with the following delays between attempts:

    • 5 seconds delay before 1st attempt.
    • 10 seconds delay after 1st attempt.
    • 30 seconds delay after 2nd attempt.
    • 60 seconds delay after 3rd attempt.
    • 300 seconds delay after 4th attempt.
    • 600 seconds delay after 5th attempt.
    • 1800 seconds delay after 6th attempt before connection is considered as failed.

    If a new DHCP lease is received by the interface during these attempts, the attempt counter is reset to zero and the attempts will continue up to 6 times as before.

    If cOS Core is unable to reach, the Cloud-Init sequence will terminate and cOS Core will start uninitialized, with its default configuration.

  4. cOS Core requests initialization files from the server at by using HTTP GET requests.

  5. The server sends back up to three initialization files. These files are described below.

  6. cOS Core will then configure itself based on the data received and, if no errors occur, it will start up as an initialized cOS Core instance.

    If any error occurs during initialization, cOS Core will start up with its default configuration but with the initialized configuration ready to be deployed. It is then up to the administrator to manually deploy those changes. Examining the local console messages generated by cOS Core during startup will help troubleshoot any initialization errors. In addition, the following command can be used to view cOS Core initialization events:

    Device:/> dconsole

    Note that restarting an initialized instance will not restart the initialization process. The Cloud-Init sequence is only performed by cOS Core if it still has a default configuration.

Instance Configuration Data Files

When cOS Core has a route to, it requests the following files from the address using HTTP GET requests and in the order they are listed below:

  1. The file "network_data.json"

    This file contains network initialization data and is retrieved using HTTP GET from:

    The file must use OpenStack 2015-10-15 JSON conventions to describe the networking information. A simple example file is listed at the end of this section.

  2. The file "meta_data.json"

    This file contains instance metadata such as instance name and SSH key. It is retrieved using HTTP GET from:

    The file must use OpenStack 2015-10-15 JSON conventions to describe the meta data. A simple example file is listed at the end of this section.

    If this file is missing or is present but does not set a strong administrator password, then the user_data file must exist and must contain the command to disable strong passwords.

  3. The file "user_data"

    This file contains a set of cOS Core CLI commands and is retrieved using HTTP GET from:

    A simple example file is listed at the end of this section.

    The following should be noted about this file's contents:

    1. There must be a line in the file which contains only the string #cli-config. The processing of commands will only begin immediately after this line.

    2. The commands allowed in the file are the same as those allowed in a standard cOS Core CLI script file. In other words, add or set or delete or cc. CLI scripting is described further in the CLI Scripts section of the separate cOS Core Administration Guide.

    3. Multiple files can be combined into a single MIME file.

    4. If a strong administrator password is not set in the meta_data.json file then this file must exist and contain the following command to disable strong passwords:

      set Settings MiscSettings EnforceStrongPasswords=No
    5. Cloud-Init uses the field ID in network_data.json file to set the interface name (and corresponding address objects). This could sometimes create problems. Adding the tag "#no_iface_rename" in the user_data file overrides the renaming and leave interface names untouched.

The following should be noted about the retrieval and processing of these files:

cOS Core Local Console Output

As the Cloud-Init initialization process progresses, cOS Core will output messages to the cOS Core local console to indicate the initialization states. For example, the following messages would be seen as the file network_data.json is successfully retrieved from the Cloud-Init server and processed:
Cloud init - Connecting to server
[Connected to]
[Received 193 bytes from]
[Received 1460 bytes from]
[Received 269 bytes from]
TCP_EventHandler total bytes 1922
[Closing connection to]
[6][Connection to closed. (Normal close)]
[INFO] Parsed network data.
[INFO] Validated network data syntax.
[INFO] Network data successfully added to configuration.
A similar set of messages is then displayed as each of the other two files, meta_data.json and user_data, are retrieved and processed.

When, all available files have been successfully processed and the configuration changes completed, a cOS Core reconfigure operation is performed automatically to activate the changes. When this is complete, the following local console message appears to indicate successful instance initialization:

 Changes done by CLOUD INIT committed
[INFO] Cloud Init provisioning mode exit.

If one of the initialization files is not available, this will be indicated by local console output similar to the following, which is for a missing network_data.json file:

[INFO] No network data found in received file.
Will use default configuration.

If there are any errors retrieved in the received files, these will be highlighted. The following local console output related to an error found in a MAC address in the network_data.json file:

[ERROR] No match found for MAC '10:00:00:c6:15:f2'
referenced by interface 'if3_OK'.
[ERROR] Failed to update system with network data configuration.

Such errors will mean that any changes must be activated manually and the Cloud-Init process will end with the local console message:

[ERROR] There are errors in the received configuration.

Configuration File Examples

Below are examples of the three types of configuration files.

  "services": [
      "type": "dns",
      "address": ""
      "type": "dns",
      "address": ""
  "networks": [
      "network_id": "some_id_1",
      "type": "ipv4_dhcp",
      "link": "some_link",
      "id": "network1"
      "network_id": "some_id_2",
      "type": "ipv4",
      "link": "some_link2",
      "id": "network2"
      "network_id": "some_id_3",
      "type": "ipv4",
      "link": "some_link2",
      "id": "network2_ip4",
  "links": [
      "type": "ovs",
      "vif_id": "some_vif_id",
      "ethernet_mac_address": "aa:aa:aa:aa:aa:aa",
      "id": "some_link",
      "mtu": 1500
      "type": "ovs",
      "vif_id": "some_vif_id_2",
      "ethernet_mac_address": "bb:bb:bb:bb:bb:bb",
      "id": "some_link2",
      "mtu": 1500

A more extensive network_data.json example can be found at this link:

  "name": "MyCloudInstance001",
  "admin_pass": "aStrongPassword121!@",
      "firstkey": "ecdsa-sha2-nistp521 AAAAB3NzaC1yc2EAAAABJQAAAQEAsn...",
      "secondkey": "ecdsa-sha2-nistp521 AAAAB3NzaC1yc2EAAAABJQAAAQEAl6...",

Additional examples of both this and the network_data.json files can be found at this link:

set Settings MiscSettings EnforceStrongPasswords=YES
add IPPolicy SourceInterface=If1 DestinationInterface=any
SourceNetwork=If1_net DestinationNetwork=all-nets
Service=all_services Name=allow_all Action=Allow