=======================================
Store metadata on a configuration drive
=======================================
You can configure OpenStack to write metadata to a special configuration drive
that attaches to the instance when it boots. The instance can mount this drive
and read files from it to get information that is normally available through
the :doc:`metadata service </user/metadata-service>`.
This metadata is different from the :doc:`user data </user/user-data>`.

One use case for using the configuration drive is to pass a networking
configuration when you do not use DHCP to assign IP addresses to
instances. For example, you might pass the IP address configuration for
the instance through the configuration drive, which the instance can
mount and access before you configure the network settings for the
instance.

Any modern guest operating system that is capable of mounting an ISO
9660 or VFAT file system can use the 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
   :command:`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
   :oslo.config:option:`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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#. To enable the configuration drive, pass the ``--config-drive true``
   parameter to the :command:`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:

   .. code-block:: console

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

   .. code-block:: console

      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
      :command:`openstack server create` command, an administrator cannot
      disable the configuration drive.

#. 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:

   .. code-block:: console

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

.. note::

   Ensure that you use at least version 0.3.1 of CirrOS for
   configuration drive support.

   If your guest operating system does not use ``udev``, the
   ``/dev/disk/by-label`` directory is not present.

   You can use the :command:`blkid` command to identify the block device that
   corresponds to the configuration drive. For example, when you boot
   the CirrOS image with the ``m1.tiny`` flavor, the device is
   ``/dev/vdb``:

   .. code-block:: console

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

   .. code-block:: console

      /dev/vdb

   Once identified, you can mount the device:

   .. code-block:: console

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

Configuration drive contents
----------------------------

In this example, the contents of the configuration drive are as follows::

   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

The files that appear on the configuration drive depend on the arguments
that you pass to the :command:`openstack server create` command.

Vendor-specific data can also be exposed to a guest in the configuration
drive. See :doc:`Vendordata </user/vendordata>` for details.

OpenStack metadata format
-------------------------

The following example shows the contents of the
``openstack/2012-08-10/meta_data.json`` and
``openstack/latest/meta_data.json`` files. These files are identical.
The file contents are formatted for readability.

.. code-block:: json

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

EC2 metadata format
-------------------

The following example shows the contents of the
``ec2/2009-04-04/meta-data.json`` and the ``ec2/latest/meta-data.json``
files. These files are identical. The file contents are formatted to
improve readability.

.. code-block:: json

   {
       "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 ``openstack/2012-08-10/user_data``, ``openstack/latest/user_data``,
``ec2/2009-04-04/user-data``, and ``ec2/latest/user-data`` file are
present only if the ``--user-data`` flag and the contents of the user
data file are passed to the :command:`openstack server create` command.

Configuration drive format
--------------------------

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

.. code-block:: console

   config_drive_format=iso9660

By default, you cannot attach the configuration drive image as a CD
drive instead of as a disk drive. To attach a CD drive, add the
following line to the ``/etc/nova/nova.conf`` file:

.. code-block:: console

   [hyperv]
   config_drive_cdrom=true

.. note:: Attaching a configuration drive as a CD drive is only supported
          by the Hyper-V compute driver.

For legacy reasons, you can configure the configuration drive to use
VFAT format instead of ISO 9660. It is unlikely that you would require
VFAT format because ISO 9660 is widely supported across operating
systems. However, to use the VFAT format, add the following line to the
``/etc/nova/nova.conf`` file:

.. code-block:: console

   config_drive_format=vfat

If you choose VFAT, the configuration drive is 64 MB.

.. deprecated:: 19.0.0

   The :oslo.config:option:`config_drive_format` option was deprecated in 19.0.0
   (Stein). The option was originally added as a workaround for a bug in
   libvirt, `#1246201`__, that was resolved in libvirt v1.2.17. As a result,
   this option is no longer necessary or useful.

   __ https://bugs.launchpad.net/nova/+bug/1246201
