8df08851d7
Improve some wording and introduce non-breaking spaces. Change-Id: I315968c155f6707b4ae57b00cf96a26b453e1d23 Co-Authored-By: Diane Fleming <diane.fleming@rackspace.com>
274 lines
14 KiB
XML
274 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE chapter [
|
|
<!-- Some useful entities borrowed from HTML -->
|
|
<!ENTITY nbsp " ">
|
|
]>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
|
xml:id="config-drive">
|
|
<title>Store metadata on a configuration drive</title>
|
|
<para>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
|
|
<link
|
|
xlink:href="http://docs.openstack.org/admin-guide-cloud/content/section_metadata-service.html"
|
|
>metadata service</link>.</para>
|
|
<para>One use case for 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
|
|
configuration for the instance through the configuration
|
|
drive, which the instance can mount and access before you
|
|
configure the network settings for the instance.</para>
|
|
<para>Any modern guest operating system that is capable of
|
|
mounting an ISO9660 or VFAT file system can use the
|
|
configuration drive.</para>
|
|
<section xml:id="requirements">
|
|
<title>Requirements and guidelines</title>
|
|
<itemizedlist>
|
|
<title>Compute host requirements</title>
|
|
<listitem>
|
|
<para>The following hypervisors support the
|
|
configuration drive: libvirt, xenserver, hyper-v,
|
|
and vmware.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>To use configuration drive with libvirt,
|
|
xenserver, or vmware, you must first install the
|
|
<package>genisoimage</package> package on each
|
|
compute host. Otherwise, instances do not boot
|
|
properly.</para>
|
|
|
|
<para>Use the <literal>mkisofs_cmd</literal> flag to
|
|
set the path where you install the
|
|
<package>genisoimage</package> program. If
|
|
<package>genisoimage</package> is in same path
|
|
as the <systemitem class="service"
|
|
>nova-compute</systemitem> service, you do not
|
|
need to set this flag.</para>
|
|
<note>
|
|
<para>By default, Ubuntu packages do not install
|
|
this package. See bug <link
|
|
xlink:href="https://bugs.launchpad.net/cloud-archive/+bug/1165174"
|
|
>#1165174</link>.</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>To use configuration drive with hyper-v, you
|
|
must set the <literal>mkisofs_cmd</literal> value
|
|
to the full path to an
|
|
<literal>mkisofs.exe</literal> installation.
|
|
Additionally, you must set the
|
|
<literal>qemu_img_cmd</literal> value in the
|
|
<literal>hyperv</literal> configuration
|
|
section to the full path to an
|
|
<literal>qemu-img</literal> command
|
|
installation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<itemizedlist>
|
|
<title>Image requirements</title>
|
|
<listitem>
|
|
<para>An image built with a recent version of the
|
|
<package>cloud-init</package> package can
|
|
automatically access metadata passed through the
|
|
configuration drive. The
|
|
<package>cloud-init</package> package version
|
|
0.7.1 works with Ubuntu and Fedora-based images,
|
|
such as RHEL.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If an image does not have the
|
|
<package>cloud-init</package> 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. See <xref
|
|
linkend="config_drive_contents"/> for details
|
|
on how data is organized on the configuration
|
|
drive.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you use Xen with a configuration drive, use
|
|
the <literal>xenapi_disable_agent</literal>
|
|
configuration parameter to disable the
|
|
agent.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<itemizedlist>
|
|
<title>Guidelines</title>
|
|
<listitem>
|
|
<para>Do not rely on the presence of the EC2 metadata
|
|
present in the configuration drive, as this
|
|
content might be removed in a future release. For
|
|
example, do not rely on files in the
|
|
<filename>ec2</filename> directory.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>When you create images that access configuration
|
|
drive data and multiple directories are under the
|
|
<filename>openstack</filename> 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,
|
|
2013-04-13 versions, try 2013-04-13 first and fall
|
|
back to a previous version if 2013-04-13 is not
|
|
present.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="enable_config_drive">
|
|
<title>Enable and access the configuration drive</title>
|
|
<procedure>
|
|
<step>
|
|
<para>To enable the configuration drive, pass the
|
|
<literal>--config-drive=true</literal>
|
|
parameter to the <command>nova boot</command>
|
|
command.</para>
|
|
<para>This example enables the configuration drive and
|
|
passes user data, two files, and two key/value
|
|
metadata pairs, all of which are accessible from
|
|
the configuration drive:</para>
|
|
<screen><prompt>$</prompt> <userinput>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</userinput></screen>
|
|
<para>You can also configure the Compute service to
|
|
always create a configuration drive.</para>
|
|
<para>Set this option in the
|
|
<filename>/etc/nova/nova.conf</filename>
|
|
file:</para>
|
|
<programlisting language="ini">force_config_drive=true</programlisting>
|
|
<note>
|
|
<para>If a user passes the
|
|
<parameter>--config-drive=true</parameter>
|
|
flag to the <command>nova boot</command>
|
|
command, an administrator cannot disable the
|
|
configuration drive.</para>
|
|
</note>
|
|
</step>
|
|
<step>
|
|
<para>The configuration drive has the
|
|
<literal>config-2</literal> volume label. If
|
|
your guest operating system supports accessing
|
|
disk by label, you can mount the configuration
|
|
drive as the
|
|
<filename>/dev/disk/by-label/config-2</filename>
|
|
device.</para>
|
|
<para>For example:</para>
|
|
<screen><prompt>#</prompt> <userinput>mkdir -p /mnt/config</userinput>
|
|
<prompt>#</prompt> <userinput>mount /dev/disk/by-label/config-2 /mnt/config</userinput></screen>
|
|
<note>
|
|
<para>Make sure that you use at least version 0.3.1
|
|
of CirrOS for configuration drive support.</para>
|
|
</note>
|
|
<para>If your guest operating system does not use
|
|
<literal>udev</literal>, the
|
|
<filename>/dev/disk/by-label</filename>
|
|
directory is not present.</para>
|
|
<para>You can use the <command>blkid</command> command
|
|
to identify the block device that corresponds to
|
|
the configuration drive. For example, when you
|
|
boot the CirrOS image with the
|
|
<literal>m1.tiny</literal> flavor, the device
|
|
is <filename>/dev/vdb</filename>:</para>
|
|
<screen><prompt>#</prompt> <userinput>blkid -t LABEL="config-2" -odevice</userinput></screen>
|
|
<screen><computeroutput>/dev/vdb</computeroutput></screen>
|
|
<para>Once identified, you can mount the
|
|
device:</para>
|
|
<screen><prompt>#</prompt> <userinput>mkdir -p /mnt/config</userinput>
|
|
<prompt>#</prompt> <userinput>mount /dev/vdb /mnt/config</userinput></screen>
|
|
</step>
|
|
</procedure>
|
|
<simplesect xml:id="config_drive_contents">
|
|
<title>Configuration drive contents</title>
|
|
<para>In this example, the contents of the configuration
|
|
drive are:</para>
|
|
<screen><computeroutput>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</computeroutput></screen>
|
|
<para>The files that appear on the configuration drive
|
|
depend on the arguments that you pass to the
|
|
<command>nova boot</command> command.</para>
|
|
</simplesect>
|
|
<simplesect xml:id="os_metadata_format">
|
|
<title>OpenStack metadata format</title>
|
|
<para>The following example shows the contents of the
|
|
<filename>openstack/2012-08-10/meta_data.json</filename>
|
|
and
|
|
<filename>openstack/latest/meta_data.json</filename>
|
|
files. These files are identical. The file contents
|
|
are formatted for readability:</para>
|
|
<programlisting language="json"><xi:include parse="text" href="samples/meta_data.json"/></programlisting>
|
|
<para>Note the effect of the <literal>--file
|
|
/etc/network/interfaces=/home/myuser/instance-interfaces</literal>
|
|
argument that was passed to the <command>nova
|
|
boot</command> command. The contents of this file
|
|
are contained in the
|
|
<filename>openstack/content/0000</filename> file
|
|
on the configuration drive, and the path is specified
|
|
as <filename>/etc/network/interfaces</filename> in the
|
|
<filename>meta_data.json</filename> file.</para>
|
|
</simplesect>
|
|
<simplesect xml:id="ec2_metadata_format">
|
|
<title>EC2 metadata format</title>
|
|
<para>The following example shows the contents of the
|
|
<filename>ec2/2009-04-04/meta-data.json</filename>,
|
|
<filename>latest/meta-data.json</filename> files.
|
|
These files are identical. The file contents are
|
|
formatted to improve readability:</para>
|
|
<programlisting language="json"><xi:include href="samples/meta_data_ec2.json" parse="text"/></programlisting>
|
|
</simplesect>
|
|
<simplesect xml:id="user_data">
|
|
<title>User data</title>
|
|
<para>The
|
|
<filename>openstack/2012-08-10/user_data</filename>,
|
|
<filename>openstack/latest/user_data</filename>,
|
|
<filename>ec2/2009-04-04/user-data</filename>, and
|
|
<filename>ec2/latest/user-data</filename> file are
|
|
present only if the <literal>--user-data</literal>
|
|
flag and the contents of the user data file are passed
|
|
to the <command>nova boot</command> command.</para>
|
|
</simplesect>
|
|
<simplesect xml:id="config_drive_format">
|
|
<title>Configuration drive format</title>
|
|
<para>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
|
|
<filename>/etc/nova/nova.conf</filename>
|
|
file:</para>
|
|
<programlisting language="ini">config_drive_format=iso9660</programlisting>
|
|
<para>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 this line to the
|
|
<filename>/etc/nova/nova.conf</filename>
|
|
file:</para>
|
|
<programlisting language="ini">config_drive_cdrom=true</programlisting>
|
|
<para>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
|
|
<filename>/etc/nova/nova.conf</filename>
|
|
file:</para>
|
|
<programlisting language="ini">config_drive_format=vfat</programlisting>
|
|
<para>If you choose VFAT, the configuration drive is
|
|
64 MB.</para>
|
|
</simplesect>
|
|
</section>
|
|
<section xml:id="config_reference">
|
|
<title>Configuration drive reference</title>
|
|
<para>The following table shows the configuration options for
|
|
the configuration drive:</para>
|
|
<xi:include href="../common/tables/nova-configdrive.xml"/>
|
|
</section>
|
|
</section>
|