openstack/openstack-manuals
Code Issues Proposed changes

Modify keystone content for Kilo

Browse Source 
Modify keystone content for Kilo as follows:

1) Replace default eventlet front-end with Apache front-end
   to provide a more production-style deployment.

   * Disable keystone service from starting up automatically
     because it creates port conflicts with Apache.
   * Use the Apache virtual host configuration template from
     the keystone source repository.
   * Use the WSGI components from the keystone source
     repository because the packages don't include them.
   * Will update source repository links after release.

2) Replace SQL back-end with Memcache back-end for tokens to
   provide a more production-style deployment.

   * Remove cron job that deletes expired tokens from the SQL
     database.

3) Enable version 3 API.

   * Change "tenant" to "project" to align with v3 API
     terminology.
   * Include tests to verify operation.

4) Replace python-keystoneclient with python-openstackclient.

   * Update openrc files to work with python-openstackclient.

5) Replace password entry on CLI with prompts.

6) Move service and endpoint creation section before user and
   project creation section to improve flow.

7) Add note about adding sections and options to default
   configuration files.

8) Disable temporary authentication token mechanism prior to
   service verification.

Many of these changes stem from keystone deprecations and
recommendations from the keystone PTL. Also, this patch only
addresses Ubuntu. For other distributions, please submit
additional patches rather than modifying this patch.

Implements: blueprint installguide-kilo
Change-Id: I9a2e53f14d6ed41df0085256c20904760a58ea25
This commit is contained in:
Matthew Kassawara
2015-03-24 20:39:39 -05:00
committed by Anne Gentle
parent 7c990e28e0
commit cd89eca969
8 changed files with 482 additions and 318 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
doc/glossary/glossary-terms.xml
View File

@@ -2667,11 +2667,13 @@
</indexterm>
<glossdef>
<para>Separates a website from other sites. Often, the domain name has
two or more parts that are separated by dots. For example, yahoo.com,
usa.gov, harvard.edu, or mail.yahoo.com.</para>
<para>A domain is an entity or container of all DNS-related
<para>In the Identity service, provides isolation between projects
and users.</para>
<para>On the Internet, separates a website from other sites. Often,
the domain name has two or more parts that are separated by dots.
For example, yahoo.com, usa.gov, harvard.edu, or
mail.yahoo.com.</para>
<para>Also, a domain is an entity or container of all DNS-related
information containing one or more records.</para>
</glossdef>
</glossentry>

2
doc/install-guide/ch_keystone.xml
View File

@@ -7,8 +7,8 @@
<title>Add the Identity service</title>
<xi:include href="../common/section_keystone-concepts.xml"/>
<xi:include href="section_keystone-install.xml"/>
<xi:include href="section_keystone-users.xml"/>
<xi:include href="section_keystone-services.xml"/>
<xi:include href="section_keystone-users.xml"/>
<xi:include href="section_keystone-verify.xml"/>
<xi:include href="section_keystone-openrc.xml"/>
</chapter>

144
doc/install-guide/section_keystone-install.xml
View File

@@ -10,7 +10,10 @@
xml:id="keystone-install">
<title>Install and configure</title>
<para>This section describes how to install and configure the OpenStack
Identity service on the controller node.</para>
Identity service, code-named keystone, on the controller node. For
performance, this configuration deploys the Apache HTTP server to
handle requests and Memcached to store tokens instead of a SQL
database.</para>
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
<title>To configure prerequisites</title>
<para>Before you configure the OpenStack Identity service, you must create
@@ -49,10 +52,26 @@
</step>
</procedure>
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
<title>To install and configure the components</title>
<title>To install and configure the Identity service components</title>
<note>
<para>Default configuration files vary by distribution. You might need
to add these sections and options rather than modifying existing
sections and options. Also, an ellipsis (...) in the configuration
snippets indicates potential default configuration options that you
should retain.</para>
</note>
<step os="ubuntu">
<para>By default, the <systemitem class="service">keystone</systemitem>
service listens on ports 5000 and 35357. However, this guide
configures the Apache HTTP server to listen on those ports. To avoid
port conflicts, disable the
<systemitem class="service">keystone</systemitem> service from starting
automatically after installation:</para>
<screen><prompt>#</prompt> <userinput>echo "manual" > /etc/init/keystone.override</userinput></screen>
</step>
<step>
<para>Run the following command to install the packages:</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install keystone python-keystoneclient</userinput></screen>
<screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install keystone python-openstackclient apache2 libapache2-mod-wsgi memcached python-memcache</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-keystone python-keystoneclient</userinput></screen>
<screen os="sles;opensuse"><prompt>#</prompt> <userinput>zypper install openstack-keystone python-keystoneclient</userinput></screen>
</step>
@@ -78,13 +97,20 @@ connection = mysql://keystone:<replaceable>KEYSTONE_DBPASS</replaceable>@<replac
<para>Replace <replaceable>KEYSTONE_DBPASS</replaceable> with the
password you chose for the database.</para>
</step>
<step>
<para>In the <literal>[memcache]</literal> section, configure
the Memcache service:</para>
<programlisting language="ini">[memcache]
...
servers = localhost:11211</programlisting>
</step>
<step>
<para>In the <literal>[token]</literal> section, configure the UUID
token provider and SQL driver:</para>
token provider and Memcached driver:</para>
<programlisting language="ini">[token]
...
provider = keystone.token.providers.uuid.Provider
driver = keystone.token.persistence.backends.sql.Token</programlisting>
driver = keystone.token.persistence.backends.memcache.Token</programlisting>
</step>
<step>
<para>In the <literal>[revoke]</literal> section, configure
@@ -92,6 +118,13 @@ driver = keystone.token.persistence.backends.sql.Token</programlisting>
<programlisting language="ini">[revoke]
...
driver = keystone.contrib.revoke.backends.sql.Revoke</programlisting>
</step>
<step>
<para>In the <literal>[DEFAULT]</literal> section, configure the
log directory:</para>
<programlisting language="ini">[DEFAULT]
...
log_dir = /var/log/keystone</programlisting>
</step>
<step>
<para>(Optional) To assist with troubleshooting,
@@ -231,11 +264,81 @@ admin_token = <replaceable>ADMIN_TOKEN</replaceable></programlisting>
</informalfigure>
</step>
</procedure>
<procedure os="ubuntu">
<title>To configure the Apache HTTP server</title>
<step>
<para>Edit the <filename>/etc/apache2/apache2.conf</filename> file and
configure the <literal>ServerName</literal> option to reference the
controller node:</para>
<programlisting>ServerName <replaceable>controller</replaceable></programlisting>
</step>
<step>
<para>Create the
<filename>/etc/apache2/sites-available/wsgi-keystone.conf</filename>
file with the following content:</para>
<programlisting>Listen 5000
Listen 35357
&lt;VirtualHost *:5000&gt;
WSGIDaemonProcess keystone-public processes=5 threads=1 user=keystone display-name=%{GROUP}
WSGIProcessGroup keystone-public
WSGIScriptAlias / /var/www/cgi-bin/keystone/main
WSGIApplicationGroup %{GLOBAL}
WSGIPassAuthorization On
&lt;IfVersion &gt;= 2.4&gt;
ErrorLogFormat "%{cu}t %M"
&lt;/IfVersion&gt;
LogLevel info
ErrorLog /var/log/apache2/keystone-error.log
CustomLog /var/log/apache2/keystone-access.log combined
&lt;/VirtualHost&gt;
&lt;VirtualHost *:35357&gt;
WSGIDaemonProcess keystone-admin processes=5 threads=1 user=keystone display-name=%{GROUP}
WSGIProcessGroup keystone-admin
WSGIScriptAlias / /var/www/cgi-bin/keystone/admin
WSGIApplicationGroup %{GLOBAL}
WSGIPassAuthorization On
&lt;IfVersion &gt;= 2.4&gt;
ErrorLogFormat "%{cu}t %M"
&lt;/IfVersion>
LogLevel info
ErrorLog /var/log/apache2/keystone-error.log
CustomLog /var/log/apache2/keystone-access.log combined
&lt;/VirtualHost&gt;</programlisting>
</step>
<step>
<para>Disable the default virtual host:</para>
<screen><prompt>#</prompt> <userinput>rm /etc/apache2/sites-enabled/000-default.conf</userinput></screen>
</step>
<step>
<para>Enable the Identity service virtual hosts:</para>
<screen><prompt>#</prompt> <userinput>ln -s /etc/apache2/sites-available/wsgi-keystone.conf /etc/apache2/sites-enabled</userinput></screen>
</step>
<step>
<para>Create the directory structure for the WSGI components:</para>
<screen><prompt>#</prompt> <userinput>mkdir -p /var/www/cgi-bin/keystone</userinput></screen>
</step>
<step>
<para>Copy the WSGI components from the upstream repository into this
directory:</para>
<screen><prompt>#</prompt> <userinput>curl https://raw.githubusercontent.com/openstack/keystone/master/httpd/keystone.py \
> /var/www/cgi-bin/keystone/main</userinput>
<prompt>#</prompt> <userinput>curl https://raw.githubusercontent.com/openstack/keystone/master/httpd/keystone.py \
> /var/www/cgi-bin/keystone/admin</userinput></screen>
</step>
<step>
<para>Adjust ownership and permissions on this directory and the files
in it:</para>
<screen><prompt>#</prompt> <userinput>chown -R keystone:keystone /var/www/cgi-bin/keystone</userinput>
<prompt>#</prompt> <userinput>chmod 755 /var/www/cgi-bin/keystone/*</userinput></screen>
</step>
</procedure>
<procedure>
<title>To finalize installation</title>
<step os="ubuntu">
<para>Restart the Identity service:</para>
<screen><prompt>#</prompt> <userinput>service keystone restart</userinput></screen>
<para>Restart the Apache HTTP server:</para>
<screen><prompt>#</prompt> <userinput>service apache2 restart</userinput></screen>
</step>
<step os="rhel;fedora;centos;opensuse;sles">
<para>Start the Identity service and configure it to start when the
@@ -255,27 +358,18 @@ admin_token = <replaceable>ADMIN_TOKEN</replaceable></programlisting>
remove the SQLite database file:</para>
<screen><prompt>#</prompt> <userinput>rm -f /var/lib/keystone/keystone.db</userinput></screen>
</step>
<step>
<para os="ubuntu;rhel;centos;fedora;opensuse;sles">By default, the Identity service stores expired tokens in the
database indefinitely. The accumulation of expired tokens considerably
increases the database size and might degrade service performance,
particularly in environments with limited resources.</para>
<para os="debian">The Keystone package already contains a cron job
<step os="rhel;centos;fedora;sles;opensuse;debian">
<para>By default, the Identity service stores expired tokens in the
SQL database indefinitely. The accumulation of expired tokens
considerably increases the database size and degrades performance
over time, particularly in environments with limited resources.</para>
<para os="sles;opensuse;debian">The packages already contain a cron job
under <filename>/etc/cron.hourly/keystone</filename>, so it is not
necessary to manually configure a periodic task that purges expired tokens
hourly. You can however have a look at (and eventually customize) the already
configured script.</para>
<para os="opensuse;sles">The Keystone package already contains a cron job
under <filename>/etc/cron.hourly/openstack-keystone</filename>, so it is not
necessary to manually configure a periodic task that purges expired tokens
hourly. You can however have a look at (and eventually customize) the already
configured script.</para>
<para os="ubuntu;rhel;centos;fedora">We recommend that you use
necessary to manually configure a periodic task that purges expired
tokens.</para>
<para os="rhel;centos;fedora">We recommend that you use
<systemitem class="service">cron</systemitem> to configure a periodic
task that purges expired tokens hourly:</para>
<screen os="ubuntu"><prompt>#</prompt> <userinput>(crontab -l -u keystone 2>&amp;1 | grep -q token_flush) || \
echo '@hourly /usr/bin/keystone-manage token_flush >/var/log/keystone/keystone-tokenflush.log 2>&amp;1' \
>> /var/spool/cron/crontabs/keystone</userinput></screen>
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>(crontab -l -u keystone 2>&amp;1 | grep -q token_flush) || \
echo '@hourly /usr/bin/keystone-manage token_flush >/var/log/keystone/keystone-tokenflush.log 2>&amp;1' \
>> /var/spool/cron/keystone</userinput></screen>

44
doc/install-guide/section_keystone-openrc.xml
View File

@@ -7,7 +7,7 @@
<title>Create OpenStack client environment scripts</title>
<para>The previous section used a combination of environment variables and
command options to interact with the Identity service via the
<command>keystone</command> client. To increase efficiency of client
<command>openstack</command> client. To increase efficiency of client
operations, OpenStack supports simple client environment scripts also
known as OpenRC files. These scripts typically contain common options for
all clients, but also support unique options. For more information, see the
@@ -15,42 +15,58 @@
<procedure>
<title>To create the scripts</title>
<para>Create client environment scripts for the <literal>admin</literal>
and <literal>demo</literal> tenants and users. Future portions of this
and <literal>demo</literal> projects and users. Future portions of this
guide reference these scripts to load appropriate credentials for client
operations.</para>
<step>
<para>Edit the <filename>admin-openrc.sh</filename> file and add the
following content:</para>
<programlisting language="bash">export OS_TENANT_NAME=admin
<programlisting language="bash">export OS_PROJECT_DOMAIN_ID=default
export OS_USER_DOMAIN_ID=default
export OS_PROJECT_NAME=admin
export OS_USERNAME=admin
export OS_PASSWORD=<replaceable>ADMIN_PASS</replaceable>
export OS_AUTH_URL=http://<replaceable>controller</replaceable>:35357/v2.0</programlisting>
export OS_AUTH_URL=http://<replaceable>controller</replaceable>:35357
export OS_IMAGE_API_VERSION=2</programlisting>
<para>Replace <literal>ADMIN_PASS</literal> with the password you chose
for the <literal>admin</literal> user in the Identity service.</para>
</step>
<step>
<para>Edit the <filename>demo-openrc.sh</filename> file and add the
following content:</para>
<programlisting language="bash">export OS_TENANT_NAME=demo
<programlisting language="bash">export OS_PROJECT_DOMAIN_ID=default
export OS_USER_DOMAIN_ID=default
export OS_PROJECT_NAME=demo
export OS_USERNAME=demo
export OS_PASSWORD=<replaceable>DEMO_PASS</replaceable>
export OS_AUTH_URL=http://<replaceable>controller</replaceable>:5000/v2.0</programlisting>
export OS_AUTH_URL=http://<replaceable>controller</replaceable>:5000
export OS_IMAGE_API_VERSION=2</programlisting>
<para>Replace <literal>DEMO_PASS</literal> with the password you chose
for the <literal>demo</literal> user in the Identity service.</para>
</step>
</procedure>
<note><title>Identity ports</title>
<para>Note the two different ports used above. Port 35357 is used for
administrative functions only. Port 5000 is for normal user
functions and is the most commonly used.</para></note>
<procedure>
<title>To load client environment scripts</title>
<para>To run clients as a specific project and user, you can simply load
the associated client environment script prior to running them. For
example:</para>
<step>
<para>To run clients as a certain tenant and user, you can simply load
the associated client environment script prior to running them. For
example, to load the location of the Identity service and
<literal>admin</literal> tenant and user credentials:</para>
<para>Load the <filename>admin-openrc.sh</filename> file to populate
environment variables with the location of the Identity service
and the <literal>admin</literal> project and user credentials:</para>
<screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput></screen>
</step>
<step>
<para>Request an authentication token:</para>
<screen><prompt>$</prompt> <userinput>openstack token issue</userinput>
<computeroutput>+------------+----------------------------------+
| Field | Value |
+------------+----------------------------------+
| expires | 2015-03-25T01:45:49.950092Z |
| id | cd4110152ac24bdeaa82e1443c910c36 |
| project_id | cf12a15c5ea84b019aec3dc45580896b |
| user_id | 4d411f2291f34941b30eef9bd797505a |
+------------+----------------------------------+</computeroutput></screen>
</step>
</procedure>
</section>

118
doc/install-guide/section_keystone-services.xml
View File

@@ -3,42 +3,72 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="keystone-services"
os="ubuntu;rhel;centos;fedora;sles;opensuse">
<title>Create the service entity and API endpoint</title>
<para>After you create tenants, users, and roles, you must create the
<glossterm>service</glossterm> entity and
<glossterm baseform="API endpoint">API endpoints</glossterm> for the
Identity service.</para>
xml:id="keystone-services">
<title>Create the service entity and API endpoints</title>
<para>The Identity service provides a catalog of services and their
locations. Each service that you add to your OpenStack environment
requires a <glossterm>service</glossterm> entity and several
<glossterm baseform="API endpoint">API endpoints</glossterm> in the
catalog.</para>
<procedure>
<title>To configure prerequisites</title>
<para>By default, the Identity service database contains no information
to support conventional authentication and catalog services. You must
use a temporary authentication token that you created in
<xref linkend="keystone-install"/> to initialize the service entity
and API endpoints for the Identity service.</para>
<para>You must pass the value of the authentication token to the
<command>openstack</command> command with the
<parameter>--os-token</parameter> parameter or set the
<envar>OS_TOKEN</envar> environment variable. Similarly, you
must also pass the value of the Identity service URL to the
<command>openstack</command> command with the
<parameter>--os-url</parameter> parameter or set the
<envar>OS_URL</envar> environment variable. This guide
uses environment variables to reduce command length.</para>
<warning>
<para>For security reasons, do not use the temporary authentication
token for longer than necessary to initialize the Identity
service.</para>
</warning>
<step>
<para>Set the <envar>OS_SERVICE_TOKEN</envar> and
<envar>OS_SERVICE_ENDPOINT</envar> environment variables, as described
in <xref linkend="keystone-users"/>.</para>
<para>Configure the authentication token:</para>
<screen><prompt>$</prompt> <userinput>export OS_TOKEN=<replaceable>ADMIN_TOKEN</replaceable></userinput></screen>
<para>Replace <replaceable>ADMIN_TOKEN</replaceable> with the
authentication token that you generated in
<xref linkend="keystone-install"/>. For example:</para>
<screen><prompt>$</prompt> <userinput>export OS_TOKEN=294a4c8a8a475f9b9836</userinput></screen>
</step>
<step>
<para>Configure the endpoint URL:</para>
<screen><prompt>$</prompt> <userinput>export OS_URL=http://<replaceable>controller</replaceable>:35357/v2.0</userinput></screen>
</step>
</procedure>
<procedure>
<title>To create the service entity and API endpoints</title>
<note os="debian">
<para>The packages can automatically create the service entity and
API endpoints.</para>
</note>
<step>
<para>The Identity service manages a catalog of services in your
OpenStack environment. Services use this catalog to locate other
services in your environment.</para>
OpenStack environment. Services use this catalog to determine
the other services available in your environment.</para>
<para>Create the service entity for the Identity service:</para>
<screen><prompt>$</prompt> <userinput>keystone service-create --name keystone --type identity \
--description "OpenStack Identity"</userinput>
<screen><prompt>$</prompt> <userinput>openstack service create --type identity \
--description "OpenStack Identity" keystone</userinput>
<computeroutput>+-------------+----------------------------------+
| Property | Value |
| Field | Value |
+-------------+----------------------------------+
| description | OpenStack Identity |
| enabled | True |
| id | 15c11a23667e427e91bc31335b45f4bd |
| name | keystone |
| type | identity |
| description | OpenStack Identity |
| enabled | True |
| id | 4ddaae90388b4ebc9d252ec2252d8d10 |
| name | keystone |
| type | identity |
+-------------+----------------------------------+</computeroutput></screen>
<note>
<para>Because OpenStack generates IDs dynamically, you will see
different values from this example command output.</para>
<para>OpenStack generates IDs dynamically, so you will see
different values in the example command output.</para>
</note>
</step>
<step>
@@ -46,7 +76,7 @@
with the services in your OpenStack environment. Services use this
catalog to determine how to communicate with other services in your
environment.</para>
<para>OpenStack provides three API endpoint variations for each service:
<para>OpenStack uses three API endpoint variants for each service:
admin, internal, and public. The admin API endpoint allows modifying
users and tenants by default, while the public and internal APIs
do not. In a production environment, the variants might reside on
@@ -55,35 +85,33 @@
outside the cloud for management tools, the admin API network might be
protected, while the internal API network is connected to each host.
Also, OpenStack supports multiple regions for scalability. For
simplicity, this configuration uses the management network for all
endpoint variations and the <literal>regionOne</literal> region.</para>
simplicity, this guide uses the management network for all
endpoint variations and the default <literal>regionOne</literal>
region.</para>
<para>Create the Identity service API endpoints:</para>
<screen><prompt>$</prompt> <userinput>keystone endpoint-create \
--service-id $(keystone service-list | awk '/ identity / {print $2}') \
<screen><prompt>$</prompt> <userinput>openstack endpoint create \
--publicurl http://<replaceable>controller</replaceable>:5000/v2.0 \
--internalurl http://<replaceable>controller</replaceable>:5000/v2.0 \
--adminurl http://<replaceable>controller</replaceable>:35357/v2.0 \
--region regionOne</userinput>
<computeroutput>+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| adminurl | http://controller:35357/v2.0 |
| id | 11f9c625a3b94a3f8e66bf4e5de2679f |
| internalurl | http://controller:5000/v2.0 |
| publicurl | http://controller:5000/v2.0 |
| region | regionOne |
| service_id | 15c11a23667e427e91bc31335b45f4bd |
+-------------+----------------------------------+</computeroutput></screen>
<note>
<para>This command references the ID of the service that you created
in the previous step.</para>
</note>
--region regionOne \
identity</userinput>
<computeroutput>+--------------+----------------------------------+
| Field | Value |
+--------------+----------------------------------+
| adminurl | http://controller:35357/v2.0 |
| id | 4a9ffc04b8eb4848a49625a3df0170e5 |
| internalurl | http://controller:5000/v2.0 |
| publicurl | http://controller:5000/v2.0 |
| region | regionOne |
| service_id | 4ddaae90388b4ebc9d252ec2252d8d10 |
| service_name | keystone |
| service_type | identity |
+--------------+----------------------------------+</computeroutput></screen>
</step>
</procedure>
<note>
<para>Each service that you add to your OpenStack environment requires
adding information such as API endpoints to the Identity service. The
sections of this guide that cover service installation include steps
to add the appropriate information to the Identity service.</para>
one or more service entities and API endpoints in the Identity
service.</para>
</note>
</section>

236
doc/install-guide/section_keystone-users.xml
View File

@@ -4,179 +4,161 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="keystone-users">
<title>Create tenants, users, and roles</title>
<para>After you install the Identity service, create
<glossterm baseform="tenant">tenants</glossterm> (projects),
<title>Create projects, users, and roles</title>
<para>The Identity service provides authentication services for each
OpenStack service. The authentication service uses a combination of
<glossterm baseform="domain">domains</glossterm>,
<glossterm baseform="project">projects</glossterm> (tenants),
<glossterm baseform="user">users</glossterm>, and
<glossterm baseform="role">roles</glossterm> for your environment. You
must use the temporary administration token that you created in
<xref linkend="keystone-install"/> and manually configure the location
(endpoint) of the Identity service before you run
<command>keystone</command> commands.</para>
<para>You can pass the value of the administration token to the
<command>keystone</command> command with the <parameter>--os-token</parameter>
option or set the temporary <envar>OS_SERVICE_TOKEN</envar> environment
variable. Similarly, you can pass the location of the Identity service
to the <command>keystone</command> command with the
<parameter>--os-endpoint</parameter> option or set the temporary
<envar>OS_SERVICE_ENDPOINT</envar> environment variable. This guide
uses environment variables to reduce command length.</para>
<para>For more information, see the
<link xlink:href="http://docs.openstack.org/openstack-ops/content/projects_users.html">Operations Guide - Managing Project and Users</link>.</para>
<procedure>
<title>To configure prerequisites</title>
<note os="debian"><para>In Debian, the admin tenant, user and roles can be
created automatically when installing the Keystone package. You
must manually create the demo tenant and user however.
</para></note>
<step>
<para>Configure the administration token:</para>
<screen><prompt>$</prompt> <userinput>export OS_SERVICE_TOKEN=<replaceable>ADMIN_TOKEN</replaceable></userinput></screen>
<para>Replace <replaceable>ADMIN_TOKEN</replaceable> with the
administration token that you generated in
<xref linkend="keystone-install"/>. For example:</para>
<screen><prompt>$</prompt> <userinput>export OS_SERVICE_TOKEN=294a4c8a8a475f9b9836</userinput></screen>
</step>
<step>
<para>Configure the endpoint:</para>
<screen><prompt>$</prompt> <userinput>export OS_SERVICE_ENDPOINT=http://<replaceable>controller</replaceable>:35357/v2.0</userinput></screen>
</step>
</procedure>
<glossterm baseform="role">roles</glossterm>.</para>
<note>
<para>For simplicity, this guide implicitly uses the
<literal>default</literal> domain.</para>
</note>
<procedure>
<title>To create tenants, users, and roles</title>
<note os="debian">
<para>The packages can automatically create the service entity and
API endpoints.</para>
</note>
<step>
<para>Create an administrative tenant, user, and role for
<para>Create an administrative project, user, and role for
administrative operations in your environment:</para>
<substeps>
<step>
<para>Create the <literal>admin</literal> tenant:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-create --name admin --description "Admin Tenant"</userinput>
<para>Create the <literal>admin</literal> project:</para>
<screen><prompt>$</prompt> <userinput>openstack project create --description "Admin Project" admin</userinput>
<computeroutput>+-------------+----------------------------------+
| Property | Value |
| Field | Value |
+-------------+----------------------------------+
| description | Admin Tenant |
| enabled | True |
| id | 6f4c1e4cbfef4d5a8a1345882fbca110 |
| name | admin |
| description | Admin Project |
| enabled | True |
| id | cf12a15c5ea84b019aec3dc45580896b |
| name | admin |
+-------------+----------------------------------+</computeroutput></screen>
<note>
<para>OpenStack generates IDs dynamically, so you will see
different values from the example command output.</para>
different values in the example command output.</para>
</note>
</step>
<step>
<para>Create the <literal>admin</literal> user:</para>
<screen><prompt>$</prompt> <userinput>keystone user-create --name admin --pass <replaceable>ADMIN_PASS</replaceable> --email <replaceable>EMAIL_ADDRESS</replaceable></userinput>
<computeroutput>+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| email | admin@example.com |
| enabled | True |
| id | ea8c352d253443118041c9c8b8416040 |
| name | admin |
| username | admin |
+----------+----------------------------------+</computeroutput></screen>
<para>Replace <replaceable>ADMIN_PASS</replaceable> with a
suitable password and <replaceable>EMAIL_ADDRESS</replaceable>
with a suitable e-mail address.</para>
<screen><prompt>$</prompt> <userinput>openstack user create --password-prompt admin</userinput>
<computeroutput>User Password:
Repeat User Password:
+------------+----------------------------------+
| Field | Value |
+------------+----------------------------------+
| email | None |
| enabled | True |
| id | 4d411f2291f34941b30eef9bd797505a |
| name | admin |
| username | admin |
+------------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>Create the <literal>admin</literal> role:</para>
<screen><prompt>$</prompt> <userinput>keystone role-create --name admin</userinput>
<computeroutput>+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| id | bff3a6083b714fa29c9344bf8930d199 |
| name | admin |
+----------+----------------------------------+</computeroutput></screen>
<screen><prompt>$</prompt> <userinput>openstack role create admin</userinput>
<computeroutput>+-------+----------------------------------+
| Field | Value |
+-------+----------------------------------+
| id | cd2cb9a39e874ea69e5d4b896eb16128 |
| name | admin |
+-------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>Add the <literal>admin</literal> role to the
<literal>admin</literal> tenant and user:</para>
<screen><prompt>$</prompt> <userinput>keystone user-role-add --user admin --tenant admin --role admin</userinput></screen>
<note>
<para>This command provides no output.</para>
</note>
<literal>admin</literal> project and user:</para>
<screen><prompt>$</prompt> <userinput>openstack role add --project admin --user admin admin</userinput>
<computeroutput>+-------+----------------------------------+
| Field | Value |
+-------+----------------------------------+
| id | cd2cb9a39e874ea69e5d4b896eb16128 |
| name | admin |
+-------+----------------------------------+</computeroutput></screen>
</step>
</substeps>
<note>
<para>Any roles that you create must map to roles specified in the
<filename>policy.json</filename> file included with each OpenStack
service. The default policy for most services grants administrative
access to the <literal>admin</literal> role. For more information,
<filename>policy.json</filename> file in the configuration file
directory of each OpenStack service. The default policy for most
services grants administrative access to the
<literal>admin</literal> role. For more information,
see the
<link xlink:href="http://docs.openstack.org/openstack-ops/content/projects_users.html">Operations Guide - Managing Projects and Users</link>.</para>
</note>
</step>
<step>
<para>Create a demo tenant and user for typical operations in your
environment:</para>
<para>This guide uses a service project that contains a unique
user for each service that you add to your environment.</para>
<substeps>
<step>
<para>Create the <literal>demo</literal> tenant:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-create --name demo --description "Demo Tenant"</userinput>
<para>Create the <literal>service</literal> project:</para>
<screen><prompt>$</prompt> <userinput>openstack project create --description "Service Project" service</userinput>
<computeroutput>+-------------+----------------------------------+
| Property | Value |
| Field | Value |
+-------------+----------------------------------+
| description | Demo Tenant |
| enabled | True |
| id | 4aa51bb942be4dd0ac0555d7591f80a6 |
| name | demo |
| description | Service Project |
| enabled | True |
| id | 55cbd79c0c014c8a95534ebd16213ca1 |
| name | service |
+-------------+----------------------------------+</computeroutput></screen>
</step>
</substeps>
</step>
<step>
<para>Regular (non-admin) tasks should use an unprivileged project
and user. As an example, this guide creates the
<literal>demo</literal> project and user.</para>
<substeps>
<step>
<para>Create the <literal>demo</literal> project:</para>
<screen><prompt>$</prompt> <userinput>openstack project create --description "Demo Project" demo</userinput>
<computeroutput>+-------------+----------------------------------+
| Field | Value |
+-------------+----------------------------------+
| description | Demo Project |
| enabled | True |
| id | ab8ea576c0574b6092bb99150449b2d3 |
| name | demo |
+-------------+----------------------------------+</computeroutput></screen>
<note>
<para>Do not repeat this step when creating additional
users for this tenant.</para>
users for this project.</para>
</note>
</step>
<step>
<para>Create the <literal>demo</literal> user under the
<literal>demo</literal> tenant:</para>
<screen><prompt>$</prompt> <userinput>keystone user-create --name demo --tenant demo --pass <replaceable>DEMO_PASS</replaceable> --email <replaceable>EMAIL_ADDRESS</replaceable></userinput>
<computeroutput>+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| email | demo@example.com |
| enabled | True |
| id | 7004dfa0dda84d63aef81cf7f100af01 |
| name | demo |
| tenantId | 4aa51bb942be4dd0ac0555d7591f80a6 |
| username | demo |
+----------+----------------------------------+</computeroutput></screen>
<para>Replace <replaceable>DEMO_PASS</replaceable> with a suitable
password and <replaceable>EMAIL_ADDRESS</replaceable> with a
suitable e-mail address.</para>
<note>
<para>Using the <literal>--tenant</literal> option
automatically assigns the <literal>_member_</literal> role
to a user. This option will also create the
<literal>_member_</literal> role if it does not exist.</para>
</note>
<para>Create the <literal>demo</literal> user:</para>
<screen><prompt>$</prompt> <userinput>openstack user create --password-prompt demo</userinput>
<computeroutput>User Password:
Repeat User Password:
+------------+----------------------------------+
| Field | Value |
+------------+----------------------------------+
| email | None |
| enabled | True |
| id | 3a81e6c8103b46709ef8d141308d4c72 |
| name | demo |
| project_id | ab8ea576c0574b6092bb99150449b2d3 |
| username | demo |
+------------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>Add the <literal>_member_</literal> role to the
<literal>demo</literal> project and user:</para>
<screen><prompt>$</prompt> <userinput>openstack role add --project demo --user demo _member_</userinput>
<computeroutput>+-------+----------------------------------+
| Field | Value |
+-------+----------------------------------+
| id | 9fe2ff9ee4384b1894a90878d3e92bab |
| name | _member_ |
+-------+----------------------------------+</computeroutput></screen>
</step>
</substeps>
<note>
<para>You can repeat this procedure to create additional tenants
<para>You can repeat this procedure to create additional projects
and users.</para>
</note>
</step>
<step>
<para>OpenStack services also require a tenant, user, and role to
interact with other services. Each service typically requires
creating one or more unique users with the <literal>admin</literal>
role under the <literal>service</literal> tenant.</para>
<substeps>
<step>
<para>Create the <literal>service</literal> tenant:</para>
<screen><prompt>$</prompt> <userinput>keystone tenant-create --name service --description "Service Tenant"</userinput>
<computeroutput>+-------------+----------------------------------+
| Property | Value |
+-------------+----------------------------------+
| description | Service Tenant |
| enabled | True |
| id | 6b69202e1bf846a4ae50d65bc4789122 |
| name | service |
+-------------+----------------------------------+</computeroutput></screen>
</step>
</substeps>
</step>
</procedure>
</section>

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

@@ -5,96 +5,150 @@
version="5.0"
xml:id="keystone-verify">
<title>Verify operation</title>
<para>This section describes how to verify operation of the Identity
service.</para>
<para>Verify operation of the Identity service before installing other
services.</para>
<procedure>
<step>
<para>Unset the temporary <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>For security reasons, disable the temporary authentication
token mechanism:</para>
<para>Edit the <filename>/etc/keystone/keystone-paste.ini</filename> file
and remove <literal>admin_token_auth</literal> from the
<literal>[pipeline:public_api]</literal>,
<literal>[pipeline:admin_api]</literal>, and
<literal>[pipeline:api_v3]</literal> sections.</para>
</step>
<step>
<para>As the <literal>admin</literal> tenant and user, request an
authentication token:</para>
<screen><prompt>$</prompt> <userinput>keystone --os-tenant-name admin --os-username admin --os-password <replaceable>ADMIN_PASS</replaceable> \
--os-auth-url http://controller:35357/v2.0 token-get</userinput>
<computeroutput>+-----------+----------------------------------+
| Property | Value |
+-----------+----------------------------------+
| expires | 2014-10-10T12:50:12Z |
| id | 8963eb5ccd864769a894ec316ef8f7d4 |
| tenant_id | 6f4c1e4cbfef4d5a8a1345882fbca110 |
| user_id | ea8c352d253443118041c9c8b8416040 |
+-----------+----------------------------------+</computeroutput></screen>
<para>Replace <replaceable>ADMIN_PASS</replaceable> with the password
you chose for the <literal>admin</literal> user in the Identity
service. You might need to use single quotes (') around your password
if it includes special characters.</para>
<para>Unset the temporary <envar>OS_TOKEN</envar> and
<envar>OS_URL</envar> environment variables:</para>
<screen><prompt>$</prompt> <userinput>unset OS_TOKEN OS_URL</userinput></screen>
</step>
<step>
<para os="ubuntu;rhel;centos;fedora;sles;opensuse">As the
<literal>admin</literal> tenant and user, list tenants to verify
that the <literal>admin</literal> tenant and user can execute
admin-only CLI commands and that the Identity service contains the
tenants that you created in <xref linkend="keystone-users"/>:</para>
<para os="debian">As the <literal>admin</literal> tenant and user, list
tenants to verify that the <literal>admin</literal> tenant and user
can execute admin-only CLI commands and that the Identity service
contains the tenants created by the configuration tool:</para>
<screen><prompt>$</prompt> <userinput>keystone --os-tenant-name admin --os-username admin --os-password <replaceable>ADMIN_PASS</replaceable> \
--os-auth-url http://controller:35357/v2.0 tenant-list</userinput>
<computeroutput>+----------------------------------+----------+---------+
| id | name | enabled |
+----------------------------------+----------+---------+
| 6f4c1e4cbfef4d5a8a1345882fbca110 | admin | True |
| 4aa51bb942be4dd0ac0555d7591f80a6 | demo | True |
| 6b69202e1bf846a4ae50d65bc4789122 | service | True |
+----------------------------------+----------+---------+</computeroutput></screen>
<para>As the <literal>admin</literal> user, request an authentication
token from the Identity version 2.0 API:</para>
<screen><prompt>$</prompt> <userinput>openstack --os-auth-url http://controller:35357 \
--os-project-name admin --os-username admin --os-auth-type password \
token issue</userinput>
<computeroutput>Password:
+------------+----------------------------------+
| Field | Value |
+------------+----------------------------------+
| expires | 2015-03-24T18:55:01Z |
| id | ff5ed908984c4a4190f584d826d75fed |
| project_id | cf12a15c5ea84b019aec3dc45580896b |
| user_id | 4d411f2291f34941b30eef9bd797505a |
+------------+----------------------------------+</computeroutput></screen>
<note>
<para>Because OpenStack generates IDs dynamically, you will see
different values from this example command output.</para>
<para>This command uses the password for the <literal>admin</literal>
user.</para>
</note>
</step>
<step>
<para>The Identity version 3 API adds support for domains that contain
projects and users. Projects and users can use the same names in
different domains. Therefore, in order to use the version 3 API,
requests must also explicitly contain at least the
<literal>default</literal> domain or use IDs. For simplicity, this
guide explicitly uses the <literal>default</literal> domain
so examples can use names instead of IDs.</para>
<screen><prompt>$</prompt> <userinput>openstack --os-auth-url http://controller:35357 \
--os-project-domain-id default --os-user-domain-id default \
--os-project-name admin --os-username admin --os-auth-type password \
token issue</userinput>
<computeroutput>Password:
+------------+----------------------------------+
| Field | Value |
+------------+----------------------------------+
| expires | 2015-03-24T18:55:01Z |
| id | ff5ed908984c4a4190f584d826d75fed |
| project_id | cf12a15c5ea84b019aec3dc45580896b |
| user_id | 4d411f2291f34941b30eef9bd797505a |
+------------+----------------------------------+</computeroutput></screen>
<note>
<para>This command uses the password for the <literal>admin</literal>
user.</para>
</note>
</step>
<step>
<para os="ubuntu;rhel;centos;fedora;sles;opensuse">As the
<literal>admin</literal> tenant and user, list users to verify
that the Identity service contains the users that you created
in <xref linkend="keystone-users"/>:</para>
<para os="debian">As the <literal>admin</literal> tenant and user, list
users to verify that the Identity service contains the users
<literal>admin</literal> user, list projects to verify that the
<literal>admin</literal> user can execute admin-only CLI commands
and that the Identity service contains the projects that you
created in <xref linkend="keystone-users"/>:</para>
<para os="debian">As the <literal>admin</literal> user, list projects
to verify that the <literal>admin</literal> user can execute
CLI commands and that the Identity service contains the projects
created by the configuration tool:</para>
<screen><prompt>$</prompt> <userinput>keystone --os-tenant-name admin --os-username admin --os-password <replaceable>ADMIN_PASS</replaceable> \
--os-auth-url http://controller:35357/v2.0 user-list</userinput>
<computeroutput>+----------------------------------+---------+---------+---------------------+
| id | name | enabled | email |
+----------------------------------+---------+---------+---------------------+
| ea8c352d253443118041c9c8b8416040 | admin | True | admin@example.com |
| 7004dfa0dda84d63aef81cf7f100af01 | demo | True | demo@example.com |
+----------------------------------+---------+---------+---------------------+</computeroutput></screen>
<screen><prompt>$</prompt> <userinput>openstack --os-auth-url http://controller:35357 \
--os-project-name admin --os-username admin --os-auth-type password \
project list</userinput>
<computeroutput>Password:
+----------------------------------+---------+
| ID | Name |
+----------------------------------+---------+
| 55cbd79c0c014c8a95534ebd16213ca1 | service |
| ab8ea576c0574b6092bb99150449b2d3 | demo |
| cf12a15c5ea84b019aec3dc45580896b | admin |
+----------------------------------+---------+</computeroutput></screen>
<note>
<para>This command uses the password for the <literal>admin</literal>
user.</para>
</note>
</step>
<step>
<para os="ubuntu;rhel;centos;fedora;sles;opensuse">As the
<literal>admin</literal> tenant and user, list roles to verify
that the Identity service contains the role that you created
in <xref linkend="keystone-users"/>:</para>
<para os="debian">As the <literal>admin</literal> tenant and user, list
roles to verify that the Identity service contains the role
created by the configuration tool:</para>
<screen><prompt>$</prompt> <userinput>keystone --os-tenant-name admin --os-username admin --os-password <replaceable>ADMIN_PASS</replaceable> \
--os-auth-url http://controller:35357/v2.0 role-list</userinput>
<computeroutput>+----------------------------------+----------+
| id | name |
+----------------------------------+----------+
| 9fe2ff9ee4384b1894a90878d3e92bab | _member_ |
| bff3a6083b714fa29c9344bf8930d199 | admin |
+----------------------------------+----------+</computeroutput></screen>
<literal>admin</literal> user, list users to verify that the
Identity service contains the users that you created in
<xref linkend="keystone-users"/>:</para>
<para os="debian">As the <literal>admin</literal> user, list users to
verify that the Identity service contains the users created by
the configuration tool:</para>
<screen><prompt>$</prompt> <userinput>openstack --os-auth-url http://controller:35357 \
--os-project-name admin --os-username admin --os-auth-type password \
user list</userinput>
<computeroutput>Password:
+----------------------------------+-------+
| ID | Name |
+----------------------------------+-------+
| 4d411f2291f34941b30eef9bd797505a | admin |
| 3a81e6c8103b46709ef8d141308d4c72 | demo |
+----------------------------------+-------+</computeroutput></screen>
<note>
<para>This command uses the password for the <literal>admin</literal>
user.</para>
</note>
</step>
<step>
<para>As the <literal>demo</literal> tenant and user, request an
authentication token:</para>
<screen><prompt>$</prompt> <userinput>keystone --os-tenant-name demo --os-username demo --os-password <replaceable>DEMO_PASS</replaceable> \
--os-auth-url http://controller:35357/v2.0 token-get</userinput>
<computeroutput>+-----------+----------------------------------+
<para os="ubuntu;rhel;centos;fedora;sles;opensuse">As the
<literal>admin</literal> user, list roles to verify that the
Identity service contains the role that you created in
<xref linkend="keystone-users"/>:</para>
<para os="debian">As the <literal>admin</literal> user, list roles to
verify that the Identity service contains the role created by the
configuration tool:</para>
<screen><prompt>$</prompt> <userinput>openstack --os-auth-url http://controller:35357 \
--os-project-name admin --os-username admin --os-auth-type password \
role list</userinput>
<computeroutput>Password:
+----------------------------------+----------+
| ID | Name |
+----------------------------------+----------+
| 9fe2ff9ee4384b1894a90878d3e92bab | _member_ |
| cd2cb9a39e874ea69e5d4b896eb16128 | admin |
+----------------------------------+----------+</computeroutput></screen>
<note>
<para>This command uses the password for the <literal>admin</literal>
user.</para>
</note>
</step>
<step>
<para>As the <literal>demo</literal> user, request an authentication
token from the Identity version 3 API:</para>
<screen><prompt>$</prompt> <userinput>openstack --os-auth-url http://controller:5000 \
--os-project-domain-id default --os-user-domain-id default \
--os-project-name demo --os-username demo --os-auth-type password \
token issue</userinput>
<computeroutput>Password:
+-----------+----------------------------------+
| Property | Value |
+-----------+----------------------------------+
| expires | 2014-10-10T12:51:33Z |
@@ -102,24 +156,20 @@
| tenant_id | 4aa51bb942be4dd0ac0555d7591f80a6 |
| user_id | 7004dfa0dda84d63aef81cf7f100af01 |
+-----------+----------------------------------+</computeroutput></screen>
<para>Replace <replaceable>DEMO_PASS</replaceable> with the password
you chose for the <literal>demo</literal> user in the Identity
service.</para>
<note>
<para>This command uses the password for the <literal>demo</literal>
user and API port 5000 which only allows regular (non-admin)
access to the Identity service API.</para>
</note>
</step>
<step>
<para>As the <literal>demo</literal> tenant and user, attempt to list
users to verify that you cannot execute admin-only CLI
commands:</para>
<screen><prompt>$</prompt> <userinput>keystone --os-tenant-name demo --os-username demo --os-password <replaceable>DEMO_PASS</replaceable> \
--os-auth-url http://controller:35357/v2.0 user-list</userinput>
<computeroutput>You are not authorized to perform the requested action, admin_required. (HTTP 403)</computeroutput></screen>
<note>
<para>Each OpenStack service references a
<filename>policy.json</filename> file to determine the operations
available to a particular tenant, user, or role. For more
information, see the
<link xlink:href="http://docs.openstack.org/openstack-ops/content/projects_users.html">Operations Guide - Managing Projects and Users</link>.</para>
</note>
<para>As the <literal>demo</literal> user, attempt to list users
to verify that it cannot execute admin-only CLI commands:</para>
<screen><prompt>$</prompt> <userinput>openstack --os-auth-url http://controller:5000 \
--os-project-domain-id default --os-user-domain-id default \
--os-project-name demo --os-username demo --os-auth-type password \
user list</userinput>
<computeroutput>ERROR: openstack You are not authorized to perform the requested action, admin_required. (HTTP 403)</computeroutput></screen>
</step>
</procedure>
</section>

16
doc/install-guide/section_launch-instance-neutron.xml
View File

@@ -10,25 +10,17 @@
<para>Most cloud images support
<glossterm>public key authentication</glossterm> rather than conventional
user name/password authentication. Before launching an instance, you must
generate a public/private key pair using <command>ssh-keygen</command>
and add the public key to your OpenStack environment.</para>
generate a public/private key pair.</para>
<step>
<para>Source the <literal>demo</literal> tenant credentials:</para>
<screen><prompt>$</prompt> <userinput>source demo-openrc.sh</userinput></screen>
</step>
<step>
<para>Generate a key pair:</para>
<screen><prompt>$</prompt> <userinput>ssh-keygen</userinput></screen>
<para>Generate and add a key pair:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-add demo-key</userinput></screen>
</step>
<step>
<para>Add the public key to your OpenStack environment:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-add --pub-key ~/.ssh/id_rsa.pub demo-key</userinput></screen>
<note>
<para>This command provides no output.</para>
</note>
</step>
<step>
<para>Verify addition of the public key:</para>
<para>Verify addition of the key pair:</para>
<screen><prompt>$</prompt> <userinput>nova keypair-list</userinput>
<computeroutput>+----------+-------------------------------------------------+
| Name | Fingerprint |