From 9b25f3f8a560f971891a5cfb7c6e98f9ce54550d Mon Sep 17 00:00:00 2001 From: Dina Belova Date: Tue, 25 Feb 2014 13:35:55 +0400 Subject: [PATCH] Start moving Climate docs from wiki to Sphinx docs * add common introduction and architecture information * create more appropriate structure for REST API docs Change-Id: I27b95aa76814f5d6bf6737c56594c7e5ba9d667c Partially implements: blueprint climate-docs --- doc/source/architecture.rst | 70 ++++++++++++++ doc/source/images/climate-architecture.png | Bin 0 -> 18674 bytes doc/source/index.rst | 15 ++- doc/source/introduction.rst | 105 +++++++++++++++++++++ doc/source/restapi/index.rst | 9 ++ doc/source/{ => restapi}/rest_api_v1.0.rst | 0 6 files changed, 198 insertions(+), 1 deletion(-) create mode 100644 doc/source/architecture.rst create mode 100644 doc/source/images/climate-architecture.png create mode 100644 doc/source/introduction.rst create mode 100644 doc/source/restapi/index.rst rename doc/source/{ => restapi}/rest_api_v1.0.rst (100%) diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst new file mode 100644 index 00000000..55c76d92 --- /dev/null +++ b/doc/source/architecture.rst @@ -0,0 +1,70 @@ +Climate architecture +==================== + +Climate design can be described by following diagram: + +.. image:: images/climate-architecture.png + :width: 700 px + :scale: 99 % + :align: left + +**climate-client** - provides the opportunity to communicate with Climate via +*REST API* (climate-api service). + +**climate-api** - waits for the REST calls from the outside world to redirect +them to the manager. climate-api communicates with climate-manager via RPC. +Runs as a separated process. + +**climate-manager** - implements all logic and operations with leases, +reservations and events. Communicates with Climate DB and stores there data +structure of connected leases, reservations (both physical and virtual) and +events. climate-manager service is responsible for running events created for +lease and process all actions that should be done this moment. Manager uses +resource-plugins to work with concrete resources (instances, volumes, compute +hosts). climate-manager uses Keystone trusts to commit actions on behalf of +user who has created lease before. + +**resource-plugin** - responsible for exact actions to do with reserved +resources (VMs, volumes, etc.) When working knows only about resource ID and +token to use. All resource plugins work in the same process as climate-manager. + +Virtual instance reservation +---------------------------- + +Virtual instance reservation mostly looks like usual instance booting for user +- he/she only passes special hints to Nova containing information about future +lease - lease start and end dates, its name, etc. Special Nova API extensions +parse these parameter and use them to call Climate, passing to it ID of just +created instance. If there is a need to reserve all instances in cloud (like in +developer labs to automate process of resource reclaiming), default reservation +extension might be used. By default it starts lease at the moment of request +and gives it one month of lifetime. + +During the time lease has not started yet, instance will be shelved. + +Compute host reservation +------------------------ + +Now process of compute hosts reserving contains two steps: + +* admin marks hosts from common pool as possible to be reserved. That is + implemented by moving these hosts to special aggregate; +* user asks for reserving of host with specified characteristics like: + + * the region + * the availability zone + * the host capabilities extra specs (scoped and non-scoped format is + accepted) + * the number of CPU cores + * the amount of free RAM + * the amount of free disk space + * the number of hosts + +Technically speaking, resource ID here will be not host ID, because there might +be many of them wanted. Resource here will be new aggregate containing reserved +hosts. The time lease starts, user may use reserved compute capacity to run +his/her instances on it passing special scheduler hint to Nova. When host is +reserved, it’s not used for usual instance running, it might be used only when +lease starts and only by passing reservation ID to Nova. That is implemented +using special Nova Scheduler filter, that passes reservation ID to Climate and +checks if user really can use reserved compute capacity. \ No newline at end of file diff --git a/doc/source/images/climate-architecture.png b/doc/source/images/climate-architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..981f7ff3d491df2e2e5e0e5c6738533d6a1998af GIT binary patch literal 18674 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 + User guide ---------- + +**APIs** + .. toctree:: :maxdepth: 1 - rest_api_v1.0 + restapi/index diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst new file mode 100644 index 00000000..f165986b --- /dev/null +++ b/doc/source/introduction.rst @@ -0,0 +1,105 @@ +Introduction +============ + +Idea of creating Climate originated with two different use cases: + +* Compute host reservation (when user with admin privileges can reserve + hardware resources that are dedicated to the sole use of a tenant) +* Virtual machine (instance) reservation (when user may ask reservation service + to provide him working VM not necessary now, but also in the future) + +Now these ideas have been transformed to more general view: with Climate user +can request the resources of cloud environment to be provided (“leased”) to his +project for specific amount on time, immediately or in future. + +Both virtual (Instances, Volumes, Networks) and hardware (full hosts with +specific characteristics of RAM, CPU and etc) resources can be allocated via +“lease”. + +In terms of benefits added, Resource Reservation Service will: + +* improve visibility of cloud resources consumption (current and planned for + future); +* enable cloud resource planning based on current and future demand from end + users; +* automate the processes of resource allocation and reclaiming; +* provide energy efficiency for physical hosts (both compute and storage ones); +* potentially provide leases as billable items for which customers can be + charged a flat fee or a premium price depending on amount of reserved cloud + resources and their usage. + +Glossary of terms +----------------- + +**Reservation** is an allocation of certain cloud resource (Nova instance, Cinder +volume, compute host, etc.) to particular project. Speaking about virtual +reservations, we may have not only simple, solid ones (like already mentioned +instances and volumes), but also complex ones - like Heat stacks and Savanna +clusters. Reservation is characterized by status, resource type and identifier +and lease it belongs to. + +**Lease** is a negotiation agreement between the provider (Climate, using OpenStack +resources) and the consumer (user) where the former agrees to make some kind of +resources (both virtual and physical) available to latter, based on a set of +lease terms presented by the consumer. Here lease may be described as contract +between user and reservation service about cloud resources to be provided right +now or later. Technically speaking, lease is a group of reservations granted to +particular project upon request. Lease is characterized by start time, end +time, set of individual reservations and associated events. + +**Event** is simply something that may happen to lease. In most simple case event +might describe lease start and lease end. Also it might be notification to user +(e.g. about soon lease expiration) and some extra actions. + +Rationale +--------- + +Climate is created to: + +* manage cloud resources not only right now, but also in the future; +* have dedicated recourses on certain amount of time; +* prepare for the peak loads and perform capacity planning; +* optimise energy consumption. + +Lease types (concepts) +---------------------- + +* **Immediate reservation**. Resources are provisioned immediately (like VM + boot or moving host to reserved user aggregate) or not at all. If request can + be fulfilled, lease is created and **success** status is returned. Lease + should be marked as **active** or **to_be_started**. Otherwise (if + request resource cannot be provisioned right now) failure status for this + request should be returned. +* **Reservation with retries**. Mostly looks like previous variant, but in case + of failure, user may want to have several (configurable number) retries to + process lease creation action. In this case request will be processed till + that will be possible to create lease but not more than set in configuration + file number of times. +* **Best-effort reservation**. Also might have place if lease creation request + cannot be fulfilled immediately. Best-effort mechanism starts something like + scavenger hunt trying to find resources for reservations. For compute hosts + reservation that makes much sense, because in case there are instances + belonging to other tenant on eligible hosts, and without them there will be + possible to reserve these hosts, Climate may start instances migration. + This operation can be timely and fairly complex and so different strategies + may be applied depending on heuristic factors such as the number, type and + state of the instances to be migrated. Also Climate should assert that there + are at least enough potential candidates for the migration prior to starting + the actual migration. If Climate decides to start migration, it returns + **success** state and marks lease as **in_progress**, otherwise - + **failure**. If this 'hunting' ends successfully before configurable + timeout has passed, lease should be marked as **active**, otherwise its + status is set to **timedout**. +* **Delayed resource acquiring** or **scheduled reservation**. In this + reservation type lease is created successfully if Climate thinks there will + be enough resources to process provisioning later (otherwise this request + returns **failure** status). Lease is marked as **inactive** till all + resources will be actually provisioned. That works pretty nice and + predictable speaking about compute hosts reservation (because hosts as + resources are got not from common cloud pool, but from admin defined pool). + So Climate is possible to predict these physical resources usage and use that + information during lease creation. If we speak about virtual reservations, + here situation is more complicated, because all resources are got from common + cloud resources pool, and Climate cannot guarantee there will be enough + resources to provision them. In this failure case lease state will be marked + as **error** with appropriate explanation. \ No newline at end of file diff --git a/doc/source/restapi/index.rst b/doc/source/restapi/index.rst new file mode 100644 index 00000000..5071bcc0 --- /dev/null +++ b/doc/source/restapi/index.rst @@ -0,0 +1,9 @@ +Climate REST API docs +********************* + +This page includes documentation for Climate APIs. + +.. toctree:: + :maxdepth: 1 + + rest_api_v1.0 diff --git a/doc/source/rest_api_v1.0.rst b/doc/source/restapi/rest_api_v1.0.rst similarity index 100% rename from doc/source/rest_api_v1.0.rst rename to doc/source/restapi/rest_api_v1.0.rst