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

doc/install-guide/section_glance-install.xml

@@ -7,96 +7,86 @@
     xmlns:html="http://www.w3.org/1999/xhtml"
     version="5.0">
   <title>Installing the Image Service</title>
-
+  <para>The Image service acts as a registry for virtual disk images. Users can add new images
-  <para>Install the Image Service on the controller node.</para>
+  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>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>
+  <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>
+      <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.
-  <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>
-  <screen><prompt>#</prompt> <userinput>openstack-db --init --service glance --password <replaceable>GLANCE_DBPASS</replaceable></userinput></screen>
+    <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
-  <para>You now have to tell the Image Service to use that database. The Image
+        have separate configuration files, so you must configure both files throughout this
-  Service provides two OpenStack services: <literal>glance-api</literal> and
+        section.</para>
-  <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>
+  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>@controller/glance</userinput></screen>
+  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
-  <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>
-
-  <note>
-    <para>These examples 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>
+<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>
-  <para>For the Image Service to use these credentials, you have to add
+      <screen><prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-api.conf keystone_authtoken auth_host <replaceable>controller</replaceable></userinput>
-  them to the configuration files.</para>
+<prompt>#</prompt> <userinput>openstack-config --set /etc/glance/glance-api.conf keystone_authtoken admin_user glance</userinput>
-
-  <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>
 <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 auth_host <replaceable>controller</replaceable></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 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>
+admin_password=<replaceable>GLANCE_PASS</replaceable></programlisting> -->
-</programlisting>
+      <para>
-
+        <note><para>If you have troubles connecting to the database, try using the IP address instead of the
-  <para>You have to register the Image Service with the Identity Service
+          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>
+  --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
-  <para>Note the <literal>id</literal> property returned 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 \
+  --publicurl=http://<replaceable>controller</replaceable>:9292 \
-  --internalurl=http://controller:9292 \
+  --internalurl=http://<replaceable>controller</replaceable>:9292 \
-  --adminurl=http://controller:9292</userinput></screen>
+  --adminurl=http://<replaceable>controller</replaceable>:9292</userinput></screen></step>
-
+    <step><para>Start the <literal>glance-api</literal> and
-  <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>
 <prompt>#</prompt> <userinput>service glance-registry start</userinput>
 <prompt>#</prompt> <userinput>chkconfig glance-api on</userinput>
@@ -108,6 +98,6 @@ admin_password=<replaceable>GLANCE_PASS</replaceable>
       <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>

doc/install-guide/section_glance-verify.xml

@@ -4,28 +4,95 @@
     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
+    <para>To test the Image Service installation, download at least one virtual machine image that
-    images that are known to work with OpenStack. CirrOS is a small test image
+        is known to work with OpenStack. For example, CirrOS is a small test image that is often
-    that is often used for testing OpenStack deployments. You can find the most
+        used for testing OpenStack deployments (<link xlink:href="http://download.cirros-cloud.net/"
-    recent CirrOS image on their <link
+            >CirrOS downloads</link>). The 64-bit CirrOS QCOW2 image is the image we'll use for this
-    xlink:href="http://download.cirros-cloud.net/">download page</link>. As of
+        walkthrough.</para>
-    this writing the most recent image is version 0.3.1. A 64-bit version in
+    <para>For more information about:</para>
-    QCOW2 format (compatible with KVM or QEMU hypervisors) can be downloaded
+    <para>
-    from there.</para>
+        <itemizedlist>
-    <para>The 64-bit CirrOS QCOW2 image is the image we'll use for this
+            <listitem>
-    walkthrough. More detailed information about how to obtain and create
+                <para>Downloading and building images, refer to the <link
-    images can be found in the <link
+                        xlink:href="http://docs.openstack.org/image-guide/content/index.html"
-    xlink:href="http://docs.openstack.org">OpenStack Compute Administration
+                        ><citetitle>OpenStack Virtual Machine Image Guide</citetitle></link>.
-    Guide</link> in the "Image Management" chapter.</para>
+                </para>
-
+            </listitem>
-    <para>The download is done in a dedicated directory:</para>
+            <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>
+<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>
-    <para>You can now use the <command>glance image-create</command> command to
+    <step><para>Use the <command>glance image-create</command> command to upload the image to the Image
-    upload the image to the Image Service, passing the image file through
+                Service, as follows:</para>
-    standard input:</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>+------------------+--------------------------------------+
@@ -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>
-
+       </step>
-    <para>The rationale for the arguments is:
+    <step><para>Use the <userinput>glance image-list</userinput> command to confirm
-        <variablelist>
+        that the image has been uploaded and to display its attributes:</para>
-            <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>
 <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>