diff --git a/doc/install-guide/source/keystone-install.rst b/doc/install-guide/source/keystone-install.rst index 9bb821ba88..b3ae929a81 100644 --- a/doc/install-guide/source/keystone-install.rst +++ b/doc/install-guide/source/keystone-install.rst @@ -1,47 +1,44 @@ -===================== Install and configure -===================== +~~~~~~~~~~~~~~~~~~~~~ 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 an SQL database. -| - -**To configure prerequisites** +Prerequisites +------------- Before you configure the OpenStack Identity service, you must create a database and an administration token. -#. To create the database, complete these steps: +#. To create the database, complete the following actions: - a. Use the database access client to connect to the database server as the - ``root`` user: + * Use the database access client to connect to the database server as the + ``root`` user: - .. code-block:: console + .. code-block:: console - $ mysql -u root -p + $ mysql -u root -p - b. Create the ``keystone`` database: + * Create the ``keystone`` database: - .. code-block:: console + .. code-block:: console - CREATE DATABASE keystone; + CREATE DATABASE keystone; - c. Grant proper access to the ``keystone`` database: + * Grant proper access to the ``keystone`` database: - .. code-block:: console + .. code-block:: console - GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'localhost' \ - IDENTIFIED BY 'KEYSTONE_DBPASS'; - GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'%' \ - IDENTIFIED BY 'KEYSTONE_DBPASS'; + GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'localhost' \ + IDENTIFIED BY 'KEYSTONE_DBPASS'; + GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'%' \ + IDENTIFIED BY 'KEYSTONE_DBPASS'; - Replace ``KEYSTONE_DBPASS`` with a suitable password. - - d. Exit the database access client. + Replace ``KEYSTONE_DBPASS`` with a suitable password. + * Exit the database access client. #. Generate a random value to use as the administration token during initial configuration: @@ -50,143 +47,142 @@ database and an administration token. $ openssl rand -hex 10 -| - .. only:: obs or rdo or ubuntu - **To install and configure the Identity service components** + Install and configure components + -------------------------------- .. include:: shared/note_configuration_vary_by_distribution.rst .. note:: - In Kilo, the keystone project deprecates Eventlet in favor of a WSGI - server. This guide uses the Apache HTTP server with ``mod_wsgi`` to - serve keystone requests on ports 5000 and 35357. By default, the - keystone service still listens on ports 5000 and 35357. Therefore, - this guide disables the keystone service. + In Kilo and Liberty releases, the keystone project deprecates eventlet + in favor of a separate web server with WSGI extensions. This guide uses + the Apache HTTP server with ``mod_wsgi`` to serve Identity service + requests on port 5000 and 35357. By default, the keystone service + still listens on ports 5000 and 35357. Therefore, this guide disables + the keystone service. The keystone project plans to remove eventlet + support in Mitaka. -.. only:: ubuntu + .. only:: ubuntu - #. Disable the keystone service from starting automatically after - installation: - - .. code-block:: console - - # echo "manual" > /etc/init/keystone.override - - #. Run the following command to install the packages: - - .. only:: ubuntu + #. Disable the keystone service from starting automatically after + installation: .. code-block:: console - # apt-get install keystone python-openstackclient apache2 libapache2-mod-wsgi memcached python-memcache + # echo "manual" > /etc/init/keystone.override -.. only:: obs or rdo + #. Run the following command to install the packages: - #. Run the following command to install the packages: + .. only:: ubuntu - .. only:: rdo + .. code-block:: console + + # apt-get install keystone python-openstackclient apache2 libapache2-mod-wsgi \ + memcached python-memcache + + .. only:: obs or rdo + + #. Run the following command to install the packages: + + .. only:: rdo + + .. code-block:: console + + # yum install openstack-keystone httpd mod_wsgi python-openstackclient \ + memcached python-memcached + + .. only:: obs + + .. code-block:: console + + # zypper install openstack-keystone python-openstackclient apache2-mod_wsgi \ + memcached python-python-memcached + + .. only:: obs or rdo + + 2. Start the Memcached service and configure it to start when the system + boots: .. code-block:: console - # yum install openstack-keystone httpd mod_wsgi python-openstackclient memcached python-memcached + # systemctl enable memcached.service + # systemctl start memcached.service - .. only:: obs + .. only:: obs or rdo or ubuntu + + 3. Edit the ``/etc/keystone/keystone.conf`` file and complete the following + actions: + + * In the ``[DEFAULT]`` section, define the value of the initial + administration token: + + .. code-block:: ini + + [DEFAULT] + ... + admin_token = ADMIN_TOKEN + + Replace ``ADMIN_TOKEN`` with the random value that you generated in a + previous step. + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mysql+pymysql://keystone:KEYSTONE_DBPASS@controller/keystone + + Replace ``KEYSTONE_DBPASS`` with the password you chose for the database. + + * In the ``[memcache]`` section, configure the Memcache service: + + .. code-block:: ini + + [memcache] + ... + servers = localhost:11211 + + * In the ``[token]`` section, configure the UUID token provider and + Memcached driver: + + .. code-block:: ini + + [token] + ... + provider = uuid + driver = memcache + + * In the ``[revoke]`` section, configure the SQL revocation driver: + + .. code-block:: ini + + [revoke] + ... + driver = sql + + * (Optional) To assist with troubleshooting, enable verbose logging in the + ``[DEFAULT]`` section: + + .. code-block:: ini + + [DEFAULT] + ... + verbose = True + + .. only:: obs or rdo or ubuntu + + 4. Populate the Identity service database: .. code-block:: console - # zypper install openstack-keystone python-openstackclient apache2-mod_wsgi memcached python-python-memcached - -.. only:: obs or rdo - - 2. Start the Memcached service and configure it to start when the system - boots: - - .. code-block:: console - - # systemctl enable memcached.service - # systemctl start memcached.service - -.. only:: obs or rdo or ubuntu - - 3. Edit the :file:`/etc/keystone/keystone.conf` file and complete the following - actions: - - a. In the ``[DEFAULT]`` section, define the value of the initial - administration token: - - .. code-block:: ini - :linenos: - - [DEFAULT] - ... - admin_token = ADMIN_TOKEN - - Replace ``ADMIN_TOKEN`` with the random value that you generated in a - previous step. - - b. In the ``[database]`` section, configure database access: - - .. code-block:: ini - :linenos: - - [database] - ... - connection = mysql+pymysql://keystone:KEYSTONE_DBPASS@controller/keystone - - Replace ``KEYSTONE_DBPASS`` with the password you chose for the database. - - c. In the ``[memcache]`` section, configure the Memcache service: - - .. code-block:: ini - :linenos: - - [memcache] - ... - servers = localhost:11211 - - d. In the ``[token]`` section, configure the UUID token provider and - Memcached driver: - - .. code-block:: ini - :linenos: - - [token] - ... - provider = keystone.token.providers.uuid.Provider - driver = keystone.token.persistence.backends.memcache.Token - - e. In the ``[revoke]`` section, configure the SQL revocation driver: - - .. code-block:: ini - :linenos: - - [revoke] - ... - driver = keystone.contrib.revoke.backends.sql.Revoke - - f. (Optional) To assist with troubleshooting, enable verbose logging in the - ``[DEFAULT]`` section: - - .. code-block:: ini - :linenos: - - [DEFAULT] - ... - verbose = True - -.. only:: obs or rdo or ubuntu - - 4. Populate the Identity service database: - - .. code-block:: console - - # su -s /bin/sh -c "keystone-manage db_sync" keystone + # su -s /bin/sh -c "keystone-manage db_sync" keystone .. only:: debian - **To install and configure the components** + Install and configure the components + ------------------------------------ #. Run the following command to install the packages: @@ -203,7 +199,6 @@ database and an administration token. which will fill the below database access directive. .. code-block:: ini - :linenos: [database] ... @@ -237,7 +232,6 @@ database and an administration token. you entered: .. code-block:: ini - :linenos: [DEFAULT] ... @@ -291,234 +285,212 @@ database and an administration token. .. only:: obs or rdo or ubuntu - **To configure the Apache HTTP server** + Configure the Apache HTTP server + -------------------------------- -.. only:: rdo + .. only:: rdo - #. Edit the :file:`/etc/httpd/conf/httpd.conf` file and configure the - ``ServerName`` option to reference the controller node: + #. Edit the ``/etc/httpd/conf/httpd.conf`` file and configure the + ``ServerName`` option to reference the controller node: - .. code-block:: apache - :linenos: + .. code-block:: apache - ServerName controller + ServerName controller - #. Create the :file:`/etc/httpd/conf.d/wsgi-keystone.conf` file with - the following content: + #. Create the ``/etc/httpd/conf.d/wsgi-keystone.conf`` file with + the following content: - .. code-block:: apache - :linenos: + .. code-block:: apache - Listen 5000 - Listen 35357 + Listen 5000 + Listen 35357 - - WSGIDaemonProcess keystone-public processes=5 threads=1 user=keystone group=keystone display-name=%{GROUP} - WSGIProcessGroup keystone-public - WSGIScriptAlias / /var/www/cgi-bin/keystone/main - WSGIApplicationGroup %{GLOBAL} - WSGIPassAuthorization On - LogLevel info - ErrorLogFormat "%{cu}t %M" - ErrorLog /var/log/httpd/keystone-error.log - CustomLog /var/log/httpd/keystone-access.log combined - + + WSGIDaemonProcess keystone-public processes=5 threads=1 user=keystone group=keystone display-name=%{GROUP} + WSGIProcessGroup keystone-public + WSGIScriptAlias / /usr/bin/keystone-wsgi-public + WSGIApplicationGroup %{GLOBAL} + WSGIPassAuthorization On + = 2.4> + ErrorLogFormat "%{cu}t %M" + + ErrorLog /var/log/httpd/keystone-error.log + CustomLog /var/log/httpd/keystone-access.log combined - - WSGIDaemonProcess keystone-admin processes=5 threads=1 user=keystone group=keystone display-name=%{GROUP} - WSGIProcessGroup keystone-admin - WSGIScriptAlias / /var/www/cgi-bin/keystone/admin - WSGIApplicationGroup %{GLOBAL} - WSGIPassAuthorization On - LogLevel info - ErrorLogFormat "%{cu}t %M" - ErrorLog /var/log/httpd/keystone-error.log - CustomLog /var/log/httpd/keystone-access.log combined - + + = 2.4> + Require all granted + + + Order allow,deny + Allow from all + + + -.. only:: ubuntu + + WSGIDaemonProcess keystone-admin processes=5 threads=1 user=keystone group=keystone display-name=%{GROUP} + WSGIProcessGroup keystone-admin + WSGIScriptAlias / /usr/bin/keystone-wsgi-admin + WSGIApplicationGroup %{GLOBAL} + WSGIPassAuthorization On + = 2.4> + ErrorLogFormat "%{cu}t %M" + + ErrorLog /var/log/httpd/keystone-error.log + CustomLog /var/log/httpd/keystone-access.log combined - #. Edit the :file:`/etc/apache2/apache2.conf` file and configure the - ``ServerName`` option to reference the controller node: + + = 2.4> + Require all granted + + + Order allow,deny + Allow from all + + + - .. code-block:: apache - :linenos: + .. only:: ubuntu - ServerName controller + #. Edit the ``/etc/apache2/apache2.conf`` file and configure the + ``ServerName`` option to reference the controller node: - #. Create the :file:`/etc/apache2/sites-available/wsgi-keystone.conf` file - with the following content: + .. code-block:: apache - .. code-block:: apache - :linenos: + ServerName controller - Listen 5000 - Listen 35357 + #. Create the ``/etc/apache2/sites-available/wsgi-keystone.conf`` file + with the following content: - - 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 - = 2.4> - ErrorLogFormat "%{cu}t %M" - - LogLevel info - ErrorLog /var/log/apache2/keystone-error.log - CustomLog /var/log/apache2/keystone-access.log combined - + .. code-block:: apache - - 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 - = 2.4> - ErrorLogFormat "%{cu}t %M" - - LogLevel info - ErrorLog /var/log/apache2/keystone-error.log - CustomLog /var/log/apache2/keystone-access.log combined - + Listen 5000 + Listen 35357 - #. Enable the Identity service virtual hosts: + + WSGIDaemonProcess keystone-public processes=5 threads=1 user=keystone group=keystone display-name=%{GROUP} + WSGIProcessGroup keystone-public + WSGIScriptAlias / /usr/bin/keystone-wsgi-public + WSGIApplicationGroup %{GLOBAL} + WSGIPassAuthorization On + = 2.4> + ErrorLogFormat "%{cu}t %M" + + ErrorLog /var/log/apache2/keystone.log + CustomLog /var/log/apache2/keystone_access.log combined - .. code-block:: console + + = 2.4> + Require all granted + + + Order allow,deny + Allow from all + + + - # ln -s /etc/apache2/sites-available/wsgi-keystone.conf /etc/apache2/sites-enabled + + WSGIDaemonProcess keystone-admin processes=5 threads=1 user=keystone group=keystone display-name=%{GROUP} + WSGIProcessGroup keystone-admin + WSGIScriptAlias / /usr/bin/keystone-wsgi-admin + WSGIApplicationGroup %{GLOBAL} + WSGIPassAuthorization On + = 2.4> + ErrorLogFormat "%{cu}t %M" + + ErrorLog /var/log/apache2/keystone.log + CustomLog /var/log/apache2/keystone_access.log combined -.. only:: obs + + = 2.4> + Require all granted + + + Order allow,deny + Allow from all + + + - #. Edit the :file:`/etc/sysconfig/apache2` file and configure the - ``APACHE_SERVERNAME`` option to reference the controller node: - - .. code-block:: apache - :linenos: - - APACHE_SERVERNAME="controller" - - #. Create the :file:`/etc/apache2/conf.d/wsgi-keystone.conf` file - with the following content: - - .. code-block:: apache - :linenos: - - Listen 5000 - Listen 35357 - - - WSGIDaemonProcess keystone-public processes=5 threads=1 user=keystone display-name=%{GROUP} - WSGIProcessGroup keystone-public - WSGIScriptAlias / /srv/www/cgi-bin/keystone/main - WSGIApplicationGroup %{GLOBAL} - WSGIPassAuthorization On - ErrorLogFormat "%{cu}t %M" - LogLevel info - ErrorLog /var/log/apache2/keystone-error.log - CustomLog /var/log/apache2/keystone-access.log combined - - - - WSGIDaemonProcess keystone-admin processes=5 threads=1 user=keystone display-name=%{GROUP} - WSGIProcessGroup keystone-admin - WSGIScriptAlias / /srv/www/cgi-bin/keystone/admin - WSGIApplicationGroup %{GLOBAL} - WSGIPassAuthorization On - ErrorLogFormat "%{cu}t %M" - LogLevel info - ErrorLog /var/log/apache2/keystone-error.log - CustomLog /var/log/apache2/keystone-access.log combined - - -.. only:: ubuntu - - 4. Create the directory structure for the WSGI components: - - .. code-block:: console - - # mkdir -p /var/www/cgi-bin/keystone - - - 5. Copy the WSGI components from the upstream repository into this - directory: - - .. code-block:: console - - # curl http://git.openstack.org/cgit/openstack/keystone/plain/httpd/keystone.py?h=stable/kilo \ - | tee /var/www/cgi-bin/keystone/main /var/www/cgi-bin/keystone/admin - - 6. Adjust ownership and permissions on this directory and the files in it: - - .. code-block:: console - - # chown -R keystone:keystone /var/www/cgi-bin/keystone - # chmod 755 /var/www/cgi-bin/keystone/* - -.. only:: obs or rdo - - 3. Create the directory structure for the WSGI components: - - .. only:: rdo + #. Enable the Identity service virtual hosts: .. code-block:: console - # mkdir -p /var/www/cgi-bin/keystone + # ln -s /etc/apache2/sites-available/wsgi-keystone.conf /etc/apache2/sites-enabled - .. only:: obs + .. only:: obs + + #. Edit the ``/etc/sysconfig/apache2`` file and configure the + ``APACHE_SERVERNAME`` option to reference the controller node: + + .. code-block:: apache + + APACHE_SERVERNAME="controller" + + #. Create the ``/etc/apache2/conf.d/wsgi-keystone.conf`` file + with the following content: + + .. code-block:: apache + + Listen 5000 + Listen 35357 + + + WSGIDaemonProcess keystone-public processes=5 threads=1 user=keystone group=keystone display-name=%{GROUP} + WSGIProcessGroup keystone-public + WSGIScriptAlias / /usr/bin/keystone-wsgi-public + WSGIApplicationGroup %{GLOBAL} + WSGIPassAuthorization On + = 2.4> + ErrorLogFormat "%{cu}t %M" + + ErrorLog /var/log/apache2/keystone.log + CustomLog /var/log/apache2/keystone_access.log combined + + + = 2.4> + Require all granted + + + Order allow,deny + Allow from all + + + + + + WSGIDaemonProcess keystone-admin processes=5 threads=1 user=keystone group=keystone display-name=%{GROUP} + WSGIProcessGroup keystone-admin + WSGIScriptAlias / /usr/bin/keystone-wsgi-admin + WSGIApplicationGroup %{GLOBAL} + WSGIPassAuthorization On + = 2.4> + ErrorLogFormat "%{cu}t %M" + + ErrorLog /var/log/apache2/keystone.log + CustomLog /var/log/apache2/keystone_access.log combined + + + = 2.4> + Require all granted + + + Order allow,deny + Allow from all + + + + + 6. Recursively change the ownership of the ``/etc/keystone`` directory: .. code-block:: console - # mkdir -p /srv/www/cgi-bin/keystone + # chown -R keystone:keystone /etc/keystone - 4. Copy the WSGI components from the upstream repository into this - directory: - - .. only:: rdo - - .. code-block:: console - - # curl http://git.openstack.org/cgit/openstack/keystone/plain/httpd/keystone.py?h=stable/kilo \ - | tee /var/www/cgi-bin/keystone/main /var/www/cgi-bin/keystone/admin - - .. only:: obs - - .. code-block:: console - - # curl http://git.openstack.org/cgit/openstack/keystone/plain/httpd/keystone.py?h=stable/kilo \ - | tee /srv/www/cgi-bin/keystone/main /srv/www/cgi-bin/keystone/admin - -.. only:: obs or rdo - - 5. Adjust ownership and permissions on this directory and the files in it: - - .. only:: rdo - - .. code-block:: console - - # chown -R keystone:keystone /var/www/cgi-bin/keystone - # chmod 755 /var/www/cgi-bin/keystone/* - - .. only:: obs - - .. code-block:: console - - # chown -R keystone:keystone /srv/www/cgi-bin/keystone - # chmod 755 /srv/www/cgi-bin/keystone/* - -.. only:: obs - - 6. Change the ownership of :file:`/etc/keystone` to give the - ``keystone`` system access to it: - - .. code-block:: console - - # chown -R keystone:keystone /etc/keystone - -| - -**To finalize the installation** +Finalize the installation +------------------------- .. only:: ubuntu @@ -554,23 +526,3 @@ database and an administration token. # systemctl enable apache2.service # systemctl start apache2.service - - #. 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. - - The packages already contain a cron job under - :file:`/etc/cron.hourly/keystone`, so it is not necessary to manually - configure a periodic task that purges expired tokens. - -.. only:: debian - - * 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. - - The packages already contain a cron job under - :file:`/etc/cron.hourly/keystone`, so it is not necessary to manually - configure a periodic task that purges expired tokens. diff --git a/doc/install-guide/source/keystone-openrc.rst b/doc/install-guide/source/keystone-openrc.rst index 365a312cd7..28b0952280 100644 --- a/doc/install-guide/source/keystone-openrc.rst +++ b/doc/install-guide/source/keystone-openrc.rst @@ -1,27 +1,25 @@ -=========================================== Create OpenStack client environment scripts -=========================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The previous section used a combination of environment variables and command options to interact with the Identity service via the -:command:`openstack` 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 +``openstack`` 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 `OpenStack User Guide `__. -To create the scripts -~~~~~~~~~~~~~~~~~~~~~ +Creating the scripts +-------------------- Create client environment scripts for the ``admin`` and ``demo`` projects and users. Future portions of this guide reference these scripts to load appropriate credentials for client operations. -#. Edit the :file:`admin-openrc.sh` file and add the following content: +#. Edit the ``admin-openrc.sh`` file and add the following content: .. code-block:: bash - :linenos: export OS_PROJECT_DOMAIN_ID=default export OS_USER_DOMAIN_ID=default @@ -30,14 +28,14 @@ scripts to load appropriate credentials for client operations. export OS_USERNAME=admin export OS_PASSWORD=ADMIN_PASS export OS_AUTH_URL=http://controller:35357/v3 + export OS_IDENTITY_API_VERSION=3 Replace ``ADMIN_PASS`` with the password you chose for the ``admin`` user in the Identity service. -#. Edit the :file:`demo-openrc.sh` file and add the following content: +#. Edit the ``demo-openrc.sh`` file and add the following content: .. code-block:: bash - :linenos: export OS_PROJECT_DOMAIN_ID=default export OS_USER_DOMAIN_ID=default @@ -46,18 +44,19 @@ scripts to load appropriate credentials for client operations. export OS_USERNAME=demo export OS_PASSWORD=DEMO_PASS export OS_AUTH_URL=http://controller:5000/v3 + export OS_IDENTITY_API_VERSION=3 Replace ``DEMO_PASS`` with the password you chose for the ``demo`` user in the Identity service. -To load client environment scripts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Using the scripts +----------------- To run clients as a specific project and user, you can simply load the associated client environment script prior to running them. For example: -#. Load the :file:`admin-openrc.sh` file to populate +#. Load the ``admin-openrc.sh`` file to populate environment variables with the location of the Identity service and the ``admin`` project and user credentials: diff --git a/doc/install-guide/source/keystone-services.rst b/doc/install-guide/source/keystone-services.rst index b910f9da48..d4c31420ce 100644 --- a/doc/install-guide/source/keystone-services.rst +++ b/doc/install-guide/source/keystone-services.rst @@ -1,13 +1,13 @@ -========================================== -Create the service entity and API endpoint -========================================== +Create the service entity and API endpoints +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Identity service provides a catalog of services and their locations. Each service that you add to your OpenStack environment requires a :term:`service` entity and several :term:`API endpoints` in the catalog. -**To configure prerequisites** +Prerequisites +------------- .. only:: obs or rdo or ubuntu @@ -17,6 +17,13 @@ in the catalog. :doc:`keystone-install` to initialize the service entity and API endpoint for the Identity service. +.. only:: debian + + .. note:: + + The packages can automatically create the service entity and API + endpoints. + You must pass the value of the authentication token to the :command:`openstack` command with the ``--os-token`` parameter or set the OS_TOKEN environment variable. Similarly, you must also pass the value of the @@ -49,7 +56,7 @@ environment variables to reduce command length. .. code-block:: console - $ export OS_URL=http://controller:35357/v2.0 + $ export OS_URL=http://controller:35357/v3 .. only:: debian @@ -58,7 +65,14 @@ environment variables to reduce command length. The packages can automatically create the service entity and API endpoint. -**To create the service entity and API endpoint** +#. Configure the Identity API version: + + .. code-block:: console + + $ export OS_IDENTITY_API_VERSION=3 + +Create the service entity and API endpoints +------------------------------------------- #. The Identity service manages a catalog of services in your OpenStack environment. Services use this catalog to determine the other services @@ -91,41 +105,72 @@ environment variables to reduce command length. 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 separate networks - that service different types of users for security reasons. For - instance, the public API network might be reachable from 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 guide uses the management network for all endpoint variations and - the default ``RegionOne`` region. + tenants by default, while the public and internal APIs do not allow these + operations. In a production environment, the variants might reside on + separate networks that service different types of users for security + reasons. For instance, the public API network might be visible from the + Internet so customers can manage their clouds. The admin API network + might be restricted to operators within the organization that manages + cloud infrastructure. The internal API network might be restricted to + the hosts that contain OpenStack services. Also, OpenStack supports + multiple regions for scalability. For simplicity, this guide uses the + management network for all endpoint variations and the default + ``RegionOne`` region. - Create the Identity service API endpoint: + Create the Identity service API endpoints: .. code-block:: console - $ openstack endpoint create \ - --publicurl http://controller:5000/v2.0 \ - --internalurl http://controller:5000/v2.0 \ - --adminurl http://controller:35357/v2.0 \ - --region RegionOne \ - identity + $ openstack endpoint create --region RegionOne \ + identity public http://controller:5000/v2.0 +--------------+----------------------------------+ | Field | Value | +--------------+----------------------------------+ - | adminurl | http://controller:35357/v2.0 | - | id | 4a9ffc04b8eb4848a49625a3df0170e5 | - | internalurl | http://controller:5000/v2.0 | - | publicurl | http://controller:5000/v2.0 | + | enabled | True | + | id | 30fff543e7dc4b7d9a0fb13791b78bf4 | + | interface | public | | region | RegionOne | - | service_id | 4ddaae90388b4ebc9d252ec2252d8d10 | + | region_id | RegionOne | + | service_id | 8c8c0927262a45ad9066cfe70d46892c | | service_name | keystone | | service_type | identity | + | url | http://controller:5000/v2.0 | + +--------------+----------------------------------+ + + $ openstack endpoint create --region RegionOne \ + identity internal http://controller:5000/v2.0 + +--------------+----------------------------------+ + | Field | Value | + +--------------+----------------------------------+ + | enabled | True | + | id | 57cfa543e7dc4b712c0ab137911bc4fe | + | interface | internal | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 6f8de927262ac12f6066cfe70d99ac51 | + | service_name | keystone | + | service_type | identity | + | url | http://controller:5000/v2.0 | + +--------------+----------------------------------+ + + $ openstack endpoint create --region RegionOne \ + identity admin http://controller:35357/v2.0 + +--------------+----------------------------------+ + | Field | Value | + +--------------+----------------------------------+ + | enabled | True | + | id | 78c3dfa3e7dc44c98ab1b1379122ecb1 | + | interface | admin | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 34ab3d27262ac449cba6cfe704dbc11f | + | service_name | keystone | + | service_type | identity | + | url | http://controller:5000/v2.0 | +--------------+----------------------------------+ .. note:: Each service that you add to your OpenStack environment requires one - or more service entities and one API endpoint in the Identity + or more service entities and three API endpoint variants in the Identity service. diff --git a/doc/install-guide/source/keystone-users.rst b/doc/install-guide/source/keystone-users.rst index 39deeddf6f..b24401454c 100644 --- a/doc/install-guide/source/keystone-users.rst +++ b/doc/install-guide/source/keystone-users.rst @@ -1,6 +1,5 @@ -================================= Create projects, users, and roles -================================= +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Identity service provides authentication services for each OpenStack service. The authentication service uses a combination of :term:`domains @@ -9,169 +8,166 @@ service. The authentication service uses a combination of :term:`domains .. note:: - For simplicity, this guide implicitly uses the ``default`` domain. - -.. only:: debian - - .. note:: - - The packages can automatically create the service entity and API - endpoint. - -To create tenants, users, and roles -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + For simplicity, this guide uses the ``default`` domain. #. Create an administrative project, user, and role for administrative operations in your environment: - a. Create the ``admin`` project: + * Create the ``admin`` project: - .. code-block:: console + .. code-block:: console - $ openstack project create --description "Admin Project" admin - +-------------+----------------------------------+ - | Field | Value | - +-------------+----------------------------------+ - | description | Admin Project | - | enabled | True | - | id | cf12a15c5ea84b019aec3dc45580896b | - | name | admin | - +-------------+----------------------------------+ + $ openstack project create --domain default \ + --description "Admin Project" admin + +-------------+----------------------------------+ + | Field | Value | + +-------------+----------------------------------+ + | description | Admin Project | + | domain_id | default | + | enabled | True | + | id | 343d245e850143a096806dfaefa9afdc | + | is_domain | False | + | name | admin | + | parent_id | None | + +-------------+----------------------------------+ - .. note:: + .. note:: - OpenStack generates IDs dynamically, so you will see different - values in the example command output. + OpenStack generates IDs dynamically, so you will see different + values in the example command output. - b. Create the ``admin`` user: + * Create the ``admin`` user: - .. code-block:: console + .. code-block:: console - $ openstack user create --password-prompt admin - User Password: - Repeat User Password: - +------------+----------------------------------+ - | Field | Value | - +------------+----------------------------------+ - | email | None | - | enabled | True | - | id | 4d411f2291f34941b30eef9bd797505a | - | name | admin | - | username | admin | - +------------+----------------------------------+ + $ openstack user create --domain default \ + --password-prompt admin + User Password: + Repeat User Password: + +-----------+----------------------------------+ + | Field | Value | + +-----------+----------------------------------+ + | domain_id | default | + | enabled | True | + | id | ac3377633149401296f6c0d92d79dc16 | + | name | admin | + +-----------+----------------------------------+ - c. Create the ``admin`` role: + * Create the ``admin`` role: - .. code-block:: console + .. code-block:: console - $ openstack role create admin - +-------+----------------------------------+ - | Field | Value | - +-------+----------------------------------+ - | id | cd2cb9a39e874ea69e5d4b896eb16128 | - | name | admin | - +-------+----------------------------------+ + $ openstack role create admin + +-------+----------------------------------+ + | Field | Value | + +-------+----------------------------------+ + | id | cd2cb9a39e874ea69e5d4b896eb16128 | + | name | admin | + +-------+----------------------------------+ - d. Add the ``admin`` role to the ``admin`` project and user: + * Add the ``admin`` role to the ``admin`` project and user: - .. code-block:: console + .. code-block:: console - $ openstack role add --project admin --user admin admin - +-------+----------------------------------+ - | Field | Value | - +-------+----------------------------------+ - | id | cd2cb9a39e874ea69e5d4b896eb16128 | - | name | admin | - +-------+----------------------------------+ + $ openstack role add --project admin --user admin admin - .. note:: + .. note:: - Any roles that you create must map to roles specified in the - :file:`policy.json` file in the configuration file directory of each - OpenStack service. The default policy for most services grants - administrative access to the ``admin`` role. For more information, - see the `Operations Guide - Managing Projects and - Users `__. + This command provides no output. + + .. note:: + + Any roles that you create must map to roles specified in the + ``policy.json`` file in the configuration file directory of each + OpenStack service. The default policy for most services grants + administrative access to the ``admin`` role. For more information, + see the `Operations Guide - Managing Projects and + Users `__. #. This guide uses a service project that contains a unique user for each - service that you add to your environment. + service that you add to your environment. Create the ``service`` + project: - a. Create the ``service`` project: + .. code-block:: console - .. code-block:: console - - $ openstack project create --description "Service Project" service - +-------------+----------------------------------+ - | Field | Value | - +-------------+----------------------------------+ - | description | Service Project | - | enabled | True | - | id | 55cbd79c0c014c8a95534ebd16213ca1 | - | name | service | - +-------------+----------------------------------+ + $ openstack project create --domain default \ + --description "Service Project" service + +-------------+----------------------------------+ + | Field | Value | + +-------------+----------------------------------+ + | description | Service Project | + | domain_id | default | + | enabled | True | + | id | 894cdfa366d34e9d835d3de01e752262 | + | is_domain | False | + | name | service | + | parent_id | None | + +-------------+----------------------------------+ #. Regular (non-admin) tasks should use an unprivileged project and user. As an example, this guide creates the ``demo`` project and user. - a. Create the ``demo`` project: + * Create the ``demo`` project: - .. code-block:: console + .. code-block:: console - $ openstack project create --description "Demo Project" demo - +-------------+----------------------------------+ - | Field | Value | - +-------------+----------------------------------+ - | description | Demo Project | - | enabled | True | - | id | ab8ea576c0574b6092bb99150449b2d3 | - | name | demo | - +-------------+----------------------------------+ + $ openstack project create --domain default \ + --description "Demo Project" demo + +-------------+----------------------------------+ + | Field | Value | + +-------------+----------------------------------+ + | description | Demo Project | + | domain_id | default | + | enabled | True | + | id | ed0b60bf607743088218b0a533d5943f | + | is_domain | False | + | name | demo | + | parent_id | None | + +-------------+----------------------------------+ - .. note:: + .. note:: Do not repeat this step when creating additional users for this project. - b. Create the ``demo`` user: + * Create the ``demo`` user: - .. code-block:: console + .. code-block:: console - $ openstack user create --password-prompt demo - User Password: - Repeat User Password: - +------------+----------------------------------+ - | Field | Value | - +------------+----------------------------------+ - | email | None | - | enabled | True | - | id | 3a81e6c8103b46709ef8d141308d4c72 | - | name | demo | - | username | demo | - +------------+----------------------------------+ + $ openstack user create --domain default \ + --password-prompt demo + User Password: + Repeat User Password: + +-----------+----------------------------------+ + | Field | Value | + +-----------+----------------------------------+ + | domain_id | default | + | enabled | True | + | id | 58126687cbcc4888bfa9ab73a2256f27 | + | name | demo | + +-----------+----------------------------------+ - c. Create the ``user`` role: + * Create the ``user`` role: - .. code-block:: console + .. code-block:: console - $ openstack role create user - +-------+----------------------------------+ - | Field | Value | - +-------+----------------------------------+ - | id | 9fe2ff9ee4384b1894a90878d3e92bab | - | name | user | - +-------+----------------------------------+ + $ openstack role create user + +-------+----------------------------------+ + | Field | Value | + +-------+----------------------------------+ + | id | 997ce8d05fc143ac97d83fdfb5998552 | + | name | user | + +-------+----------------------------------+ - d. Add the ``user`` role to the ``demo`` project and user: + * Add the ``user`` role to the ``demo`` project and user: - .. code-block:: console + .. code-block:: console - $ openstack role add --project demo --user demo user - +-------+----------------------------------+ - | Field | Value | - +-------+----------------------------------+ - | id | 9fe2ff9ee4384b1894a90878d3e92bab | - | name | user | - +-------+----------------------------------+ + $ openstack role add --project demo --user demo user + + .. note:: + + This command provides no output. .. note:: diff --git a/doc/install-guide/source/keystone-verify.rst b/doc/install-guide/source/keystone-verify.rst index 105a87dda0..f3de9915ba 100644 --- a/doc/install-guide/source/keystone-verify.rst +++ b/doc/install-guide/source/keystone-verify.rst @@ -1,6 +1,5 @@ -================ Verify operation -================ +~~~~~~~~~~~~~~~~ Verify operation of the Identity service before installing other services. @@ -10,7 +9,7 @@ services. 1. For security reasons, disable the temporary authentication token mechanism: - Edit the :file:`/etc/keystone/keystone-paste.ini` + Edit the ``/etc/keystone/keystone-paste.ini`` file and remove ``admin_token_auth`` from the ``[pipeline:public_api]``, ``[pipeline:admin_api]``, and ``[pipeline:api_v3]`` sections. @@ -20,7 +19,7 @@ services. 1. For security reasons, disable the temporary authentication token mechanism: - Edit the :file:`/usr/share/keystone/keystone-dist-paste.ini` + Edit the ``/usr/share/keystone/keystone-dist-paste.ini`` file and remove ``admin_token_auth`` from the ``[pipeline:public_api]``, ``[pipeline:admin_api]``, and ``[pipeline:api_v3]`` sections. @@ -31,38 +30,11 @@ services. $ unset OS_TOKEN OS_URL -3. As the ``admin`` user, request an authentication token from - the Identity version 2.0 API: +3. As the ``admin`` user, request an authentication token: .. code-block:: console - $ openstack --os-auth-url http://controller:35357 \ - --os-project-name admin --os-username admin \ - --os-auth-type password token issue - Password: - +------------+----------------------------------+ - | Field | Value | - +------------+----------------------------------+ - | expires | 2015-03-24T18:55:01Z | - | id | ff5ed908984c4a4190f584d826d75fed | - | project_id | cf12a15c5ea84b019aec3dc45580896b | - | user_id | 4d411f2291f34941b30eef9bd797505a | - +------------+----------------------------------+ - - .. note:: - - This command uses the password for the ``admin`` user. - -4. 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 ``default`` - domain or use IDs. For simplicity, this guide explicitly uses - the ``default`` domain so examples can use names instead of IDs. - - .. code-block:: console - - $ openstack --os-auth-url http://controller:35357 \ + $ openstack --os-auth-url http://controller:35357/v3 \ --os-project-domain-id default --os-user-domain-id default \ --os-project-name admin --os-username admin --os-auth-type password \ token issue @@ -80,75 +52,11 @@ services. This command uses the password for the ``admin`` user. -5. As the ``admin`` user, list projects to verify that the - ``admin`` user can execute admin-only CLI commands and - that the Identity service contains the projects that you - created in :doc:`keystone-users`: +4. As the ``demo`` user, request an authentication token: .. code-block:: console - $ openstack --os-auth-url http://controller:35357 \ - --os-project-name admin --os-username admin \ - --os-auth-type password project list - Password: - +----------------------------------+---------+ - | ID | Name | - +----------------------------------+---------+ - | 55cbd79c0c014c8a95534ebd16213ca1 | service | - | ab8ea576c0574b6092bb99150449b2d3 | demo | - | cf12a15c5ea84b019aec3dc45580896b | admin | - +----------------------------------+---------+ - - .. note:: - - This command uses the password for the ``admin`` user. - -6. As the ``admin`` user, list users to verify that the Identity service - contains the users that you created in :doc:`keystone-users`: - - .. code-block:: console - - $ openstack --os-auth-url http://controller:35357 \ - --os-project-name admin --os-username admin \ - --os-auth-type password user list - Password: - +----------------------------------+-------+ - | ID | Name | - +----------------------------------+-------+ - | 4d411f2291f34941b30eef9bd797505a | admin | - | 3a81e6c8103b46709ef8d141308d4c72 | demo | - +----------------------------------+-------+ - - .. note:: - - This command uses the password for the ``admin`` user. - -7. As the ``admin`` user, list roles to verify that the Identity service - contains the role that you created in :doc:`keystone-users`: - - .. code-block:: console - - $ openstack --os-auth-url http://controller:35357 \ - --os-project-name admin --os-username admin \ - --os-auth-type password role list - Password: - +----------------------------------+-------+ - | ID | Name | - +----------------------------------+-------+ - | 9fe2ff9ee4384b1894a90878d3e92bab | user | - | cd2cb9a39e874ea69e5d4b896eb16128 | admin | - +----------------------------------+-------+ - - .. note:: - - This command uses the password for the ``admin`` user. - -8. As the ``demo`` user, request an authentication token from - the Identity version 3 API: - - .. code-block:: console - - $ openstack --os-auth-url http://controller:5000 \ + $ openstack --os-auth-url http://controller:5000/v3 \ --os-project-domain-id default --os-user-domain-id default \ --os-project-name demo --os-username demo --os-auth-type password \ token issue @@ -167,16 +75,3 @@ services. This command uses the password for the ``demo`` user and API port 5000 which only allows regular (non-admin) access to the Identity service API. - -9. As the ``demo`` user, attempt to list users - to verify that it cannot execute admin-only CLI commands: - - .. code-block:: console - - $ 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 - Password: - ERROR: openstack You are not authorized to perform the - requested action, admin_required. (HTTP 403)