Merge "Convert Cloud Admin Guide files to RST"

doc/admin-guide-cloud-rst/source/index.rst

@@ -17,6 +17,7 @@ Contents
 .. toctree::
    :maxdepth: 2
 
+   common/get_started_with_openstack.rst
    identity_management.rst
    dashboard.rst
    compute.rst
@@ -30,7 +31,6 @@ Contents
    common/glossary.rst
 
 .. TODO (DC)
-   Add get_started_with_openstack.rst and format the table :/
    Add preface.rst
    Add chapter files
 

doc/common-rst/get_started_block_storage.rst

@@ -0,0 +1,37 @@
+.. :orphan:
+
+OpenStack Block Storage
+-----------------------
+
+The OpenStack Block Storage service (cinder) adds persistent storage to
+a virtual machine. Block Storage provides an infrastructure for managing
+volumes, and interacts with OpenStack Compute to provide volumes for
+instances. The service also enables management of volume snapshots, and
+volume types.
+
+The Block Storage service consists of the following components:
+
+cinder-api
+  Accepts API requests, and routes them to the cinder-volume for
+  action.
+
+cinder-volume
+  Interacts directly with the Block Storage service, and processes
+  such as the cinder-scheduler. It also interacts with these processes
+  through a message queue. The cinder-volume service responds to read
+  and write requests sent to the Block Storage service to maintain
+  state. It can interact with a variety of storage providers through a
+  driver architecture.
+
+cinder-scheduler daemon
+  Selects the optimal storage provider node on which to create the
+  volume. A similar component to the nova-scheduler.
+
+cinder-backup daemon
+  The cinder-backup service provides backing up volumes of any type to
+  a backup storage provider. Like the cinder-volume service, it can
+  interact with a variety of storage providers through a driver
+  architecture.
+
+Messaging queue
+  Routes information between the Block Storage processes.

doc/common-rst/get_started_compute.rst

@@ -0,0 +1,145 @@
+.. :orphan:
+
+OpenStack Compute
+-----------------
+
+Use OpenStack Compute to host and manage cloud computing systems.
+OpenStack Compute is a major part of an Infrastructure-as-a-Service
+(IaaS) system. The main modules are implemented in Python.
+
+OpenStack Compute interacts with OpenStack Identity for authentication,
+OpenStack Image Service for disk and server images, and OpenStack
+dashboard for the user and administrative interface. Image access is
+limited by projects, and by users; quotas are limited per project (the
+number of instances, for example). OpenStack Compute can scale
+horizontally on standard hardware, and download images to launch
+instances.
+
+OpenStack Compute consists of the following areas and their components:
+
+``nova-api`` service
+  Accepts and responds to end user compute API calls. The service
+  supports the OpenStack Compute API, the Amazon EC2 API, and a
+  special Admin API for privileged users to perform administrative
+  actions. It enforces some policies and initiates most orchestration
+  activities, such as running an instance.
+
+``nova-api-metadata`` service
+  Accepts metadata requests from instances. The nova-api-metadata
+  service is generally used when you run in multi-host mode with
+  nova-network installations. For details, see `Metadata
+  service <http://docs.openstack.org/admin-guide-cloud/content/section_metadata-service.html>`__
+  in the OpenStack Cloud Administrator Guide.
+
+.. TODO Fix the link above when the file is converted.
+
+  On Debian systems, it is included in the nova-api package, and can
+  be selected through debconf.
+
+``nova-compute`` service
+  A worker daemon that creates and terminates virtual machine
+  instances through hypervisor APIs. For example:
+
+  - XenAPI for XenServer/XCP
+
+  - libvirt for KVM or QEMU
+
+  - VMwareAPI for VMware
+
+  Processing is fairly complex. Basically, the daemon accepts actions
+  from the queue and performs a series of system commands such as
+  launching a KVM instance and updating its state in the database.
+
+``nova-scheduler`` service
+  Takes a virtual machine instance request from the queue and
+  determines on which compute server host it runs.
+
+``nova-conductor`` module
+  Mediates interactions between the nova-compute service and the
+  database. It eliminates direct accesses to the cloud database made
+  by the nova-compute service. The nova-conductor module scales
+  horizontally. However, do not deploy it on nodes where the
+  nova-compute service runs. For more information, see `A new Nova
+  service:
+  nova-conductor <http://russellbryantnet.wordpress.com/2012/11/19/a-new-nova-service-nova-conductor/>`__.
+
+``nova-cert`` module
+  A server daemon that serves the Nova Cert service for X509
+  certificates. Used to generate certificates for
+  ``euca-bundle-image``. Only needed for the EC2 API.
+
+``nova-network worker`` daemon
+  Similar to the nova-compute service, accepts networking tasks from
+  the queue and manipulates the network. Performs tasks such as
+  setting up bridging interfaces or changing IPtables rules.
+
+``nova-consoleauth`` daemon
+  Authorizes tokens for users that console proxies provide. See
+  nova-novncproxy and nova-xvpvncproxy. This service must be running
+  for console proxies to work. You can run proxies of either type
+  against a single nova-consoleauth service in a cluster
+  configuration. For information, see `About
+  nova-consoleauth <http://docs.openstack.org/admin-guide-cloud/content/about-nova-consoleauth.html>`__.
+
+``nova-novncproxy`` daemon
+  Provides a proxy for accessing running instances through a VNC
+  connection. Supports browser-based novnc clients.
+
+``nova-spicehtml5proxy`` daemon
+  Provides a proxy for accessing running instances through a SPICE
+  connection. Supports browser-based HTML5 client.
+
+``nova-xvpvncproxy`` daemon
+  Provides a proxy for accessing running instances through a VNC
+  connection. Supports an OpenStack-specific Java client.
+
+``nova-cert`` daemon
+  x509 certificates.
+
+In Debian, a unique nova-consoleproxy package provides the
+nova-novncproxy, nova-spicehtml5proxy, and nova-xvpvncproxy packages. To
+select packages, edit the :file:`/etc/default/nova-consoleproxy` file or use
+the debconf interface. You can also manually edit the
+:file:`/etc/default/nova-consoleproxy` file, and stop and start the console
+daemons.
+
+nova-objectstore daemon
+  An S3 interface for registering images with the OpenStack Image
+  service. Used primarily for installations that must support
+  euca2ools. The euca2ools tools talk to nova-objectstore in *S3
+  language*, and nova-objectstore translates S3 requests into Image
+  service requests.
+
+euca2ools client
+  A set of command-line interpreter commands for managing cloud
+  resources. Although it is not an OpenStack module, you can configure
+  nova-api to support this EC2 interface. For more information, see
+  the `Eucalyptus 3.4
+  Documentation <https://www.eucalyptus.com/docs/eucalyptus/3.4/index.html>`__.
+
+nova client
+  Enables users to submit commands as a tenant administrator or end
+  user.
+
+The queue
+  A central hub for passing messages between daemons. Usually
+  implemented with `RabbitMQ <http://www.rabbitmq.com/>`__, but can be
+  implemented with an AMQP message queue, such as `Apache
+  Qpid <http://qpid.apache.org/>`__ or `Zero
+  MQ <http://www.zeromq.org/>`__.
+
+SQL database
+  Stores most build-time and run-time states for a cloud
+  infrastructure, including:
+
+  -  Available instance types
+
+  -  Instances in use
+
+  -  Available networks
+
+  -  Projects
+
+  Theoretically, OpenStack Compute can support any database that
+  SQL-Alchemy supports. Common databases are SQLite3 for test and
+  development work, MySQL, and PostgreSQL.

doc/common-rst/get_started_conceptual_architecture.rst

@@ -0,0 +1,10 @@
+.. :orphan:
+
+Conceptual architecture
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The following diagram shows the relationships among the OpenStack
+services:
+
+.. image:: figures/openstack_kilo_conceptual_arch.png
+   :alt: OpenStack conceptual architecture

doc/common-rst/get_started_dashboard.rst

@@ -0,0 +1,22 @@
+.. :orphan:
+
+OpenStack dashboard
+-------------------
+
+The OpenStack dashboard is a modular `Django web
+application <https://www.djangoproject.com/>`__ that provides a
+graphical interface to OpenStack services.
+
+.. image:: figures/horizon-screenshot.jpg
+
+The dashboard is usually deployed through
+`mod_wsgi <http://code.google.com/p/modwsgi/>`__ in Apache. You can
+modify the dashboard code to make it suitable for different sites.
+
+From a network architecture point of view, this service must be
+accessible to customers and the public API for each OpenStack service.
+To use the administrator functionality for other services, it must also
+connect to Admin API endpoints, which should not be accessible by
+customers.
+
+

doc/common-rst/get_started_database_service.rst

@@ -0,0 +1,63 @@
+.. :orphan:
+
+Database service overview
+-------------------------
+
+The Database service provides scalable and reliable cloud provisioning
+functionality for both relational and non-relational database engines.
+Users can quickly and easily use database features without the burden of
+handling complex administrative tasks. Cloud users and database
+administrators can provision and manage multiple database instances as
+needed.
+
+The Database service provides resource isolation at high performance
+levels, and automates complex administrative tasks such as deployment,
+configuration, patching, backups, restores, and monitoring.
+
+**Process flow example**
+
+This example is a high-level process flow for using Database services:
+
+#. The OpenStack Administrator configures the basic infrastructure using
+   the following steps:
+
+   #. Install the Database service.
+   #. Create an image for each type of database. For example, one for MySQL
+      and one for MongoDB.
+   #. Use the ``trove-manage`` command to import images and offer them to
+      tenants.
+
+#. The OpenStack end user deploys the Database service using the following
+   steps:
+
+   #. Create a Database service instance using the :command:`trove create`
+      command.
+   #. Use the :command:`trove list` command to get the ID of the instance,
+      followed by the :command:`trove show` command to get the IP address of
+      it.
+   #. Access the Database service instance using typical database access
+      commands. For example, with MySQL::
+
+         $ mysql -u myuser -p -h TROVE_IP_ADDRESS mydb
+
+The Database service includes the following components:
+
+``python-troveclient`` command-line client
+  A CLI that communicates with the ``trove-api`` component.
+
+``trove-api`` component
+  Provides an OpenStack-native RESTful API that supports JSON to
+  provision and manage Trove instances.
+
+``trove-conductor`` service
+  Runs on the host, and receives messages from guest instances that
+  want to update information on the host.
+
+``trove-taskmanager`` service
+  Instruments the complex system flows that support provisioning
+  instances, managing the lifecycle of instances, and performing
+  operations on instances.
+
+``trove-guestagent`` service
+  Runs within the guest instance. Manages and performs operations on
+  the database itself.

doc/common-rst/get_started_identity.rst

@@ -0,0 +1,87 @@
+.. :orphan:
+
+OpenStack Identity concepts
+---------------------------
+
+The OpenStack Identity service performs the following functions:
+
+- Tracking users and their permissions.
+
+- Providing a catalog of available services with their API endpoints.
+
+When installing OpenStack Identity service, you must register each
+service in your OpenStack installation. Identity service can then track
+which OpenStack services are installed, and where they are located on
+the network.
+
+To understand OpenStack Identity, you must understand the following
+concepts:
+
+User
+  Digital representation of a person, system, or service who uses
+  OpenStack cloud services. The Identity service validates that
+  incoming requests are made by the user who claims to be making the
+  call. Users have a login and may be assigned tokens to access
+  resources. Users can be directly assigned to a particular tenant and
+  behave as if they are contained in that tenant.
+
+Credentials
+  Data that confirms the user's identity. For example: user name and
+  password, user name and API key, or an authentication token provided
+  by the Identity Service.
+
+Authentication
+  The process of confirming the identity of a user. OpenStack Identity
+  confirms an incoming request by validating a set of credentials
+  supplied by the user.
+
+  These credentials are initially a user name and password, or a user
+  name and API key. When user credentials are validated, OpenStack
+  Identity issues an authentication token which the user provides in
+  subsequent requests.
+
+Token
+  An alpha-numeric string of text used to access OpenStack APIs and
+  resources. A token may be revoked at any time and is valid for a
+  finite duration.
+
+  While OpenStack Identity supports token-based authentication in this
+  release, the intention is to support additional protocols in the
+  future. Its main purpose is to be an integration service, and not
+  aspire to be a full-fledged identity store and management solution.
+
+Tenant
+  A container used to group or isolate resources. Tenants also group
+  or isolate identity objects. Depending on the service operator, a
+  tenant may map to a customer, account, organization, or project.
+
+Service
+  An OpenStack service, such as Compute (nova), Object Storage
+  (swift), or Image service (glance). It provides one or more
+  endpoints in which users can access resources and perform
+  operations.
+
+Endpoint
+  A network-accessible address where you access a service, usually a
+  URL address. If you are using an extension for templates, an
+  endpoint template can be created, which represents the templates of
+  all the consumable services that are available across the regions.
+
+Role
+  A personality with a defined set of user rights and privileges to
+  perform a specific set of operations.
+
+  In the Identity service, a token that is issued to a user includes
+  the list of roles. Services that are being called by that user
+  determine how they interpret the set of roles a user has and to
+  which operations or resources each role grants access.
+
+Keystone Client
+  A command line interface for the OpenStack Identity API. For
+  example, users can run the ``keystone service-create`` and
+  ``keystone endpoint-create`` commands to register services in their
+  OpenStack installations.
+
+The following diagram shows the OpenStack Identity process flow:
+
+.. image:: figures/SCH_5002_V00_NUAC-Keystone.png

doc/common-rst/get_started_image_service.rst

@@ -0,0 +1,40 @@
+.. :orphan:
+
+OpenStack Image Service
+-----------------------
+
+The OpenStack Image Service is central to Infrastructure-as-a-Service
+(IaaS) as shown in Conceptual architecture. It accepts API requests for disk
+or server images, and image metadata from end users or OpenStack Compute
+components. It also supports the storage of disk or server images on various
+repository types, including OpenStack Object Storage.
+
+.. TODO (DC) On line 7, add link to get_started_conceptual_architecture.rst
+
+A number of periodic processes run on the OpenStack Image Service to
+support caching. Replication services ensure consistency and
+availability through the cluster. Other periodic processes include
+auditors, updaters, and reapers.
+
+The OpenStack Image Service includes the following components:
+
+glance-api
+  Accepts Image API calls for image discovery, retrieval, and storage.
+
+glance-registry
+  Stores, processes, and retrieves metadata about images. Metadata
+  includes items such as size and type.
+
+  .. note::
+
+     The registry is a private internal service meant for use by
+     OpenStack Image Service. Do not disclose it to users.
+
+Database
+  Stores image metadata and you can choose your database depending on
+  your preference. Most deployments use MySQL or SQLite.
+
+Storage repository for image files
+  Various repository types are supported including normal file
+  systems, Object Storage, RADOS block devices, HTTP, and Amazon S3.
+  Note that some repositories will only support read-only usage.

doc/common-rst/get_started_logical_architecture.rst

@@ -0,0 +1,43 @@
+.. :orphan:
+
+Logical architecture
+~~~~~~~~~~~~~~~~~~~~
+
+To design, deploy, and configure OpenStack, administrators must
+understand the logical architecture.
+
+As shown in Conceptual architecture, OpenStack consists of several
+independent parts, named the OpenStack services. All services authenticate
+through a common Identity service. Individual services interact with each
+other through public APIs, except where privileged administrator commands
+are necessary.
+
+.. TODO (DC) Add link to figure in get_started_conceptual_architecture.rst
+
+Internally, OpenStack services are composed of several processes. All
+services have at least one API process, which listens for API requests,
+preprocesses them and passes them on to other parts of the service. With
+the exception of the Identity service, the actual work is done by
+distinct processes.
+
+For communication between the processes of one service, an AMQP message
+broker is used. The service's state is stored in a database. When
+deploying and configuring your OpenStack cloud, you can choose among
+several message broker and database solutions, such as RabbitMQ, Qpid,
+MySQL, MariaDB, and SQLite.
+
+Users can access OpenStack via the web-based user interface implemented
+by the OpenStack dashboard, via `command-line
+clients <http://docs.openstack.org/cli-reference/content>`__ and by
+issuing API requests through tools like browser plug-ins or :command:`curl`.
+For applications, `several SDKs <http://developer.openstack.org/#sdk>`__
+are available. Ultimately, all these access methods issue REST API calls
+to the various OpenStack services.
+
+.. TODO (DC) on line 30, Add link to get_started_openstack_dashboard.RST
+
+The following diagram shows the most common, but not the only possible,
+architecture for an OpenStack cloud:
+
+.. image:: figures/openstack-arch-kilo-logical-v1.png
+   :alt: Logical architecture

doc/common-rst/get_started_object_storage.rst

@@ -0,0 +1,34 @@
+.. :orphan:
+
+OpenStack Object Storage
+------------------------
+
+The OpenStack Object Storage is a multi-tenant object storage system. It
+is highly scalable and can manage large amounts of unstructured data at
+low cost through a RESTful HTTP API.
+
+It includes the following components:
+
+Proxy servers (swift-proxy-server)
+  Accepts OpenStack Object Storage API and raw HTTP requests to upload
+  files, modify metadata, and create containers. It also serves file
+  or container listings to web browsers. To improve performance, the
+  proxy server can use an optional cache that is usually deployed with
+  memcache.
+
+Account servers (swift-account-server)
+  Manages accounts defined with Object Storage.
+
+Container servers (swift-container-server)
+  Manages the mapping of containers or folders, within Object Storage.
+
+Object servers (swift-object-server)
+  Manages actual objects,such as files, on the storage nodes.
+
+Various periodic processes
+  Performs housekeeping tasks on the large data store. The replication
+  services ensure consistency and availability through the cluster.
+  Other periodic processes include auditors, updaters, and reapers.
+
+WSGI middleware
+  Handles authentication and is usually OpenStack Identity.

doc/common-rst/get_started_openstack_networking.rst

@@ -0,0 +1,34 @@
+.. :orphan:
+
+OpenStack Networking
+--------------------
+
+OpenStack Networking (neutron) allows you to create and attach interface
+devices managed by other OpenStack services to networks. Plug-ins can be
+implemented to accommodate different networking equipment and software,
+providing flexibility to OpenStack architecture and deployment.
+
+It includes the following components:
+
+neutron-server
+  Accepts and routes API requests to the appropriate OpenStack
+  Networking plug-in for action.
+
+OpenStack Networking plug-ins and agents
+  Plugs and unplugs ports, creates networks or subnets, and provides
+  IP addressing. These plug-ins and agents differ depending on the
+  vendor and technologies used in the particular cloud. OpenStack
+  Networking ships with plug-ins and agents for Cisco virtual and
+  physical switches, NEC OpenFlow products, Open vSwitch, Linux
+  bridging, and the VMware NSX product.
+
+  The common agents are L3 (layer 3), DHCP (dynamic host IP
+  addressing), and a plug-in agent.
+
+Messaging queue
+  Used by most OpenStack Networking installations to route information
+  between the neutron-server and various agents, as well as a database
+  to store networking state for particular plug-ins.
+
+OpenStack Networking mainly interacts with OpenStack Compute to provide
+networks and connectivity for its instances.

doc/common-rst/get_started_orchestration.rst

@@ -0,0 +1,35 @@
+.. :orphan:
+
+Orchestration module concepts
+-----------------------------
+
+The Orchestration module provides a template-based orchestration for
+describing a cloud application, by running OpenStack API calls to
+generate running cloud applications. The software integrates other core
+components of OpenStack into a one-file template system. The templates
+allow you to create most OpenStack resource types, such as instances,
+floating IPs, volumes, security groups and users. It also provides
+advanced functionality, such as instance high availability, instance
+auto-scaling, and nested stacks. This enables OpenStack core projects to
+receive a larger user base.
+
+The service enables deployers to integrate with the Orchestration module
+directly or through custom plug-ins.
+
+The Orchestration module consists of the following components:
+
+``heat`` command-line client
+  A CLI that communicates with the heat-api to run AWS CloudFormation
+  APIs. End developers can directly use the Orchestration REST API.
+
+``heat-api`` component
+  An OpenStack-native REST API that processes API requests by sending
+  them to the heat-engine over Remote Procedure Call (RPC).
+
+``heat-api-cfn`` component
+  An AWS Query API that is compatible with AWS CloudFormation. It
+  processes API requests by sending them to the heat-engine over RPC.
+
+``heat-engine``
+  Orchestrates the launching of templates and provides events back to
+  the API consumer.

doc/common-rst/get_started_sahara.rst

@@ -0,0 +1,41 @@
+.. :orphan:
+
+Data processing service
+-----------------------
+
+The Data processing service for OpenStack (sahara) aims to provide users
+with a simple means to provision data processing (Hadoop, Spark)
+clusters by specifying several parameters like Hadoop version, cluster
+topology, node hardware details and a few more. After a user fills in
+all the parameters, the Data processing service deploys the cluster in a
+few minutes. Sahara also provides a means to scale already provisioned
+clusters by adding/removing worker nodes on demand.
+
+The solution addresses the following use cases:
+
+- Fast provisioning of Hadoop clusters on OpenStack for development and
+  QA.
+
+- Utilization of unused compute power from general purpose OpenStack
+  IaaS cloud.
+
+- Analytics-as-a-Service for ad-hoc or bursty analytic workloads.
+
+Key features are:
+
+- Designed as an OpenStack component.
+
+- Managed through REST API with UI available as part of OpenStack
+  dashboard.
+
+- Support for different Hadoop distributions:
+
+  - Pluggable system of Hadoop installation engines.
+
+  - Integration with vendor specific management tools, such as Apache
+    Ambari or Cloudera Management Console.
+
+- Predefined templates of Hadoop configurations with the ability to
+  modify parameters.
+
+- User-friendly UI for ad-hoc analytics queries based on Hive or Pig.

doc/common-rst/get_started_storage_concepts.rst

@@ -0,0 +1,69 @@
+.. :orphan:
+
+Storage concepts
+----------------
+
+The OpenStack stack uses the following storage types:
+
+.. list-table:: Storage types
+   :header-rows: 1
+   :widths: 30 30 30
+
+   * - On-instance / ephemeral
+     - Block storage (cinder)
+     - Object Storage (swift)
+   * - Runs operating systems and provides scratch space
+     - Used for adding additional persistent storage to a virtual machine (VM)
+     - Used for storing virtual machine images and data
+   * - Persists until VM is terminated
+     - Persists until deleted
+     - Persists until deleted
+   * - Access associated with a VM
+     - Access associated with a VM
+     - Available from anywhere
+   * - Implemented as a filesystem underlying OpenStack Compute
+     - Mounted via OpenStack Block Storage controlled protocol (for example, iSCSI)
+     - REST API
+   * - Administrator configures size setting, based on flavors
+     - Sizings based on need
+     - Easily scalable for future growth
+   * - Example: 10 GB first disk, 30 GB/core second disk
+     - Example: 1 TB "extra hard drive"
+     - Example: 10s of TBs of data set storage
+
+.. note::
+
+   - *You cannot use OpenStack Object Storage like a traditional hard
+     drive.* The Object Storage relaxes some of the constraints of a
+     POSIX-style file system to get other gains. You can access the
+     objects through an API which uses HTTP. Subsequently you don't have
+     to provide atomic operations (that is, relying on eventual
+     consistency), you can scale a storage system easily and avoid a
+     central point of failure.
+
+   - *The OpenStack Image service is used to manage the virtual machine
+     images in an OpenStack cluster, not store them.* It provides an
+     abstraction to different methods for storage - a bridge to the
+     storage, not the storage itself.
+
+   - *The OpenStack Object Storage can function on its own.* The Object
+     Storage (swift) product can be used independently of the Compute
+     (nova) product.
+
+swift client
+  Enables users to submit commands to the REST API through a
+  command-line client authorized as either a admin user, reseller
+  user, or swift user.
+
+swift-init
+  Script that initializes the building of the ring file, takes daemon
+  names as parameter and offers commands. Documented in
+  http://docs.openstack.org/developer/swift/admin_guide.html#managing-services.
+
+swift-recon
+  A cli tool used to retrieve various metrics and telemetry information
+  about a cluster, that has been collected by the swift-recon middleware.
+
+swift-ring-builder
+  Storage ring build and rebalance utility. Documented in
+  http://docs.openstack.org/developer/swift/admin_guide.html#managing-the-rings.

doc/common-rst/get_started_telemetry.rst

@@ -0,0 +1,53 @@
+.. :orphan:
+
+Telemetry module
+----------------
+
+The Telemetry module performs 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.
+
+- Creates alarms when collected data breaks defined rules.
+
+The Telemetry module 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 alarm evaluator (``ceilometer-alarm-evaluator``)
+  Runs on one or more central management servers to determine when
+  alarms fire due to the associated statistic trend crossing a
+  threshold over a sliding time window.
+
+An alarm notifier (``ceilometer-alarm-notifier``)
+  Runs on one or more central management servers to allow alarms to be
+  set based on the threshold evaluation for a collection of samples.
+
+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.

doc/common-rst/get_started_with_openstack.rst

@@ -0,0 +1,148 @@
+:orphan:
+
+==========================
+Get started with OpenStack
+==========================
+
+The OpenStack project is an open source cloud computing platform for all
+types of clouds, which aims to be simple to implement, massively
+scalable, and feature rich. Developers and cloud computing technologists
+from around the world create the OpenStack project.
+
+OpenStack provides an Infrastructure-as-a-Service (IaaS) solution
+through a set of interrelated services. Each service offers an
+application programming interface (API) that facilitates this
+integration. Depending on your needs, you can install some or all
+services.
+
+The following table describes the OpenStack services that make up the
+OpenStack architecture:
+
+.. list-table:: OpenStack Services
+   :header-rows: 1
+   :widths: 10 10 40
+
+   * - Service
+     - Project name
+     - Description
+   * - `Dashboard <http://www.openstack.org/software/openstack-dashboard/>`__
+     - `Horizon <http://docs.openstack.org/developer/horizon/>`__
+     - Provides a web-based self-service portal to interact with underlying
+       OpenStack services, such as launching an instance, assigning IP
+       addresses and configuring access controls.
+   * - `Compute <http://www.openstack.org/software/openstack-compute/>`__
+     - `Nova <http://docs.openstack.org/developer/nova/>`__
+     - Manages the lifecycle of compute instances in an OpenStack environment.
+       Responsibilities include spawning, scheduling and decommissioning of
+       virtual machines on demand.
+   * - `Networking <http://www.openstack.org/software/openstack-networking/>`__
+     - `Neutron <http://docs.openstack.org/developer/neutron/>`__
+     - Enables Network-Connectivity-as-a-Service for other OpenStack services,
+       such as OpenStack Compute. Provides an API for users to define networks
+       and the attachments into them. Has a pluggable architecture that
+       supports many popular networking vendors and technologies.
+   * - `Object Storage <http://www.openstack.org/software/openstack-storage/>`__
+     - `Swift <http://docs.openstack.org/developer/swift/>`__
+     - Stores and retrieves arbitrary unstructured data objects via a RESTful,
+       HTTP based API. It is highly fault tolerant with its data replication
+       and scale-out architecture. Its implementation is not like a file server
+       with mountable directories. In this case, it writes objects and files to
+       multiple drives, ensuring the data is replicated across a server
+       cluster.
+   * - `Block Storage <http://www.openstack.org/software/openstack-storage/>`__
+     - `Cinder <http://docs.openstack.org/developer/cinder/>`__
+     - Provides persistent block storage to running instances. Its pluggable
+       driver architecture facilitates the creation and management of block
+       storage devices.
+   * - `Identity service <http://www.openstack.org/software/openstack-shared-services/>`__
+     - `Keystone <http://docs.openstack.org/developer/keystone/>`__
+     - Provides an authentication and authorization service for other
+       OpenStack services. Provides a catalog of endpoints for all
+       OpenStack services.
+   * - `Image service <http://www.openstack.org/software/openstack-shared-services/>`__
+     - `Glance <http://docs.openstack.org/developer/glance/>`__
+     - Stores and retrieves virtual machine disk images. OpenStack Compute
+       makes use of this during instance provisioning.
+   * - `Telemetry <http://www.openstack.org/software/openstack-shared-services/>`__
+     - `Ceilometer <http://docs.openstack.org/developer/ceilometer/>`__
+     - Monitors and meters the OpenStack cloud for billing, benchmarking,
+       scalability, and statistical purposes.
+   * - `Orchestration <http://www.openstack.org/software/openstack-shared-services/>`__
+     - `Heat <http://docs.openstack.org/developer/heat/>`__
+     - Orchestrates multiple composite cloud applications by using either the
+       native HOT template format or the AWS CloudFormation template format,
+       through both an OpenStack-native REST API and a
+       CloudFormation-compatible Query API.
+   * - `Database service <http://www.openstack.org/software/openstack-shared-services/>`__
+     - `Trove <http://docs.openstack.org/developer/trove/>`__
+     - Provides scalable and reliable Cloud Database-as-a-Service functionality
+       for both relational and non-relational database engines.
+   * - `Data processing service <http://www.openstack.org/software/openstack-shared-services/>`__
+     - `Sahara <http://docs.openstack.org/developer/sahara/>`__
+     - Provides capabilties to provision and scale Hadoop clusters in OpenStack
+       by specifying parameters like Hadoop version, cluster topology and nodes
+       hardware details.
+
+.. include:: get_started_conceptual_architecture.rst
+.. include:: get_started_logical_architecture.rst
+
+.. toctree::
+   :hidden:
+
+   get_started_conceptual_architecture.rst
+   get_started_logical_architecture.rst
+
+OpenStack services
+~~~~~~~~~~~~~~~~~~
+
+This section describes OpenStack services in detail.
+
+.. include:: get_started_compute.rst
+
+.. include:: get_started_storage_concepts.rst
+
+.. include:: get_started_object_storage.rst
+
+.. include:: get_started_block_storage.rst
+
+.. include:: get_started_openstack_networking.rst
+
+.. include:: get_started_dashboard.rst
+
+.. include:: get_started_identity.rst
+
+.. include:: get_started_image_service.rst
+
+.. include:: get_started_telemetry.rst
+
+.. include:: get_started_orchestration.rst
+
+.. include:: get_started_database_service.rst
+
+.. include:: get_started_sahara.rst
+
+.. toctree::
+   :hidden:
+
+   get_started_compute.rst
+   get_started_storage_concepts.rst
+   get_started_object_storage.rst
+   get_started_block_storage.rst
+   get_started_openstack_networking.rst
+   get_started_dashboard.rst
+   get_started_identity.rst
+   get_started_image_service.rst
+   get_started_telemetry.rst
+   get_started_orchestration.rst
+   get_started_database_service.rst
+   get_started_sahara.rst
+
+Feedback
+~~~~~~~~
+
+To provide feedback on documentation, join and use the
+openstack-docs@lists.openstack.org mailing list at `OpenStack
+Documentation Mailing
+List <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>`__,
+or `report a
+bug <https://bugs.launchpad.net/openstack-manuals/+filebug>`__.