Provide dev-ref update

This change set updates the dev-ref documentation for
Ceilometer-PowerVM.

Change-Id: Id6f1a181c3b134488d500f2e04f4690c9d2536df

.gitignore

@@ -4,3 +4,5 @@
 ceilometer_powervm.egg-info/
 *.pyc
 doc/build
+AUTHORS
+ChangeLog

README.rst

@@ -2,116 +2,66 @@
 Support for PowerVM Performance Monitoring
 ==========================================
 
-Include the URL of your launchpad blueprint:
-
-https://blueprints.launchpad.net/ceilometer/+spec/example
-https://blueprints.launchpad.net/python-ceilometerclient/+spec/example
-
 The IBM PowerVM hypervisor provides virtualization on POWER hardware.
 PowerVM customers can see benefits in their environments by making use
-of OpenStack. This blueprint outlines implementing Ceilometer-compatible
+of OpenStack. This project implements a Ceilometer-compatible compute
-compute agent plugins. These, along with a Nova driver and Neutron agent
+inspector.  This inspector, along with the PowerVM Nova driver and Neutron
-defined in other blueprints, will provide capability for PowerVM
+agent, provides capability for PowerVM customers to natively monitor
-customers to natively monitor utilization and statistics for instances
+utilization and statistics for instances running on OpenStack-managed systems.
-running on OpenStack managed systems.
 
-Problem description
+
+Problem Description
 ===================
 
-PowerVM supports a variety of Performance Monitoring interfaces within
+PowerVM supports a variety of performance monitoring interfaces within
 the platform, providing virtual machine and system monitoring data.
-Today, however, Ceilometer does not collect metrics for virtual machines
+Ceilometer-powervm implements a Ceilometer-based compute inspector for the
-running on the PowerVM platform. With the proposal of a PowerVM Nova
+PowerVM hypervisor.
-driver it is necessary to extend support for PowerVM into Ceilometer as
-well.
 
-This blueprint will outlines implementing Ceilometer-compatible compute
+Inspector Description
-agent plugins for the PowerVM hypervisor. With this update the
+=====================
-Ceilometer compute agent will run on each PowerVM compute node and will
-poll against the PowerVM REST API to retrieve data on running instances.
 
-Proposed change
+The Ceilometer compute agent provides an inspector framework that allows
-===============
-
-This blueprint, along with associated blueprints in Nova and Neutron,
-plans to bring the PowerVM hypervisor into the OpenStack community.
-
-The Ceilometer compute agent provides a framework that allows
 hypervisors to integrate support for gathering instance statistics and
-utilization details into Ceilometer. The proposed change plans to build
+utilization details into Ceilometer. This project provides a standard
-upon the work that the Ceilometer community has done within the compute
+Ceilometer virt inspector that pulls its data from the PowerVM Performance and
-agent by adding support for gathering instance data from the PowerVM
+Capacity Monitoring (PCM) infrastructure.
-Performance Monitoring infrastructure.
 
-A new compute agent inspector will be added for PowerVM. This will
+This inspector retrieves instance monitoring data for cpu, network, memory, and
-follow the existing inspector specification and poll PowerVM Performance
+disk usage. Interactions with PowerVM PCM occur using the PowerVM REST API
-Monitoring to retrieve instance monitoring data. Data on instance cpu,
+stack through `pypowervm`_, an open source python project.
-network, memory, and disk usage will be returned by the inspector when
-called by the associated pollster. Interactions with PowerVM Performance
-Monitoring will occur using the PowerVM REST API stack via an open
-source python wrapper to be defined.
 
-These changes are planned to be developed in StackForge under a powervm
+This inspector requires that the PowerVM system be configured for management
-project. A separate blueprint will be proposed for the ‘L’ release of
+via `NovaLink`_.
-OpenStack to promote it to the Ceilometer project. This will allow for a
-longer period of time to show functional testing and drive maturity.
 
-Until the promotion to the core Ceilometer project is complete, these
+.. _pypowervm: https://github.com/pypowervm/pypowervm
-changes will be marked experimental.
+.. _NovaLink: http://www-01.ibm.com/common/ssi/cgi-bin/ssialias?infotype=AN&subtype=CA&htmlfid=897/ENUS215-262&appname=USN
 
-Alternatives
-------------
 
-Alternatives include writing a PowerVM-specific compute agent or
+End User Impact
-separate PowerVM-specific compute agent plugins. These solutions do not
-follow the existing Ceilometer standard for hypervisor instance
-monitoring, would not fit within broader project goals, and would end up
-re-implementing logic.
-
-Data model impact
------------------
-
-None
-
-REST API impact
 ---------------
 
-None
+The users of the cloud are able to see the metrics for their virtual machines.
-
+As PowerVM deals with 'disk buses' rather than specific disks, the hard disk
-Security impact
+data is reported at a 'per bus' level (i.e. each SCSI or Virtual Fibre Channel
----------------
+bus).
-
-None
-
-Pipeline impact
----------------
-
-This change extends the existing Ceilometer compute agent and should
-have no Pipeline impact.
-
-Other end user impact
----------------------
-
-None to the deployer.
-
-For the Kilo release of OpenStack, the administrator will need to obtain
-the change from StackForge (and understand its experimental status).
 
 Performance/Scalability Impacts
 -------------------------------
 
-This change should have no impacts to performance or scalability of the
+None.
-system. The amount of data being gathered and processed will be similar
-to that of the existing libvirt, vmware, and hyper-v inspectors.
 
 Other deployer impact
 ---------------------
 
-The cloud administrator will need to refer to documentation on how to
+The cloud administrator needs to install the ceilometer-powervm project on
-configure OpenStack for use with a PowerVM hypervisor.
+their PowerVM compute node.  It must be installed on the `NovaLink`_ virtual
+machine on the PowerVM system.
 
-Assuming the PowerVM REST API and Python wrapper library are available,
+The cloud administrator needs to configure their 'hypervisor_inspector' as
-no additional configuration should be required.
+powervm.
+
+No other configuration is required.
 
 Developer impact
 ----------------
@@ -124,88 +74,25 @@ Implementation
 Assignee(s)
 -----------
 
-Primary assignee: adreznec
+Primary assignee: thorst
 
-Other contributors: thorst kyleh dwarcher
+Ongoing maintainer: thorst
 
-Ongoing maintainer: adreznec
-
-Work Items
-----------
-
--  Create a PowerVM-specific inspector in the
-   /ceilometer/compute/virt/powervm folder. Stub out the methods.
-
--  Create a PowerVM helper utility for interfacing with the PowerVM REST
-   API python wrapper.
-
--  Implement inspector calls to match the virt inspector abstraction,
-   making calls against the PowerVM REST API to collect cpu, vnic, disk,
-   and memory statistics.
-
--  Provide extensive unit tests (part of other work items).
-
--  Implement a functional automation server that listens for incoming
-   change set commits from the community and provides a non-gating vote
-   (+1 or -1) on the change.
 
 Future lifecycle
 ================
 
-Ongoing maintenance of the PowerVM compute agent inspector will be
+Ongoing maintenance of the PowerVM compute inspector will be handled by the IBM
-handled by the IBM OpenStack team over the course of the next two
+OpenStack team.
-release cycles. In the Kilo timeframe this change will remain in
-StackForge, with a target of merging in the ‘L’ timeframe and continued
-maintenance and updates as the Ceilometer architecture requires.
 
 Dependencies
 ============
 
 -  The Ceilometer compute agent.
 
--  Will utilize the PowerVM REST API specification for management. Will
+-  The `pypowervm`_ library.
-   utilize future versions of this specification as it becomes
-   available: http://ibm.co/1lThV9R
 
--  Will build on top of a new open source python binding to previously
+-  A `NovaLink`_ enabled PowerVM system.
-   noted PowerVM REST API. This will be a prerequisite to utilizing the
-   driver.
-
-Testing
-=======
-
-Tempest Tests
--------------
-
-Since the tempest tests should be implementation-agnostic, the existing
-tempest tests should be able to run against the PowerVM polling code
-without issue. This blueprint does not foresee any changes based off
-this work.
-
-Thorough unit tests will be created with the agent to validate specific
-functions within this implementation.
-
-Functional Tests
-----------------
-
-A third party functional test environment will be created. It will
-monitor for incoming neutron change sets. Once it detects a new change
-set, it will utilize the existing lifecycle API tests. A non-gating vote
-(+1 or -1) will be provided with information (logs) based on the result.
-
-API Tests
----------
-
-The REST APIs are not planned to change as part of this. Existing APIs
-should be valid. All testing is planned within the functional testing
-system and via unit tests.
-
-Documentation Impact
-====================
-
-No documentation additions are anticipated. If the existing developer
-documentation is updated to reflect more hypervisor-specific items, this
-agent will follow suit.
 
 References
 ==========
@@ -213,6 +100,10 @@ References
 -  Ceilometer Architecture:
    http://docs.openstack.org/developer/ceilometer/architecture.html
 
+-  pypowervm: https://github.com/pypowervm/pypowervm
+
+-  NovaLink: http://www-01.ibm.com/common/ssi/cgi-bin/ssialias?infotype=AN&subtype=CA&htmlfid=897/ENUS215-262&appname=USN
+
 -  PowerVM REST API Initial Specification (may require a newer version
    as they become available): http://ibm.co/1lThV9R
 
@@ -221,4 +112,3 @@ References
 
 -  PowerVM Best Practices:
    http://www.redbooks.ibm.com/abstracts/sg248062.html?Open
-

doc/source/devref/development_environment.rst

@@ -40,6 +40,17 @@ Grab the code::
 Setting up your environment
 ---------------------------
 
-.. todo::
+The purpose of this project is to provide the 'glue' between OpenStack
+Telemetry (Ceilometer) and PowerVM.  The `pypowervm`_ project is used to
+control and monitor PowerVM systems.
 
-    Add in steps for environment setup
+It is recommended that you clone down the OpenStack Ceilometer project along
+with pypowervm into your respective development environment.
+
+Running the tox python targets for tests will automatically clone these down
+via the requirements.  When run with tox, it pulls the necessary requirements
+into a virtualenv.
+
+Additional project requirements may be found in the requirements.txt file.
+
+.. _pypowervm: https://github.com/pypowervm/pypowervm

doc/source/devref/usage.rst

@@ -16,6 +16,10 @@
 
 Usage
 =====
-- Install the ceilometer-powervm plugin on the compute server
+- Configure the PowerVM system for `NovaLink`_
+- Install the ceilometer-powervm plugin on the `NovaLink`_ VM on the PowerVM
+  Server.
 - Set the hypervisor_inspector in the ceilometer.conf to "powervm"
 - Start the ceilometer-agent-compute on the compute server
+
+.. _NovaLink: http://www-01.ibm.com/common/ssi/cgi-bin/ssialias?infotype=AN&subtype=CA&htmlfid=897/ENUS215-262&appname=USN

doc/source/index.rst

@@ -24,6 +24,16 @@ Documentation on Ceilometer can be found at the `Ceilometer documentation`_.
 
 .. _`Ceilometer documentation`: http://docs.openstack.org/developer/ceilometer
 
+Ceilometer-PowerVM Information and Configuration
+================================================
+
+Contents:
+
+.. toctree::
+    :maxdepth: 1
+
+    readme
+
 Ceilometer-PowerVM Policies
 ===========================
 

doc/source/readme.rst

@@ -0,0 +1 @@
+.. include:: ../../README.rst