Updated/edited Image chapter.

Install: Added short intro. Turned steps into procedures.
  Fixed the credentials. Added note about using IP address.
  Commented out redundant config.
Verify: Added link to Virtual Machine Image Guide. Turned steps into procedure.
  Added info about -is-public value.

Change-Id: I27b8397957ac352b25e868d821e9c921d6ec80c9
This commit is contained in:
Summer Long 2013-10-10 11:55:23 +10:00 committed by Andreas Jaeger
parent 9c0396e981
commit eaf681ed5a
2 changed files with 168 additions and 155 deletions

View File

@ -7,107 +7,97 @@
xmlns:html="http://www.w3.org/1999/xhtml"
version="5.0">
<title>Installing the Image Service</title>
<para>Install the Image Service on the controller node.</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>sudo apt-get install glance</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-glance</userinput></screen>
<screen os="opensuse"><prompt>#</prompt> <userinput>zypper install openstack-glance</userinput></screen>
<para>The Image Service stores information about images in a database.
This guide uses the MySQL database used by other OpenStack services.
<phrase os="ubuntu">The Ubuntu packages create an sqlite database by
default. Delete the <filename>glance.sqlite</filename> file created in
the <filename>/var/lib/glance/</filename> directory.</phrase></para>
<para>Use the <command>openstack-db</command> command to create the
database and tables for the Image Service, as well as a database user
called <literal>glance</literal> to connect to the database. Replace
<literal><replaceable>GLANCE_DBPASS</replaceable></literal> with a
password of your choosing.</para>
<screen><prompt>#</prompt> <userinput>openstack-db --init --service glance --password <replaceable>GLANCE_DBPASS</replaceable></userinput></screen>
<para>You now have to tell the Image Service to use that database. The Image
Service provides two OpenStack services: <literal>glance-api</literal> and
<literal>glance-registry</literal>. They each have separate configuration
files, so you will have to configure both throughout this section.</para>
<screen><prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-api.conf \
DEFAULT sql_connection mysql://glance:<replaceable>GLANCE_PASS</replaceable>@controller/glance</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-registry.conf \
DEFAULT sql_connection mysql://glance:<replaceable>GLANCE_PASS</replaceable>@controller/glance</userinput></screen>
<para>Create a user called <literal>glance</literal> that the Image
Service can use to authenticate with the Identity Service. Use the
<literal>service</literal> tenant and give the user the
<literal>admin</literal> role.</para>
<para>The Image service acts as a registry for virtual disk images. Users can add new images
or take a snapshot (copy) of an existing server for immediate storage. Snapshots can be
used as back up or as templates for new servers. Registered images can be stored in the
Object Storage service, as well as in other locations (for example, in simple file
systems or external web servers).</para>
<note>
<para>These examples assume you have the appropriate environment
variables set to specify your credentials, as described in
<xref linkend="keystone-verify"/>.</para>
<para>Steps in this procedure assume you have the appropriate environment
variables set to specify your credentials, as described in
<xref linkend="keystone-verify"/>.</para>
</note>
<screen><prompt>#</prompt> <userinput>keystone user-create --name=glance --pass=<replaceable>GLANCE_PASS</replaceable> --email=<replaceable>glance@example.com</replaceable></userinput>
<prompt>#</prompt> <userinput>keystone user-role-add --user=glance --tenant=service --role=admin</userinput></screen>
<para>For the Image Service to use these credentials, you have to add
them to the configuration files.</para>
<screen><prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-api.conf keystone_authtoken auth_host controller</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-api.conf keystone_authtoken admin_user keystone</userinput>
<procedure>
<title>Install the Image Service</title>
<step><para>Install the Image Service on the controller node.</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>sudo apt-get install glance</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-glance</userinput></screen>
<screen os="opensuse"><prompt>#</prompt> <userinput>zypper install openstack-glance</userinput></screen></step>
<step><para>The Image Service stores information about images in a database.
This guide uses the MySQL database used by other OpenStack services.
<phrase os="ubuntu">The Ubuntu packages create an sqlite database by
default. Delete the <filename>glance.sqlite</filename> file created in
the <filename>/var/lib/glance/</filename> directory.</phrase></para>
<para>Use the <command>openstack-db</command> command to create the
database and tables for the Image Service, as well as a database user
called <literal>glance</literal> to connect to the database. Replace
<literal><replaceable>GLANCE_DBPASS</replaceable></literal> with a
password of your choosing.</para>
<screen><prompt>#</prompt> <userinput>openstack-db --init --service glance --password <replaceable>GLANCE_DBPASS</replaceable></userinput></screen></step>
<step><para>Tell the Image Service to use the created database. The Image Service provides two OpenStack
services: <literal>glance-api</literal> and <literal>glance-registry</literal>. They each
have separate configuration files, so you must configure both files throughout this
section.</para>
<screen><prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-api.conf \
DEFAULT sql_connection mysql://glance:<replaceable>GLANCE_PASS</replaceable>@<replaceable>controller</replaceable>/glance</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-registry.conf \
DEFAULT sql_connection mysql://glance:<replaceable>GLANCE_PASS</replaceable>@<replaceable>controller</replaceable>/glance</userinput></screen></step>
<step><para>Create a user called <literal>glance</literal> that the Image
Service can use to authenticate with the Identity Service. Use the
<literal>service</literal> tenant and give the user the
<literal>admin</literal> role.</para>
<screen><prompt>#</prompt> <userinput>keystone user-create --name=glance --pass=<replaceable>GLANCE_PASS</replaceable> --email=<replaceable>glance@example.com</replaceable></userinput>
<prompt>#</prompt> <userinput>keystone user-role-add --user=glance --tenant=service --role=admin</userinput></screen></step>
<step><para>Add the credentials to the Image Service's configuration files.</para>
<screen><prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-api.conf keystone_authtoken auth_host <replaceable>controller</replaceable></userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-api.conf keystone_authtoken admin_user glance</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-api.conf keystone_authtoken admin_tenant_name service</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-api.conf keystone_authtoken admin_password <replaceable>GLANCE_PASS</replaceable></userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-registry.conf keystone_authtoken auth_host controller</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-registry.conf keystone_authtoken admin_user keystone</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-registry.conf keystone_authtoken auth_host <replaceable>controller</replaceable></userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-registry.conf keystone_authtoken admin_user glance</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-registry.conf keystone_authtoken admin_tenant_name service</userinput>
<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-registry.conf keystone_authtoken admin_password <replaceable>GLANCE_PASS</replaceable></userinput></screen>
<para>You also have to add the credentials to the files
<!-- <para>You also have to add the credentials to the files
<filename>/etc/glance/glance-api-paste.ini</filename> and
<filename>/etc/glance/glance-registry-paste.ini</filename>. Open each file
in a text editor and locate the section <literal>[filter:authtoken]</literal>.
Make sure the following options are set:</para>
<programlisting language="ini">[filter:authtoken]
paste.filter_factory=keystoneclient.middleware.auth_token:filter_factory
auth_host=controller
admin_user=glance
admin_tenant_name=service
admin_password=<replaceable>GLANCE_PASS</replaceable>
</programlisting>
<para>You have to register the Image Service with the Identity Service
so that other OpenStack services can locate it. Register the service and
specify the endpoint using the <command>keystone</command> command.</para>
<screen><prompt>#</prompt> <userinput>keystone service-create --name=glance --type=image \
--description="Glance Image Service"</userinput></screen>
<para>Note the <literal>id</literal> property returned and use it when
creating the endpoint.</para>
<screen><prompt>#</prompt> <userinput>keystone endpoint-create \
admin_password=<replaceable>GLANCE_PASS</replaceable></programlisting> -->
<para>
<note><para>If you have troubles connecting to the database, try using the IP address instead of the
host name in the credentials.</para></note>
</para></step>
<step><para>Register the Image Service with the Identity Service
so that other OpenStack services can locate it. Register the service and
specify the endpoint using the <command>keystone</command> command.</para>
<screen><prompt>#</prompt> <userinput>keystone service-create --name=glance --type=image \
--description="Glance Image Service"</userinput></screen></step>
<step><para>Note the service's <literal>id</literal> property returned in the previous step and use it when
creating the endpoint.</para>
<screen><prompt>#</prompt> <userinput>keystone endpoint-create \
--service-id=<replaceable>the_service_id_above</replaceable> \
--publicurl=http://controller:9292 \
--internalurl=http://controller:9292 \
--adminurl=http://controller:9292</userinput></screen>
<para>Finally, start the <literal>glance-api</literal> and
<literal>glance-registry</literal> services and configure them to
start when the system boots.</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>service glance-api start</userinput>
--publicurl=http://<replaceable>controller</replaceable>:9292 \
--internalurl=http://<replaceable>controller</replaceable>:9292 \
--adminurl=http://<replaceable>controller</replaceable>:9292</userinput></screen></step>
<step><para>Start the <literal>glance-api</literal> and
<literal>glance-registry</literal> services and configure them to
start when the system boots.</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>service glance-api start</userinput>
<prompt>#</prompt> <userinput>service glance-registry start</userinput>
<prompt>#</prompt> <userinput>chkconfig glance-api on</userinput>
<prompt>#</prompt> <userinput>chkconfig glance-registry on</userinput></screen>
<screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>service openstack-glance-api start</userinput>
<screen os="rhel;fedora;centos"><prompt>#</prompt> <userinput>service openstack-glance-api start</userinput>
<prompt>#</prompt> <userinput>service openstack-glance-registry start</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-glance-api on</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-glance-registry on</userinput></screen>
<screen os="opensuse"><prompt>#</prompt> <userinput>systemctl start openstack-glance-api.service</userinput>
<screen os="opensuse"><prompt>#</prompt> <userinput>systemctl start openstack-glance-api.service</userinput>
<prompt>#</prompt> <userinput>systemctl start openstack-glance-registry.service</userinput>
<prompt>#</prompt> <userinput>systemctl enable openstack-glance-api.service</userinput>
<prompt>#</prompt> <userinput>systemctl enable openstack-glance-registry.service</userinput></screen>
<prompt>#</prompt> <userinput>systemctl enable openstack-glance-registry.service</userinput></screen></step>
</procedure>
</section>

View File

@ -4,29 +4,96 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Verifying the Image Service Installation</title>
<para>To test the Image Service installation, download some virtual machine
images that are known to work with OpenStack. CirrOS is a small test image
that is often used for testing OpenStack deployments. You can find the most
recent CirrOS image on their <link
xlink:href="http://download.cirros-cloud.net/">download page</link>. As of
this writing the most recent image is version 0.3.1. A 64-bit version in
QCOW2 format (compatible with KVM or QEMU hypervisors) can be downloaded
from there.</para>
<para>The 64-bit CirrOS QCOW2 image is the image we'll use for this
walkthrough. More detailed information about how to obtain and create
images can be found in the <link
xlink:href="http://docs.openstack.org">OpenStack Compute Administration
Guide</link> in the "Image Management" chapter.</para>
<para>The download is done in a dedicated directory:</para>
<screen><prompt>$</prompt> <userinput>mkdir images</userinput>
<para>To test the Image Service installation, download at least one virtual machine image that
is known to work with OpenStack. For example, CirrOS is a small test image that is often
used for testing OpenStack deployments (<link xlink:href="http://download.cirros-cloud.net/"
>CirrOS downloads</link>). The 64-bit CirrOS QCOW2 image is the image we'll use for this
walkthrough.</para>
<para>For more information about:</para>
<para>
<itemizedlist>
<listitem>
<para>Downloading and building images, refer to the <link
xlink:href="http://docs.openstack.org/image-guide/content/index.html"
><citetitle>OpenStack Virtual Machine Image Guide</citetitle></link>.
</para>
</listitem>
<listitem>
<para>How to manage images, refer to the "Image Management" chapter in the <link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_manage_images.html"><citetitle>OpenStack User
Guide</citetitle></link>.</para>
</listitem>
</itemizedlist>
</para>
<procedure>
<title>Upload and View an Image in the Image Service</title>
<step><para>Download the image into a dedicated directory:</para>
<screen><prompt>$</prompt> <userinput>mkdir images</userinput>
<prompt>$</prompt> <userinput>cd images/</userinput>
<prompt>$</prompt> <userinput>curl -O http://cdn.download.cirros-cloud.net/0.3.1/cirros-0.3.1-x86_64-disk.img</userinput></screen>
<para>You can now use the <command>glance image-create</command> command to
upload the image to the Image Service, passing the image file through
standard input:</para>
<screen><prompt>#</prompt> <userinput>glance image-create --name="CirrOS 0.3.1" --disk-format=qcow2 \
<prompt>$</prompt> <userinput>curl -O http://cdn.download.cirros-cloud.net/0.3.1/cirros-0.3.1-x86_64-disk.img</userinput></screen></step>
<step><para>Use the <command>glance image-create</command> command to upload the image to the Image
Service, as follows:</para>
<para><screen><prompt>#</prompt> <userinput>glance image-create --name=<replaceable>imageLabel</replaceable> --disk-format=<replaceable>fileFormat</replaceable> \
--container-format=<replaceable>containerFormat</replaceable> --is-public=<replaceable>accessValue</replaceable> &lt; <replaceable>imageFile</replaceable></userinput></screen></para>
<para>Where: <variablelist>
<varlistentry>
<term><literal><replaceable>imageLabel</replaceable></literal></term>
<listitem>
<para>Arbitrary label. This is the name by which users will refer to the image.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal><replaceable>fileFormat</replaceable></literal></term>
<listitem>
<para>Specifies the format of the image file. Valid formats include
<literal>qcow2</literal>, <literal>raw</literal>,
<literal>vhd</literal>, <literal>vmdk</literal>,
<literal>vdi</literal>, <literal>iso</literal>,
<literal>aki</literal>, <literal>ari</literal>, and
<literal>ami</literal>.</para>
<para>You can verify the format using the <command>file</command>
command:
<screen><prompt>$</prompt> <userinput>file cirros-0.3.1-x86_64-disk.img</userinput>
<computeroutput>cirros-0.3.1-x86_64-disk.img: QEMU QCOW Image (v2), 41126400 bytes</computeroutput></screen></para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal><replaceable>containerFormat</replaceable></literal></term>
<listitem>
<para>Specifies the container format. Valid formats include:
<literal>bare</literal>, <literal>ovf</literal>,
<literal>aki</literal>, <literal>ari</literal> and
<literal>ami</literal>.</para>
<para>Specify <literal>bare</literal> to indicate that the image file is
not in a file format that contains metadata about the virtual
machine. Although this field is currently required, it is not
actually used by any of the OpenStack services and has no effect on
system behavior. Because the value is not used anywhere, it safe to
always specify <literal>bare</literal> as the container
format.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal><replaceable>accessValue</replaceable></literal></term>
<listitem>
<para>Specifies image access:
<itemizedlist>
<listitem><para>true - All users will be able to view
and use the image.</para></listitem>
<listitem><para>false - Only administrators will be
able to view and use the image.</para></listitem>
</itemizedlist></para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal><replaceable>imageFile</replaceable></literal></term>
<listitem>
<para>Specifies the name of your downloaded image file.</para>
</listitem>
</varlistentry>
</variablelist></para>
<para>For example:</para>
<screen><prompt>#</prompt> <userinput>glance image-create --name="CirrOS 0.3.1" --disk-format=qcow2 \
--container-format=bare --is-public=true &lt; cirros-0.3.1-x86_64-disk.img</userinput>
<computeroutput>+------------------+--------------------------------------+
| Property | Value |
@ -48,62 +115,18 @@
| status | active |
| updated_at | 2013-05-08T18:59:18 |
+------------------+--------------------------------------+</computeroutput></screen>
<note>
<para>The returned image ID is generated dynamically, and therefore
will be different on your deployment than in this example.</para>
</note>
<para>The rationale for the arguments is:
<variablelist>
<varlistentry>
<term><literal>name="CirrOS 0.3.1"</literal></term>
<listitem>
<para>The <literal>name</literal> field is an arbitrary label. In this example
the name encodes the distribution and version:
<literal>CirrOS 0.3.1</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>disk-format=qcow2</literal></term>
<listitem>
<para>The <literal>disk-format</literal> field specifies the format of the image
file. In this case, the image file format is QCOW2, which can be verified
using the <command>file</command> command:
<screen><prompt>$</prompt> <userinput>file cirros-0.3.1-x86_64-disk.img</userinput>
<computeroutput>cirros-0.3.1-x86_64-disk.img: QEMU QCOW Image (v2), 41126400 bytes</computeroutput></screen>
</para>
<para>Other valid formats are <literal>raw</literal>, <literal>vhd</literal>,
<literal>vmdk</literal>, <literal>vdi</literal>, <literal>iso</literal>,
<literal>aki</literal>, <literal>ari</literal> and
<literal>ami</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>container-format=bare</literal></term>
<listitem>
<para>The <literal>container-format</literal> field is required by the
<command>glance image-create</command> command but isn't actually used by any of
the OpenStack services, so the value specified here has no effect on system
behavior. We specify <literal>bare</literal> to indicate that the image file
is not in a file format that contains metadata about the virtual
machine.</para>
<para>Because the value is not used anywhere, it safe to always specify
<literal>bare</literal> as the container format, although the command
will accept other formats: <literal>ovf</literal>, <literal>aki</literal>,
<literal>ari</literal> and <literal>ami</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>Now a <userinput>glance image-list</userinput> should show the image attributes:</para>
<screen><prompt>#</prompt> <userinput>glance image-list</userinput>
<note>
<para>The returned image ID is generated dynamically, and therefore
will be different on your deployment than in this example.</para>
</note>
</step>
<step><para>Use the <userinput>glance image-list</userinput> command to confirm
that the image has been uploaded and to display its attributes:</para>
<screen><prompt>#</prompt> <userinput>glance image-list</userinput>
<computeroutput>+--------------------------------------+-----------------+-------------+------------------+----------+--------+
| ID | Name | Disk Format | Container Format | Size | Status |
+--------------------------------------+-----------------+-------------+------------------+----------+--------+
| acafc7c0-40aa-4026-9673-b879898e1fc2 | CirrOS 0.3.1 | qcow2 | bare | 13147648 | active |
+--------------------------------------+-----------------+-------------+------------------+----------+--------+</computeroutput></screen>
+--------------------------------------+-----------------+-------------+------------------+----------+--------+</computeroutput></screen></step>
</procedure>
</section>