diff options
30 files changed, 1751 insertions, 1 deletions
diff --git a/install-guide/source/conf.py b/install-guide/source/conf.py new file mode 100644 index 00000000..91391951 --- /dev/null +++ b/install-guide/source/conf.py @@ -0,0 +1,304 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import os +# import sys + + +import openstackdocstheme + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +# TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder' +# extensions = + +# Add any paths that contain templates here, relative to this directory. +# templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Installation Guide for Telemetry Data Collection Service' +bug_tag = u'install-guide' +copyright = u'2016, OpenStack contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1' + +# A few variables have to be set for the log-a-bug feature. +# giturl: The location of conf.py on Git. Must be set manually. +# gitsha: The SHA checksum of the bug description. Automatically extracted from git log. +# bug_tag: Tag for categorizing the bug. Must be set manually. +# These variables are passed to the logabug code via html_context. +giturl = u'http://git.openstack.org/cgit/openstack/ceilometer/tree/install-guide/source' +git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '" +gitsha = os.popen(git_cmd).read().strip('\n') +html_context = {"gitsha": gitsha, "bug_tag": bug_tag, + "giturl": giturl, + "bug_project": "ceilometer"} + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ["install-base-config-common.rst", + "install-base-prereq-common.rst", + "configure_services/nova/install-nova-common.rst", + "configure_services/swift/install-swift-config-common.rst", + "configure_services/swift/install-swift-prereq-common.rst"] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'openstackdocs' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = [openstackdocstheme.get_html_theme_path()] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +# html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = [] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +# So that we can enable "log-a-bug" links from each output HTML page, this +# variable must be set to a format that includes year, month, day, hours and +# minutes. +html_last_updated_fmt = '%Y-%m-%d %H:%M' + + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_domain_indices = True + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'install-guide' + +# If true, publish source files +html_copy_source = False + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # 'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'InstallGuide.tex', u'Install Guide', + u'OpenStack contributors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# If true, show page references after internal links. +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'installguide', u'Install Guide', + [u'OpenStack contributors'], 1) +] + +# If true, show URL addresses after external links. +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'InstallGuide', u'Install Guide', + u'OpenStack contributors', 'InstallGuide', + 'This guide shows OpenStack end users how to install ' + 'an OpenStack cloud.', 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# texinfo_appendices = [] + +# If false, no module index is generated. +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# texinfo_no_detailmenu = False + +# -- Options for Internationalization output ------------------------------ +locale_dirs = ['locale/'] + +# -- Options for PDF output -------------------------------------------------- + +pdf_documents = [ + ('index', u'InstallGuide', u'Install Guide', + u'OpenStack contributors') +] diff --git a/install-guide/source/configure_services/cinder/install-cinder-obs.rst b/install-guide/source/configure_services/cinder/install-cinder-obs.rst new file mode 100644 index 00000000..3e7557f3 --- /dev/null +++ b/install-guide/source/configure_services/cinder/install-cinder-obs.rst @@ -0,0 +1,44 @@ +Enable Block Storage meters for openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses notifications to collect Block Storage service meters. +Perform these steps on the controller and Block Storage nodes. + +.. note:: + + Your environment must include the Block Storage service. + +Configure Cinder to use Telemetry +--------------------------------- + +Edit the ``/etc/cinder/cinder.conf`` file and complete the +following actions: + +* In the ``[oslo_messaging_notifications]`` section, configure notifications: + + .. code-block:: ini + + [oslo_messaging_notifications] + ... + driver = messagingv2 + +Finalize installation +--------------------- + +#. Restart the Block Storage services on the controller node: + + .. code-block:: console + + # systemctl restart openstack-cinder-api.service openstack-cinder-scheduler.service + +#. Restart the Block Storage services on the storage nodes: + + .. code-block:: console + + # systemctl restart openstack-cinder-volume.service + +#. Use the ``cinder-volume-usage-audit`` command on Block Storage nodes + to retrieve meters on demand. For more information, see the + `OpenStack Administrator Guide <http://docs.openstack.org/admin-guide/ + telemetry-data-collection.html#block-storage-audit-script-setup-to-get- + notifications>`__. diff --git a/install-guide/source/configure_services/cinder/install-cinder-rdo.rst b/install-guide/source/configure_services/cinder/install-cinder-rdo.rst new file mode 100644 index 00000000..75877e0b --- /dev/null +++ b/install-guide/source/configure_services/cinder/install-cinder-rdo.rst @@ -0,0 +1,44 @@ +Enable Block Storage meters for Red Hat Enterprise Linux and CentOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses notifications to collect Block Storage service meters. +Perform these steps on the controller and Block Storage nodes. + +.. note:: + + Your environment must include the Block Storage service. + +Configure Cinder to use Telemetry +--------------------------------- + +Edit the ``/etc/cinder/cinder.conf`` file and complete the +following actions: + +* In the ``[oslo_messaging_notifications]`` section, configure notifications: + + .. code-block:: ini + + [oslo_messaging_notifications] + ... + driver = messagingv2 + +Finalize installation +--------------------- + +#. Restart the Block Storage services on the controller node: + + .. code-block:: console + + # systemctl restart openstack-cinder-api.service openstack-cinder-scheduler.service + +#. Restart the Block Storage services on the storage nodes: + + .. code-block:: console + + # systemctl restart openstack-cinder-volume.service + +#. Use the ``cinder-volume-usage-audit`` command on Block Storage nodes + to retrieve meters on demand. For more information, see the + `OpenStack Administrator Guide <http://docs.openstack.org/admin-guide/ + telemetry-data-collection.html#block-storage-audit-script-setup-to-get- + notifications>`__. diff --git a/install-guide/source/configure_services/cinder/install-cinder-ubuntu.rst b/install-guide/source/configure_services/cinder/install-cinder-ubuntu.rst new file mode 100644 index 00000000..8049542d --- /dev/null +++ b/install-guide/source/configure_services/cinder/install-cinder-ubuntu.rst @@ -0,0 +1,45 @@ +Enable Block Storage meters for Ubuntu +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses notifications to collect Block Storage service meters. +Perform these steps on the controller and Block Storage nodes. + +.. note:: + + Your environment must include the Block Storage service. + +Configure Cinder to use Telemetry +--------------------------------- + +Edit the ``/etc/cinder/cinder.conf`` file and complete the +following actions: + +* In the ``[oslo_messaging_notifications]`` section, configure notifications: + + .. code-block:: ini + + [oslo_messaging_notifications] + ... + driver = messagingv2 + +Finalize installation +--------------------- + +#. Restart the Block Storage services on the controller node: + + .. code-block:: console + + # service cinder-api restart + # service cinder-scheduler restart + +#. Restart the Block Storage services on the storage nodes: + + .. code-block:: console + + # service cinder-volume restart + +#. Use the ``cinder-volume-usage-audit`` command on Block Storage nodes + to retrieve meters on demand. For more information, see the + `OpenStack Administrator Guide <http://docs.openstack.org/admin-guide/ + telemetry-data-collection.html#block-storage-audit-script-setup-to-get- + notifications>`__. diff --git a/install-guide/source/configure_services/glance/install-glance-obs.rst b/install-guide/source/configure_services/glance/install-glance-obs.rst new file mode 100644 index 00000000..10abd2f9 --- /dev/null +++ b/install-guide/source/configure_services/glance/install-glance-obs.rst @@ -0,0 +1,44 @@ +Enable Image service meters for openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses notifications to collect Image service meters. Perform +these steps on the controller node. + +Configure the Image service to use Telemetry +-------------------------------------------- + +* Edit the ``/etc/glance/glance-api.conf`` and + ``/etc/glance/glance-registry.conf`` files and + complete the following actions: + + * In the ``[DEFAULT]``, ``[oslo_messaging_notifications]``, and + ``[oslo_messaging_rabbit]`` sections, configure notifications and RabbitMQ + message broker access: + + .. code-block:: ini + + [DEFAULT] + ... + rpc_backend = rabbit + + [oslo_messaging_notifications] + ... + driver = messagingv2 + + [oslo_messaging_rabbit] + ... + rabbit_host = controller + rabbit_userid = openstack + rabbit_password = RABBIT_PASS + + Replace ``RABBIT_PASS`` with the password you chose for + the ``openstack`` account in ``RabbitMQ``. + +Finalize installation +--------------------- + +* Restart the Image service: + + .. code-block:: console + + # systemctl restart openstack-glance-api.service openstack-glance-registry.service diff --git a/install-guide/source/configure_services/glance/install-glance-rdo.rst b/install-guide/source/configure_services/glance/install-glance-rdo.rst new file mode 100644 index 00000000..73709f52 --- /dev/null +++ b/install-guide/source/configure_services/glance/install-glance-rdo.rst @@ -0,0 +1,44 @@ +Enable Image service meters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses notifications to collect Image service meters. Perform +these steps on the controller node. + +Configure the Image service to use Telemetry +-------------------------------------------- + +* Edit the ``/etc/glance/glance-api.conf`` and + ``/etc/glance/glance-registry.conf`` files and + complete the following actions: + + * In the ``[DEFAULT]``, ``[oslo_messaging_notifications]``, and + ``[oslo_messaging_rabbit]`` sections, configure notifications and RabbitMQ + message broker access: + + .. code-block:: ini + + [DEFAULT] + ... + rpc_backend = rabbit + + [oslo_messaging_notifications] + ... + driver = messagingv2 + + [oslo_messaging_rabbit] + ... + rabbit_host = controller + rabbit_userid = openstack + rabbit_password = RABBIT_PASS + + Replace ``RABBIT_PASS`` with the password you chose for + the ``openstack`` account in ``RabbitMQ``. + +Finalize installation +--------------------- + +* Restart the Image service: + + .. code-block:: console + + # systemctl restart openstack-glance-api.service openstack-glance-registry.service diff --git a/install-guide/source/configure_services/glance/install-glance-ubuntu.rst b/install-guide/source/configure_services/glance/install-glance-ubuntu.rst new file mode 100644 index 00000000..8d2397e2 --- /dev/null +++ b/install-guide/source/configure_services/glance/install-glance-ubuntu.rst @@ -0,0 +1,45 @@ +Enable Image service meters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses notifications to collect Image service meters. Perform +these steps on the controller node. + +Configure the Image service to use Telemetry +-------------------------------------------- + +* Edit the ``/etc/glance/glance-api.conf`` and + ``/etc/glance/glance-registry.conf`` files and + complete the following actions: + + * In the ``[DEFAULT]``, ``[oslo_messaging_notifications]``, and + ``[oslo_messaging_rabbit]`` sections, configure notifications and RabbitMQ + message broker access: + + .. code-block:: ini + + [DEFAULT] + ... + rpc_backend = rabbit + + [oslo_messaging_notifications] + ... + driver = messagingv2 + + [oslo_messaging_rabbit] + ... + rabbit_host = controller + rabbit_userid = openstack + rabbit_password = RABBIT_PASS + + Replace ``RABBIT_PASS`` with the password you chose for + the ``openstack`` account in ``RabbitMQ``. + +Finalize installation +--------------------- + +* Restart the Image service: + + .. code-block:: console + + # service glance-registry restart + # service glance-api restart diff --git a/install-guide/source/configure_services/nova/install-nova-common.rst b/install-guide/source/configure_services/nova/install-nova-common.rst new file mode 100644 index 00000000..716faf5f --- /dev/null +++ b/install-guide/source/configure_services/nova/install-nova-common.rst @@ -0,0 +1,79 @@ +2. Edit the ``/etc/ceilometer/ceilometer.conf`` file and + complete the following actions: + + * In the ``[DEFAULT]`` and ``[oslo_messaging_rabbit]`` sections, + configure ``RabbitMQ`` message queue access: + + .. code-block:: ini + + [DEFAULT] + ... + rpc_backend = rabbit + + [oslo_messaging_rabbit] + ... + rabbit_host = controller + rabbit_userid = openstack + rabbit_password = RABBIT_PASS + + Replace ``RABBIT_PASS`` with the password you chose for the + ``openstack`` account in ``RabbitMQ``. + + * In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections, + configure Identity service access: + + .. code-block:: ini + + [DEFAULT] + ... + auth_strategy = keystone + + [keystone_authtoken] + ... + auth_uri = http://controller:5000 + auth_url = http://controller:35357 + memcached_servers = controller:11211 + auth_type = password + project_domain_name = default + user_domain_name = default + project_name = service + username = ceilometer + password = CEILOMETER_PASS + + Replace ``CEILOMETER_PASS`` with the password you chose for the + Telemetry service database. + + * In the ``[service_credentials]`` section, configure service + credentials: + + .. code-block:: ini + + [service_credentials] + ... + os_auth_url = http://controller:5000/v2.0 + os_username = ceilometer + os_tenant_name = service + os_password = CEILOMETER_PASS + interface = internalURL + region_name = RegionOne + + Replace ``CEILOMETER_PASS`` with the password you chose for + the ``ceilometer`` user in the Identity service. + +Configure Compute to use Telemetry +---------------------------------- + +* Edit the ``/etc/nova/nova.conf`` file and configure + notifications in the ``[DEFAULT]`` section: + + .. code-block:: ini + + [DEFAULT] + ... + instance_usage_audit = True + instance_usage_audit_period = hour + notify_on_state_change = vm_and_task_state + + [oslo_messaging_notifications] + ... + driver = messagingv2 diff --git a/install-guide/source/configure_services/nova/install-nova-obs.rst b/install-guide/source/configure_services/nova/install-nova-obs.rst new file mode 100644 index 00000000..82b6edf8 --- /dev/null +++ b/install-guide/source/configure_services/nova/install-nova-obs.rst @@ -0,0 +1,32 @@ +Enable Compute service meters for openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses a combination of notifications and an agent to collect +Compute meters. Perform these steps on each compute node. + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # zypper install openstack-ceilometer-agent-compute + +.. include:: install-nova-common.rst + +Finalize installation +--------------------- + +#. Start the agent and configure it to start when the system boots: + + .. code-block:: console + + # systemctl enable openstack-ceilometer-agent-compute.service + # systemctl start openstack-ceilometer-agent-compute.service + +#. Restart the Compute service: + + .. code-block:: console + + # systemctl restart openstack-nova-compute.service diff --git a/install-guide/source/configure_services/nova/install-nova-rdo.rst b/install-guide/source/configure_services/nova/install-nova-rdo.rst new file mode 100644 index 00000000..49884a00 --- /dev/null +++ b/install-guide/source/configure_services/nova/install-nova-rdo.rst @@ -0,0 +1,32 @@ +Enable Compute service meters for Red Hat Enterprise Linux and CentOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses a combination of notifications and an agent to collect +Compute meters. Perform these steps on each compute node. + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # yum install openstack-ceilometer-compute python-ceilometerclient python-pecan + +.. include:: install-nova-common.rst + +Finalize installation +--------------------- + +#. Start the agent and configure it to start when the system boots: + + .. code-block:: console + + # systemctl enable openstack-ceilometer-compute.service + # systemctl start openstack-ceilometer-compute.service + +#. Restart the Compute service: + + .. code-block:: console + + # systemctl restart openstack-nova-compute.service diff --git a/install-guide/source/configure_services/nova/install-nova-ubuntu.rst b/install-guide/source/configure_services/nova/install-nova-ubuntu.rst new file mode 100644 index 00000000..acfbbe59 --- /dev/null +++ b/install-guide/source/configure_services/nova/install-nova-ubuntu.rst @@ -0,0 +1,31 @@ +Enable Compute service meters for Ubuntu +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses a combination of notifications and an agent to collect +Compute meters. Perform these steps on each compute node. + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get install ceilometer-agent-compute + +.. include:: install-nova-common.rst + +Finalize installation +--------------------- + +#. Restart the agent: + + .. code-block:: console + + # service ceilometer-agent-compute restart + +#. Restart the Compute service: + + .. code-block:: console + + # service nova-compute restart diff --git a/install-guide/source/configure_services/swift/install-swift-config-common.rst b/install-guide/source/configure_services/swift/install-swift-config-common.rst new file mode 100644 index 00000000..5af6aa23 --- /dev/null +++ b/install-guide/source/configure_services/swift/install-swift-config-common.rst @@ -0,0 +1,40 @@ +Configure Object Storage to use Telemetry +----------------------------------------- + +Perform these steps on the controller and any other nodes that +run the Object Storage proxy service. + +* Edit the ``/etc/swift/proxy-server.conf`` file + and complete the following actions: + + * In the ``[filter:keystoneauth]`` section, add the + ``ResellerAdmin`` role: + + .. code-block:: ini + + [filter:keystoneauth] + ... + operator_roles = admin, user, ResellerAdmin + + * In the ``[pipeline:main]`` section, add ``ceilometer``: + + .. code-block:: ini + + [pipeline:main] + pipeline = ceilometer catch_errors gatekeeper healthcheck proxy-logging cache container_sync bulk ratelimit authtoken keystoneauth container-quotas account-quotas slo dlo versioned_writes proxy-logging proxy-server + + * In the ``[filter:ceilometer]`` section, configure notifications: + + .. code-block:: ini + + [filter:ceilometer] + paste.filter_factory = ceilometermiddleware.swift:filter_factory + ... + control_exchange = swift + url = rabbit://openstack:RABBIT_PASS@controller:5672/ + driver = messagingv2 + topic = notifications + log_level = WARN + + Replace ``RABBIT_PASS`` with the password you chose for the + ``openstack`` account in ``RabbitMQ``. diff --git a/install-guide/source/configure_services/swift/install-swift-obs.rst b/install-guide/source/configure_services/swift/install-swift-obs.rst new file mode 100644 index 00000000..e0680111 --- /dev/null +++ b/install-guide/source/configure_services/swift/install-swift-obs.rst @@ -0,0 +1,31 @@ +Enable Object Storage meters for openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses a combination of polling and notifications to collect +Object Storage meters. + +.. note:: + + Your environment must include the Object Storage service. + +.. include:: install-swift-prereq-common.rst + +Install components +------------------ + +* Install the packages: + + .. code-block:: console + + # zypper install python-ceilometermiddleware + +.. include:: install-swift-config-common.rst + +Finalize installation +--------------------- + +* Restart the Object Storage proxy service: + + .. code-block:: console + + # systemctl restart openstack-swift-proxy.service diff --git a/install-guide/source/configure_services/swift/install-swift-prereq-common.rst b/install-guide/source/configure_services/swift/install-swift-prereq-common.rst new file mode 100644 index 00000000..35600795 --- /dev/null +++ b/install-guide/source/configure_services/swift/install-swift-prereq-common.rst @@ -0,0 +1,36 @@ +Prerequisites +------------- + +The Telemetry service requires access to the Object Storage service +using the ``ResellerAdmin`` role. Perform these steps on the controller +node. + +#. Source the ``admin`` credentials to gain access to admin-only + CLI commands. + + .. code-block:: console + + $ . admin-openrc + +#. Create the ``ResellerAdmin`` role: + + .. code-block:: console + + $ openstack role create ResellerAdmin + +-----------+----------------------------------+ + | Field | Value | + +-----------+----------------------------------+ + | domain_id | None | + | id | 462fa46c13fd4798a95a3bfbe27b5e54 | + | name | ResellerAdmin | + +-----------+----------------------------------+ + +#. Add the ``ResellerAdmin`` role to the ``ceilometer`` user: + + .. code-block:: console + + $ openstack role add --project service --user ceilometer ResellerAdmin + + .. note:: + + This command provides no output. diff --git a/install-guide/source/configure_services/swift/install-swift-rdo.rst b/install-guide/source/configure_services/swift/install-swift-rdo.rst new file mode 100644 index 00000000..14a34f65 --- /dev/null +++ b/install-guide/source/configure_services/swift/install-swift-rdo.rst @@ -0,0 +1,31 @@ +Enable Object Storage meters for Red Hat Enterprise Linux and CentOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses a combination of polling and notifications to collect +Object Storage meters. + +.. note:: + + Your environment must include the Object Storage service. + +.. include:: install-swift-prereq-common.rst + +Install components +------------------ + +* Install the packages: + + .. code-block:: console + + # yum install python-ceilometermiddleware + +.. include:: install-swift-config-common.rst + +Finalize installation +--------------------- + +* Restart the Object Storage proxy service: + + .. code-block:: console + + # systemctl restart openstack-swift-proxy.service diff --git a/install-guide/source/configure_services/swift/install-swift-ubuntu.rst b/install-guide/source/configure_services/swift/install-swift-ubuntu.rst new file mode 100644 index 00000000..99421c13 --- /dev/null +++ b/install-guide/source/configure_services/swift/install-swift-ubuntu.rst @@ -0,0 +1,31 @@ +Enable Object Storage meters for Ubuntu +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Telemetry uses a combination of polling and notifications to collect +Object Storage meters. + +.. note:: + + Your environment must include the Object Storage service. + +.. include:: install-swift-prereq-common.rst + +Install components +------------------ + +* Install the packages: + + .. code-block:: console + + # apt-get install python-ceilometermiddleware + +.. include:: install-swift-config-common.rst + +Finalize installation +--------------------- + +* Restart the Object Storage proxy service: + + .. code-block:: console + + # service swift-proxy restart diff --git a/install-guide/source/database/environment-nosql-database-obs.rst b/install-guide/source/database/environment-nosql-database-obs.rst new file mode 100644 index 00000000..2ec8e774 --- /dev/null +++ b/install-guide/source/database/environment-nosql-database-obs.rst @@ -0,0 +1,78 @@ +.. _environment-nosql-database-obs: + +NoSQL database for openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Telemetry service uses a NoSQL database to store information. The database +typically runs on the controller node. The procedures in this guide use +MongoDB. + +Install and configure components +-------------------------------- + +1. Enable the Open Build Service repositories for MongoDB based on + your openSUSE or SLES version: + + On openSUSE: + + .. code-block:: console + + # zypper addrepo -f obs://server:database/openSUSE_Leap_42.1 Database + + On SLES: + + .. code-block:: console + + # zypper addrepo -f obs://server:database/SLE_12_SP1 Database + + .. note:: + + The packages are signed by GPG key ``05905EA8``. You should + verify the fingerprint of the imported GPG key before using it. + + .. code-block:: console + + Key Name: server:database OBS Project <server:database@build.opensuse.org> + Key Fingerprint: 116EB863 31583E47 E63CDF4D 562111AC 05905EA8 + Key Created: Mon 08 Dec 2014 09:54:12 AM UTC + Key Expires: Wed 15 Feb 2017 09:54:12 AM UTC + + Install the MongoDB package: + + .. code-block:: console + + # zypper install mongodb + +2. Edit the ``/etc/mongodb.conf`` file and complete the following + actions: + + * Configure the ``bind_ip`` key to use the management interface + IP address of the controller node. + + .. code-block:: ini + + bind_ip = 10.0.0.11 + + * By default, MongoDB creates several 1 GB journal files + in the ``/var/lib/mongodb/journal`` directory. + If you want to reduce the size of each journal file to + 128 MB and limit total journal space consumption to 512 MB, + assert the ``smallfiles`` key: + + .. code-block:: ini + + smallfiles = true + + You can also disable journaling. For more information, see the + `MongoDB manual <http://docs.mongodb.org/manual/>`__. + +Finalize installation +--------------------- + +* Start the MongoDB service and configure it to start when + the system boots: + + .. code-block:: console + + # systemctl enable mongodb.service + # systemctl start mongodb.service diff --git a/install-guide/source/database/environment-nosql-database-rdo.rst b/install-guide/source/database/environment-nosql-database-rdo.rst new file mode 100644 index 00000000..07564918 --- /dev/null +++ b/install-guide/source/database/environment-nosql-database-rdo.rst @@ -0,0 +1,50 @@ +.. _environment-nosql-database-rdo: + +NoSQL database for Red Hat Enterprise Linux and CentOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Telemetry service uses a NoSQL database to store information. The database +typically runs on the controller node. The procedures in this guide use +MongoDB. + +Install and configure components +-------------------------------- + +1. Install the MongoDB packages: + + .. code-block:: console + + # yum install mongodb-server mongodb + +2. Edit the ``/etc/mongod.conf`` file and complete the following + actions: + + * Configure the ``bind_ip`` key to use the management interface + IP address of the controller node. + + .. code-block:: ini + + bind_ip = 10.0.0.11 + + * By default, MongoDB creates several 1 GB journal files + in the ``/var/lib/mongodb/journal`` directory. + If you want to reduce the size of each journal file to + 128 MB and limit total journal space consumption to 512 MB, + assert the ``smallfiles`` key: + + .. code-block:: ini + + smallfiles = true + + You can also disable journaling. For more information, see the + `MongoDB manual <http://docs.mongodb.org/manual/>`__. + +Finalize installation +--------------------- + +* Start the MongoDB service and configure it to start when the system boots: + + .. code-block:: console + + # systemctl enable mongod.service + # systemctl start mongod.service diff --git a/install-guide/source/database/environment-nosql-database-ubuntu.rst b/install-guide/source/database/environment-nosql-database-ubuntu.rst new file mode 100644 index 00000000..f52162d8 --- /dev/null +++ b/install-guide/source/database/environment-nosql-database-ubuntu.rst @@ -0,0 +1,52 @@ +.. _environment-nosql-database-ubuntu: + +NoSQL database for Ubuntu +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Telemetry service uses a NoSQL database to store information. The database +typically runs on the controller node. The procedures in this guide use +MongoDB. + +Install and configure components +-------------------------------- + +1. Install the MongoDB packages: + + .. code-block:: console + + # apt-get install mongodb-server mongodb-clients python-pymongo + +2. Edit the ``/etc/mongodb.conf`` file and complete the following + actions: + + * Configure the ``bind_ip`` key to use the management interface + IP address of the controller node. + + .. code-block:: ini + + bind_ip = 10.0.0.11 + + * By default, MongoDB creates several 1 GB journal files + in the ``/var/lib/mongodb/journal`` directory. + If you want to reduce the size of each journal file to + 128 MB and limit total journal space consumption to 512 MB, + assert the ``smallfiles`` key: + + .. code-block:: ini + + smallfiles = true + + You can also disable journaling. For more information, see the + `MongoDB manual <http://docs.mongodb.org/manual/>`__. + +Finalize installation +--------------------- + +* If you change the journaling configuration, stop the MongoDB + service, remove the initial journal files, and start the service: + + .. code-block:: console + + # service mongodb stop + # rm /var/lib/mongodb/journal/prealloc.* + # service mongodb start diff --git a/install-guide/source/get_started.rst b/install-guide/source/get_started.rst new file mode 100644 index 00000000..3b8ebd6d --- /dev/null +++ b/install-guide/source/get_started.rst @@ -0,0 +1,41 @@ +========================================== +Telemetry Data Collection service overview +========================================== + +The Telemetry Data Collection services provide the following functions: + +* Efficiently polls metering data related to OpenStack services. + +* Collects event and metering data by monitoring notifications sent + from services. + +* Publishes collected data to various targets including data stores and + message queues. + +The Telemetry service consists of the following components: + +A compute agent (``ceilometer-agent-compute``) + Runs on each compute node and polls for resource utilization + statistics. There may be other types of agents in the future, but + for now our focus is creating the compute agent. + +A central agent (``ceilometer-agent-central``) + Runs on a central management server to poll for resource utilization + statistics for resources not tied to instances or compute nodes. + Multiple agents can be started to scale service horizontally. + +A notification agent (``ceilometer-agent-notification``) + Runs on a central management server(s) and consumes messages from + the message queue(s) to build event and metering data. + +A collector (``ceilometer-collector``) + Runs on central management server(s) and dispatches collected + telemetry data to a data store or external consumer without + modification. + +An API server (``ceilometer-api``) + Runs on one or more central management servers to provide data + access from the data store. + +These services communicate by using the OpenStack messaging bus. Only +the collector and API server have access to the data store.
\ No newline at end of file diff --git a/install-guide/source/index.rst b/install-guide/source/index.rst new file mode 100644 index 00000000..431e9efb --- /dev/null +++ b/install-guide/source/index.rst @@ -0,0 +1,31 @@ +================================= +Telemetry Data Collection service +================================= + +.. toctree:: + :maxdepth: 2 + + get_started.rst + install-base-obs.rst + install-base-rdo.rst + install-base-ubuntu.rst + configure_services/glance/install-glance-obs.rst + configure_services/glance/install-glance-rdo.rst + configure_services/glance/install-glance-ubuntu.rst + configure_services/nova/install-nova-obs.rst + configure_services/nova/install-nova-rdo.rst + configure_services/nova/install-nova-ubuntu.rst + configure_services/cinder/install-cinder-obs.rst + configure_services/cinder/install-cinder-rdo.rst + configure_services/cinder/install-cinder-ubuntu.rst + configure_services/swift/install-swift-obs.rst + configure_services/swift/install-swift-rdo.rst + configure_services/swift/install-swift-ubuntu.rst + verify.rst + next-steps.rst + database/environment-nosql-database-obs.rst + database/environment-nosql-database-rdo.rst + database/environment-nosql-database-ubuntu.rst + +This chapter assumes a working setup of OpenStack following the base +Installation Guide. diff --git a/install-guide/source/install-base-config-common.rst b/install-guide/source/install-base-config-common.rst new file mode 100644 index 00000000..17d12107 --- /dev/null +++ b/install-guide/source/install-base-config-common.rst @@ -0,0 +1,76 @@ +2. Edit the ``/etc/ceilometer/ceilometer.conf`` file and complete + the following actions: + + * In the ``[database]`` section, configure database access: + + .. code-block:: ini + + [database] + ... + connection = mongodb://ceilometer:CEILOMETER_DBPASS@controller:27017/ceilometer + + Replace ``CEILOMETER_DBPASS`` with the password you chose for the + Telemetry service database. You must escape special characters such + as ':', '/', '+', and '@' in the connection string in accordance + with `RFC2396 <https://www.ietf.org/rfc/rfc2396.txt>`_. + + * In the ``[DEFAULT]`` and ``[oslo_messaging_rabbit]`` sections, + configure ``RabbitMQ`` message queue access: + + .. code-block:: ini + + [DEFAULT] + ... + rpc_backend = rabbit + + [oslo_messaging_rabbit] + ... + rabbit_host = controller + rabbit_userid = openstack + rabbit_password = RABBIT_PASS + + Replace ``RABBIT_PASS`` with the password you chose for the + ``openstack`` account in ``RabbitMQ``. + + * In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections, + configure Identity service access: + + .. code-block:: ini + + [DEFAULT] + ... + auth_strategy = keystone + + [keystone_authtoken] + ... + auth_uri = http://controller:5000 + auth_url = http://controller:35357 + memcached_servers = controller:11211 + auth_type = password + project_domain_name = default + user_domain_name = default + project_name = service + username = ceilometer + password = CEILOMETER_PASS + + Replace ``CEILOMETER_PASS`` with the password you chose for + the ``ceilometer`` user in the Identity service. + + * In the ``[service_credentials]`` section, configure service credentials: + + .. code-block:: ini + + [service_credentials] + ... + auth_type = password + auth_url = http://controller:5000/v3 + project_domain_name = default + user_domain_name = default + project_name = service + username = ceilometer + password = CEILOMETER_PASS + interface = internalURL + region_name = RegionOne + + Replace ``CEILOMETER_PASS`` with the password you chose for + the ``ceilometer`` user in the Identity service. diff --git a/install-guide/source/install-base-obs.rst b/install-guide/source/install-base-obs.rst new file mode 100644 index 00000000..8843a6d2 --- /dev/null +++ b/install-guide/source/install-base-obs.rst @@ -0,0 +1,117 @@ +.. _install_obs: + +Install and configure for openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the +Telemetry service, code-named ceilometer, on the controller node. + +This section assumes that you already have a working OpenStack +environment with at least the following components installed: +Compute, Image Service, Identity. + +Prerequisites +------------- + +Before you install and configure the Telemetry service, you must +create a database, service credentials, and API endpoints. However, +unlike other services, the Telemetry service uses a NoSQL database. +See :ref:`environment-nosql-database-obs` to install and configure +MongoDB before proceeding further. + +1. Create the ``ceilometer`` database: + + .. code-block:: console + + # mongo --host controller --eval ' + db = db.getSiblingDB("ceilometer"); + db.addUser({user: "ceilometer", + pwd: "CEILOMETER_DBPASS", + roles: [ "readWrite", "dbAdmin" ]})' + + MongoDB shell version: 2.4.x + connecting to: controller:27017/test + { + "user" : "ceilometer", + "pwd" : "72f25aeee7ad4be52437d7cd3fc60f6f", + "roles" : [ + "readWrite", + "dbAdmin" + ], + "_id" : ObjectId("5489c22270d7fad1ba631dc3") + } + + Replace ``CEILOMETER_DBPASS`` with a suitable password. + + .. note:: + + If the command fails saying you are not authorized to insert a user, + you may need to temporarily comment out the ``auth`` option in + the ``/etc/mongodb.conf`` file, restart the MongoDB service using + ``systemctl restart mongodb``, and try calling the command again. + +.. include:: install-base-prereq-common.rst + +Install and configure components +-------------------------------- + +1. Install the packages: + + .. code-block:: console + + # zypper install openstack-ceilometer-api \ + openstack-ceilometer-collector \ + openstack-ceilometer-agent-notification \ + openstack-ceilometer-agent-central python-ceilometerclient + +.. include:: install-base-config-common.rst + +* In the ``[collector]`` section, configure the dispatcher: + + .. code-block:: ini + + [collector] + ... + dispatcher = database + +Configure the Apache HTTP server +-------------------------------- + +* Create the ``/etc/apache2/conf.d/wsgi-ceilometer.conf`` file + with the following content: + + .. code-block:: apache + + Listen 8777 + + <VirtualHost *:8777> + WSGIDaemonProcess ceilometer-api processes=2 threads=10 user=ceilometer group=ceilometer display-name=%{GROUP} + WSGIProcessGroup ceilometer-api + WSGIScriptAlias / "/var/www/cgi-bin/ceilometer/app" + WSGIApplicationGroup %{GLOBAL} + ErrorLog /var/log/apache2/ceilometer_error.log + CustomLog /var/log/apache2/ceilometer_access.log combined + </VirtualHost> + + WSGISocketPrefix /var/run/apache2 + +Finalize installation +--------------------- + +#. Reload the Apache HTTP server: + + .. code-block:: console + + # systemctl reload apache2.service + +#. Start the Telemetry services and configure them to start when the + system boots: + + .. code-block:: console + + # systemctl enable openstack-ceilometer-agent-notification.service \ + openstack-ceilometer-agent-central.service \ + openstack-ceilometer-collector.service + # systemctl start openstack-ceilometer-agent-notification.service \ + openstack-ceilometer-agent-central.service \ + openstack-ceilometer-collector.service diff --git a/install-guide/source/install-base-prereq-common.rst b/install-guide/source/install-base-prereq-common.rst new file mode 100644 index 00000000..2e4bacdd --- /dev/null +++ b/install-guide/source/install-base-prereq-common.rst @@ -0,0 +1,102 @@ +2. Source the ``admin`` credentials to gain access to admin-only + CLI commands: + + .. code-block:: console + + $ . admin-openrc + +3. To create the service credentials, complete these steps: + + * Create the ``ceilometer`` user: + + .. code-block:: console + + $ openstack user create --domain default --password-prompt ceilometer + User Password: + Repeat User Password: + +-----------+----------------------------------+ + | Field | Value | + +-----------+----------------------------------+ + | domain_id | e0353a670a9e496da891347c589539e9 | + | enabled | True | + | id | c859c96f57bd4989a8ea1a0b1d8ff7cd | + | name | ceilometer | + +-----------+----------------------------------+ + + * Add the ``admin`` role to the ``ceilometer`` user. + + .. code-block:: console + + $ openstack role add --project service --user ceilometer admin + + .. note:: + + This command provides no output. + + * Create the ``ceilometer`` service entity: + + .. code-block:: console + + $ openstack service create --name ceilometer \ + --description "Telemetry" metering + +-------------+----------------------------------+ + | Field | Value | + +-------------+----------------------------------+ + | description | Telemetry | + | enabled | True | + | id | 5fb7fd1bb2954fddb378d4031c28c0e4 | + | name | ceilometer | + | type | metering | + +-------------+----------------------------------+ + +4. Create the Telemetry service API endpoints: + + .. code-block:: console + + $ openstack endpoint create --region RegionOne \ + metering public http://controller:8777 + +--------------+----------------------------------+ + | Field | Value | + +--------------+----------------------------------+ + | enabled | True | + | id | b808b67b848d443e9eaaa5e5d796970c | + | interface | public | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 5fb7fd1bb2954fddb378d4031c28c0e4 | + | service_name | ceilometer | + | service_type | metering | + | url | http://controller:8777 | + +--------------+----------------------------------+ + + $ openstack endpoint create --region RegionOne \ + metering internal http://controller:8777 + +--------------+----------------------------------+ + | Field | Value | + +--------------+----------------------------------+ + | enabled | True | + | id | c7009b1c2ee54b71b771fa3d0ae4f948 | + | interface | internal | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 5fb7fd1bb2954fddb378d4031c28c0e4 | + | service_name | ceilometer | + | service_type | metering | + | url | http://controller:8777 | + +--------------+----------------------------------+ + + $ openstack endpoint create --region RegionOne \ + metering admin http://controller:8777 + +--------------+----------------------------------+ + | Field | Value | + +--------------+----------------------------------+ + | enabled | True | + | id | b2c00566d0604551b5fe1540c699db3d | + | interface | admin | + | region | RegionOne | + | region_id | RegionOne | + | service_id | 5fb7fd1bb2954fddb378d4031c28c0e4 | + | service_name | ceilometer | + | service_type | metering | + | url | http://controller:8777 | + +--------------+----------------------------------+ diff --git a/install-guide/source/install-base-rdo.rst b/install-guide/source/install-base-rdo.rst new file mode 100644 index 00000000..ca9255d0 --- /dev/null +++ b/install-guide/source/install-base-rdo.rst @@ -0,0 +1,93 @@ +.. _install_rdo: + +Install and configure for Red Hat Enterprise Linux and CentOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the +Telemetry service, code-named ceilometer, on the controller node. + +This section assumes that you already have a working OpenStack +environment with at least the following components installed: +Compute, Image Service, Identity. + +Prerequisites +------------- + +Before you install and configure the Telemetry service, you must +create a database, service credentials, and API endpoints. However, +unlike other services, the Telemetry service uses a NoSQL database. +See :ref:`environment-nosql-database-rdo` to install and configure +MongoDB before proceeding further. + +1. Create the ``ceilometer`` database: + + .. code-block:: console + + # mongo --host controller --eval ' + db = db.getSiblingDB("ceilometer"); + db.createUser({user: "ceilometer", + pwd: "CEILOMETER_DBPASS", + roles: [ "readWrite", "dbAdmin" ]})' + + MongoDB shell version: 2.6.x + connecting to: controller:27017/test + Successfully added user: { "user" : "ceilometer", "roles" : [ "readWrite", "dbAdmin" ] } + + Replace ``CEILOMETER_DBPASS`` with a suitable password. + +.. include:: install-base-prereq-common.rst + +Install and configure components +-------------------------------- + +1. Install the packages: + + .. code-block:: console + + # yum install openstack-ceilometer-api \ + openstack-ceilometer-collector openstack-ceilometer-notification \ + openstack-ceilometer-central python-ceilometerclient + +.. include:: install-base-config-common.rst + +Configure the Apache HTTP server +-------------------------------- + +* Create the ``/etc/httpd/conf.d/wsgi-ceilometer.conf`` file with + the following content: + + .. code-block:: apache + + Listen 8777 + + <VirtualHost *:8777> + WSGIDaemonProcess ceilometer-api processes=2 threads=10 user=ceilometer group=ceilometer display-name=%{GROUP} + WSGIProcessGroup ceilometer-api + WSGIScriptAlias / "/var/www/cgi-bin/ceilometer/app" + WSGIApplicationGroup %{GLOBAL} + ErrorLog /var/log/httpd/ceilometer_error.log + CustomLog /var/log/httpd/ceilometer_access.log combined + </VirtualHost> + + WSGISocketPrefix /var/run/httpd + +Finalize installation +--------------------- + +#. Reload the Apache HTTP server: + + .. code-block:: console + + # systemctl reload httpd.service + +#. Start the Telemetry services and configure them to start when the + system boots: + + .. code-block:: console + + # systemctl enable openstack-ceilometer-notification.service \ + openstack-ceilometer-central.service \ + openstack-ceilometer-collector.service + # systemctl start openstack-ceilometer-notification.service \ + openstack-ceilometer-central.service \ + openstack-ceilometer-collector.service diff --git a/install-guide/source/install-base-ubuntu.rst b/install-guide/source/install-base-ubuntu.rst new file mode 100644 index 00000000..83f47ca3 --- /dev/null +++ b/install-guide/source/install-base-ubuntu.rst @@ -0,0 +1,110 @@ +.. _install_ubuntu: + +Install and configure for Ubuntu +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the +Telemetry service, code-named ceilometer, on the controller node. + +This section assumes that you already have a working OpenStack +environment with at least the following components installed: +Compute, Image Service, Identity. + +Prerequisites +------------- + +Before you install and configure the Telemetry service, you must +create a database, service credentials, and API endpoints. However, +unlike other services, the Telemetry service uses a NoSQL database. +See :ref:`environment-nosql-database-ubuntu` to install and configure +MongoDB before proceeding further. + +1. Create the ``ceilometer`` database: + + .. code-block:: console + + # mongo --host controller --eval ' + db = db.getSiblingDB("ceilometer"); + db.addUser({user: "ceilometer", + pwd: "CEILOMETER_DBPASS", + roles: [ "readWrite", "dbAdmin" ]})' + + MongoDB shell version: 2.4.x + connecting to: controller:27017/test + { + "user" : "ceilometer", + "pwd" : "72f25aeee7ad4be52437d7cd3fc60f6f", + "roles" : [ + "readWrite", + "dbAdmin" + ], + "_id" : ObjectId("5489c22270d7fad1ba631dc3") + } + + Replace ``CEILOMETER_DBPASS`` with a suitable password. + + .. note:: + + If the command fails saying you are not authorized to insert a user, + you may need to temporarily comment out the ``auth`` option in + the ``/etc/mongodb.conf`` file, restart the MongoDB service using + ``systemctl restart mongodb``, and try calling the command again. + +.. include:: install-base-prereq-common.rst + +Install and configure components +-------------------------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get install ceilometer-api ceilometer-collector \ + ceilometer-agent-central ceilometer-agent-notification + python-ceilometerclient + +.. include:: install-base-config-common.rst + +Configure the Apache HTTP server +-------------------------------- + +#. Create the ``/etc/apache2/sites-available/wsgi-ceilometer.conf`` file + with the following content: + + .. code-block:: apache + + Listen 8777 + + <VirtualHost *:8777> + WSGIDaemonProcess ceilometer-api processes=2 threads=10 user=ceilometer group=ceilometer display-name=%{GROUP} + WSGIProcessGroup ceilometer-api + WSGIScriptAlias / "/var/www/cgi-bin/ceilometer/app" + WSGIApplicationGroup %{GLOBAL} + ErrorLog /var/log/apache2/ceilometer_error.log + CustomLog /var/log/apache2/ceilometer_access.log combined + </VirtualHost> + + WSGISocketPrefix /var/run/apache2 + +#. Enable the Telemetry service virtual hosts: + + .. code-block:: console + + # a2ensite ceilometer + +Finalize installation +--------------------- + +#. Reload the Apache HTTP server: + + .. code-block:: console + + # service apache2 reload + +#. Restart the Telemetry services: + + .. code-block:: console + + # service ceilometer-agent-central restart + # service ceilometer-agent-notification restart + # service ceilometer-collector restart diff --git a/install-guide/source/next-steps.rst b/install-guide/source/next-steps.rst new file mode 100644 index 00000000..80c0c8ab --- /dev/null +++ b/install-guide/source/next-steps.rst @@ -0,0 +1,9 @@ +.. _next-steps: + +Next steps +~~~~~~~~~~ + +Your OpenStack environment now includes the ceilometer service. + +To add additional services, see +docs.openstack.org/draft/install-guides/index.html . diff --git a/install-guide/source/verify.rst b/install-guide/source/verify.rst new file mode 100644 index 00000000..2c97a3ff --- /dev/null +++ b/install-guide/source/verify.rst @@ -0,0 +1,70 @@ +.. _verify: + +Verify operation +~~~~~~~~~~~~~~~~ + +Verify operation of the Telemetry service. These steps only include the +Image service meters to reduce clutter. Environments with ceilometer +integration for additional services contain more meters. + +.. note:: + + Perform these steps on the controller node. + +#. Source the ``admin`` credentials to gain access to + admin-only CLI commands: + + .. code-block:: console + + $ . admin-openrc + +#. List available meters: + + .. code-block:: console + + $ ceilometer meter-list + +--------------+-------+-------+--------------------------------------+---------+------------+ + | Name | Type | Unit | Resource ID | User ID | Project ID | + +--------------+-------+-------+--------------------------------------+---------+------------+ + | image | gauge | image | acafc7c0-40aa-4026-9673-b879898e1fc2 | None | cf12a15... | + | image.size | gauge | B | acafc7c0-40aa-4026-9673-b879898e1fc2 | None | cf12a15... | + +--------------+-------+-------+--------------------------------------+---------+------------+ + +#. Download the CirrOS image from the Image service: + + .. code-block:: console + + $ IMAGE_ID=$(glance image-list | grep 'cirros' | awk '{ print $2 }') + $ glance image-download $IMAGE_ID > /tmp/cirros.img + +#. List available meters again to validate detection of the image + download: + + .. code-block:: console + + $ ceilometer meter-list + +----------------+-------+-------+--------------------------------------+---------+------------+ + | Name | Type | Unit | Resource ID | User ID | Project ID | + +----------------+-------+-------+--------------------------------------+---------+------------+ + | image | gauge | image | acafc7c0-40aa-4026-9673-b879898e1fc2 | None | cf12a15... | + | image.download | delta | B | acafc7c0-40aa-4026-9673-b879898e1fc2 | None | cf12a15... | + | image.serve | delta | B | acafc7c0-40aa-4026-9673-b879898e1fc2 | None | cf12a15... | + | image.size | gauge | B | acafc7c0-40aa-4026-9673-b879898e1fc2 | None | cf12a15... | + +----------------+-------+-------+--------------------------------------+---------+------------+ + +#. Retrieve usage statistics from the ``image.download`` meter: + + .. code-block:: console + + $ ceilometer statistics -m image.download -p 60 + +--------+---------------------+---------------------+------------+------------+------------+------------+-------+----------+----------------------------+----------------------------+ + | Period | Period Start | Period End | Max | Min | Avg | Sum | Count | Duration | Duration Start | Duration End | + +--------+---------------------+---------------------+------------+------------+------------+------------+-------+----------+----------------------------+----------------------------+ + | 60 | 2015-04-21T12:21:45 | 2015-04-21T12:22:45 | 13200896.0 | 13200896.0 | 13200896.0 | 13200896.0 | 1 | 0.0 | 2015-04-21T12:22:12.983000 | 2015-04-21T12:22:12.983000 | + +--------+---------------------+---------------------+------------+------------+------------+------------+-------+----------+----------------------------+----------------------------+ + +#. Remove the previously downloaded image file ``/tmp/cirros.img``: + + .. code-block:: console + + $ rm /tmp/cirros.img diff --git a/test-requirements.txt b/test-requirements.txt index 9aa5d54c..e146daf7 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -12,6 +12,7 @@ PyMySQL>=0.6.2 # MIT License os-win>=0.2.3 # Apache-2.0 oslo.cache>=1.5.0 # Apache-2.0 # Docs Requirements +openstackdocstheme>=1.0.3 # Apache-2.0 oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0 reno>=1.6.2 # Apache2 oslotest>=1.10.0 # Apache-2.0 @@ -84,6 +84,13 @@ commands = [testenv:releasenotes] commands = sphinx-build -a -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html +[testenv:install-guide] +# NOTE(jaegerandi): this target does not use constraints because +# upstream infra does not yet support it. Once that's fixed, we can +# drop the install_command. +install_command = pip install -U --force-reinstall {opts} {packages} +commands = sphinx-build -a -E -W -d install-guide/build/doctrees -b html install-guide/source install-guide/build/html + [testenv:genconfig] commands = oslo-config-generator --config-file=etc/ceilometer/ceilometer-config-generator.conf @@ -116,7 +123,7 @@ commands = pifpaf --debug run elasticsearch oslo_debug_helper {posargs} [flake8] ignore = -exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build +exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build,install-guide show-source = True [hacking] |