openstack/openstack-manuals
Code Issues Proposed changes

Install Guide: add a chapter about client commands

Browse Source 
This new chapter is taken from the common/ section, and explains how to
install clients on machines outside the OpenStack cluster. The install
guide can be misleading about how to use clients to administrate the
cloud, adding this section will hopefully help clarifying this.

pom.xml is modified to add an audience target (installer), used to build
specific parts of the common files.

backport: none
Change-Id: Ib4187d86bb2e3d7d9a26df426e17b4f4039a90fa
This commit is contained in:
Gauvain Pocentek 2013-11-19 20:32:38 +01:00 committed by annegentle
parent 2b47120191
commit ed8fd1c397
10 changed files with 204 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
doc/common/section_cli_openrc.xml
View File

@ -2,96 +2,110 @@
<section xmlns="http://docbook.org/ns/docbook" <section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="cli_openrc" audience="enduser"> xml:id="cli_openrc">
<!-- create similar file for admin user --> <?dbhtml stop-chunking?>
<title>Create and source the OpenStack RC file</title> <title>The OpenStack RC file</title>
<para>To set the required environment variables for the OpenStack <para>To set the required environment variables for the OpenStack
command-line clients, you must either create or download an command-line clients, you must create an environment
environment file, and source it. It is project-specific and file.<phrase audience="enduser"> If your OpenStack
contains the credentials used by all OpenStack installation provides it, you can download the file from
services.</para> the OpenStack dashboard as an administrative user or any
other user.</phrase> This project-specific environment
file contains the credentials that all OpenStack services
use.</para>
<para>When you source the file, environment variables are set for <para>When you source the file, environment variables are set for
your current shell. They allow the commands to communicate to your current shell. The variables enable the OpenStack client
the OpenStack services that run in the cloud.</para> commands to communicate with the OpenStack services that run
<para>If your OpenStack installation provides it, you can download in the cloud.</para>
the file from the OpenStack dashboard as an administrative <section xml:id="openrc-dashboard" audience="enduser">
user or any other user.</para> <title>Download and source the OpenStack RC file</title>
<procedure> <procedure>
<step> <step>
<para>Log in to the OpenStack dashboard, choose the <para>Log in to the OpenStack dashboard, choose the
project for which you want to download the OpenStack project for which you want to download the
RC file, and click <guibutton>Access &amp; OpenStack RC file, and click <guibutton>Access
Security</guibutton>.</para> &amp; Security</guibutton>.</para>
</step> </step>
<step> <step>
<para>Click <guibutton>Download OpenStack RC <para>Click <guibutton>Download OpenStack RC
File</guibutton> and save the file.</para> File</guibutton> and save the file.</para>
</step> </step>
<step> <step>
<para>Copy the <filename>openrc.sh</filename> file to the <para>Copy the <filename>openrc.sh</filename> file to
machine from where you want to run OpenStack the machine from where you want to run OpenStack
commands.</para> commands.</para>
<para>For example, copy the file to the machine from where <para>For example, copy the file to the machine from
you want to upload an image with a glance client where you want to upload an image with a glance
command.</para> client command.</para>
</step> </step>
<step> <step>
<para>On any shell from where you want to run OpenStack <para>On any shell from where you want to run
commands, source the <filename>openrc.sh</filename> OpenStack commands, source the
file for the respective project.</para> <filename>openrc.sh</filename> file for the
<para>In this example, you source the respective project.</para>
<filename>demo-openrc.sh</filename> file for the <para>In this example, you source the
demo project:</para> <filename>demo-openrc.sh</filename> file for
<screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen> the demo project:</para>
</step> <screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen>
<step> </step>
<para>When you are prompted for an OpenStack password, <step>
enter the password for the user who downloaded the <para>When you are prompted for an OpenStack password,
<filename>openrc.sh</filename> file.</para> enter the password for the user who downloaded the
</step> <filename>openrc.sh</filename> file.</para>
<step> </step>
<para>When you run OpenStack client commands, you can </procedure>
override some environment variable settings by using </section>
the options that are listed at the end of the <section xml:id="openrc-create">
<command>nova help</command> output. For example, <title>Create and source the OpenStack RC file</title>
you can override the <literal>OS_PASSWORD</literal> <para audience="enduser">Alternatively, you can create the
setting in the <filename>openrc.sh</filename> file by <filename>openrc.sh</filename> file from
specifying a password on a nova command, as scratch.</para>
follows:</para> <procedure>
<screen><prompt>$</prompt> <userinput>nova --password &lt;password> image-list</userinput></screen> <step>
<para>Where <parameter>password</parameter> is your <para>Create the <filename>openrc.sh</filename> file
password.</para> and add the authentication information:</para>
</step> <programlisting language="bash" audience="enduser">export OS_USERNAME=<replaceable>USERNAME</replaceable>
</procedure>
<para>Alternatively, you can create the
<filename>openrc.sh</filename> file from scratch.</para>
<procedure>
<step>
<para>Create the <filename>openrc.sh</filename> file
and add the authentication information:</para>
<programlisting language="bash">export OS_USERNAME=<replaceable>USERNAME</replaceable>
export OS_PASSWORD=<replaceable>PASSWORD</replaceable> export OS_PASSWORD=<replaceable>PASSWORD</replaceable>
export OS_TENANT_NAME=<replaceable>PROJECT_NAME</replaceable> export OS_TENANT_NAME=<replaceable>PROJECT_NAME</replaceable>
export OS_AUTH_URL=<replaceable>https://IDENTITY_HOST:PORT/v2.0</replaceable> export OS_AUTH_URL=<replaceable>https://IDENTITY_HOST:PORT/v2.0</replaceable>
# The following lines can be omitted # The following lines can be omitted
export OS_TENANT_ID=<replaceable>9d792532ffce494583138c495801d164</replaceable> export OS_TENANT_ID=<replaceable>9d792532ffce494583138c495801d164</replaceable>
export OS_REGION_NAME=<replaceable>RegionOne</replaceable></programlisting> export OS_REGION_NAME=<replaceable>RegionOne</replaceable></programlisting>
</step> <programlisting language="bash" audience="installer">export OS_USERNAME=admin
<step> export OS_PASSWORD=<replaceable>ADMIN_PASS</replaceable>
<para>On any shell from where you want to run OpenStack export OS_TENANT_NAME=admin
commands, source the <filename>openrc.sh</filename> export OS_AUTH_URL=http://<replaceable>controller</replaceable>:35357/v2.0</programlisting>
file for the respective project.</para> </step>
<screen><prompt>$</prompt> <userinput>source openrc.sh</userinput></screen> <step>
</step> <para>On any shell from where you want to run
</procedure> OpenStack commands, source the
<note> <filename>openrc.sh</filename> file for the
<para>You are not prompted for the password with this method. respective project:</para>
The password lives in clear text format in the <screen><prompt>$</prompt> <userinput>source openrc.sh</userinput></screen>
<filename>openrc.sh</filename> file. Restrict the </step>
permissions on this file to avoid security problems. You </procedure>
can also remove the <literal>OS_PASSWORD</literal> <note audience="enduser">
variable from the file, and use the <para>You are not prompted for the password with this
<parameter>--password</parameter> parameter with method. The password lives in clear text format in the
OpenStack client commands.</para> <filename>openrc.sh</filename> file. Restrict the
</note> permissions on this file to avoid security problems.
You can also remove the <literal>OS_PASSWORD</literal>
variable from the file, and use the
<parameter>--password</parameter> parameter with
OpenStack client commands.</para>
</note>
</section>
<section xml:id="override-variables">
<title>Override environment variable values</title>
<para>When you run OpenStack client commands, you can override
some environment variable settings by using the options
that are listed at the end of the <command>nova
help</command> output. For example, you can override
the <option>OS_PASSWORD</option> setting in the
<filename>openrc.sh</filename> file by specifying a
password on a <command>nova</command> command, as follows:</para>
<screen><prompt>$</prompt> <userinput>nova --password &lt;password> image-list</userinput></screen>
<para>Where <parameter>password</parameter> is your
password.</para>
</section>
</section> </section>

20
doc/common/section_cli_overview.xml
View File

@ -13,11 +13,14 @@
xml:id="section_cli_overview"> xml:id="section_cli_overview">
<title>Overview</title> <title>Overview</title>
<para>You can use the OpenStack command-line clients to run simple <para>You can use the OpenStack command-line clients to run simple
commands that make API calls. You can use these commands in commands that make API calls. You can run these commands from
scripts to automate tasks. Internally, each client command the command line or in scripts to automate tasks. As long as
runs cURL commands that embed API requests. The OpenStack APIs you provide OpenStack credentials, you can run these commands
are RESTful APIs that use the HTTP protocol, including on any machine.</para>
methods, URIs, media types, and response codes.</para> <para>Internally, each client command runs cURL commands that
embed API requests. The OpenStack APIs are RESTful APIs that
use the HTTP protocol, including methods, URIs, media types,
and response codes.</para>
<para>These open-source Python clients run on Linux or Mac OS X <para>These open-source Python clients run on Linux or Mac OS X
systems and are easy to learn and use. Each OpenStack service systems and are easy to learn and use. Each OpenStack service
has its own command-line client. On some client commands, you has its own command-line client. On some client commands, you
@ -88,9 +91,10 @@
ad hoc processing.</para> ad hoc processing.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>An OpenStack <command>common</command> client is in development.</para> <para>An OpenStack <command>common</command> client is in
<para audience="adminuser">For client installation instructions, see development.</para>
<link <para audience="adminuser">For client installation instructions,
see <link
xlink:href="http://docs.openstack.org/user-guide/content/install_clients.html" xlink:href="http://docs.openstack.org/user-guide/content/install_clients.html"
>Install the OpenStack command-line clients</link>. For >Install the OpenStack command-line clients</link>. For
information about the OpenStack RC file, see <link information about the OpenStack RC file, see <link

1
doc/install-guide/bk_openstackinstallguide.xml
View File

@ -557,6 +557,7 @@
<xi:include href="ch_basics.xml"/> <xi:include href="ch_basics.xml"/>
<xi:include href="ch_debconf.xml"/> <xi:include href="ch_debconf.xml"/>
<xi:include href="ch_keystone.xml"/> <xi:include href="ch_keystone.xml"/>
<xi:include href="ch_clients.xml"/>
<xi:include href="ch_glance.xml"/> <xi:include href="ch_glance.xml"/>
<xi:include href="ch_nova.xml"/> <xi:include href="ch_nova.xml"/>
<xi:include href="ch_horizon.xml"/> <xi:include href="ch_horizon.xml"/>

10
doc/install-guide/ch_clients.xml Normal file
View File

@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter 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="ch_clients">
<title>Install and configure the OpenStack clients</title>
<xi:include href="../common/section_cli_overview.xml"/>
<xi:include href="../common/section_cli_install.xml"/>
<xi:include href="../common/section_cli_openrc.xml"/>
</chapter>

1
doc/install-guide/pom.xml
View File

@ -85,6 +85,7 @@
</executions> </executions>
<configuration> <configuration>
<!-- These parameters apply to pdf and webhelp --> <!-- These parameters apply to pdf and webhelp -->
<profileAudience>installer</profileAudience>
<xincludeSupported>true</xincludeSupported> <xincludeSupported>true</xincludeSupported>
<sourceDirectory>.</sourceDirectory> <sourceDirectory>.</sourceDirectory>
<includes> <includes>

151
doc/install-guide/section_keystone-verify.xml
View File

@ -1,85 +1,88 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<section xml:id="keystone-verify" <section xml:id="keystone-verify"
xmlns="http://docbook.org/ns/docbook" xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Verify the Identity Service installation</title> <title>Verify the Identity Service installation</title>
<procedure>
<para>To verify the Identity Service is installed and configured <step>
correctly, first unset the <envar>OS_SERVICE_TOKEN</envar> and <para>To verify that the Identity Service is installed and
<envar>OS_SERVICE_ENDPOINT</envar> environment variables. These configured correctly, clear the values in the
were only used to bootstrap the administrative user and register <envar>OS_SERVICE_TOKEN</envar> and
the Identity Service.</para> <envar>OS_SERVICE_ENDPOINT</envar> environment
variables:</para>
<screen><prompt>#</prompt> <userinput>unset OS_SERVICE_TOKEN OS_SERVICE_ENDPOINT</userinput></screen> <screen><prompt>#</prompt> <userinput>unset OS_SERVICE_TOKEN OS_SERVICE_ENDPOINT</userinput></screen>
<para>These variables, which were used to bootstrap the
<para>You can now use regular username-based authentication. administrative user and register the Identity Service, are no
Request an authentication token using the <literal>admin</literal> longer needed.</para>
user and the password you chose during the earlier administrative </step>
user-creation step.</para> <step>
<para>You can now use regular user name-based
<para os="rhel;centos;fedora;opensuse;sles;ubuntu"> authentication.</para>
See <xref linkend="keystone-users"/> for further details. <para>Request a authentication token by using the
</para> <literal>admin</literal> user and the password you chose for
<para os="debian"> that user:</para>
See <xref linkend="keystone-install"/> for further details. <screen><prompt>#</prompt> <userinput>keystone --os-username=admin --os-password=<replaceable>ADMIN_PASS</replaceable> \
</para>
<screen><prompt>#</prompt> <userinput>keystone --os-username=admin --os-password=<replaceable>ADMIN_PASS</replaceable> \
--os-auth-url=http://controller:35357/v2.0 token-get</userinput></screen> --os-auth-url=http://controller:35357/v2.0 token-get</userinput></screen>
<para>In response, you receive a token paired with your user ID.
<para>You should receive a token in response, paired with your user ID. This verifies that the Identity Service is running on the
This verifies that keystone is running on the expected endpoint, and expected endpoint and that your user account is established
that your user account is established with the expected credentials.</para> with the expected credentials.</para>
</step>
<para>Next, verify that authorization is behaving as expected by requesting <step>
authorization on a tenant.</para> <para>Verify that authorization behaves as expected. To do so,
request authorization on a tenant:</para>
<screen><prompt>#</prompt> <userinput>keystone --os-username=admin --os-password=<replaceable>ADMIN_PASS</replaceable> \ <screen><prompt>#</prompt> <userinput>keystone --os-username=admin --os-password=<replaceable>ADMIN_PASS</replaceable> \
--os-tenant-name=admin --os-auth-url=http://controller:35357/v2.0 token-get</userinput></screen> --os-tenant-name=admin --os-auth-url=http://controller:35357/v2.0 token-get</userinput></screen>
<para>In response, you receive a token that includes the ID of
<para>You should receive a new token in response, this time including the the tenant that you specified. This verifies that your user
ID of the tenant you specified. This verifies that your user account has account has an explicitly defined role on the specified tenant
an explicitly defined role on the specified tenant, and that the tenant and the tenant exists as expected.</para>
exists as expected.</para> </step>
<step>
<para>You can also set your <literal>--os-*</literal> variables in your <para>You can also set your <literal>--os-*</literal> variables
environment to simplify command-line usage. Set up a in your environment to simplify command-line usage. Set up a
<filename>keystonerc</filename> file with the admin credentials and <filename>openrc.sh</filename> file with the admin
admin endpoint.</para> credentials and admin endpoint:</para>
<programlisting language="bash">export OS_USERNAME=admin
<programlisting language="bash">export OS_USERNAME=admin
export OS_PASSWORD=<replaceable>ADMIN_PASS</replaceable> export OS_PASSWORD=<replaceable>ADMIN_PASS</replaceable>
export OS_TENANT_NAME=admin export OS_TENANT_NAME=admin
export OS_AUTH_URL=http://controller:35357/v2.0</programlisting> export OS_AUTH_URL=http://controller:35357/v2.0</programlisting>
</step>
<para>You can source this file to read in the environment variables.</para> <step>
<para>Source this file to read in the environment
<screen><prompt>#</prompt> <userinput>source keystonerc</userinput></screen> variables:</para>
<screen><prompt>#</prompt> <userinput>source openrc.sh</userinput></screen>
<para>Verify that your <filename>keystonerc</filename> is configured </step>
correctly by performing the same command as above, but without the <step>
<literal>--os-*</literal> arguments.</para> <para>Verify that your <filename>openrc.sh</filename> file is
configured correctly. Run the same command without the
<screen><prompt>$</prompt> <userinput>keystone token-get</userinput></screen> <literal>--os-*</literal> arguments:</para>
<screen><prompt>$</prompt> <userinput>keystone token-get</userinput></screen>
<para>The command returns a token and the ID of the specified tenant. <para>The command returns a token and the ID of the specified
This verifies that you have configured your environment variables tenant. This verifies that you have configured your
correctly.</para> environment variables correctly.</para>
</step>
<para>Finally, verify that your admin account has authorization to <step>
perform administrative commands.</para> <para>Verify that your admin account has authorization to
perform administrative commands:</para>
<screen><prompt>#</prompt> <userinput>keystone user-list</userinput> <screen><prompt>#</prompt> <userinput>keystone user-list</userinput>
<computeroutput> <computeroutput>+----------------------------------+---------+--------------------+--------+
+----------------------------------+---------+--------------------+--------+
| id | enabled | email | name | | id | enabled | email | name |
+----------------------------------+---------+--------------------+--------+ +----------------------------------+---------+--------------------+--------+
| a4c2d43f80a549a19864c89d759bb3fe | True | admin@example.com | admin | | a4c2d43f80a549a19864c89d759bb3fe | True | admin@example.com | admin |
</computeroutput></screen> +----------------------------------+---------+--------------------+--------+</computeroutput></screen>
<para>This verifies that your user account has the
<para>This verifies that your user account has the <literal>admin</literal> role, which matches the role used
<literal>admin</literal> role, which matches the role used in in the Identity Service <filename>policy.json</filename>
the Identity Service <filename>policy.json</filename> file.</para> file.</para>
<note>
<para>As long as you define your credentials and the Identity
Service endpoint through the command line or environment
variables, you can run all OpenStack client commands from
any machine. For details, see <xref linkend="ch_clients"
/>.</para>
</note>
</step>
</procedure>
</section> </section>

2
doc/install-guide/section_nova-network.xml
View File

@ -87,7 +87,7 @@ public_interface=eth1</programlisting>
<para>Create a network that virtual machines can use. Do this once <para>Create a network that virtual machines can use. Do this once
for the entire installation and not on each compute node. Run the for the entire installation and not on each compute node. Run the
<command>nova network-create</command> command on the controller:</para> <command>nova network-create</command> command on the controller:</para>
<screen><prompt>#</prompt> <userinput>source keystonerc</userinput></screen> <screen><prompt>#</prompt> <userinput>source openrc.sh</userinput></screen>
<screen><prompt>#</prompt> <userinput>nova network-create vmnet --fixed-range-v4=10.0.0.0/24 \ <screen><prompt>#</prompt> <userinput>nova network-create vmnet --fixed-range-v4=10.0.0.0/24 \
--bridge-interface=br100 --multi-host=T</userinput></screen> --bridge-interface=br100 --multi-host=T</userinput></screen>
</section> </section>

2
doc/pom.xml
View File

@ -16,7 +16,7 @@
<module>image-guide</module> <module>image-guide</module>
<module>install-guide</module> <module>install-guide</module>
<module>security-guide</module> <module>security-guide</module>
<module>training-guide</module> <module>training-guides</module>
<module>user-guide</module> <module>user-guide</module>
<module>user-guide-admin</module> <module>user-guide-admin</module>
</modules> </modules>

1
doc/training-guides/pom.xml
View File

@ -1,3 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" <project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

3
tools/test.py
View File

@ -50,7 +50,8 @@ KNOWN_OS_VALUES = ["debian",
# List of recognized (allowable) audience profiling directives. # List of recognized (allowable) audience profiling directives.
KNOWN_AUDIENCE_VALUES = ["enduser", KNOWN_AUDIENCE_VALUES = ["enduser",
"adminuser"] "adminuser",
"installer"]
# NOTE(berendt): check_output as provided in Python 2.7.5 to make script # NOTE(berendt): check_output as provided in Python 2.7.5 to make script