Using cloud-init with User Data

This technical guide provides a step-by-step approach to using cloud-init in an OUTSCALE instance, to implement automation in the Cloud environment.

Indeed, when you create an instance in the OUTSCALE Cloud, you can transmit user data to this instance. These user data are used to execute scripts or automated configuration tasks.

Prerequisites

Ensure the following:

  • This page assumes a knowledge of cloud-init. For a more general introduction to that tool, see Introduction to cloud-init.

  • The instance must have a public DNS name, accessible from the Internet.

  • The security group of the instance must authorize SSH, HTTP, and HTTPS connections.

By default, user data scripts and cloud-init directives are executed only on the first start cycle of the instance.

Method of User Data Definition

You can define user data for your instance in different ways:

  • With the Cockpit web interface in Expert mode, as plain text

  • With the Cockpit web interface in Expert mode, as single or multipart MIME-type file

    It is the latter method that will be used for the step-by-step approach in the rest of this page.

  • By API request with a Base64-encoded text string

    The following example shows how to specify the content of a local file as a Base64-encoded text string in a command-line request:

    $ osc-cli api CreateVms \
    --ImageId "ami-abcd1234" \
    --KeypairName "my-key-pair" \
    --VmType "tinav4.c1r1p2" \
    --SubnetId "subnet-abcd1234" \
    --SecurityGroupIds "['sg-abcd1234']" \
    --UserData "$(cat my_script | base64)"

    For more information, see Installing and Configuring OSC CLI.

Step-by-Step Approach: User Data in Cockpit with MIME-type Files as Input

1/ Create an Instance

Follow the instance creation procedure in the page Expert Mode: Launching Instances Using Cockpit, until you reach the User Data screen.

In the next steps, we use an instance created from an Ubuntu OUTSCALE Machine Image (OMI).

2/ Write the User Data

Example 1: Modification of the Hostname (via text/cloud-config Content)

In this example, we request a modification of the hostname (implicitly using the set_hostname module of cloud_init_modules that is configured by default in the official Ubuntu OMI).

Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
#cloud-config
##Update hostname at first boot
hostname: test-userdata

Example 2: Installation of Packages (via text/cloud-config Content)

In this example, we request the installation of the python-pip package. To do so, we must first enable the package-update-upgrade-install module (which is by default disabled in the official Ubuntu OMI) by explicitly calling the cloud_config_modules directive.

Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
#cloud-config
cloud_config_modules:
- package-update-upgrade-install
package_update: true
cloud_final_modules:
- [scripts-user, always]
##Install python-pip package
packages:
 - python-pip

Example 3: Writing to Files or to the Console Output (via text/x-shellscript Content)

In this example, we request the execution of some instructions defined in shell scripts (/bin/sh and /bin/bash):

  • Writing to the console output (/dev/ttyS0)

  • Writing to new files (/root/output.txt and /tmp/output.txt)

  • Modifying existing files (/root/.bashrc and /root/.vimrc)

The text/x-shellscript content type provides the user script that the cloud_final_modules module of cloud-init must execute.

Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
#!/bin/sh
##Writing in file
echo "Hello there. This is written with append." >> /root/output.txt
##Writing to console
echo "Hello there." >> /dev/ttyS0
#!/bin/bash
##Writing in file
/bin/echo "Hello there." >> /tmp/output.txt

cat > /root/.bashrc <<EOF
set -o vi
unalias -a
alias ll='ls -l'
EOF
touch /root/.vimrc
cat > /root/.vimrc <<EOF
set t_ti= t_te=
set compatible
set expandtab ts=2 sw=2 ai
EOF

Example 4: Combination of text/cloud-config and text/x-shellscript Contents

  • Cloud-init behaves differently depending on the format of user data. One of the most widespread formats for user data scripts, aside from the shell format, is the cloud-config format.

  • By default, cloud-init authorizes only one content type at a time in the user data.

  • A multipart MIME-type file enables the script to switch the way the user data are executed by cloud-init. For more information on multipart MIME-type files, see Mime Multi Part Archive on the cloud-init website.

In this example, we request the execution of scripts by successively using the text/cloud-config and text/x-shellscript content types seen previously, in one multipart MIME-type file.

Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0

--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"

#cloud-config
package_update: true
# update hostname
hostname: test-userdata

--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
#!/bin/bash
/bin/echo "Hello there." >> /tmp/output.txt
--//

In this combined case:

  1. Start the user data by the header:

    Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0

  2. Prepend each cloud-config part and x-shellscript part with the characters --//.

  3. End the user data with the characters --//.

3/ Paste the User Data in the Free Section Field

Paste the user data in the Free section field of the User Data screen of Cockpit.

4/ Confirm the Instance Creation

Click Next and then the final confirmation button to create the instance.

Verification of the User Data

To verify the user data transmitted to the instance, you can connect to the instance and launch the following Curl command:

$ curl http://169.254.169.254/latest/user-data

To verify that the instructions are executed, you can check:

  • The console output in Cockpit. For more information, see Viewing the Console Output of an Instance.

  • The logs of cloud-init, available in the file /var/log/cloud-init-output.log in the case of an Ubuntu instance.

    Instances created from CentOS official OMIs do not include cloud-init-output.log.

Related Pages