Store metadata on a configuration drive¶

Requirements and guidelines¶

To use the configuration drive, you must follow the following requirements for the compute host and image.

Compute host requirements

• The following hypervisors support the configuration drive: libvirt, XenServer, Hyper-V, VMware, and (since 17.0.0 Queens) PowerVM.

  Also, the Bare Metal service supports the configuration drive.

• To use configuration drive with libvirt, XenServer, or VMware, you must first install the genisoimage package on each compute host. Otherwise, instances do not boot properly.

  Use the mkisofs_cmd flag to set the path where you install the genisoimage program. If genisoimage is in same path as the nova-compute service, you do not need to set this flag.

• To use configuration drive with Hyper-V, you must set the mkisofs_cmd value to the full path to an mkisofs.exe installation. Additionally, you must set the qemu_img_cmd value in the hyperv configuration section to the full path to an qemu-img command installation.

• To use configuration drive with PowerVM or the Bare Metal service, you do not need to prepare anything because these treat the configuration drive properly.

Image requirements

• An image built with a recent version of the cloud-init package can automatically access metadata passed through the configuration drive. The cloud-init package version 0.7.1 works with Ubuntu, Fedora based images (such as Red Hat Enterprise Linux) and openSUSE based images (such as SUSE Linux Enterprise Server).
• If an image does not have the cloud-init package installed, you must customize the image to run a script that mounts the configuration drive on boot, reads the data from the drive, and takes appropriate action such as adding the public key to an account. You can read more details about how data is organized on the configuration drive.
• If you use Xen with a configuration drive, use the xenserver.disable_agent configuration parameter to disable the agent.

Guidelines

• Do not rely on the presence of the EC2 metadata in the configuration drive, because this content might be removed in a future release. For example, do not rely on files in the ec2 directory.
• When you create images that access configuration drive data and multiple directories are under the openstack directory, always select the highest API version by date that your consumer supports. For example, if your guest image supports the 2012-03-05, 2012-08-05, and 2013-04-13 versions, try 2013-04-13 first and fall back to a previous version if 2013-04-13 is not present.

Enable and access the configuration drive¶

1. To enable the configuration drive, pass the --config-drive true parameter to the openstack server create command.

   The following example enables the configuration drive and passes user data, a user data file, and two key/value metadata pairs, all of which are accessible from the configuration drive:

   $ openstack server create --config-drive true --image my-image-name \
     --flavor 1 --key-name mykey --user-data ./my-user-data.txt \
     --property role=webservers --property essential=false MYINSTANCE
   

   You can also configure the Compute service to always create a configuration drive by setting the following option in the /etc/nova/nova.conf file:

   force_config_drive = true
   

   It is also possible to force the config drive by specifying the img_config_drive=mandatory property in the image.

   Note

   If a user passes the --config-drive true flag to the openstack server create command, an administrator cannot disable the configuration drive.

2. If your guest operating system supports accessing disk by label, you can mount the configuration drive as the /dev/disk/by-label/configurationDriveVolumeLabel device. In the following example, the configuration drive has the config-2 volume label:

   # mkdir -p /mnt/config
   # mount /dev/disk/by-label/config-2 /mnt/config
   

# blkid -t LABEL="config-2" -odevice

/dev/vdb

# mkdir -p /mnt/config
# mount /dev/vdb /mnt/config

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

{
    "availability_zone": "nova",
    "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"
}

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

config_drive_format=iso9660

[hyperv]
config_drive_cdrom=true

config_drive_format=vfat