path: root/doc/source/install/install-rdo.rst

.. _install-rdo:

Install and configure for Red Hat Enterprise Linux and CentOS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section describes how to install and configure the Orchestration service
for Red Hat Enterprise Linux 7 and CentOS 7.

Prerequisites
-------------

Before you install and configure Orchestration, you must create a
database, service credentials, and API endpoints. Orchestration also
requires additional information in the Identity service.

#. To create the database, complete these steps:

   * Use the database access client to connect to the database
     server as the ``root`` user:

     .. code-block:: console

        $ mysql -u root -p

   * Create the ``heat`` database:

     .. code-block:: console

        CREATE DATABASE heat;

   * Grant proper access to the ``heat`` database:

     .. code-block:: console

        GRANT ALL PRIVILEGES ON heat.* TO 'heat'@'localhost' \
          IDENTIFIED BY 'HEAT_DBPASS';
        GRANT ALL PRIVILEGES ON heat.* TO 'heat'@'%' \
          IDENTIFIED BY 'HEAT_DBPASS';

     Replace ``HEAT_DBPASS`` with a suitable password.

   * Exit the database access client.

#. Source the ``admin`` credentials to gain access to
   admin-only CLI commands:

   .. code-block:: console

      $ . admin-openrc

#. To create the service credentials, complete these steps:

   * Create the ``heat`` user:

     .. code-block:: console

        $ openstack user create --domain default --password-prompt heat
        User Password:
        Repeat User Password:
        +-----------+----------------------------------+
        | Field     | Value                            |
        +-----------+----------------------------------+
        | domain_id | e0353a670a9e496da891347c589539e9 |
        | enabled   | True                             |
        | id        | ca2e175b851943349be29a328cc5e360 |
        | name      | heat                             |
        +-----------+----------------------------------+

   * Add the ``admin`` role to the ``heat`` user:

     .. code-block:: console

        $ openstack role add --project service --user heat admin

     .. note::

        If installing OpenStack manually following the `Keystone install
        guide`_, the name of the services project is ``service`` as given
        above. However, traditional methods of installing RDO (such as
        PackStack and TripleO) use ``services`` as the name of the service
        project. If you installed RDO using a Puppet-based method, substitute
        ``services`` as the project name.

     .. _`Keystone install guide`: https://docs.openstack.org/keystone/latest/install/keystone-users-rdo.html

     .. note::

        This command provides no output.

   * Create the ``heat`` and ``heat-cfn`` service entities:

     .. code-block:: console

        $ openstack service create --name heat \
          --description "Orchestration" orchestration
        +-------------+----------------------------------+
        | Field       | Value                            |
        +-------------+----------------------------------+
        | description | Orchestration                    |
        | enabled     | True                             |
        | id          | 727841c6f5df4773baa4e8a5ae7d72eb |
        | name        | heat                             |
        | type        | orchestration                    |
        +-------------+----------------------------------+

        $ openstack service create --name heat-cfn \
          --description "Orchestration"  cloudformation
        +-------------+----------------------------------+
        | Field       | Value                            |
        +-------------+----------------------------------+
        | description | Orchestration                    |
        | enabled     | True                             |
        | id          | c42cede91a4e47c3b10c8aedc8d890c6 |
        | name        | heat-cfn                         |
        | type        | cloudformation                   |
        +-------------+----------------------------------+

#. Create the Orchestration service API endpoints:

   .. code-block:: console

      $ openstack endpoint create --region RegionOne \
        orchestration public http://controller:8004/v1/%\(tenant_id\)s
      +--------------+-----------------------------------------+
      | Field        | Value                                   |
      +--------------+-----------------------------------------+
      | enabled      | True                                    |
      | id           | 3f4dab34624e4be7b000265f25049609        |
      | interface    | public                                  |
      | region       | RegionOne                               |
      | region_id    | RegionOne                               |
      | service_id   | 727841c6f5df4773baa4e8a5ae7d72eb        |
      | service_name | heat                                    |
      | service_type | orchestration                           |
      | url          | http://controller:8004/v1/%(tenant_id)s |
      +--------------+-----------------------------------------+

      $ openstack endpoint create --region RegionOne \
        orchestration internal http://controller:8004/v1/%\(tenant_id\)s
      +--------------+-----------------------------------------+
      | Field        | Value                                   |
      +--------------+-----------------------------------------+
      | enabled      | True                                    |
      | id           | 9489f78e958e45cc85570fec7e836d98        |
      | interface    | internal                                |
      | region       | RegionOne                               |
      | region_id    | RegionOne                               |
      | service_id   | 727841c6f5df4773baa4e8a5ae7d72eb        |
      | service_name | heat                                    |
      | service_type | orchestration                           |
      | url          | http://controller:8004/v1/%(tenant_id)s |
      +--------------+-----------------------------------------+

      $ openstack endpoint create --region RegionOne \
        orchestration admin http://controller:8004/v1/%\(tenant_id\)s
      +--------------+-----------------------------------------+
      | Field        | Value                                   |
      +--------------+-----------------------------------------+
      | enabled      | True                                    |
      | id           | 76091559514b40c6b7b38dde790efe99        |
      | interface    | admin                                   |
      | region       | RegionOne                               |
      | region_id    | RegionOne                               |
      | service_id   | 727841c6f5df4773baa4e8a5ae7d72eb        |
      | service_name | heat                                    |
      | service_type | orchestration                           |
      | url          | http://controller:8004/v1/%(tenant_id)s |
      +--------------+-----------------------------------------+

   .. code-block:: console

      $ openstack endpoint create --region RegionOne \
        cloudformation public http://controller:8000/v1
      +--------------+----------------------------------+
      | Field        | Value                            |
      +--------------+----------------------------------+
      | enabled      | True                             |
      | id           | b3ea082e019c4024842bf0a80555052c |
      | interface    | public                           |
      | region       | RegionOne                        |
      | region_id    | RegionOne                        |
      | service_id   | c42cede91a4e47c3b10c8aedc8d890c6 |
      | service_name | heat-cfn                         |
      | service_type | cloudformation                   |
      | url          | http://controller:8000/v1        |
      +--------------+----------------------------------+

      $ openstack endpoint create --region RegionOne \
        cloudformation internal http://controller:8000/v1
      +--------------+----------------------------------+
      | Field        | Value                            |
      +--------------+----------------------------------+
      | enabled      | True                             |
      | id           | 169df4368cdc435b8b115a9cb084044e |
      | interface    | internal                         |
      | region       | RegionOne                        |
      | region_id    | RegionOne                        |
      | service_id   | c42cede91a4e47c3b10c8aedc8d890c6 |
      | service_name | heat-cfn                         |
      | service_type | cloudformation                   |
      | url          | http://controller:8000/v1        |
      +--------------+----------------------------------+

      $ openstack endpoint create --region RegionOne \
        cloudformation admin http://controller:8000/v1
      +--------------+----------------------------------+
      | Field        | Value                            |
      +--------------+----------------------------------+
      | enabled      | True                             |
      | id           | 3d3edcd61eb343c1bbd629aa041ff88b |
      | interface    | internal                         |
      | region       | RegionOne                        |
      | region_id    | RegionOne                        |
      | service_id   | c42cede91a4e47c3b10c8aedc8d890c6 |
      | service_name | heat-cfn                         |
      | service_type | cloudformation                   |
      | url          | http://controller:8000/v1        |
      +--------------+----------------------------------+

#. Orchestration requires additional information in the Identity service to
   manage stacks. To add this information, complete these steps:

   * Create the ``heat`` domain that contains projects and users
     for stacks:

     .. code-block:: console

        $ openstack domain create --description "Stack projects and users" heat
        +-------------+----------------------------------+
        | Field       | Value                            |
        +-------------+----------------------------------+
        | description | Stack projects and users         |
        | enabled     | True                             |
        | id          | 0f4d1bd326f2454dacc72157ba328a47 |
        | name        | heat                             |
        +-------------+----------------------------------+

   * Create the ``heat_domain_admin`` user to manage projects and users
     in the ``heat`` domain:

     .. code-block:: console

       $ openstack user create --domain heat --password-prompt heat_domain_admin
       User Password:
       Repeat User Password:
       +-----------+----------------------------------+
       | Field     | Value                            |
       +-----------+----------------------------------+
       | domain_id | 0f4d1bd326f2454dacc72157ba328a47 |
       | enabled   | True                             |
       | id        | b7bd1abfbcf64478b47a0f13cd4d970a |
       | name      | heat_domain_admin                |
       +-----------+----------------------------------+

   * Add the ``admin`` role to the ``heat_domain_admin`` user in the
     ``heat`` domain to enable administrative stack management
     privileges by the ``heat_domain_admin`` user:

     .. code-block:: console

        $ openstack role add --domain heat --user-domain heat --user heat_domain_admin admin

     .. note::

        This command provides no output.

   * Create the ``heat_stack_owner`` role:

     .. code-block:: console

        $ openstack role create heat_stack_owner
        +-----------+----------------------------------+
        | Field     | Value                            |
        +-----------+----------------------------------+
        | domain_id | None                             |
        | id        | 15e34f0c4fed4e68b3246275883c8630 |
        | name      | heat_stack_owner                 |
        +-----------+----------------------------------+

   * Add the ``heat_stack_owner`` role to the ``demo`` project and user to
     enable stack management by the ``demo`` user:

     .. code-block:: console

        $ openstack role add --project demo --user demo heat_stack_owner

     .. note::

        This command provides no output.

     .. note::

        You must add the ``heat_stack_owner`` role to each user
        that manages stacks.

   * Create the ``heat_stack_user`` role:

     .. code-block:: console

        $ openstack role create heat_stack_user
        +-----------+----------------------------------+
        | Field     | Value                            |
        +-----------+----------------------------------+
        | domain_id | None                             |
        | id        | 88849d41a55d4d1d91e4f11bffd8fc5c |
        | name      | heat_stack_user                  |
        +-----------+----------------------------------+

     .. note::

        The Orchestration service automatically assigns the
        ``heat_stack_user`` role to users that it creates
        during stack deployment. By default, this role restricts
        API <Application Programming Interface (API)> operations.
        To avoid conflicts, do not add
        this role to users with the ``heat_stack_owner`` role.

Install and configure components
--------------------------------

.. note::

   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.

#. Install the packages:

   .. code-block:: console

      # yum install openstack-heat-api openstack-heat-api-cfn \
        openstack-heat-engine

2. Edit the ``/etc/heat/heat.conf`` file and complete the following
   actions:

   * In the ``[database]`` section, configure database access:

     .. code-block:: ini

        [database]
        ...
        connection = mysql+pymysql://heat:HEAT_DBPASS@controller/heat

     Replace ``HEAT_DBPASS`` with the password you chose for the
     Orchestration database.

   * In the ``[DEFAULT]`` section,
     configure ``RabbitMQ`` message queue access:

     .. code-block:: ini

        [DEFAULT]
        ...
        transport_url = rabbit://openstack:RABBIT_PASS@controller

     Replace ``RABBIT_PASS`` with the password you chose for the
     ``openstack`` account in ``RabbitMQ``.

   * In the ``[keystone_authtoken]``, ``[trustee]``,
     and ``[clients_keystone]`` sections,
     configure Identity service access:

     .. code-block:: ini

        [keystone_authtoken]
        ...
        www_authenticate_uri = http://controller:5000
        auth_url = http://controller:5000
        memcached_servers = controller:11211
        auth_type = password
        project_domain_name = default
        user_domain_name = default
        project_name = service
        username = heat
        password = HEAT_PASS

        [trustee]
        ...
        auth_type = password
        auth_url = http://controller:5000
        username = heat
        password = HEAT_PASS
        user_domain_name = default

        [clients_keystone]
        ...
        auth_uri = http://controller:5000

     Replace ``HEAT_PASS`` with the password you chose for the
     ``heat`` user in the Identity service.

   * In the ``[DEFAULT]`` section, configure the metadata and
     wait condition URLs:

     .. code-block:: ini

        [DEFAULT]
        ...
        heat_metadata_server_url = http://controller:8000
        heat_waitcondition_server_url = http://controller:8000/v1/waitcondition

   * In the ``[DEFAULT]`` section, configure the stack domain and
     administrative credentials:

     .. code-block:: ini

        [DEFAULT]
        ...
        stack_domain_admin = heat_domain_admin
        stack_domain_admin_password = HEAT_DOMAIN_PASS
        stack_user_domain_name = heat

     Replace ``HEAT_DOMAIN_PASS`` with the password you chose for the
     ``heat_domain_admin`` user in the Identity service.

3. Populate the Orchestration database:

   .. code-block:: console

      # su -s /bin/sh -c "heat-manage db_sync" heat

   .. note::

      Ignore any deprecation messages in this output.

Finalize installation
---------------------

* Start the Orchestration services and configure them to start
  when the system boots:

  .. code-block:: console

     # systemctl enable openstack-heat-api.service \
       openstack-heat-api-cfn.service openstack-heat-engine.service
     # systemctl start openstack-heat-api.service \
       openstack-heat-api-cfn.service openstack-heat-engine.service