openstack/openstack-manuals
Code Issues Proposed changes
bcce6ce360
openstack-manuals/doc/install-guide/section_ceilometer-controller.xml
Sean M. Collins b2ddfaf3d5 Replace "regionOne" with "RegionOne" 
This fixes an inconsistency between the install guide
and other OpenStack components, which names the first region in Camel Case.

Change-Id: I80a1827e9008777e73dce1dd3a95ece5dd614744
Related-Change: I8f47be1b4b43defb86b4da2a34c5f40494361045
2015-04-27 10:37:00 -04:00

426 lines
20 KiB
XML
Raw Blame History

<?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 os="opensuse;sles;ubuntu">/etc/mongodb.conf</filename>
<filename os="rhel;centos;fedora">/etc/mongod.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 os="centos;fedora;rhel"><prompt>#</prompt> <userinput>mongo --host <replaceable>controller</replaceable> --eval '
db = db.getSiblingDB("ceilometer");
db.createUser({user: "ceilometer",
pwd: "<replaceable>CEILOMETER_DBPASS</replaceable>",
roles: [ "readWrite", "dbAdmin" ]})'</userinput>
<computeroutput>MongoDB shell version: 2.6.x
connecting to: controller:27017/test
Successfully added user: { "user" : "ceilometer", "roles" : [ "readWrite", "dbAdmin" ] }</computeroutput></screen>
<screen os="ubuntu;opensuse;sles"><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: 2.4.x
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>openstack user create --password-prompt ceilometer</userinput>
<computeroutput>User Password:
Repeat User Password:
+----------+----------------------------------+
| Field | Value |
+----------+----------------------------------+
| email | None |
| enabled | True |
| id | b7657c9ea07a4556aef5d34cf70713a3 |
| name | ceilometer |
| username | ceilometer |
+----------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>Add the <literal>admin</literal> role to the
<literal>ceilometer</literal> user.</para>
<screen><prompt>$</prompt> <userinput>openstack role add --project service --user ceilometer admin</userinput>
<computeroutput>+-------+----------------------------------+
| Field | Value |
+-------+----------------------------------+
| id | cd2cb9a39e874ea69e5d4b896eb16128 |
| name | admin |
+-------+----------------------------------+</computeroutput></screen>
</step>
<step>
<para>Create the <literal>ceilometer</literal> service
entity:</para>
<screen><prompt>$</prompt> <userinput>openstack service create --type metering \
--description "Telemetry" ceilometer</userinput>
<computeroutput>+-------------+----------------------------------+
| Field | Value |
+-------------+----------------------------------+
| description | Telemetry |
| enabled | True |
| id | 3405453b14da441ebb258edfeba96d83 |
| name | ceilometer |
| type | metering |
+-------------+----------------------------------+</computeroutput></screen>
</step>
</substeps>
</step>
<step>
<para>Create the Telemetry module API endpoint:</para>
<screen><prompt>$</prompt> <userinput>openstack endpoint create \
--publicurl http://<replaceable>controller</replaceable>:8777 \
--internalurl http://<replaceable>controller</replaceable>:8777 \
--adminurl http://<replaceable>controller</replaceable>:8777 \
--region RegionOne \
metering</userinput>
<computeroutput>+--------------+----------------------------------+
| Field | Value |
+--------------+----------------------------------+
| adminurl | http://controller:8777 |
| id | d3716d85b10d4e60a67a52c6af0068cd |
| internalurl | http://controller:8777 |
| publicurl | http://controller:8777 |
| region | RegionOne |
| service_id | 3405453b14da441ebb258edfeba96d83 |
| service_name | ceilometer |
| service_type | metering |
+--------------+----------------------------------+</computeroutput></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> and
<literal>[oslo_messaging_rabbit]</literal> sections, configure
<application>RabbitMQ</application> message queue access:</para>
<programlisting language="ini">[DEFAULT]
...
rpc_backend = rabbit
[oslo_messaging_rabbit]
...
rabbit_host = <replaceable>controller</replaceable>
rabbit_userid = openstack
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
<para>Replace <replaceable>RABBIT_PASS</replaceable> with the
password you chose for the <literal>openstack</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>
os_endpoint_type = internalURL
os_region_name = RegionOne</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>
View Git Blame Copy Permalink