Using Cloud-Init with Virtual Machine Workloads
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 newuserData
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"
}
}
}'
Updated over 3 years ago