openstack-manuals/doc/install-guide/section_ceilometer-controller.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!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="ceilometer-controller-install">
  <title>Install and configure controller node</title>
  <para>This section describes how to install and configure the Telemetry
    module, code-named ceilometer, on the controller node. The Telemetry
    module uses separate agents to collect measurements from each OpenStack
    service in your environment.</para>
  <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
    <title>To configure prerequisites</title>
    <para>Before you install and configure Telemetry, you must install
      <application>MongoDB</application>, create a MongoDB database,
      service credentials, and API endpoint.</para>
    <step os="opensuse;sles">
      <para>Enable the Open Build Service repositories for MongoDB based on
        your openSUSE or SLES version:</para>
      <para>On openSUSE:</para>
      <screen><prompt>#</prompt> <userinput>zypper addrepo -f obs://server:database/openSUSE_13.2 Database</userinput></screen>
      <para>On SLES:</para>
      <screen><prompt>#</prompt> <userinput>zypper addrepo -f obs://server:database/SLE_12 Database</userinput></screen>
      <note>
        <para>The packages are signed by GPG key
          <literal>562111AC05905EA8</literal>. You should
          verify the fingerprint of the imported GPG key before using
          it.</para>
        <programlisting>Key Name: server:database OBS Project &lt;server:database@build.opensuse.org&gt;
Key Fingerprint: 116EB86331583E47E63CDF4D562111AC05905EA8
Key Created: Thu Oct 11 20:08:39 2012
Key Expires: Sat Dec 20 20:08:39 2014</programlisting>
      </note>
    </step>
    <step>
      <para>Install the MongoDB package:</para>
      <screen os="rhel;centos;fedora"><prompt>#</prompt> <userinput>yum install mongodb-server mongodb</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install mongodb</userinput></screen>
      <screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install mongodb-server mongodb-clients python-pymongo</userinput></screen>
    </step>
    <step>
      <para>Edit the <filename>/etc/mongodb.conf</filename> file and
        complete the following actions:</para>
      <substeps>
        <step>
          <para>Configure the <literal>bind_ip</literal> key to use the
            management interface IP address of the controller node.</para>
          <programlisting language="ini">bind_ip = 10.0.0.11</programlisting>
        </step>
        <step>
          <para>By default, MongoDB creates several 1&nbsp;GB journal files
            in the <filename>/var/lib/mongodb/journal</filename>
            directory. If you want to reduce the size of each journal file
            to 128&nbsp;MB and limit total journal space consumption to
            512&nbsp;MB, assert the <literal>smallfiles</literal> key:</para>
          <programlisting language="ini">smallfiles = true</programlisting>
          <para os="ubuntu">If you change the journaling configuration,
            stop the MongoDB service, remove the initial journal files, and
            start the service:</para>
          <screen os="ubuntu"><prompt>#</prompt> <userinput>service mongodb stop</userinput>
<prompt>#</prompt> <userinput>rm /var/lib/mongodb/journal/prealloc.*</userinput>
<prompt>#</prompt> <userinput>service mongodb start</userinput></screen>
          <para>You can also disable journaling. For more information, see
            the <link xlink:href="http://docs.mongodb.org/manual/"
            >MongoDB manual</link>.</para>
        </step>
        <step os="ubuntu">
          <para>Restart the MongoDB service:</para>
          <screen><prompt>#</prompt> <userinput>service mongodb restart</userinput></screen>
        </step>
        <step os="centos;fedora;opensuse;rhel;sles">
          <para>Start the MongoDB services and configure them to start when
            the system boots:</para>
          <screen os="opensuse;sles"><prompt>#</prompt> <userinput>systemctl enable mongodb.service</userinput>
<prompt>#</prompt> <userinput>systemctl start mongodb.service</userinput></screen>
      <!-- NB: The use of mongod, and not mongodb, in the below screen is
      intentional. -->
          <screen os="centos;fedora;rhel"><prompt>#</prompt> <userinput>systemctl enable mongod.service</userinput>
<prompt>#</prompt> <userinput>systemctl start mongod.service</userinput></screen>
        </step>
      </substeps>
    </step>
    <step>
      <para>Create the <literal>ceilometer</literal> database:</para>
      <screen><prompt>#</prompt> <userinput>mongo --host <replaceable>controller</replaceable> --eval '
  db = db.getSiblingDB("ceilometer");
  db.addUser({user: "ceilometer",
  pwd: "<replaceable>CEILOMETER_DBPASS</replaceable>",
  roles: [ "readWrite", "dbAdmin" ]})'</userinput>

<computeroutput>MongoDB shell version: X.Y.Z
connecting to: controller:27017/test
{
 "user" : "ceilometer",
 "pwd" : "72f25aeee7ad4be52437d7cd3fc60f6f",
 "roles" : [
  "readWrite",
  "dbAdmin"
 ],
 "_id" : ObjectId("5489c22270d7fad1ba631dc3")
}</computeroutput></screen>
      <para>Replace <replaceable>CEILOMETER_DBPASS</replaceable> with a
        suitable password.</para>
    </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 service credentials, complete these steps:</para>
      <substeps>
        <step>
          <para>Create the <literal>ceilometer</literal> user:</para>
          <screen><prompt>$</prompt> <userinput>keystone user-create --name ceilometer --pass <replaceable>CEILOMETER_PASS</replaceable></userinput></screen>
          <para>Replace <replaceable>CEILOMETER_PASS</replaceable> with a
            suitable password.</para>
        </step>
        <step>
          <para>Add the <literal>admin</literal> role to the
            <literal>ceilometer</literal> user.</para>
         <screen><prompt>$</prompt> <userinput>keystone user-role-add --user ceilometer --tenant service --role admin</userinput></screen>
        </step>
        <step>
          <para>Create the <literal>ceilometer</literal> service
            entity:</para>
          <screen><prompt>$</prompt> <userinput>keystone service-create --name ceilometer --type metering \
  --description "Telemetry"</userinput></screen>
        </step>
      </substeps>
    </step>
    <step>
      <para>Create the Telemetry module API endpoint:</para>
      <screen><prompt>$</prompt> <userinput>keystone endpoint-create \
  --service-id $(keystone service-list | awk '/ metering / {print $2}') \
  --publicurl http://<replaceable>controller</replaceable>:8777 \
  --internalurl http://<replaceable>controller</replaceable>:8777 \
  --adminurl http://<replaceable>controller</replaceable>:8777</userinput> \
  --region regionOne</screen>
    </step>
  </procedure>
  <procedure os="debian">
    <title>To configure prerequisites</title>
    <para>Before you install and configure Telemetry, you must install
      <application>MongoDB</application>.</para>
    <step>
      <para>Install the MongoDB package:</para>
      <screen><prompt>#</prompt> <userinput>apt-get install mongodb-server</userinput></screen>
    </step>
    <step>
      <para>Edit the <filename>/etc/mongodb.conf</filename> file and
        complete the following actions:</para>
      <substeps>
        <step>
          <para>Configure the <literal>bind_ip</literal> key to use the
            management interface IP address of the controller node.</para>
          <programlisting language="ini">bind_ip = 10.0.0.11</programlisting>
        </step>
        <step>
          <para>By default, MongoDB creates several 1&nbsp;GB journal files
            in the <filename>/var/lib/mongodb/journal</filename>
            directory. If you want to reduce the size of each journal file
            to 128&nbsp;MB and limit total journal space consumption to
            512&nbsp;MB, assert the <literal>smallfiles</literal> key:</para>
          <programlisting language="ini">smallfiles = true</programlisting>
          <para>If you change the journaling configuration, stop the MongoDB
            service, remove the initial journal files, and start the
            service:</para>
          <screen><prompt>#</prompt> <userinput>service mongodb stop</userinput>
<prompt>#</prompt> <userinput>rm /var/lib/mongodb/journal/prealloc.*</userinput>
<prompt>#</prompt> <userinput>service mongodb start</userinput></screen>
          <para>You can also disable journaling. For more information, see
            the <link xlink:href="http://docs.mongodb.org/manual/"
            >MongoDB manual</link>.</para>
        </step>
        <step>
          <para>Restart the MongoDB service:</para>
          <screen><prompt>#</prompt> <userinput>service mongodb restart</userinput></screen>
        </step>
      </substeps>
    </step>
  </procedure>
  <procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
    <title>To install and configure the Telemetry module components</title>
    <step>
      <para>Install the packages:</para>
      <screen os="ubuntu"><prompt>#</prompt> <userinput>apt-get install ceilometer-api ceilometer-collector ceilometer-agent-central \
  ceilometer-agent-notification ceilometer-alarm-evaluator ceilometer-alarm-notifier \
  python-ceilometerclient</userinput></screen>
      <screen os="centos;fedora;rhel"><prompt>#</prompt> <userinput>yum install openstack-ceilometer-api openstack-ceilometer-collector \
  openstack-ceilometer-notification openstack-ceilometer-central openstack-ceilometer-alarm \
  python-ceilometerclient</userinput></screen>
      <screen os="opensuse;sles"><prompt>#</prompt> <userinput>zypper install openstack-ceilometer-api openstack-ceilometer-collector \
  openstack-ceilometer-agent-notification openstack-ceilometer-agent-central python-ceilometerclient \
  openstack-ceilometer-alarm-evaluator openstack-ceilometer-alarm-notifier</userinput></screen>
    </step>
    <step>
      <para>Generate a random value to use as the telemetry secret:</para>
      <screen><prompt>$</prompt> <userinput>openssl rand -hex 10</userinput></screen>
    </step>
    <step>
      <para>Edit the <filename>/etc/ceilometer/ceilometer.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 = mongodb://ceilometer:<replaceable>CEILOMETER_DBPASS</replaceable>@<replaceable>controller</replaceable>:27017/ceilometer</programlisting>
          <para>Replace <replaceable>CEILOMETER_DBPASS</replaceable> with
            the password you chose for the Telemetry module database. You
            must escape special characters such as ':', '/', '+', and '@'
            in the connection string in accordance with RFC2396.</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>[DEFAULT]</literal> and
            <literal>[keystone_authtoken]</literal> sections, configure
            Identity service access:</para>
          <programlisting language="ini">[DEFAULT]
...
auth_strategy = keystone

[keystone_authtoken]
...
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0
identity_uri = http://<replaceable>controller</replaceable>:35357
admin_tenant_name = service
admin_user = ceilometer
admin_password = <replaceable>CEILOMETER_PASS</replaceable></programlisting>
          <para>Replace <replaceable>CEILOMETER_PASS</replaceable> with the
            password you chose for the <literal>celiometer</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>[service_credentials]</literal>
            section, configure service credentials:</para>
          <programlisting language="ini">[service_credentials]
...
os_auth_url = http://<replaceable>controller</replaceable>:5000/v2.0
os_username = ceilometer
os_tenant_name = service
os_password = <replaceable>CEILOMETER_PASS</replaceable></programlisting>
          <para>Replace <replaceable>CEILOMETER_PASS</replaceable> with
            the password you chose for the <literal>ceilometer</literal>
            user in the Identity service.</para>
        </step>
        <step>
          <para>In the <literal>[publisher]</literal> section, configure
            the telemetry secret:</para>
          <programlisting language="ini">[publisher]
...
telemetry_secret = <replaceable>TELEMETRY_SECRET</replaceable></programlisting>
          <para>Replace <replaceable>TELEMETRY_SECRET</replaceable> with the
            telemetry secret that you generated in a previous step.</para>
        </step>
        <step os="opensuse;sles">
          <para>In the <literal>[collector]</literal> section, configure the
            dispatcher:</para>
<!-- should this be 'dispatcher = database' ? -->
          <programlisting language="ini">[collector]
...
dispatcher = database</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>
  </procedure>

  <procedure os="debian">
  <title>To install and configure the Telemetry module components</title>
    <step>
      <para>Install the packages:</para>
      <screen><prompt>#</prompt> <userinput>apt-get install ceilometer-api ceilometer-collector ceilometer-agent-central \
  ceilometer-agent-notification ceilometer-alarm-evaluator ceilometer-alarm-notifier \
  python-ceilometerclient</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>Generate a random value to use as the telemetry secret:</para>
      <screen><prompt>$</prompt> <userinput>openssl rand -hex 10</userinput></screen>
    </step>
    <step>
      <para>Edit the <filename>/etc/ceilometer/ceilometer.conf</filename> file
        and complete the following actions:</para>
      <substeps>
        <step>
          <para>In the <literal>[publisher]</literal> section, configure
            the telemetry secret:</para>
          <programlisting language="ini">[publisher]
...
telemetry_secret = <replaceable>TELEMETRY_SECRET</replaceable></programlisting>
          <para>Replace <replaceable>TELEMETRY_SECRET</replaceable> with the
            telemetry secret that you generated in a previous step.</para>
        </step>
        <step>
          <para>In the <literal>[service_credentials]</literal>
            section, configure service credentials:</para>
          <programlisting language="ini">[service_credentials]
...
os_auth_url = http://<replaceable>controller</replaceable>:5000/v2.0
os_username = ceilometer
os_tenant_name = service
os_password = <replaceable>CEILOMETER_PASS</replaceable></programlisting>
          <para>Replace <replaceable>CEILOMETER_PASS</replaceable> with
            the password you chose for the <literal>ceilometer</literal>
            user in the Identity service.</para>
        </step>
      </substeps>
    </step>
  </procedure>
  <procedure>
    <title>To finalize installation</title>
    <step os="ubuntu;debian">
      <para>Restart the Telemetry services:</para>
      <screen><prompt>#</prompt> <userinput>service ceilometer-agent-central restart</userinput>
<prompt>#</prompt> <userinput>service ceilometer-agent-notification restart</userinput>
<prompt>#</prompt> <userinput>service ceilometer-api restart</userinput>
<prompt>#</prompt> <userinput>service ceilometer-collector restart</userinput>
<prompt>#</prompt> <userinput>service ceilometer-alarm-evaluator restart</userinput>
<prompt>#</prompt> <userinput>service ceilometer-alarm-notifier restart</userinput></screen>
    </step>
    <step os="rhel;centos;fedora;sles;opensuse">
      <para>Start the Telemetry services and configure them to start when the
        system boots:</para>
      <screen><prompt>#</prompt> <userinput>systemctl enable openstack-ceilometer-api.service openstack-ceilometer-notification.service \
  openstack-ceilometer-central.service openstack-ceilometer-collector.service \
  openstack-ceilometer-alarm-evaluator.service openstack-ceilometer-alarm-notifier.service</userinput>
<prompt>#</prompt> <userinput>systemctl start openstack-ceilometer-api.service openstack-ceilometer-notification.service \
  openstack-ceilometer-central.service openstack-ceilometer-collector.service \
  openstack-ceilometer-alarm-evaluator.service openstack-ceilometer-alarm-notifier.service</userinput></screen>
    </step>
  </procedure>
</section>