Summary

cloud-init is the Ubuntu package that handles early initialization of a cloud instance. It is installed in the official Ubuntu live server images since the release of 18.04, Ubuntu Cloud Images and also in the official Ubuntu images available on EC2.

Some of the things it configures are:

cloud-init's behavior can be configured via user-data. User-data is passed to cloud-init by the user to the cloud provider at launch time, usually as a parameter in the CLI, template, or cloud portal used to launch an instance.

User Data Input Formats

User data that will be acted upon by cloud-init must be in one of the following types:

User-Data Scripts

As popularized by alestic.com, user-data scripts are a convenient way to do something on first boot of a launched instance. This input format is accepted to cloud-init and handled as you would expect. The script will be invoked at an "rc.local" like point in the boot sequence.

For example:

$ cat myscript.sh
#!/bin/sh
echo "Hello World.  The time is now $(date -R)!" | tee /root/output.txt

$ euca-run-instances --key mykey --user-data-file myscript.sh ami-a07d95c9 

After running the above, you can expect that /root/output.txt will contain the desired text.

Cloud Config Syntax

Cloud Config is the simplest way to accomplish some things via user-data. Using cloud-config syntax, the user can specify certain things in a human friendly format. These things include:

The file must be valid yaml syntax.

Here are some simple examples of what can be done with cloud-config syntax:

Multipart Input

A single format of user data might not be enough to accomplish what you want. For example, you may want to insert an upstart job and also run a user-data script.

There is a tool in cloud-utils's bin/ directory called 'write-mime-multipart' which can aid creating mime multipart content.

Consider the following example:

$ cat my-boothook.txt
#!/bin/sh
echo "Hello World!"
echo "This will run as soon as possible in the boot sequence"

$ cat my-user-script.txt
#!/usr/bin/perl
print "This is a user script (rc.local)\n"

$ cat my-include.txt
# these urls will be read pulled in if they were part of user-data
# comments are allowed.  The format is one url per line
http://www.ubuntu.com/robots.txt
http://www.w3schools.com/html/lastpage.htm

$ cat my-upstart-job.txt
description "a test upstart job"
start on stopped rc RUNLEVEL=[2345]
console output
task
script
echo "====BEGIN======="
echo "HELLO From an Upstart Job"
echo "=====END========"
end script

$ cat my-cloudconfig.txt
#cloud-config
ssh_import_id: [smoser]
apt_sources:
 - source: "ppa:smoser/ppa"

Now, given the files above in the current directory, you can do:

$ ls
my-boothook.txt     my-include.txt      my-user-script.txt
my-cloudconfig.txt  my-upstart-job.txt

$ write-mime-multipart --output=combined-userdata.txt \
   my-boothook.txt:text/cloud-boothook \
   my-include.txt:text/x-include-url \
   my-upstart-job.txt:text/upstart-job \
   my-user-script.txt:text/x-shellscript \
   my-cloudconfig.txt

$ ls -l combined-userdata.txt 
-rw-r--r-- 1 smoser smoser 1782 2010-07-01 16:08 combined-userdata.txt

$ gzip combined-userdata.txt
$ ls -l combined-userdata.txt.gz 
-rw-r--r-- 1 smoser smoser 659 2010-07-01 16:08 combined-userdata.txt.gz

$ euca-run-instances ami-a07d95c9 --user-data-file=combined-userdata.txt.gz

Now, when your instance is booted, you will have

Also, notice

More information

Video:- Introduction to cloud-init

Examples of user-data for cloud-init can be seen in the Github examples directory.

Using cloud-init with example clouds:

Footnotes

  1. The following was output of 'ec2-run-instances --user-data-file=ud.txt' where ud.txt was sufficiently large on 2010-06-28: 'Client.InvalidParameterValue: User data is limited to 16384 bytes' (1)

CloudInit (last edited 2021-07-25 16:34:51 by danielbowers)