Configuring virtual machines manually can be a time consuming task with potential for mistakes to occur. It's also not feasible to manually apply configurations in auto-scaling scenarios. As such, StackPath exposes cloud-init functionality on virtual machine workloads allowing you to provide a set of instructions that are automatically applied on the first boot of new virtual machine instances.

Cloud-init can be used to execute scripts to bootstrap your instances or to install configuration management software and execute a playbook to ensure configurations match throughout your workload deployment.

Determine Your Requirments

First, determine your requirements and consider what your virtual machine instances need to initialize for use. In this example we'll install and configure the popular configuration management utility Puppet so that our instance can connect to a puppet master and apply a complex configuration that matches the rest of our workload instances.

Create Your Cloud-init User Data

In order to use cloud-init with a StackPath virtual machine you will need to prepare user data that is applied on workload creation. With our puppet example we need at least the following:

#cloud-config
puppet:
 conf:
   agent:
     server: "puppetmaster.stackpath.com"
     certname: "%i"
   ca_cert: |
     -----BEGIN CERTIFICATE-----
     <certificate-data>
     -----END CERTIFICATE-----

The userdata.yaml file above configures puppetd with puppetmaster.stackpath.com as the master server and the instance's id as the certname. The ca_cert option holds the puppetmaster certificate in PEM format and will be stored in /var/lib/puppet/ssl/ca/ca_crt.pem on the virtual machine instance.

Instance ids are in the format: vmi-$workload_name-$deployment_target-$location-$instance_number.stack-$stack_id.
There are many other examples of the kinds of user data available in cloud-init's documentation.

Base64 Encode Your User Data

The StackPath API requires base64 encoded user data. On most Linux and macOS systems you can use the base64 command to encode your data using either heredoc syntax or file input.

Using heredoc:

$ base64 << EOF
#cloud-config
puppet:
 conf:
   agent:
     server: "puppetmaster.stackpath.com"
     certname: "%i"
   ca_cert: |
     -----BEGIN CERTIFICATE-----
     <certificate-data>
     -----END CERTIFICATE-----
EOF

Using a file, in this case userdata.yaml:

base64 -i userdata.yaml

Both of the above examples output the string to provide as userData in our StackPath API request:

I2Nsb3VkLWNvbmZpZwpwdXBwZXQ6CiBjb25mOgogICBhZ2VudDoKICAgICBzZXJ2ZXI6ICJwdXBwZXRtYXN0ZXIuc3RhY2twYXRoLmNvbSIKICAgICBjZXJ0bmFtZTogIiVpIgogICBjYV9jZXJ0OiB8CiAgICAgLS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCiAgICAgPGNlcnQtZGF0YT4KICAgICAtLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==

Configuring UserData

Cloud-init user data can be configured when creating a workload or added later in a workload update.

🚧

Updates Do Not Apply To Running Instances

userData is parsed and executed on first boot of the instance. Updates to existing workloads will only apply to future instances in the workload. Existing instances will not have the new userData applied.

Creating a Workload With Cloud-Init User Data

Add your base64 encoded userData to the virtual machine specification. For example, ensure our previously prepared userData is added to the workload spec as per the example below:

{
  "workload": {
    "spec": {
      "virtualMachines": {
        "$DNS_NAME": {
          "userData": "I2Nsb3VkLWNvbmZpZwpwdXBwZXQ6CiBjb25mOgogICBhZ2VudDoKICAgICBzZXJ2ZXI6ICJwdXBwZXRtYXN0ZXIuc3RhY2twYXRoLmNvbSIKICAgICBjZXJ0bmFtZTogIiVpIgogICBjYV9jZXJ0OiB8CiAgICAgLS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCiAgICAgPGNlcnQtZGF0YT4KICAgICAtLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg=="
        }
      }
    }
  }
}

Updating a Workload

🚧

Provide the Current Metadata Version

You must provide the current metadata version when issuing a PATCH request, otherwise the request will fail.

If you want to update or add user data to an existing workload you need to send a PATCH request to update your workload, including the userData configuration in the virtualMachines spec. For example, issue a request similar to below to add our user data example to a virtual machine workload. Update the $STACK_ID and $WORKLOAD_ID in the URL and ensure a valid $BEARER_TOKEN and $DNS_NAME are provided in your API call:

curl -s -X PATCH https://gateway.stackpath.com/workload/v1/stacks/$STACK_ID/workloads/$WORKLOAD_ID \
-H "Authorization: bearer $BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "workload": {
    "spec": {
      "virtualMachines": {
        "$DNS_NAME": {
          "userData": "I2Nsb3VkLWNvbmZpZwpwdXBwZXQ6CiBjb25mOgogICBhZ2VudDoKICAgICBzZXJ2ZXI6ICJwdXBwZXRtYXN0ZXIuc3RhY2twYXRoLmNvbSIKICAgICBjZXJ0bmFtZTogIiVpIgogICBjYV9jZXJ0OiB8CiAgICAgLS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCiAgICAgPGNlcnQtZGF0YT4KICAgICAtLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg=="
        }
      }
    },
    "metadata": {
      "version": "7"
    }
  }
}'