diff --git a/doc/admin-guide-cloud-rst/source/index.rst b/doc/admin-guide-cloud-rst/source/index.rst index ee6cefb51a..8894ab9a82 100644 --- a/doc/admin-guide-cloud-rst/source/index.rst +++ b/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 @@ -29,7 +30,6 @@ Contents common/glossary.rst .. TODO (DC) - Add get_started_with_openstack.rst and format the table :/ Add preface.rst Add chapter files diff --git a/doc/common-rst/figures/SCH_5002_V00_NUAC-Keystone.png b/doc/common-rst/figures/SCH_5002_V00_NUAC-Keystone.png new file mode 100644 index 0000000000..88702402a7 Binary files /dev/null and b/doc/common-rst/figures/SCH_5002_V00_NUAC-Keystone.png differ diff --git a/doc/common-rst/figures/SCH_5002_V00_NUAC-Keystone.svg b/doc/common-rst/figures/SCH_5002_V00_NUAC-Keystone.svg new file mode 100644 index 0000000000..81fb3f91e6 --- /dev/null +++ b/doc/common-rst/figures/SCH_5002_V00_NUAC-Keystone.svg @@ -0,0 +1,2908 @@ + + + +image/svg+xmlSchéma RéseauSchéma RéseauVBackground-1SolidNone Status bar item.7KeystoneKeystone +Status bar item.19EndpointEndpoint +Status bar item.46ServiceService +Status bar itemUser/ APIUser/ API +Status bar item.89ServiceService +Status bar item.22User/ APIUser/ API +Status bar item.104User/ APIUser/ API +Status bar item.13KeystoneKeystone +Sheet.91Sheet.26Sheet.116Sheet.54Sheet.57The Temporary Token is provided along the requestThe Temporary Token is provided along the request +KeySheet.70Sheet.71Sheet.72Sheet.73Sheet.74Sheet.75ContactUser.50Add list item permissionsNetworkSheet.67Sheet.3Sheet.38Sheet.173- Keystone provides Alice with a list of services3. Keystone provides user with a list of services +Sheet.79Sheet.86Sheet.494- The service verifies Alice’s token4. The service verifies the user's token +Network.80Sheet.53Sheet.59The Keystone Identity ManagerThe Keystone Identity Manager +Sheet.515- Keystone provides extra info along with the token5. Keystone provides extra information and the token +ConfigureUser.95Sheet.11Sheet.68Sheet.69A Temporary Token is createdA Temporary Token is created +KeySheet.61Sheet.62Sheet.63Sheet.64Sheet.65Sheet.66Sheet.502- Alice requests all the tenants she has2. User requests all the tenants +Contact.102User.105Sheet.6Sheet.43Credentials are sentCredentials are sent +Sheet.94Sheet.21- Alice wants to launch an instance1. User wants to launch an instance +Contact.106Sheet.109Sheet.32Sheet.41Is the Token correct ?Is the Token correct ? +Sheet.25Search.33Sheet.31Sheet.76Sheet.35Sheet.24Does it allow that service usage ?Does it allow that service usage ? +Sheet.23Search.33Sheet.33Sheet.206- The service executes the request6. The service executes the request +Sheet.297- The service reports the status back to Alice7. The service reports the status back to the user +Sheet.30Sheet.44The instance is reachable hereThe instance is reachable here +Sheet.112Sheet.12Sheet.55Alice determines the correct endpoint to launch an instanceAlice determines the correct endpoint to launch an instance +LinkSheet.118Sheet.120Alice’s tenant is authorized to access the serviceAlice’s tenant is authorized to access the service +Sheet.117The token matches with the requestThe token matches with the request +Sheet.81Sheet.99A generic catalog is sentA generic catalog is sent +Sheet.78Sheet.52DocumentSheet.37Sheet.82Sheet.9Discussion.45Sheet.27Sheet.56The token is provided along the requestThe token is provided along the request +Sheet.48Sheet.83LockSheet.40Sheet.34The instance has been createdThe instance has been created +Sheet.39Sheet.85NewSheet.87Sheet.88That token belongs to the user AliceThat token belongs to the user Alice +Sheet.100Status bar item.96ServiceService +Sheet.98The service validates the request against its own policyThe service validates the request against its own policy +Sheet.101Sheet.110Sheet.111Keystone provides a list of services for the tenantKeystone sends a list of +available services +Sheet.128Sheet.124DocumentSheet.90Sheet.92The tenant token is providedThe tenant token is provided +Sheet.122Sheet.121LockNetwork.123Sheet.4Sheet.93The service creates a new instanceThe service creates a new instance +Sheet.129Sheet.130A list of tenants is sentA list of tenants is sent +Sheet.131Sheet.132DocumentSheet.134Sheet.135Sheet.136Credentials are sent with the desired tenantCredentials are sent +with desired tenant +Sheet.137Sheet.138Sheet.139Discussion.45 \ No newline at end of file diff --git a/doc/common-rst/figures/horizon-screenshot.jpg b/doc/common-rst/figures/horizon-screenshot.jpg new file mode 100644 index 0000000000..9c2ca84097 Binary files /dev/null and b/doc/common-rst/figures/horizon-screenshot.jpg differ diff --git a/doc/common-rst/figures/openstack-arch-kilo-logical-v1.png b/doc/common-rst/figures/openstack-arch-kilo-logical-v1.png new file mode 100644 index 0000000000..7da9d5e1e2 Binary files /dev/null and b/doc/common-rst/figures/openstack-arch-kilo-logical-v1.png differ diff --git a/doc/common-rst/figures/openstack-arch-kilo-logical-v1.svg b/doc/common-rst/figures/openstack-arch-kilo-logical-v1.svg new file mode 100644 index 0000000000..5ae21382ce --- /dev/null +++ b/doc/common-rst/figures/openstack-arch-kilo-logical-v1.svg @@ -0,0 +1,7246 @@ + + + OpenStack logical architecture + + + + image/svg+xml + + OpenStack logical architecture + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + I + + nternet + + + + + + + + + + + + + + + + + + + + + - CLI clients(nova, cinder, neutron and so on) - Cloud management tools - GUI tools + + + + + + + + + Horizon + + + + + + + + OpenStack Dashboard + + + + + + + HTTP(S) + + + + + + + + Instance + + + + + + + + + Guest agent + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + cinder-api + + + + + + + + + + Queue + + + + + + + + + + + cinder-volume + + + + + + + + + + + Cinder database + + + + + + + + + + + + Volume provider + + + + + + + + + + + scheduler + + + + + + + + + + OpenStack Block Storage + + + + + + + + + glance-api + + + + + + + + + + + Glance database + + + + + + + + + + glance- registry + + + + + + + + + + + + + + + + + + + OpenStack + + + Image service + + + + + + + + + + + + + + + + + + neutron- server + + + + + + + + + + Queue + + + + + + + + + + + Neutron database + + + + + + + + + OpenStack Networking + + + + + + + + + + + + + + + + + + Queue + + + + + + + + + + + + Trove Database + + + + + + + + + + + + OpenStack Database Service + + + + + + + + + swift-account- server + + + + + + + + + + swift-object- server + + + + + + + + + + swift-container- server + + + + + + + + + + swift-proxy- server + + + + + + + + + + + Account databas e + + + + + + + + + + + Object database + + + + + + + + + + + Container database + + + + + + + + + + + + + trove- api + + + + + + + + + + trove- taskmanager + + + + + + + + + + trove- conductor + + + + + + + + + + + + + neutron- l3-agent * + + + + + + + + + + neutron- dhcp-agent + + + + + + + + + + + + Neutron L2 agent * + + + + + + + + + + + on plugin * + + + + + + + + + + Neutron 3rd party plugin + + + + + + + + + + + + + + + + + + + + + + + + + keystone-all + + + + + + + + + + + + + + + + + + + + + + LDAP + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Queue + + + + + + + + + + + + Ironic Database + + + + + + + + + OpenStack + + + Bare Metal Service + + + + + + + + + ironic- api + + + + + + + + + + ironic- conductor + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + drivers + + + + + + + + + Openstack Object Storage + + + + + + + + + + + + + + + + + + Queue + + + + + + + + OpenStack + + + Orchestration + + + + + + + + + heat-api + + + + + + + + + + heat-engine + + + + + + + + + + + heat- api-cfn + + + + + + + + + + + + + + + + + + + + + + OpenStack Identity Service + + + + + + + + + + + + + + + + + + + + + + + OpenStack Telemetry + + + + + + + + + ceilometer -api + + + + + + + + + + + Queue + + + + + + + + + + ceilometer- agent-central + + + + + + + + + + ceilometer- agent-compute + + + + + + + + + + + + + ceilometer-agent- notification + + + + + + + + + + + + ceilometer database + + + + + + + + + + ceilometer- collector + + + + + + + + + + + + + ceilometer-alarm- evaluator + + + + + + + + + + + ceilometer-alarm- notifier + + + + + + + + + + + + Log or HTTP callback + + + + + + + + + + + nova-api + + + + + + + + + + Queue + + + + + + + + + + nova-scheduler + + + + + + + + + + + Nova database + + + + + + + + + + + + + + + + + + + + + + + + + nova-console + + + + + + + + + + + + + + + + + + + + + + nova-cert + + + + + + + + + + + + nova-compute + + + + + + + + + + Hypervisor + + + + + + + + + + OpenStack + + + Compute + + + + + + + + + + + + + + + + OpenStack + + + Data Processing + + + + + + + + + sahara-all + + + + + + + + + + + sahara database + + + + + + + + + + Queue + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Optional, depends + glancestore + cinder- + nova-conductor + nova-consoleauth + database + optional + diff --git a/doc/common-rst/figures/openstack_kilo_conceptual_arch.png b/doc/common-rst/figures/openstack_kilo_conceptual_arch.png new file mode 100644 index 0000000000..c76efbbec0 Binary files /dev/null and b/doc/common-rst/figures/openstack_kilo_conceptual_arch.png differ diff --git a/doc/common-rst/figures/openstack_kilo_conceptual_arch.svg b/doc/common-rst/figures/openstack_kilo_conceptual_arch.svg new file mode 100644 index 0000000000..a717c35dde --- /dev/null +++ b/doc/common-rst/figures/openstack_kilo_conceptual_arch.svg @@ -0,0 +1,2158 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Trove + + + + + + + + + + Sahara + + + + + + + + + + Heat + + + + + + + + + + Nova + + + + + + + + + + Glance + + + + + + + + + + Ironic + + + + + + + + + + Neutron + + + + + + + + + + + + + + + + + + + + + + + + + + + + Provision + + + + + + + + + + Provides PXE network for + + + + + + + + + + Provides volumes to + + + + + + + + + + Orchestration + + + + + + + + + + Boots data processing instances via + + + + + + + + + + Assigns jobs to + + + + + + + + + + Provision, operation and management + + + + + + + + + + Boots database instances via + + + + + + + + + + Backups databases in + + + + + + + + + + Orchestrates clusters via + + + + + + + + + + Saves data or job binary in + + + + + + + + + + Provision + + + + + + + + + + Fetchs images via + + + + + + + + + + + + Stores images in + + + + + + + + + + Registers guest images in + + + + + + + + + + Provides network connection for + + + + + + + + + + Registers hadoop images in + + + + + + + + + + Swift + + + + + + + + + + VMs + + + + + + + + + + + Backups volumes in + + + + + + + + + + Cinder + + + + + + + + + + Keystone + + + + + + + + + + Ceilometer + + + + + + + + + + Horizon + + + + + + + + + + + Monitor + + + + + + + + + + Provides auth + + + + + + + + + + Provides UI + + + + + + + + + + + + + + + + + Provides images + + + + diff --git a/doc/common-rst/get_started_block_storage.rst b/doc/common-rst/get_started_block_storage.rst new file mode 100644 index 0000000000..4430a85439 --- /dev/null +++ b/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. diff --git a/doc/common-rst/get_started_compute.rst b/doc/common-rst/get_started_compute.rst new file mode 100644 index 0000000000..02d59fcb5c --- /dev/null +++ b/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 `__ + 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 `__. + +``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 `__. + +``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 `__. + +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 `__, but can be + implemented with an AMQP message queue, such as `Apache + Qpid `__ or `Zero + MQ `__. + +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. diff --git a/doc/common-rst/get_started_conceptual_architecture.rst b/doc/common-rst/get_started_conceptual_architecture.rst new file mode 100644 index 0000000000..342b2e4338 --- /dev/null +++ b/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 diff --git a/doc/common-rst/get_started_dashboard.rst b/doc/common-rst/get_started_dashboard.rst new file mode 100644 index 0000000000..b01a239a77 --- /dev/null +++ b/doc/common-rst/get_started_dashboard.rst @@ -0,0 +1,22 @@ +.. :orphan: + +OpenStack dashboard +------------------- + +The OpenStack dashboard is a modular `Django web +application `__ that provides a +graphical interface to OpenStack services. + +.. image:: figures/horizon-screenshot.jpg + +The dashboard is usually deployed through +`mod_wsgi `__ 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. + + diff --git a/doc/common-rst/get_started_database_service.rst b/doc/common-rst/get_started_database_service.rst new file mode 100644 index 0000000000..6af38d53a2 --- /dev/null +++ b/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. diff --git a/doc/common-rst/get_started_identity.rst b/doc/common-rst/get_started_identity.rst new file mode 100644 index 0000000000..1a1761d284 --- /dev/null +++ b/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 diff --git a/doc/common-rst/get_started_image_service.rst b/doc/common-rst/get_started_image_service.rst new file mode 100644 index 0000000000..88909bfa91 --- /dev/null +++ b/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. diff --git a/doc/common-rst/get_started_logical_architecture.rst b/doc/common-rst/get_started_logical_architecture.rst new file mode 100644 index 0000000000..280bdbcff7 --- /dev/null +++ b/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 `__ and by +issuing API requests through tools like browser plug-ins or :command:`curl`. +For applications, `several SDKs `__ +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 diff --git a/doc/common-rst/get_started_object_storage.rst b/doc/common-rst/get_started_object_storage.rst new file mode 100644 index 0000000000..2fe4abff36 --- /dev/null +++ b/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. diff --git a/doc/common-rst/get_started_openstack_networking.rst b/doc/common-rst/get_started_openstack_networking.rst new file mode 100644 index 0000000000..19fbaec01c --- /dev/null +++ b/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. diff --git a/doc/common-rst/get_started_orchestration.rst b/doc/common-rst/get_started_orchestration.rst new file mode 100644 index 0000000000..7dc3d2aa12 --- /dev/null +++ b/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. diff --git a/doc/common-rst/get_started_sahara.rst b/doc/common-rst/get_started_sahara.rst new file mode 100644 index 0000000000..828f149f63 --- /dev/null +++ b/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. diff --git a/doc/common-rst/get_started_storage_concepts.rst b/doc/common-rst/get_started_storage_concepts.rst new file mode 100644 index 0000000000..faef91ddfa --- /dev/null +++ b/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. diff --git a/doc/common-rst/get_started_telemetry.rst b/doc/common-rst/get_started_telemetry.rst new file mode 100644 index 0000000000..81f52bf06f --- /dev/null +++ b/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. diff --git a/doc/common-rst/get_started_with_openstack.rst b/doc/common-rst/get_started_with_openstack.rst new file mode 100644 index 0000000000..c48cd128a1 --- /dev/null +++ b/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 `__ + - `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 `__ + - `Nova `__ + - Manages the lifecycle of compute instances in an OpenStack environment. + Responsibilities include spawning, scheduling and decommissioning of + virtual machines on demand. + * - `Networking `__ + - `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 `__ + - `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 `__ + - `Cinder `__ + - Provides persistent block storage to running instances. Its pluggable + driver architecture facilitates the creation and management of block + storage devices. + * - `Identity service `__ + - `Keystone `__ + - Provides an authentication and authorization service for other + OpenStack services. Provides a catalog of endpoints for all + OpenStack services. + * - `Image service `__ + - `Glance `__ + - Stores and retrieves virtual machine disk images. OpenStack Compute + makes use of this during instance provisioning. + * - `Telemetry `__ + - `Ceilometer `__ + - Monitors and meters the OpenStack cloud for billing, benchmarking, + scalability, and statistical purposes. + * - `Orchestration `__ + - `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 `__ + - `Trove `__ + - Provides scalable and reliable Cloud Database-as-a-Service functionality + for both relational and non-relational database engines. + * - `Data processing service `__ + - `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 `__, +or `report a +bug `__.