openstack-manuals/doc/install-guide/section_heat-install.xml

<?xml version="1.0" encoding="UTF-8"?>
<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="heat-install-controller-node">
  <title>Install and configure Orchestration</title>
  <para>This section describes how to install and configure the
    Orchestration module, code-named heat, on the controller node.</para>
  <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
    <title>To configure prerequisites</title>
    <para>Before you install and configure Orchestration, you must create a
      database and Identity service credentials including endpoints.</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>heat</literal> database:</para>
          <screen><userinput>CREATE DATABASE heat;</userinput></screen>
        </step>
        <step>
          <para>Grant proper access to the <literal>heat</literal>
            database:</para>
          <screen><userinput>GRANT ALL PRIVILEGES ON heat.* TO 'heat'@'localhost' \
  IDENTIFIED BY '<replaceable>HEAT_DBPASS</replaceable>';</userinput>
<userinput>GRANT ALL PRIVILEGES ON heat.* TO 'heat'@'%' \
  IDENTIFIED BY '<replaceable>HEAT_DBPASS</replaceable>';</userinput></screen>
          <para>Replace <replaceable>HEAT_DBPASS</replaceable> with a suitable
            password.</para>
        </step>
        <step>
          <para>Exit the database access client.</para>
        </step>
      </substeps>
    </step>
    <step>
      <para>Source the <literal>admin</literal> credentials to gain access to
        admin-only CLI commands:</para>
      <screen><prompt>$</prompt> <userinput>source admin-openrc.sh</userinput></screen>
    </step>
    <step>
      <para>To create the Identity service credentials, complete these
        steps:</para>
      <substeps>
        <step>
          <para>Create the <literal>heat</literal> user:</para>
          <screen><prompt>$</prompt> <userinput>keystone user-create --name heat --pass <replaceable>HEAT_PASS</replaceable></userinput>
<computeroutput>+----------+----------------------------------+
| Property |              Value               |
+----------+----------------------------------+
|  email   |                                  |
| enabled  |               True               |
|    id    | 7fd67878dcd04d0393469ef825a7e005 |
|   name   |               heat               |
| username |               heat               |
+----------+----------------------------------+</computeroutput></screen>
          <para>Replace <replaceable>HEAT_PASS</replaceable> with a suitable
            password.</para>
        </step>
        <step>
          <para>Link the <literal>heat</literal> user to the
            <literal>service</literal> tenant and <literal>admin</literal>
            role:</para>
          <screen><prompt>$</prompt> <userinput>keystone user-role-add --user heat --tenant service --role admin</userinput></screen>
          <note>
            <para>This command provides no output.</para>
          </note>
        </step>
        <step>
          <para>Create the <literal>heat_stack_user</literal> and
            <literal>heat_stack_owner</literal> roles:</para>
          <screen><prompt>$</prompt> <userinput>keystone role-create --name heat_stack_user</userinput>
<prompt>$</prompt> <userinput>keystone role-create --name heat_stack_owner</userinput></screen>
          <para>By default, users created by Orchestration use the
            <literal>heat_stack_user</literal> role.</para>
          <para>The <literal>heat_stack_user</literal> role is for users
            created by heat, and is restricted to specific API actions.
            The <literal>heat_stack_owner</literal> role is assigned to
            users who create heat stacks.</para>
          <warning><para>Because the <literal>heat_stack_owner</literal>
              role has limited operational access to heat, you must never
              assign this role to a user with a <literal>heat_stack_user</literal>
              role.</para></warning>
        </step>
        <step>
          <para>Create the <literal>heat</literal> and
            <literal>heat-cfn</literal> services:</para>
          <screen><prompt>$</prompt> <userinput>keystone service-create --name heat --type orchestration \
  --description "Orchestration"</userinput>
<computeroutput>+-------------+----------------------------------+
|   Property  |              Value               |
+-------------+----------------------------------+
| description |          Orchestration           |
|   enabled   |               True               |
|      id     | 031112165cad4c2bb23e84603957de29 |
|     name    |               heat               |
|     type    |          orchestration           |
+-------------+----------------------------------+</computeroutput>
<prompt>$</prompt> <userinput>keystone service-create --name heat-cfn --type cloudformation \
  --description "Orchestration"</userinput>
<computeroutput>+-------------+----------------------------------+
|   Property  |              Value               |
+-------------+----------------------------------+
| description |          Orchestration           |
|   enabled   |               True               |
|      id     | 297740d74c0a446bbff867acdccb33fa |
|     name    |             heat-cfn             |
|     type    |          cloudformation          |
+-------------+----------------------------------+</computeroutput></screen>
        </step>
        <step>
          <para>Create the Identity service endpoints:</para>
          <screen><prompt>$</prompt> <userinput>keystone endpoint-create \
  --service-id $(keystone service-list | awk '/ orchestration / {print $2}') \
  --publicurl http://<replaceable>controller</replaceable>:8004/v1/%\(tenant_id\)s \
  --internalurl http://<replaceable>controller</replaceable>:8004/v1/%\(tenant_id\)s \
  --adminurl http://<replaceable>controller</replaceable>:8004/v1/%\(tenant_id\)s \
  --region regionOne</userinput>
<computeroutput>+-------------+-----------------------------------------+
|   Property  |                  Value                  |
+-------------+-----------------------------------------+
|   adminurl  | http://controller:8004/v1/%(tenant_id)s |
|      id     |     f41225f665694b95a46448e8676b0dc2    |
| internalurl | http://controller:8004/v1/%(tenant_id)s |
|  publicurl  | http://controller:8004/v1/%(tenant_id)s |
|    region   |                regionOne                |
|  service_id |     031112165cad4c2bb23e84603957de29    |
+-------------+-----------------------------------------+</computeroutput>
<prompt>$</prompt> <userinput>keystone endpoint-create \
  --service-id $(keystone service-list | awk '/ cloudformation / {print $2}') \
  --publicurl http://<replaceable>controller</replaceable>:8000/v1 \
  --internalurl http://<replaceable>controller</replaceable>:8000/v1 \
  --adminurl http://<replaceable>controller</replaceable>:8000/v1 \
  --region regionOne</userinput>
<computeroutput>+-------------+----------------------------------+
|   Property  |              Value               |
+-------------+----------------------------------+
|   adminurl  |    http://controller:8000/v1     |
|      id     | f41225f665694b95a46448e8676b0dc2 |
| internalurl |    http://controller:8000/v1     |
|  publicurl  |    http://controller:8000/v1     |
|    region   |            regionOne             |
|  service_id | 297740d74c0a446bbff867acdccb33fa |
+-------------+----------------------------------+</computeroutput></screen>
        </step>
      </substeps>
    </step>
  </procedure>
  <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
    <title>To install and configure the Orchestration components</title>
    <step>
      <para>Run the following commands to install the packages:</para>
      <screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install heat-api heat-api-cfn heat-engine python-heatclient</userinput></screen>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install openstack-heat-api openstack-heat-api-cfn openstack-heat-engine \
  python-heatclient</userinput></screen>
      <screen os="sles;opensuse"><prompt>#</prompt> <userinput>zypper install openstack-heat-api openstack-heat-api-cfn openstack-heat-engine \
  python-heatclient</userinput></screen>
    </step>
    <step>
      <para>Edit the <filename>/etc/heat/heat.conf</filename> file and
        complete the following actions:</para>
      <substeps>
        <step>
          <para>In the <literal>[database]</literal> section, configure
            database access:</para>
          <programlisting language="ini">[database]
...
connection = mysql://heat:<replaceable>HEAT_DBPASS</replaceable>@<replaceable>controller</replaceable>/heat</programlisting>
          <para>Replace <replaceable>HEAT_DBPASS</replaceable> with the
            password you chose for the Orchestration database.</para>
        </step>
        <step>
          <para>In the <literal>[DEFAULT]</literal> section, configure
            <application>RabbitMQ</application> message broker access:</para>
          <programlisting language="ini">[DEFAULT]
...
rpc_backend = rabbit
rabbit_host = <replaceable>controller</replaceable>
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
          <para>Replace <replaceable>RABBIT_PASS</replaceable> with the
            password you chose for the <literal>guest</literal> account in
            <application>RabbitMQ</application>.</para>
        </step>
        <step>
          <para>In the <literal>[keystone_authtoken]</literal> and
            <literal>[ec2authtoken]</literal> sections, configure Identity
            service access:</para>
          <programlisting language="ini">[keystone_authtoken]
...
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0
identity_uri = http://<replaceable>controller</replaceable>:35357
admin_tenant_name = service
admin_user = heat
admin_password = <replaceable>HEAT_PASS</replaceable>

[ec2authtoken]
...
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0</programlisting>
          <para>Replace <replaceable>HEAT_PASS</replaceable> with the
            password you chose for the <literal>heat</literal> user
            in the Identity service.</para>
          <note>
            <para>Comment out any <literal>auth_host</literal>,
              <literal>auth_port</literal>, and
              <literal>auth_protocol</literal> options because the
              <literal>identity_uri</literal> option replaces them.</para>
          </note>
        </step>
        <step>
          <para>In the <literal>[DEFAULT]</literal> section, configure
            the metadata and wait condition URLs:</para>
          <programlisting language="ini">[DEFAULT]
...
heat_metadata_server_url = http://<replaceable>controller</replaceable>:8000
heat_waitcondition_server_url = http://<replaceable>controller</replaceable>:8000/v1/waitcondition</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>
      <para>Populate the Orchestration database:</para>
      <screen><prompt>#</prompt> <userinput>su -s /bin/sh -c "heat-manage db_sync" heat</userinput></screen>
    </step>
  </procedure>
  <procedure os="debian">
    <title>To install and configure the Orchestration components</title>
    <step>
      <para>Run the following commands to install the packages:</para>
      <screen><prompt>#</prompt> <userinput>apt-get install heat-api heat-api-cfn heat-engine python-heat-client</userinput></screen>
    </step>
    <step>
      <para>Respond to prompts for
        <link linkend="debconf-dbconfig-common">database management</link>,
        <link linkend="debconf-keystone_authtoken">Identity service
        credentials</link>,
        <link linkend="debconf-api-endpoints">service endpoint
        registration</link>, and
        <link linkend="debconf-rabbitmq">message broker
        credentials</link>.</para>
    </step>
    <step>
      <para>Edit the <filename>/etc/heat/heat.conf</filename> file and
        complete the following actions:</para>
      <substeps>
        <step>
          <para>In the <literal>[ec2authtoken]</literal> section, configure
            Identity service access:</para>
          <programlisting language="ini">[ec2authtoken]
...
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0</programlisting>
        </step>
      </substeps>
    </step>
  </procedure>
  <procedure>
    <title>To finalize installation</title>
    <step os="ubuntu;debian">
      <para>Restart the Orchestration services:</para>
      <screen><prompt>#</prompt> <userinput>service heat-api restart</userinput>
<prompt>#</prompt> <userinput>service heat-api-cfn restart</userinput>
<prompt>#</prompt> <userinput>service heat-engine restart</userinput></screen>
    </step>
    <step os="rhel;fedora;centos;sles;opensuse">
      <para>Start the Orchestration services and configure them to start when
        the system boots:</para>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>systemctl enable openstack-heat-api.service openstack-heat-api-cfn.service \
  openstack-heat-engine.service</userinput>
<prompt>#</prompt> <userinput>systemctl start openstack-heat-api.service openstack-heat-api-cfn.service \
  openstack-heat-engine.service</userinput></screen>
      <para os="sles">On SLES:</para>
      <screen os="sles"><prompt>#</prompt> <userinput>service openstack-heat-api start</userinput>
<prompt>#</prompt> <userinput>service openstack-heat-api-cfn start</userinput>
<prompt>#</prompt> <userinput>service openstack-heat-engine start</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-heat-api on</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-heat-api-cfn on</userinput>
<prompt>#</prompt> <userinput>chkconfig openstack-heat-engine on</userinput></screen>
      <para os="opensuse">On openSUSE:</para>
      <screen os="opensuse"><prompt>#</prompt> <userinput>systemctl enable openstack-heat-api.service openstack-heat-api-cfn.service \
  openstack-heat-engine.service</userinput>
<prompt>#</prompt> <userinput>systemctl start openstack-heat-api.service openstack-heat-api-cfn.service \
  openstack-heat-engine.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/heat/heat.sqlite</userinput></screen>
    </step>
  </procedure>
</section>