d90fbeadc5
The duplicate in doc/common/section_getstart_object-storage.xml will be removed with https://review.openstack.org/#/c/106834/ . Change-Id: I1f98a479568be9f07a324e60a2dffb9d348f25e4
254 lines
14 KiB
XML
254 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE chapter [
|
|
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
|
|
%openstack;
|
|
]>
|
|
<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>. This metadata is different from the user
|
|
data.</para>
|
|
<para>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.</para>
|
|
<para>Any modern guest operating system that is capable of mounting an ISO
|
|
9660 or VFAT file system can use the configuration drive.</para>
|
|
<section xml:id="requirements">
|
|
<title>Requirements and guidelines</title>
|
|
<para>To use the configuration drive, you must follow the following
|
|
requirements for the compute host and image.</para>
|
|
<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>
|
|
</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 Red Hat Enterprise Linux.</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 about 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 in the
|
|
configuration drive, because 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, and 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>The following 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 by setting the following 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
|
|
<literal>--config-drive=true</literal> flag to the
|
|
<command>nova boot</command> command, an
|
|
administrator cannot disable the configuration
|
|
drive.</para>
|
|
</note>
|
|
</step>
|
|
<step>
|
|
<para>If your guest operating system supports accessing disk by
|
|
label, you can mount the configuration drive as the
|
|
<filename>/dev/disk/by-label/<replaceable>configurationDriveVolumeLabel</replaceable></filename>
|
|
device. In the following example, the configuration drive
|
|
has the <filename>config-2</filename> volume label.</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>Ensure 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
|
|
as follows:</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> and the
|
|
<filename>ec2/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
|
|
the following 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>
|