Tutorial

In this tutorial, we will create our first cloud-init user data script and deploy it into an LXD container. We’ll be using LXD for this tutorial because it provides first class support for cloud-init user data as well as systemd support. Because it is container based, it allows for quick testing and iterating on our user data definition.

Setup LXD

Skip this section if you already have LXD setup.

Install LXD

$ sudo snap install lxd

If you don’t have snap, you can install LXD using one of the other installation options.

Initialize LXD

$ lxd init --minimal

The minimal configuration should work fine for our purposes. It can always be changed at a later time if needed.

Define our user data

Now that LXD is setup, we can define our user data. Create the following file on your local filesystem at /tmp/my-user-data:

#cloud-config
runcmd:
  - echo 'Hello, World!' > /var/tmp/hello-world.txt

Here we are defining our cloud-init user data in the cloud-config format, using the runcmd module to define a command to run. When applied, it should write Hello, World! to /var/tmp/hello-world.txt.

Launch a container with our user data

Now that we have LXD setup and our user data defined, we can launch an instance with our user data:

$ lxc launch ubuntu:focal my-test --config=user.user-data="$(cat /tmp/my-user-data)"

Verify that cloud-init ran successfully

After launching the container, we should be able to connect to our instance using

$ lxc shell my-test

You should now be in a shell inside the LXD instance. Before validating the user data, let’s wait for cloud-init to complete successfully:

$ cloud-init status --wait
.....
cloud-init status: done
$

We can now verify that cloud-init received the expected user data:

$ cloud-init query userdata
#cloud-config
runcmd:
  - echo 'Hello, World!' > /var/tmp/hello-world.txt

We can also assert the user data we provided is a valid cloud-config:

$ cloud-init schema --system --annotate
Valid cloud-config: system userdata
$

Finally, verify that our user data was applied successfully:

$ cat /var/tmp/hello-world.txt
Hello, World!
$

We can see that cloud-init has consumed our user data successfully!

Tear down

Exit the container shell (i.e., using exit or ctrl-d). Once we have exited the container, we can stop the container using:

$ lxc stop my-test

and we can remove the container using:

$ lxc rm my-test

What’s next?

In this tutorial, we used the runcmd module to execute a shell command. The full list of modules available can be found in modules documentation. Each module contains examples of how to use it.

You can also head over to the examples page for examples of more common use cases.