Config drive

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 (e.g., IP address, netmask, 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.

In addition, 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 as of this writing (0.7.1) has been confirmed to work with Ubuntu, as well as Fedora-based images such as RHEL.

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.

	Note
	To use config drive, the genisoimage program must be installed on each compute host. In the Ubuntu packages, it is not installed by default (see bug #1165174). Make sure you install this program on each compute host before attempting to use config drive, or an instance will not boot properly.

	Note
	If you use Xen with a config drive, disable the agent through the xenapi_disable_agent configuration parameter.

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 will be accessible from the config drive as described below.

$ 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
	As of this writing, there is no mechanism for an administrator to disable use of the config drive if a user passes the --config-drive=true flag to the nova boot command.

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

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 would be:

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

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 it 2013-04-13 isn't present.

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.

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 readbility:

{
    "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"
    ]
}

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.

The default format of the config drive as an ISO 9660 filesystem. To explicitly specify the ISO 9660 format, add the following line to /etc/nova/nova.conf:

config_drive_format=iso9660

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 VFAT is chosen, the config drive will be 64MB in size.

The following table contains all options for config drive.