Install Guide: add a chapter about client commands
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:
parent
2b47120191
commit
ed8fd1c397
@ -2,96 +2,110 @@
|
||||
<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="cli_openrc" audience="enduser">
|
||||
<!-- create similar file for admin user -->
|
||||
<title>Create and source the OpenStack RC file</title>
|
||||
xml:id="cli_openrc">
|
||||
<?dbhtml stop-chunking?>
|
||||
<title>The OpenStack RC file</title>
|
||||
<para>To set the required environment variables for the OpenStack
|
||||
command-line clients, you must either create or download an
|
||||
environment file, and source it. It is project-specific and
|
||||
contains the credentials used by all OpenStack
|
||||
services.</para>
|
||||
command-line clients, you must create an environment
|
||||
file.<phrase audience="enduser"> If your OpenStack
|
||||
installation provides it, you can download the file from
|
||||
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
|
||||
your current shell. They allow the commands to communicate to
|
||||
the OpenStack services that run in the cloud.</para>
|
||||
<para>If your OpenStack installation provides it, you can download
|
||||
the file from the OpenStack dashboard as an administrative
|
||||
user or any other user.</para>
|
||||
<procedure>
|
||||
<step>
|
||||
<para>Log in to the OpenStack dashboard, choose the
|
||||
project for which you want to download the OpenStack
|
||||
RC file, and click <guibutton>Access &
|
||||
Security</guibutton>.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>Click <guibutton>Download OpenStack RC
|
||||
File</guibutton> and save the file.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>Copy the <filename>openrc.sh</filename> file to the
|
||||
machine from where you want to run OpenStack
|
||||
commands.</para>
|
||||
<para>For example, copy the file to the machine from where
|
||||
you want to upload an image with a glance client
|
||||
command.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>On any shell from where you want to run OpenStack
|
||||
commands, source the <filename>openrc.sh</filename>
|
||||
file for the respective project.</para>
|
||||
<para>In this example, you source the
|
||||
<filename>demo-openrc.sh</filename> file for the
|
||||
demo project:</para>
|
||||
<screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen>
|
||||
</step>
|
||||
<step>
|
||||
<para>When you are prompted for an OpenStack password,
|
||||
enter the password for the user who downloaded the
|
||||
<filename>openrc.sh</filename> file.</para>
|
||||
</step>
|
||||
<step>
|
||||
<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 <literal>OS_PASSWORD</literal>
|
||||
setting in the <filename>openrc.sh</filename> file by
|
||||
specifying a password on a nova command, as
|
||||
follows:</para>
|
||||
<screen><prompt>$</prompt> <userinput>nova --password <password> image-list</userinput></screen>
|
||||
<para>Where <parameter>password</parameter> is your
|
||||
password.</para>
|
||||
</step>
|
||||
</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>
|
||||
your current shell. The variables enable the OpenStack client
|
||||
commands to communicate with the OpenStack services that run
|
||||
in the cloud.</para>
|
||||
<section xml:id="openrc-dashboard" audience="enduser">
|
||||
<title>Download and source the OpenStack RC file</title>
|
||||
<procedure>
|
||||
<step>
|
||||
<para>Log in to the OpenStack dashboard, choose the
|
||||
project for which you want to download the
|
||||
OpenStack RC file, and click <guibutton>Access
|
||||
& Security</guibutton>.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>Click <guibutton>Download OpenStack RC
|
||||
File</guibutton> and save the file.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>Copy the <filename>openrc.sh</filename> file to
|
||||
the machine from where you want to run OpenStack
|
||||
commands.</para>
|
||||
<para>For example, copy the file to the machine from
|
||||
where you want to upload an image with a glance
|
||||
client command.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>On any shell from where you want to run
|
||||
OpenStack commands, source the
|
||||
<filename>openrc.sh</filename> file for the
|
||||
respective project.</para>
|
||||
<para>In this example, you source the
|
||||
<filename>demo-openrc.sh</filename> file for
|
||||
the demo project:</para>
|
||||
<screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen>
|
||||
</step>
|
||||
<step>
|
||||
<para>When you are prompted for an OpenStack password,
|
||||
enter the password for the user who downloaded the
|
||||
<filename>openrc.sh</filename> file.</para>
|
||||
</step>
|
||||
</procedure>
|
||||
</section>
|
||||
<section xml:id="openrc-create">
|
||||
<title>Create and source the OpenStack RC file</title>
|
||||
<para audience="enduser">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" audience="enduser">export OS_USERNAME=<replaceable>USERNAME</replaceable>
|
||||
export OS_PASSWORD=<replaceable>PASSWORD</replaceable>
|
||||
export OS_TENANT_NAME=<replaceable>PROJECT_NAME</replaceable>
|
||||
export OS_AUTH_URL=<replaceable>https://IDENTITY_HOST:PORT/v2.0</replaceable>
|
||||
# The following lines can be omitted
|
||||
export OS_TENANT_ID=<replaceable>9d792532ffce494583138c495801d164</replaceable>
|
||||
export OS_REGION_NAME=<replaceable>RegionOne</replaceable></programlisting>
|
||||
</step>
|
||||
<step>
|
||||
<para>On any shell from where you want to run OpenStack
|
||||
commands, source the <filename>openrc.sh</filename>
|
||||
file for the respective project.</para>
|
||||
<screen><prompt>$</prompt> <userinput>source openrc.sh</userinput></screen>
|
||||
</step>
|
||||
</procedure>
|
||||
<note>
|
||||
<para>You are not prompted for the password with this method.
|
||||
The password lives in clear text format in the
|
||||
<filename>openrc.sh</filename> file. Restrict the
|
||||
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>
|
||||
<programlisting language="bash" audience="installer">export OS_USERNAME=admin
|
||||
export OS_PASSWORD=<replaceable>ADMIN_PASS</replaceable>
|
||||
export OS_TENANT_NAME=admin
|
||||
export OS_AUTH_URL=http://<replaceable>controller</replaceable>:35357/v2.0</programlisting>
|
||||
</step>
|
||||
<step>
|
||||
<para>On any shell from where you want to run
|
||||
OpenStack commands, source the
|
||||
<filename>openrc.sh</filename> file for the
|
||||
respective project:</para>
|
||||
<screen><prompt>$</prompt> <userinput>source openrc.sh</userinput></screen>
|
||||
</step>
|
||||
</procedure>
|
||||
<note audience="enduser">
|
||||
<para>You are not prompted for the password with this
|
||||
method. The password lives in clear text format in the
|
||||
<filename>openrc.sh</filename> file. Restrict the
|
||||
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 <password> image-list</userinput></screen>
|
||||
<para>Where <parameter>password</parameter> is your
|
||||
password.</para>
|
||||
</section>
|
||||
</section>
|
||||
|
@ -13,11 +13,14 @@
|
||||
xml:id="section_cli_overview">
|
||||
<title>Overview</title>
|
||||
<para>You can use the OpenStack command-line clients to run simple
|
||||
commands that make API calls. You can use these commands in
|
||||
scripts to automate tasks. 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>
|
||||
commands that make API calls. You can run these commands from
|
||||
the command line or in scripts to automate tasks. As long as
|
||||
you provide OpenStack credentials, you can run these commands
|
||||
on any machine.</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
|
||||
systems and are easy to learn and use. Each OpenStack service
|
||||
has its own command-line client. On some client commands, you
|
||||
@ -88,9 +91,10 @@
|
||||
ad hoc processing.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>An OpenStack <command>common</command> client is in development.</para>
|
||||
<para audience="adminuser">For client installation instructions, see
|
||||
<link
|
||||
<para>An OpenStack <command>common</command> client is in
|
||||
development.</para>
|
||||
<para audience="adminuser">For client installation instructions,
|
||||
see <link
|
||||
xlink:href="http://docs.openstack.org/user-guide/content/install_clients.html"
|
||||
>Install the OpenStack command-line clients</link>. For
|
||||
information about the OpenStack RC file, see <link
|
||||
|
@ -557,6 +557,7 @@
|
||||
<xi:include href="ch_basics.xml"/>
|
||||
<xi:include href="ch_debconf.xml"/>
|
||||
<xi:include href="ch_keystone.xml"/>
|
||||
<xi:include href="ch_clients.xml"/>
|
||||
<xi:include href="ch_glance.xml"/>
|
||||
<xi:include href="ch_nova.xml"/>
|
||||
<xi:include href="ch_horizon.xml"/>
|
||||
|
10
doc/install-guide/ch_clients.xml
Normal file
10
doc/install-guide/ch_clients.xml
Normal 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>
|
@ -85,6 +85,7 @@
|
||||
</executions>
|
||||
<configuration>
|
||||
<!-- These parameters apply to pdf and webhelp -->
|
||||
<profileAudience>installer</profileAudience>
|
||||
<xincludeSupported>true</xincludeSupported>
|
||||
<sourceDirectory>.</sourceDirectory>
|
||||
<includes>
|
||||
|
@ -1,85 +1,88 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<section xml:id="keystone-verify"
|
||||
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">
|
||||
|
||||
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">
|
||||
<title>Verify the Identity Service installation</title>
|
||||
|
||||
<para>To verify the Identity Service is installed and configured
|
||||
correctly, first unset the <envar>OS_SERVICE_TOKEN</envar> and
|
||||
<envar>OS_SERVICE_ENDPOINT</envar> environment variables. These
|
||||
were only used to bootstrap the administrative user and register
|
||||
the Identity Service.</para>
|
||||
|
||||
<screen><prompt>#</prompt> <userinput>unset OS_SERVICE_TOKEN OS_SERVICE_ENDPOINT</userinput></screen>
|
||||
|
||||
<para>You can now use regular username-based authentication.
|
||||
Request an authentication token using the <literal>admin</literal>
|
||||
user and the password you chose during the earlier administrative
|
||||
user-creation step.</para>
|
||||
|
||||
<para os="rhel;centos;fedora;opensuse;sles;ubuntu">
|
||||
See <xref linkend="keystone-users"/> for further details.
|
||||
</para>
|
||||
<para os="debian">
|
||||
See <xref linkend="keystone-install"/> for further details.
|
||||
</para>
|
||||
|
||||
<screen><prompt>#</prompt> <userinput>keystone --os-username=admin --os-password=<replaceable>ADMIN_PASS</replaceable> \
|
||||
<procedure>
|
||||
<step>
|
||||
<para>To verify that the Identity Service is installed and
|
||||
configured correctly, clear the values in the
|
||||
<envar>OS_SERVICE_TOKEN</envar> and
|
||||
<envar>OS_SERVICE_ENDPOINT</envar> environment
|
||||
variables:</para>
|
||||
<screen><prompt>#</prompt> <userinput>unset OS_SERVICE_TOKEN OS_SERVICE_ENDPOINT</userinput></screen>
|
||||
<para>These variables, which were used to bootstrap the
|
||||
administrative user and register the Identity Service, are no
|
||||
longer needed.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>You can now use regular user name-based
|
||||
authentication.</para>
|
||||
<para>Request a authentication token by using the
|
||||
<literal>admin</literal> user and the password you chose for
|
||||
that user:</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>
|
||||
|
||||
<para>You should receive a token in response, paired with your user ID.
|
||||
This verifies that keystone is running on the expected endpoint, and
|
||||
that your user account is established with the expected credentials.</para>
|
||||
|
||||
<para>Next, verify that authorization is behaving as expected by requesting
|
||||
authorization on a tenant.</para>
|
||||
|
||||
<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>
|
||||
|
||||
<para>You should receive a new token in response, this time including the
|
||||
ID of the tenant you specified. This verifies that your user account has
|
||||
an explicitly defined role on the specified tenant, and that the tenant
|
||||
exists as expected.</para>
|
||||
|
||||
<para>You can also set your <literal>--os-*</literal> variables in your
|
||||
environment to simplify command-line usage. Set up a
|
||||
<filename>keystonerc</filename> file with the admin credentials and
|
||||
admin endpoint.</para>
|
||||
|
||||
<programlisting language="bash">export OS_USERNAME=admin
|
||||
<para>In response, you receive a token paired with your user ID.
|
||||
This verifies that the Identity Service is running on the
|
||||
expected endpoint and that your user account is established
|
||||
with the expected credentials.</para>
|
||||
</step>
|
||||
<step>
|
||||
<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> \
|
||||
--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
|
||||
the tenant that you specified. This verifies that your user
|
||||
account has an explicitly defined role on the specified tenant
|
||||
and the tenant exists as expected.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>You can also set your <literal>--os-*</literal> variables
|
||||
in your environment to simplify command-line usage. Set up a
|
||||
<filename>openrc.sh</filename> file with the admin
|
||||
credentials and admin endpoint:</para>
|
||||
<programlisting language="bash">export OS_USERNAME=admin
|
||||
export OS_PASSWORD=<replaceable>ADMIN_PASS</replaceable>
|
||||
export OS_TENANT_NAME=admin
|
||||
export OS_AUTH_URL=http://controller:35357/v2.0</programlisting>
|
||||
|
||||
<para>You can source this file to read in the environment variables.</para>
|
||||
|
||||
<screen><prompt>#</prompt> <userinput>source keystonerc</userinput></screen>
|
||||
|
||||
<para>Verify that your <filename>keystonerc</filename> is configured
|
||||
correctly by performing the same command as above, but without the
|
||||
<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.
|
||||
This verifies that you have configured your environment variables
|
||||
correctly.</para>
|
||||
|
||||
<para>Finally, verify that your admin account has authorization to
|
||||
perform administrative commands.</para>
|
||||
|
||||
<screen><prompt>#</prompt> <userinput>keystone user-list</userinput>
|
||||
<computeroutput>
|
||||
+----------------------------------+---------+--------------------+--------+
|
||||
</step>
|
||||
<step>
|
||||
<para>Source this file to read in the environment
|
||||
variables:</para>
|
||||
<screen><prompt>#</prompt> <userinput>source openrc.sh</userinput></screen>
|
||||
</step>
|
||||
<step>
|
||||
<para>Verify that your <filename>openrc.sh</filename> file is
|
||||
configured correctly. Run the same command without the
|
||||
<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. This verifies that you have configured your
|
||||
environment variables correctly.</para>
|
||||
</step>
|
||||
<step>
|
||||
<para>Verify that your admin account has authorization to
|
||||
perform administrative commands:</para>
|
||||
<screen><prompt>#</prompt> <userinput>keystone user-list</userinput>
|
||||
<computeroutput>+----------------------------------+---------+--------------------+--------+
|
||||
| id | enabled | email | name |
|
||||
+----------------------------------+---------+--------------------+--------+
|
||||
| a4c2d43f80a549a19864c89d759bb3fe | True | admin@example.com | admin |
|
||||
</computeroutput></screen>
|
||||
|
||||
<para>This verifies that your user account has the
|
||||
<literal>admin</literal> role, which matches the role used in
|
||||
the Identity Service <filename>policy.json</filename> file.</para>
|
||||
+----------------------------------+---------+--------------------+--------+</computeroutput></screen>
|
||||
<para>This verifies that your user account has the
|
||||
<literal>admin</literal> role, which matches the role used
|
||||
in the Identity Service <filename>policy.json</filename>
|
||||
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>
|
||||
|
@ -87,7 +87,7 @@ public_interface=eth1</programlisting>
|
||||
<para>Create a network that virtual machines can use. Do this once
|
||||
for the entire installation and not on each compute node. Run the
|
||||
<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 \
|
||||
--bridge-interface=br100 --multi-host=T</userinput></screen>
|
||||
</section>
|
||||
|
@ -16,7 +16,7 @@
|
||||
<module>image-guide</module>
|
||||
<module>install-guide</module>
|
||||
<module>security-guide</module>
|
||||
<module>training-guide</module>
|
||||
<module>training-guides</module>
|
||||
<module>user-guide</module>
|
||||
<module>user-guide-admin</module>
|
||||
</modules>
|
||||
|
@ -1,3 +1,4 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
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">
|
||||
|
@ -50,7 +50,8 @@ KNOWN_OS_VALUES = ["debian",
|
||||
|
||||
# List of recognized (allowable) audience profiling directives.
|
||||
KNOWN_AUDIENCE_VALUES = ["enduser",
|
||||
"adminuser"]
|
||||
"adminuser",
|
||||
"installer"]
|
||||
|
||||
|
||||
# NOTE(berendt): check_output as provided in Python 2.7.5 to make script
|
||||
|
Loading…
Reference in New Issue
Block a user