Red Hat Training

A Red Hat training course is available for Red Hat OpenStack Platform

4.8. Creating a customized instance

Cloud users can specify additional data to use when they launch an instance, such as a shell script that the instance runs on boot. The cloud user can use the following methods to pass data to instances:

User data
Use to include instructions in the instance launch command for cloud-init to execute.
Instance metadata
A list of key-value pairs that you can specify when you create or update an instance.

You can access the additional data passed to the instance by using a config drive or the metadata service.

Config drive
You can attach a config drive to an instance when it boots. The config drive is presented to the instance as a read-only drive. The instance can mount this drive and read files from it. You can use the config drive as a source for cloud-init information. Config drives are useful when combined with cloud-init for server bootstrapping, and when you want to pass large files to your instances. For example, you can configure cloud-init to automatically mount the config drive and run the setup scripts during the initial instance boot. Config drives are created with the volume label of config-2, and attached to the instance when it boots. The contents of any additional files passed to the config drive are added to the user_data file in the openstack/{version}/ directory of the config drive. cloud-init retrieves the user data from this file.
Metadata service
Uses a REST API to retrieve data specific to an instance. Instances access this service at or at fe80::a9fe:a9fe.

cloud-init can use both a config drive and the metadata service to consume the additional data for customizing an instance. The cloud-init package supports several data input formats. Shell scripts and the cloud-config format are the most common input formats:

  • Shell scripts: The data declaration begins with #! or Content-Type: text/x-shellscript. Shell scripts are invoked last in the boot process.
  • cloud-config format: The data declaration begins with #cloud-config or Content-Type: text/cloud-config. cloud-config files must be valid YAML to be parsed and executed by cloud-init.

cloud-init has a maximum user data size of 16384 bytes for data passed to an instance. You cannot change the size limit, therefore use gzip compression when you need to exceed the size limit.

4.8.1. Customizing an instance by using user data

You can use user data to include instructions in the instance launch command. cloud-init executes these commands to customize the instance as the last step in the boot process.


  1. Create a file with instructions for cloud-init. For example, create a bash script that installs and enables a web server on the instance:

    $ vim /home/scripts/install_httpd
    yum -y install httpd python-psycopg2
    systemctl enable httpd --now
  2. Launch an instance with the --user-data option to pass the bash script:

    $ openstack server create \
    --image rhel8 \
    --flavor default \
    --nic net-id=web-server-network \
    --security-group default \
    --key-name web-server-keypair \
    --user-data /home/scripts/install_httpd \
    --wait web-server-instance
  3. When the instance state is active, attach a floating IP address:

    $ openstack floating ip create web-server-network
    $ openstack server add floating ip web-server-instance
  4. Log in to the instance with SSH:

    $ ssh -i ~/.ssh/web-server-keypair cloud-user@
  5. Check that the customization was successfully performed. For example, to check that the web server has been installed and enabled, enter the following command:

    $ curl http://localhost | grep Test
    <title>Test Page for the Apache HTTP Server on Red Hat Enterprise Linux</title>
    <h1>Red Hat Enterprise Linux <strong>Test Page</strong></h1>
  6. Review the /var/log/cloud-init.log file for relevant messages, such as whether or not the cloud-init executed:

    $ sudo less /var/log/cloud-init.log
    ...output omitted...[DEBUG]: Cloud-init v. 0.7.9 finished at Sat, 23 Jun 2018 02:26:02 +0000. Datasource DataSourceOpenStack [net,ver=2].  Up 21.25 seconds