2.11. Config drive

Introduction

OpenStack can be configured to write metadata to a special configuration drive that will be attached to the instance when it boots. The instance can retrieve any information that would normally be available through the metadata service by mounting this disk and reading files from it.
One use case for the config drive is to pass networking configuration (such as, IP address, netmask, and gateway) when DHCP is not being used to assign IP addresses to instances. The instance's IP configuration can be transmitted using the config drive, which can be mounted and accessed before the instance's network settings have been configured.
The config drive can be used by any guest operating system that is capable of mounting an ISO9660 or VFAT file system. This functionality should be available on all modern operating systems.

Compute host requirements

Config drive is currently supported by the following hypervisors: libvirt, hyper-v and vmware.
To use config drive with libvirt, or vmware, the genisoimage program must be installed on each compute host. Make sure you install this program on each compute host before attempting to use config drive, or an instance will not boot properly. The path to where genisoimage is installed can be set using the mkisofs_cmd flag. If genisoimage is in the path used by nova-compute you do not need to set the value of this flag.
To use config drive with hyper-v, you must set the value of the mkisofs_cmd to the full path to an installation of mkisofs.exe. Additionally, you will need to set the value of the qemu_img_cmd flag in the hyperv configuration section to the full path to an installation of the qemu-img command.

Image requirements

An image that has been built with a recent version of the cloud-init package will be able to automatically access metadata passed via config drive. The current version of cloud-init has been confirmed to work with Red Hat Enterprise Linux images.
If an image does not have the cloud-init package installed, the image must be customized to run a script that mounts the config drive on boot, reads the data from the drive, and takes appropriate action such as adding the public key to an account. See below for details on how data is organized on the config drive.

Enabling the config drive

To enable the config drive, pass the --config-drive=true parameter when calling nova boot. Here is a complex example that enables the config drive as well as passing user data, two files, and two key/value metadata pairs, all of which are accessible from the config drive.
$ nova boot --config-drive=true --image my-image-name --key-name mykey --flavor 1 --user-data ./my-user-data.txt myinstance --file /etc/network/interfaces=/home/myuser/instance-interfaces --file known_hosts=/home/myuser/.ssh/known_hosts --meta role=webservers --meta essential=false
You can also configure the Compute service to always create a config drive by setting the following option in /etc/nova/nova.conf:
force_config_drive=true

Note

If a user passes the --config-drive=true flag to the nova boot command, an administrator cannot disable the config drive.

Accessing the config drive from inside an instance

The config drive will have a volume label of config-2. If your guest OS supports accessing disk by label, you should be able to mount the config drive as the /dev/disk/by-label/config-2 device. For example:
# mkdir -p /mnt/config
# mount /dev/disk/by-label/config-2 /mnt/config

Note

The cirros 0.3.0 test image does not have support for the config drive. Support will be added in version 0.3.1.
If your guest operating system does not use udev, then the /dev/disk/by-label directory will not be present. The blkid command can be used to identify the block device that corresponds to the config drive. For example, when booting the cirros image with the m1.tiny flavor, the device will be /dev/vdb:
# blkid -t LABEL="config-2" -odevice
/dev/vdb
Once identified, the device can then be mounted:
# mkdir -p /mnt/config
# mount /dev/vdb /mnt/config

Contents of the config drive

The files that will be present in the config drive will vary depending on the arguments that were passed to nova boot. Based on the example above, the contents of the config drive is:
ec2/2009-04-04/meta-data.json
ec2/2009-04-04/user-data
ec2/latest/meta-data.json
ec2/latest/user-data
openstack/2012-08-10/meta_data.json
openstack/2012-08-10/user_data
openstack/content
openstack/content/0000
openstack/content/0001
openstack/latest/meta_data.json
openstack/latest/user_data

Guidelines for accessing config drive data

Do not rely on the presence of the EC2 metadata present in the config drive (i.e., files under the ec2 directory), as this content may be removed in a future release.
When creating images that access config drive data, if there are multiple directories under the openstack directory, always select the highest API version by date that your consumer supports. For example, if your guest image can support versions 2012-03-05, 2012-08-05, 2013-04-13. It is best to try 2013-04-13 first and fall back to an earlier version if 2013-04-13 is not present.

Format of OpenStack metadata

Here is an example of the contents of openstack/2012-08-10/meta_data.json, openstack/latest/meta_data.json (these two files are identical), formatted to improve readability:
{
    "availability_zone": "nova",
    "files": [
        {
            "content_path": "/content/0000",
            "path": "/etc/network/interfaces"
        },
        {
            "content_path": "/content/0001",
            "path": "known_hosts"
        }
    ],
    "hostname": "test.novalocal",
    "launch_index": 0,
    "name": "test",
    "meta": {
            "role": "webservers"
            "essential": "false"
    },
    "public_keys": {
        "mykey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
    },
    "uuid": "83679162-1378-4288-a2d4-70e13ec132aa"
}
Note the effect of the --file /etc/network/interfaces=/home/myuser/instance-interfaces argument passed to the original nova boot command. The contents of this file are contained in the file openstack/content/0000 file on the config drive, and the path is specified as /etc/network/interfaces in the meta_data.json file.

Format of EC2 metadata

Here is an example of the contents of ec2/2009-04-04/meta-data.json, latest/meta-data.json (these two files are identical) formatted to improve readability:
{
    "ami-id": "ami-00000001",
    "ami-launch-index": 0,
    "ami-manifest-path": "FIXME",
    "block-device-mapping": {
        "ami": "sda1",
        "ephemeral0": "sda2",
        "root": "/dev/sda1",
        "swap": "sda3"
    },
    "hostname": "test.novalocal",
    "instance-action": "none",
    "instance-id": "i-00000001",
    "instance-type": "m1.tiny",
    "kernel-id": "aki-00000002",
    "local-hostname": "test.novalocal",
    "local-ipv4": null,
    "placement": {
        "availability-zone": "nova"
    },
    "public-hostname": "test.novalocal",
    "public-ipv4": "",
    "public-keys": {
        "0": {
            "openssh-key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
        }
    },
    "ramdisk-id": "ari-00000003",
    "reservation-id": "r-7lfps8wj",
    "security-groups": [
        "default"
    ]
}

User data

The files openstack/2012-08-10/user_data, openstack/latest/user_data, ec2/2009-04-04/user-data, and ec2/latest/user-data, will only be present if the --user-data flag was passed to nova boot and will contain the contents of the user data file passed as the argument.

Format of the config drive

The default format of the config drive is an ISO 9660 filesystem. To explicitly specify the ISO 9660 format, the following line is in /etc/nova/nova.conf:
config_drive_format=iso9660
By default, you cannot attach the config drive image as a CD drive instead of a disk drive. Change this setting in /etc/nova/nova.conf to true if you want a CD drive attached.
config_drive_cdrom=true
For legacy reasons, the config drive can be configured to use VFAT format instead of ISO 9660. It is unlikely that you would require VFAT format, since ISO 9660 is widely supported across operating systems. However, if you wish to use the VFAT format, add the following line to /etc/nova/nova.conf instead:
config_drive_format=vfat
If you choose VFAT, the config drive is 64 MBs.

Configuration Reference

The following table shows all options for the config drive.

Table 2.3. Description of configuration options for configdrive

Configuration option=Default value Description
config_drive_cdrom=False (BoolOpt) Attaches the Config Drive image as a CD drive instead of a disk drive
config_drive_format=iso9660 (StrOpt) Config drive format. One of iso9660 (default) or vfat
config_drive_inject_password=False (BoolOpt) Sets the admin password in the config drive image
config_drive_skip_versions=1.0 2007-01-19 2007-03-01 2007-08-29 2007-10-10 2007-12-15 2008-02-01 2008-09-01 (StrOpt) List of metadata versions to skip placing into the config drive
config_drive_tempdir=None (StrOpt) Where to put temporary files associated with config drive creation
force_config_drive=None (StrOpt) Set to force injection to take place on a config drive (if set, valid options are: always)
mkisofs_cmd=genisoimage (StrOpt) Name and optionally path of the tool used for ISO image creation