![Matthew Kassawara](/assets/img/avatar_default.png)
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
379 lines
18 KiB
XML
379 lines
18 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section[
|
|
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
|
|
%openstack;
|
|
]>
|
|
<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="keystone-install">
|
|
<title>Install and configure</title>
|
|
<para>This section describes how to install and configure the OpenStack
|
|
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
|
|
a database and an administration token.</para>
|
|
<step>
|
|
<para>To create the database, complete these steps:</para>
|
|
<substeps>
|
|
<step>
|
|
<para>Use the database access client to connect to the database
|
|
server as the <literal>root</literal> user:</para>
|
|
<screen><prompt>$</prompt> <userinput>mysql -u root -p</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Create the <literal>keystone</literal> database:</para>
|
|
<screen><userinput>CREATE DATABASE keystone;</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Grant proper access to the <literal>keystone</literal>
|
|
database:</para>
|
|
<screen><userinput>GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'localhost' \
|
|
IDENTIFIED BY '<replaceable>KEYSTONE_DBPASS</replaceable>';</userinput>
|
|
<userinput>GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'%' \
|
|
IDENTIFIED BY '<replaceable>KEYSTONE_DBPASS</replaceable>';</userinput></screen>
|
|
<para>Replace <replaceable>KEYSTONE_DBPASS</replaceable> with a suitable password.</para>
|
|
</step>
|
|
<step>
|
|
<para>Exit the database access client.</para>
|
|
</step>
|
|
</substeps>
|
|
</step>
|
|
<step>
|
|
<para>Generate a random value to use as the administration token during
|
|
initial configuration:</para>
|
|
<screen os="ubuntu;rhel;centos;fedora"><prompt>$</prompt> <userinput>openssl rand -hex 10</userinput></screen>
|
|
<screen os="sles;opensuse"><prompt>$</prompt> <userinput>openssl rand 10 | hexdump -e '1/1 "%.2x"'</userinput></screen>
|
|
</step>
|
|
</procedure>
|
|
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
|
|
<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-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>
|
|
<step>
|
|
<para>Edit the <filename>/etc/keystone/keystone.conf</filename> file and
|
|
complete the following actions:</para>
|
|
<substeps>
|
|
<step>
|
|
<para>In the <literal>[DEFAULT]</literal> section, define the value
|
|
of the initial administration token:</para>
|
|
<programlisting language="ini">[DEFAULT]
|
|
...
|
|
admin_token = <replaceable>ADMIN_TOKEN</replaceable></programlisting>
|
|
<para>Replace <replaceable>ADMIN_TOKEN</replaceable> with the random
|
|
value that you generated in a previous step.</para>
|
|
</step>
|
|
<step>
|
|
<para>In the <literal>[database]</literal> section, configure
|
|
database access:</para>
|
|
<programlisting language="ini">[database]
|
|
...
|
|
connection = mysql://keystone:<replaceable>KEYSTONE_DBPASS</replaceable>@<replaceable>controller</replaceable>/keystone</programlisting>
|
|
<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 Memcached driver:</para>
|
|
<programlisting language="ini">[token]
|
|
...
|
|
provider = keystone.token.providers.uuid.Provider
|
|
driver = keystone.token.persistence.backends.memcache.Token</programlisting>
|
|
</step>
|
|
<step>
|
|
<para>In the <literal>[revoke]</literal> section, configure
|
|
the SQL revocation driver:</para>
|
|
<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,
|
|
enable verbose logging in the <literal>[DEFAULT]</literal> section:</para>
|
|
<programlisting language="ini">[DEFAULT]
|
|
...
|
|
verbose = True</programlisting>
|
|
</step>
|
|
</substeps>
|
|
</step>
|
|
<step os="rhel;centos;fedora">
|
|
<para>Create generic certificates and keys and restrict access to the
|
|
associated files:</para>
|
|
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>keystone-manage pki_setup --keystone-user keystone --keystone-group keystone</userinput>
|
|
<prompt>#</prompt> <userinput>chown -R keystone:keystone /var/log/keystone</userinput>
|
|
<prompt>#</prompt> <userinput>chown -R keystone:keystone /etc/keystone/ssl</userinput>
|
|
<prompt>#</prompt> <userinput>chmod -R o-rwx /etc/keystone/ssl</userinput></screen>
|
|
</step>
|
|
<step os="ubuntu;rhel;centos;fedora">
|
|
<para>Populate the Identity service database:</para>
|
|
<screen><prompt>#</prompt> <userinput>su -s /bin/sh -c "keystone-manage db_sync" keystone</userinput></screen>
|
|
</step>
|
|
</procedure>
|
|
<procedure os="debian">
|
|
<title>To install and configure the components</title>
|
|
<step>
|
|
<para>Run the following command to install the packages:</para>
|
|
<screen><prompt>#</prompt> <userinput>apt-get install keystone</userinput></screen>
|
|
<note><para><package>python-keystoneclient</package> will automatically be installed as
|
|
it is a dependency of the <package>keystone</package> package.</para></note>
|
|
</step>
|
|
<step>
|
|
<para>Respond to prompts for <xref linkend="debconf-dbconfig-common"/>, which
|
|
will fill the below database access directive.</para>
|
|
<programlisting language="ini">[database]
|
|
...
|
|
connection = mysql://keystone:<replaceable>KEYSTONE_DBPASS</replaceable>@<replaceable>controller</replaceable>/keystone</programlisting>
|
|
<para>If you decide to not use <command>dbconfig-common</command>, then you will have to
|
|
create the database and manage its access rights yourself, and run the
|
|
following by hand.</para>
|
|
<screen><prompt>#</prompt> <userinput>keystone-manage db_sync</userinput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Generate a random value to use as the administration token during
|
|
initial configuration:</para>
|
|
<screen><prompt>$</prompt> <userinput>openssl rand -hex 10</userinput></screen>
|
|
<para>Configure the initial administration token:</para>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata scale="50" fileref="figures/debconf-screenshots/keystone_1_admin_token.png"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
<para>Use the random value that you generated in a previous step. If you
|
|
install using non-interactive mode or you do not specify this token,
|
|
the configuration tool generates a random value.</para>
|
|
<para>Later on, the package will configure the below directive with the
|
|
value you entered:</para>
|
|
<programlisting language="ini">[DEFAULT]
|
|
...
|
|
admin_token = <replaceable>ADMIN_TOKEN</replaceable></programlisting>
|
|
</step>
|
|
<step>
|
|
<para>Create the <literal>admin</literal> tenant and user:</para>
|
|
<para>During the final stage of the package installation, it is possible
|
|
to automatically create an admin tenant and an admin user. This can
|
|
later be used for other OpenStack services to contact the Identity
|
|
service. This is the equivalent of running the below commands:</para>
|
|
<screen><prompt>#</prompt> <userinput>keystone tenant-create --name admin --description "Admin Tenant"</userinput>
|
|
<prompt>#</prompt> <userinput>keystone user-create --name admin --pass <replaceable>ADMIN_PASS</replaceable> --email root@localhost</userinput>
|
|
<prompt>#</prompt> <userinput>keystone role-create --name admin</userinput>
|
|
<prompt>#</prompt> <userinput>keystone user-role-add user-role-add --user admin --role admin --tenant admin</userinput></screen>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata scale="50"
|
|
fileref="figures/debconf-screenshots/keystone_2_register_admin_tenant_yes_no.png"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
<para> </para>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata scale="50"
|
|
fileref="figures/debconf-screenshots/keystone_3_admin_user_name.png"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
<para> </para>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata scale="50"
|
|
fileref="figures/debconf-screenshots/keystone_4_admin_user_email.png"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
<para> </para>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata scale="50"
|
|
fileref="figures/debconf-screenshots/keystone_5_admin_user_pass.png"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
<para> </para>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata scale="50"
|
|
fileref="figures/debconf-screenshots/keystone_6_admin_user_pass_confirm.png"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
</step>
|
|
<step>
|
|
<title>Create the Identity service endpoints</title>
|
|
<para>In Debian, the Keystone package offers automatic registration of Keystone
|
|
in the service catalogue. This is equivalent of running the below commands:</para>
|
|
<screen><prompt>#</prompt> <userinput>keystone service-create --name keystone --type identity --description "OpenStack Identity"</userinput>
|
|
<prompt>#</prompt> <userinput>keystone endpoint-create \
|
|
--service-id $(keystone service-list | awk '/ identity / {print $2}') \
|
|
--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></screen>
|
|
<informalfigure>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata scale="50"
|
|
fileref="figures/debconf-screenshots/keystone_7_register_endpoint.png"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</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
|
|
|
|
<VirtualHost *:5000>
|
|
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
|
|
<IfVersion >= 2.4>
|
|
ErrorLogFormat "%{cu}t %M"
|
|
</IfVersion>
|
|
LogLevel info
|
|
ErrorLog /var/log/apache2/keystone-error.log
|
|
CustomLog /var/log/apache2/keystone-access.log combined
|
|
</VirtualHost>
|
|
|
|
<VirtualHost *:35357>
|
|
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
|
|
<IfVersion >= 2.4>
|
|
ErrorLogFormat "%{cu}t %M"
|
|
</IfVersion>
|
|
LogLevel info
|
|
ErrorLog /var/log/apache2/keystone-error.log
|
|
CustomLog /var/log/apache2/keystone-access.log combined
|
|
</VirtualHost></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 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
|
|
system boots:</para>
|
|
<screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>systemctl enable openstack-keystone.service</userinput>
|
|
<prompt>#</prompt> <userinput>systemctl start openstack-keystone.service</userinput></screen>
|
|
<para os="sles">On SLES:</para>
|
|
<screen os="sles"><prompt>#</prompt> <userinput>service openstack-keystone start</userinput>
|
|
<prompt>#</prompt> <userinput>chkconfig openstack-keystone on</userinput></screen>
|
|
<para os="opensuse">On openSUSE:</para>
|
|
<screen os="opensuse"><prompt>#</prompt> <userinput>systemctl enable openstack-keystone.service</userinput>
|
|
<prompt>#</prompt> <userinput>systemctl start openstack-keystone.service</userinput></screen>
|
|
</step>
|
|
<step os="ubuntu">
|
|
<para>By default, the Ubuntu packages create a SQLite database.</para>
|
|
<para>Because this configuration uses a SQL database server, you can
|
|
remove the SQLite database file:</para>
|
|
<screen><prompt>#</prompt> <userinput>rm -f /var/lib/keystone/keystone.db</userinput></screen>
|
|
</step>
|
|
<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.</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="rhel;centos;fedora"><prompt>#</prompt> <userinput>(crontab -l -u keystone 2>&1 | grep -q token_flush) || \
|
|
echo '@hourly /usr/bin/keystone-manage token_flush >/var/log/keystone/keystone-tokenflush.log 2>&1' \
|
|
>> /var/spool/cron/keystone</userinput></screen>
|
|
</step>
|
|
</procedure>
|
|
</section>
|