diff --git a/README.rst b/README.rst index e330b9c8..995dd54c 100644 --- a/README.rst +++ b/README.rst @@ -5,6 +5,12 @@ ClearLinux Docs are written in :abbr:`ReStructuredText (ReST)` AKA ``.rst``, whi makes it easy to build parsable, command-line readable, indexed, and search-friendly documentation and APIs with `Sphinx`_. + +.. _requirements: + +Requirements +------------ + Building the docs with Sphinx, however, requires a few prerequisites: * `GNU make`_ @@ -40,16 +46,18 @@ Dependencies fulfilled, let's now clone that gitlab repo: .. tip:: - If the first time you've cloned the ``project-docs`` is following along with this tutorial, - you can skip this section; go straight ahead to the :ref:`Run make` section. However, if you - cloned an earlier version and had trouble generating HTML documentation locally, try the steps - documented here. + If the first time you've cloned ``project-docs`` is following along + with this tutorial, you may skip this section; go straight ahead to the + :ref:`Run make` section. However, if you cloned an earlier version and + had trouble generating HTML documentation locally, try the steps documented + here. -Before running Sphinx, we need to correct some of the problems in the Gitlab repo. -Running :command:`make` straightaway from the root of our clone won't work. We need to delete the -existing :file:`conf.py` file and also rename the existing index file so it can generate a new one -with the correct parameters. Some files in the Gitlab repo are remnant of a build on a Windows -box, and they don't quite work on Linux. +Before running Sphinx, we need to correct some of the problems in the Gitlab +repo. Running :command:`make` straightaway from the root of our clone won't +work. We need to delete the existing :file:`conf.py` file and also rename +the existing index file so it can generate a new one with the correct +parameters. Some files in the Gitlab repo are remnant of a build on a Windows +box, and they don't quite work on Linux. .. code-block:: console @@ -61,22 +69,26 @@ box, and they don't quite work on Linux. $ mv source/index.rst source/oldindex.rst -In the cloned source directory, we have all the .rst files we need to build the docs. We -run a native instance of :command:`sphinx-quickstart`. The program will run you through -a series of questions. The main things to be conscious of here: +In the cloned source directory, we have all the .rst files we need to build +the docs. We run a native instance of :command:`sphinx-quickstart`. The +program will run you through a series of questions. The main things to be +conscious of here: * Tell it to use the existing :file:`source/` directory as the Root path for - the documentation; this is where it looks to find what it needs to generate the HTML. -* It's better to tell it to **not** separate the source and build directories; if you - answer "y" here, Sphinx will generate *another* :file:`source/` directory, which - can be confusing. -* The running quickstart also creates as :file:`_static` directory where you should put - all images, screenshots, and other static content. The builder might complain about this - directory if it exists already, but it's easy to fix. + the documentation; this is where it looks to find what it needs to generate + the HTML. +* It's better to tell it to **not** separate the source and build directories; + if you answer "y" here, Sphinx will generate *another* :file:`source/` directory, + which can be confusing. +* Running quickstart also creates a :file:`_static` directory where you + should put all images, screenshots, and other content that is linked as static + content. The builder has been known to complain about this directory if it exists + already, but it's easy to fix. * Run the builder only once. -What follows here is a log from a successful :command:`sphinx-quickstart` build started from -within an older clone of the :file:`project-docs/` directory. Blank answers indicate default. +What follows here is a log from a successful :command:`sphinx-quickstart` build +started from within an older clone of the :file:`project-docs/` directory. Blank +answers indicate default. .. code-block:: console @@ -155,18 +167,20 @@ within an older clone of the :file:`project-docs/` directory. Blank answers ind Finished: An initial directory structure has been created. - You should now populate your master file source/index.rst and create other documentation - source files. Use the Makefile to build the docs, like so: + You should now populate your master file source/index.rst and create other + documentation source files. Use the Makefile to build the docs, like so: make builder - where "builder" is one of the supported builders, e.g. html, latex or linkcheck. + where "builder" is one of the supported builders, e.g. html, latex or + linkcheck. .. _run_make: Run make -------- -Finally are we ready to run :command:`make`. Be sure to :command:`cd` to the :file:`source/` -directory before running :command:`make` ``html``, or the doc format of your choice. +Finally are we ready to run :command:`make`. Be sure to :command:`cd` to the +:file:`source/` directory before running :command:`make` ``html``, or the doc +format of your choice. .. code-block:: console @@ -182,12 +196,14 @@ directory before running :command:`make` ``html``, or the doc format of your cho Build finished. The HTML pages are in _build/html. -Open one of these pages in a web browser to view the rendered documentation. If needed, you can -copy the contents of the oldindex.rst into the generated index file, re-run :command:`make`, to -generate the new HTML, and your local Table of Contents should index and update accordingly. +Open one of these pages in a web browser to view the rendered documentation. +If needed, you can copy the contents of the oldindex.rst into the generated +index file, re-run :command:`make`, to generate the new HTML, and your local +Table of Contents should index and update accordingly. -For tips on how to contribute documentation formatted in the .rst style needed to integrate on the -Clearlinux.org website, please see `Theming Sphinx`_. +For tips on how to contribute documentation formatted in the .rst style +needed to integrate on the Clearlinux.org website, please see + `Theming Sphinx`_. .. _Sphinx: http://sphinx-doc.org/ .. _GNU make: https://www.gnu.org/software/make/ diff --git a/source/gs-clear-containers-gettting-started.rst b/source/gs-clear-containers-gettting-started.rst index b698937c..256904f6 100644 --- a/source/gs-clear-containers-gettting-started.rst +++ b/source/gs-clear-containers-gettting-started.rst @@ -18,7 +18,7 @@ or better. However, binaries for a range of operating systems are available from Currently experimental builds are available for: - CentOS*, Scientific Linux* 7 -- Fedora* 21, 22 +- Fedora* 21, 22, 23 - openSUSE* 13.1, 13.2, Tumbleweed - SUSE* Linux Enterprise 12 - Debian* 8.0 @@ -69,7 +69,7 @@ instructions below: Source Code =========== -The experimental source code is based on the Docker version 1.8.1 upstream release and is available at: +The experimental source code is based on the Docker version 1.9.0 upstream release and is available at: - https://github.com/clearlinux/docker diff --git a/source/openstack_telemetry_compute.rst b/source/openstack_telemetry_compute.rst new file mode 100644 index 00000000..16db9093 --- /dev/null +++ b/source/openstack_telemetry_compute.rst @@ -0,0 +1,82 @@ +OpenStack* Telemetry - Enable compute service meters +############################################################ + +Telemetry uses a combination of notifications and an agent to +collect Compute meters. Perform these steps on each compute node. + +Configure components +----------------------------------------------- + +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:: + + [DEFAULT] + ... + rpc_backend = rabbit + + [oslo_messaging_rabbit] + ... + rabbit_host = controller + rabbit_userid = openstack + rabbit_password = RABBIT_PASS + + Replace the ``RABBIT_PASS`` with the password you chose for the openstack account in RabbitMQ. + +#. In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections, configure Identity service access:: + + [DEFAULT] + ... + auth_strategy = keystone + + [keystone_authtoken] + ... + auth_uri = http://controller:5000 + auth_url = http://controller:35357 + auth_plugin = password + project_domain_id = default + user_domain_id = 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:: + + [service_credentials] + ... + os_auth_url = http://controller:5000/v2.0 + os_username = ceilometer + os_tenant_name = service + os_password = CEILOMETER_PASS + os_endpoint_type = internalURL + os_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:: + + [DEFAULT] + ... + instance_usage_audit = True + instance_usage_audit_period = hour + notify_on_state_change = vm_and_task_state + notification_driver = messagingv2 + + +Finalize the installation +----------------------------------------------- + +#. Restart the agent:: + + # systemctl enable ceilometer-agent-compute.service + # systemctl restart ceilometer-agent-compute.service + +#. Restart the compute service:: + + # systemctl restart nova-compute.service diff --git a/source/openstack_telemetry_image.rst b/source/openstack_telemetry_image.rst new file mode 100644 index 00000000..86614c4b --- /dev/null +++ b/source/openstack_telemetry_image.rst @@ -0,0 +1,35 @@ +OpenStack* Telemetry - 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]`` section, configure notifications and RabbitMQ message broker access:: + + [DEFAULT] + ... + notification_driver = messagingv2 + rpc_backend = rabbit + + [oslo_messaging_rabbit] + ... + rabbit_host = controller + rabbit_userid = openstack + rabbit_password = RABBIT_PASS + + Replace the ``RABBIT_PASS`` with the password you chose for the openstack account in RabbitMQ. + +Finalize the installation +---------------------------- + +#. Restart the image service:: + + # systemctl restart glance-registry.service + # systemctl restart glance-api.service diff --git a/source/openstack_telemetry_verify.rst b/source/openstack_telemetry_verify.rst new file mode 100644 index 00000000..a6a54714 --- /dev/null +++ b/source/openstack_telemetry_verify.rst @@ -0,0 +1,59 @@ +OpenStack* Telemetry - Verify Operation +############################################################ + +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. + + +#. Source the ``admin`` credentials to gain access to admin-only CLI + commands:: + + $ source admin-openrc.sh + +#. List available meters:: + + $ 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:: + + $ 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:: + + $ 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:: + + $ 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:: + + $ rm /tmp/cirros.img + + + + +