openstack/senlin
Code Issues Proposed changes

Rework senlin docs based on CLI changes

Browse Source 
This patch reworks the senlin documentation to reflect recent changes to
the senlinclient where the senlin command line is completely dropped.

Change-Id: Ia30d67935281695cc94205942df1ca2b3df6feae
This commit is contained in:
tengqm
2016-03-25 03:07:54 -04:00
parent c7ca07eb5d
commit a482de0f87
18 changed files with 407 additions and 413 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
doc/source/developer/authorization.rst
View File

@@ -63,11 +63,10 @@ There are several ways to raise a service request to the Senlin API, each of
which has its own characteristics that will affect the way authentication
and/or authorization is performed.
1) Users interact with Senlin service API using the Senlin client (i.e. the
`python-senlinclient` package) which includes a command line interface (CLI)
named `senlin`. The requests, after being preprocessed by the OpenStack SDK
will contain a valid Keystone token that can be validated by the
`auth_token` WSGI middleware.
1) Users interact with Senlin service API using the OpenStack client (i.e. the
plugin provided by the `python-senlinclient` package). The requests, after
being preprocessed by the OpenStack SDK will contain a valid Keystone token
that can be validated by the `auth_token` WSGI middleware.
2) Users interact with Senlin service API directly by making HTTP requests
where the requester's credentials have been validated by Keystone so the
requests will carry a valid Keystone token for verification by the

3
doc/source/developer/policies/load_balance_v1.rst
View File

@@ -77,7 +77,8 @@ load-balancer. The map may contain values for keys like "``type``",
"``delay``", "``max_retries``", "``http_method``" etc.
For more details specifications of the policy specifications, you can use the
command :command:`senlin policy-type-show senlin.policy.loadbalance-1.0`.
:command:`opentack cluster policy type show senlin.policy.loadbalance-1.0`
command.
Load Balancer Management

4
doc/source/developer/policy_type.rst
View File

@@ -254,5 +254,5 @@ by a restart of the ``senlin-engine`` process.
$ sudo pip install -e .
Now, when you do a ``senlin policy-type-list``, you will see your policy
type listed along with other existing policy types.
Now, when you do a :command:`openstack cluster policy type list`, you will see
your policy type listed along with other existing policy types.

4
doc/source/developer/profile_type.rst
View File

@@ -232,5 +232,5 @@ a restart of the ``senlin-engine`` process.
$ sudo pip install -e .
Now, when you do a ``senlin profile-type-list``, you will see your profile
type listed along with other existing profile types.
Now, when you do a :command:`openstack cluster profile type list`, you will
see your profile type listed along with other existing profile types.

2
doc/source/developer/testing.rst
View File

@@ -85,4 +85,4 @@ running single tests by providing a regex::
A more convenient way to run specific test is to name the unit test directly,
as shown below::
$ python -m testtools.run senlin.tests.db.test_cluster_api
$ python -m testtools.run senlin.tests.unit.db.test_cluster_api

8
doc/source/install.rst
View File

@@ -156,12 +156,14 @@ Install Senlin Client
Verify Your Installation
------------------------
To check whether Senlin Server is successfully installed, run command 'senlin build-info'
in a console. The installation is successful if the command output looks similar to the following.
To check whether Senlin server and Senlin client have been installed
successfully, run command ``openstack cluster build info`` in a console.
The installation is successful if the command output looks similar to the
following.
::
$ senlin build-info
$ openstack cluster build info
+----------+---------------------+
| Property | Value |
+----------+---------------------+

7
doc/source/overview.rst
View File

@@ -46,10 +46,11 @@ The developers are focusing on creating an OpenStack style project using
OpenStack design tenets, implemented in Python. We have started with a close
interaction with Heat project.
senlin
------
senlinclient
------------
The :program:`senlin` tool is a command line interface that communicates with
The :program:`senlinclient` package provides a plugin for the openstackclient
tool so you have a command line interface to communicate with
the :program:`senlin-api` to manage clusters, nodes, profiles, policies,
actions and events. End developers could also use the Senlin REST API directly.

52
doc/source/user/actions.rst
View File

@@ -56,7 +56,7 @@ Listing Actions
The following command shows the actions known by the Senlin engine::
$ senlin action-list
$ openstack cluster action list
+----------+-------------------------+----------------+-----------+----------+------------+-------------+
| id | name | action | status | target | depends_on | depended_by |
+----------+-------------------------+----------------+-----------+----------+------------+-------------+
@@ -72,24 +72,23 @@ The following command shows the actions known by the Senlin engine::
| e973552e | node_create_b716052d | NODE_CREATE | SUCCEEDED | b716052d | | |
+----------+-------------------------+----------------+-----------+----------+------------+-------------+
The :program:`senlin` command line supports various options when listing the
actions.
The :program:`openstack cluster` command line supports various options when
listing the actions.
Sorting the List
----------------
You can specify the sorting keys and sorting direction when list actions,
using the option :option:`--sort` (or :option:`-o`). The :option:`--sort`
option accepts a string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``,
where the keys used are action properties and the dirs can be one of ``asc``
and ``desc``. When omitted, Senlin sorts a given key using ``asc`` as the
default direction.
using the option :option:`--sort`. The :option:`--sort` option accepts a
string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``, where the keys used
are action properties and the dirs can be one of ``asc`` and ``desc``. When
omitted, Senlin sorts a given key using ``asc`` as the default direction.
For example, the following command instructs the :program:`senlin` command
line to sort actions using the ``name`` property in descending order::
For example, the following command instructs the :program:`openstack cluster`
command to sort actions using the ``name`` property in descending order::
$ senlin action-list -o name:desc
$ openstack cluster action list --sort name:desc
When sorting the list of actions, you can use one of ``name``, ``target``,
``action``, ``created_at`` and ``status``.
@@ -98,11 +97,10 @@ When sorting the list of actions, you can use one of ``name``, ``target``,
Filtering the List
------------------
You can filter the list of actions using the :option:`--filters`` (or
:option:`-f`). For example, the following command filters the action list by
the ``action`` property::
You can filter the list of actions using the :option:`--filters``. For example,
the following command filters the action list by the ``action`` property::
$ senlin action-list -f action=CLUSTER_SCALE_OUT
$ openstack cluster action list --filters action=CLUSTER_SCALE_OUT
The option :option:`--filters` accepts a list of key-value pairs separated by
semicolon (``;``), where each pair is expected to be of format ``key=val``.
@@ -115,17 +113,17 @@ Paginating the Query results
In case you have a huge collection of actions (which is highly likely the
case), you can limit the number of actions returned using the option
:option:`--limit <LIMIT>` (or :option:`--l <LIMIT>`). For example::
:option:`--limit <LIMIT>`. For example::
$ senlin action-list -l 1
$ openstack cluster action list --limit 1
Another option you can specify is the ID of an action after which you want to
see the returned list starts. In other words, you don't want to see those
actions with IDs that is or come before the one you specify. You can use the
option :option:`--marker <ID>` (or :option:`-m <ID>`) for this purpose. For
example::
option :option:`--marker <ID>` for this purpose. For example::
$ senlin action-list -l 1 -m 2959122e-11c7-4e82-b12f-f49dc5dac270
$ openstack cluster action list --limit 1 \
--marker 2959122e-11c7-4e82-b12f-f49dc5dac270
Only 1 action record is returned in this example and its UUID comes after the
the one specified from the command line.
@@ -134,16 +132,16 @@ the one specified from the command line.
Showing Details of an Action
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use the :program:`senlin` command line to show the details about an
action you are interested in. When specifying the identity of the action, you
can use its name, its ID or its "short ID" . Senlin API and engine will verify
if the identifier you specified can uniquely identify an action. An error
message will be returned if there is no action matching the identifier or if
more than one action matching it.
You can use the :program:`openstack cluster` command to show the details about
an action you are interested in. When specifying the identity of the action,
you can use its name, its ID or its "short ID" . Senlin API and engine will
verify if the identifier you specified can uniquely identify an action. An
error message will be returned if there is no action matching the identifier
or if more than one action matching it.
An example is shown below::
$ senlin action-show 8fac487f
$ openstack cluster action show 8fac487f
+---------------+--------------------------------------+
| Property | Value |
+---------------+--------------------------------------+

76
doc/source/user/bindings.rst
View File

@@ -32,31 +32,29 @@ disable it or update some properties of the policy object.
Listing Policies Attached to a Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :program:`senlin` tool provides the :command:`cluster-policy-list` command
to list policy objects that are attached to a cluster. You can provide the
name, the ID or the "short ID" of a cluster as the identifier to reference a
cluster. For example, the command below lists the policies attached to the
cluster ``webservers``::
The :program:`openstack cluster` command provides a sub-command
:command:`policy binding list` to list policy objects that are attached to a
cluster. You can provide the name, the ID or the "short ID" of a cluster as
the identifier to reference a cluster. For example, the command below lists
the policies attached to the cluster ``webservers``::
$ senlin cluster-policy-list webservers
$ openstack cluster policy binding list webservers
Sorting the List
----------------
You can specify the sorting keys and sorting direction when list cluster
policies, using the option :option:`--sort` (or :option:`-o`). The
:option:`--sort` option accepts a string of format
``key1[:dir1],key2[:dir2],key3[:dir3]``, where the keys used are properties
of the policy bound to a cluster and the dirs can be one of ``asc`` and
``desc``. When omitted, Senlin sorts a given key using ``asc`` as the default
direction.
policies, using the option :option:`--sort`. The :option:`--sort` option
accepts a string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``, where the
keys used are properties of the policy bound to a cluster and the dirs can be
one of ``asc`` and ``desc``. When omitted, Senlin sorts a given key using
``asc`` as the default direction.
For example, the following command instructs the :program:`senlin` command
line to sort policy bindings using the ``enabled`` property in descending
order::
For example, the following command line sorts the policy bindings using the
``enabled`` property in descending order::
$ senlin cluster-policy-list -o enabled:desc
$ openstack cluster policy binding list --sort enabled:desc
When sorting the list of policies, ``enabled`` is the only key you can specify
for sorting.
@@ -65,12 +63,12 @@ for sorting.
Filtering the List
------------------
The :program:`senlin` command line also provides options for filtering the
policy list at the server side. The option :option:`--filters` (or
:option:`-f`) can be used for this purpose. For example, the following command
filters clusters by the ``enabled`` field::
The :program:`openstack cluster` command also supports options for filtering
the policy list at the server side. The option :option:`--filters` can be used
for this purpose. For example, the following command filters clusters by the
``enabled`` field::
$ senlin cluster-policy-list -f enabled=True c3
$ openstack cluster policy binding list --filters enabled=True c3
+-----------+--------+-----------------------+---------+
| policy_id | policy | type | enabled |
+-----------+--------+-----------------------+---------+
@@ -89,18 +87,18 @@ Attaching a Policy to a Cluster
Senlin permits policy objects to be attached to clusters and to be detached
from clusters dynamically. When attaching a policy object to a cluster, you
can customize the policy properties for the particular cluster. For example,
you can specify whether the policy should be enabled once attached.
you can specify whether the policy should be enabled once attached.
The following options are supported for the :command:`cluster-policy-attach`
command:
The following options are supported for the command
:command:`openstack cluster policy attach`:
- :option:`--enabled` (or :option:`-e`): a boolean indicating whether the
policy to be enabled once attached.
- :option:`--enabled`: a boolean indicating whether the policy to be enabled
once attached.
For example, the following command attaches a policy named ``up01`` to the
cluster ``c3``, with its enabled status set to ``True``::
$ senlin cluster-policy-attach -e -p up01 c3
$ openstack cluster policy attach --enabled --policy up01 c3
Note that most of the time, Senlin doesn't more than one policy of the same
type to be attached to the same cluster. This restriction is relaxed for some
@@ -118,10 +116,11 @@ Showing Policy Properties on a Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To examine the detailed properties of a policy object that has been attached
to a cluster, you can use the command :command:`cluster-policy-show` with the
policy identifier and the cluster identifier specified. For example::
to a cluster, you can use the :command:`openstack cluster policy binding show`
command with the policy identifier and the cluster identifier specified. For
example::
$ senlin cluster-policy-show -p dp01 c3
$ openstack cluster policy binding show --policy dp01 c3
+--------------+--------------------------------------+
| Property | Value |
+--------------+--------------------------------------+
@@ -141,12 +140,15 @@ Updating Policy Properties on a Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once a policy is attached to a cluster, you can request its property on this
cluster be changed by using the command :command:`cluster-policy-update`. At
this stage, you can specify the ``enabled`` property to be updated.
cluster be changed by using the command
:command:`openstack cluster policy binding update`. Presently, you can only
specify the ``enabled`` property to be updated.
For example, the following command disables a policy on the specified cluster::
$ senlin cluster-policy-update -e False -p dp01 mycluster
$ openstack cluster policy binding update \
--enabled False --policy dp01 \
mycluster
The Senlin engine will perform validation of the arguments in the same way as
that for the policy attach operation. You can use the name, the ID or the
@@ -158,10 +160,10 @@ Detach a Policy from a Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Finally, to remove the binding between a specified policy object from a
cluster, you can use the :command:`cluster-policy-detach` command as shown
below::
cluster, you can use the :command:`openstack cluster policy detach` command as
shown below::
$ senlin cluster-policy-detach -p dp01 mycluster
$ openstack cluster policy detach --policy dp01 mycluster
This command will detach the specified policy from the specified cluster.
You will use the option :option:`--policy` (or `-p`) to specify the policy.
You will use the option :option:`--policy` to specify the policy.

191
doc/source/user/clusters.rst
View File

@@ -37,7 +37,7 @@ Listing Clusters
The following command shows the clusters managed by the Senlin service::
$ senlin cluster-list
$ openstack cluster list
+----------+------+--------+---------------------+
| id | name | status | created_at |
+----------+------+--------+---------------------+
@@ -48,10 +48,9 @@ The following command shows the clusters managed by the Senlin service::
Note that the first column in the output table is a *short ID* of a cluster
object. Senlin command line use short IDs to save real estate on screen so
that more useful information can be shown on a single line. To show the *full
ID* in the list, you can add the :option:`-F` (or :option:`--full-id`) option
to the command::
ID* in the list, you can add the :option:`--full-id` option to the command::
$ senlin cluster-list -F
$ openstack cluster list --full-id
+--------------------+------+--------+---------------------+------------+
| id | name | status | created_at | updated_at |
+--------------------+------+--------+---------------------+------------+
@@ -64,16 +63,15 @@ Sorting the List
----------------
You can specify the sorting keys and sorting direction when list clusters,
using the option :option:`--sort` (or :option:`-o`). The :option:`--sort`
option accepts a string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``,
where the keys used are cluster properties and the dirs can be one of ``asc``
and ``desc``. When omitted, Senlin sorts a given key using ``asc`` as the
default direction.
using the option :option:`--sort`. The :option:`--sort` option accepts a
string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``, where the keys used
are cluster properties and the dirs can be one of ``asc`` and ``desc``. When
omitted, Senlin sorts a given key using ``asc`` as the default direction.
For example, the following command instructs the :program:`senlin` command
line to sort clusters using the ``name`` property in descending order::
For example, the following command sorts the clusters using the ``name``
property in descending order::
$ senlin cluster-list -o name:desc
$ openstack cluster list --sort name:desc
When sorting the list of clusters, you can use one of ``name``, ``status``,
``init_at``, ``created_at`` and ``updated_at``.
@@ -82,12 +80,12 @@ When sorting the list of clusters, you can use one of ``name``, ``status``,
Filtering the List
------------------
The :program:`senlin` command line also provides options for filtering the
cluster list at the server side. The option :option:`--filters` (or
:option:`-f`) can be used for this purpose. For example, the following command
filters clusters by the ``status`` field::
The :program:`openstack cluster list` command also provides options for
filtering the cluster list at the server side. The option :option:`--filters`
can be used for this purpose. For example, the following command filters the
clusters by the ``status`` field::
$ senlin cluster-list -f status=ACTIVE
$ openstack cluster list --filters status=ACTIVE
+----------+------+--------+---------------------+
| id | name | status | created_at |
+----------+------+--------+---------------------+
@@ -106,9 +104,9 @@ Paginating the Query Results
In case you have a huge collection of clusters, you can limit the number of
clusters returned from Senlin server each time, using the option
:option:`--limit <LIMIT>` (or :option:`--l <LIMIT>`). For example::
:option:`--limit <LIMIT>`. For example::
$ senlin cluster-list -l 1
$ openstack cluster list --limit 1
+----------+------+--------+---------------------+
| id | name | status | created_at |
+----------+------+--------+---------------------+
@@ -118,10 +116,10 @@ clusters returned from Senlin server each time, using the option
Another option you can specify is the ID of a cluster after which you want to
see the returned list starts. In other words, you don't want to see those
clusters with IDs that is or come before the one you specify. You can use the
option :option:`--marker <ID>` (or :option:`-m <ID>`) for this purpose. For
example::
option :option:`--marker <ID>` for this purpose. For example::
$ senlin cluster-list -l 1 -m 2959122e-11c7-4e82-b12f-f49dc5dac270
$ openstack cluster list --limit 1 \
--marker 2959122e-11c7-4e82-b12f-f49dc5dac270
+----------+------+--------+---------------------+
| id | name | status | created_at |
+----------+------+--------+---------------------+
@@ -138,7 +136,7 @@ Creating a Cluster
To create a cluster, you need to provide the ID or name of the profile to be
associated with the cluster. For example::
$ senlin cluster-create --profile qstack c3
$ openstack cluster create --profile qstack c3
+------------------+--------------------------------------+
| Property | Value |
+------------------+--------------------------------------+
@@ -164,10 +162,10 @@ associated with the cluster. For example::
From the output you can see that a new cluster object created and put to
``INIT`` status. Senlin will verify if profile specified using the option
:option:`--profile <PROFILE>` (or :option:`-p <PROFILE>`) does exist. The
server allows the ``<PROFILE>`` value to be a profile name, a profile ID or
the short ID of a profile object. If the profile is not found or multiple
profiles found matching the value, you will receive an error message.
:option:`--profile <PROFILE>` does exist. The server allows the ``<PROFILE>``
value to be a profile name, a profile ID or the short ID of a profile object.
If the profile is not found or multiple profiles found matching the value, you
will receive an error message.
Controlling Cluster Capacity
@@ -184,7 +182,10 @@ The following command creates a cluster named "``test_cluster``", with its
desired capacity set to 2, its minimum size set to 1 and its maximum size set
to 3::
$ senlin cluster-create -n 1 -c 2 -m 3 -p myprofile test_cluster
$ openstack cluster create --desired_capacity 2 \
--min-size 1 --max-size 3 \
--profile myprofile \
test_cluster
Senlin API and Senlin engine will validate the settings for these capacity
arguments when receiving this request. An error message will be returned if
@@ -207,10 +208,9 @@ as the "metadata" for the cluster.
Since cluster operations may take some time to finish when being executed and
Senlin interacts with the backend services to make it happen, there needs a
way to verify whether an operation has timed out. When creating a cluster
using the :program:`senlin` command line tool, you can use the option
:option:`--timeout <TIMEOUT>` (or :option:`-t <TIMEOUT>`) to specify the
default time out in number of seconds. This value would be the global setting
for the cluster.
using the :program:`opentack cluster create` command line, you can use the
option :option:`--timeout <TIMEOUT>` to specify the default time out in number
of seconds. This value would be the global setting for the cluster.
Showing Details of a Cluster
@@ -226,7 +226,7 @@ no cluster matching the identifier or if more than one cluster matching it.
An example is shown below::
$ senlin cluster-show c3
$ openstack cluster show c3
+------------------+--------------------------------------+
| Property | Value |
+------------------+--------------------------------------+
@@ -259,20 +259,20 @@ Updating a Cluster
~~~~~~~~~~~~~~~~~~
Once a cluster has been created, you change its properties using the
:program:`senlin` command line. For example, to change the name of a cluster,
you can use the following command::
:program:`openstack cluster update` command. For example, to change the name
of a cluster, you can use the following command::
$ senlin cluster-update -n web_bak web_servers
$ openstack cluster update --name web_bak web_servers
You can change the ``timeout`` property using option :option:`--timeout` (or
:option:`-t`) for the ``cluster-update`` command. You can change the metadata
associated with cluster using option :option:`--metadata` (or :option:`-M`).
You can change the ``timeout`` property using option :option:`--timeout`.
You can change the metadata associated with cluster using option
:option:`--metadata`.
Using the :command:`cluster-update` command, you can change the profile used
by the cluster and its member nodes. The following example launches a global
update on the cluster for switching to a different profile::
Using the :command:`openstack cluster update` command, you can change the
profile used by the cluster and its member nodes. The following example
launches a global update on the cluster for switching to a different profile::
$ senlin cluster-update -p fedora21_server web_cluster
$ openstack cluster update --profile fedora21_server web_cluster
Suppose the cluster ``web_cluster`` is now using a profile of type
``os.nova.server`` where a Fedora 20 image is used, the command above will
@@ -290,21 +290,21 @@ information.
Resizing a Cluster
~~~~~~~~~~~~~~~~~~
The :program:`senlin` tool supports several different commands to resize a
cluster.
The :program:`openstack cluster` command line supports several different
sub-commands to resize a cluster.
``cluster-resize``
------------------
``openstack cluster resize``
----------------------------
The command :command:`cluster-resize` takes several arguments that allow you
to resize a cluster in various ways:
The command :command:`openstack cluster resize` takes several arguments that
allow you to resize a cluster in various ways:
- you can change the size of a cluster to a specified number;
- you can add a specified number of nodes to a cluster or remove a specified
number of nodes from a cluster;
- you can instruct :program:`senlin` to resize a cluster by a specified
percentage;
- you can instruct :program:`openstack cluster resize` to resize a cluster by
a specified percentage;
- you can tune the ``min_size`` and/or ``max_size`` property of a cluster when
resizing it;
- you can request a size change made on a best-effort basis, if the resize
@@ -313,7 +313,7 @@ to resize a cluster in various ways:
resize operation.
You can specify one and only one of the following options for the
:command:`cluster-resize` command:
:command:`openstack cluster resize` command:
- use :option:`--capacity <CAPACITY>` (:option:`-c <CAPACITY>`) to specify
the exact value of the new cluster size;
@@ -326,35 +326,33 @@ The following command resizes the cluster ``test_cluster`` to 2 nodes,
provided that the ``min_size`` is less than or equal to 2 and the ``max_size``
is either no less than 2 or equal to -1 (indicating that there is no upper
bound for the cluster size). This command makes use of the option
:option:`--capacity <CAPACITY>` (or :option:`-c <CAPACITY>`), where
``<CAPACITY>`` is the new size of the cluster::
:option:`--capacity <CAPACITY>`, where ``<CAPACITY>`` is the new size of the
cluster::
$ senlin cluster-resize -c 2 test_cluster
$ openstack cluster resize --capacity 2 test_cluster
Another way to resize a cluster is by specifying the :option:`--adjustment
<ADJUSTMENT>` (or :option:`-a <ADJUSTMENT>`) option, where ``<ADJUSTMENT>``
can be a positive or a negative integer giving the number of nodes to add or
remove respectively. For example, the following command adds two nodes to the
specified cluster::
<ADJUSTMENT>` option, where ``<ADJUSTMENT>`` can be a positive or a negative
integer giving the number of nodes to add or remove respectively. For example,
the following command adds two nodes to the specified cluster::
$ senlin cluster-resize -a 2 test_cluster
$ openstack cluster resize --adjustment 2 test_cluster
The following command removes two nodes from the specified cluster::
$ senlin cluster-resize -a -2 test_cluster
$ openstack cluster resize --adjustment -2 test_cluster
Yet another way to resize a cluster is by specifying the size change in
percentage. You will use the option :option:`--percentage <PERCENTAGE>` (or
:option:`-p <PERCENTAGE>` for this purpose. The ``<PERCENTAGE>`` value can be
either a positive float value or a negative float value giving the percentage
of cluster size. For example, the following command increases the cluster size
by 30%::
percentage. You will use the option :option:`--percentage <PERCENTAGE>` for
this purpose. The ``<PERCENTAGE>`` value can be either a positive float value
or a negative float value giving the percentage of cluster size. For example,
the following command increases the cluster size by 30%::
$ senlin cluster-resize -p 30 test_cluster
$ openstack cluster resize --percentage 30 test_cluster
The following command decreases the cluster size by 25%::
$ senlin cluster-resize -p -25 test_cluster
$ openstack cluster resize --percentage -25 test_cluster
Senlin engine computes the actual number of nodes to add or to remove based on
the current size of the cluster, the specified percentage value, the
@@ -371,19 +369,19 @@ the value based on the following rules:
- If the value of the new capacity is between 0 and -1, Senlin will round it
down to -1;
- The new capacity should be in the range of ``min_size`` and ``max_size``,
inclusively, unless option :option:`--strict` (or :option:`-s`) is specified;
inclusively, unless option :option:`--strict` is specified;
- The range checking will be performed against the current size constraints if
no new value for ``min_size`` and/or ``max_size`` is given, or else Senlin
will first verify the new size constraints and perform range checking
against the new constraints;
- If option :option:`--min-step <MIN_STEP>` (or :option:`-t <MIN_STEP>`) is
specified, the ``<MIN_STEP>`` value will be used if the absolute value of
the new capacity value is less than ``<MIN_STEP>``.
- If option :option:`--min-step <MIN_STEP>` is specified, the ``<MIN_STEP>``
value will be used if the absolute value of the new capacity value is less
than ``<MIN_STEP>``.
If option :option:`--strict`` (or :option:`-s`) is specified, Senlin will
strictly conform to the cluster size constraints. If the capacity value falls
out of the range, the request will be rejected. When :option:`--strict` is set
to False, Senlin engine will do a resize on a best-effort basis.
If option :option:`--strict`` is specified, Senlin will strictly conform to
the cluster size constraints. If the capacity value falls out of the range,
the request will be rejected. When :option:`--strict` is set to ``False``,
Senlin engine will do a resize on a best-effort basis.
Suppose we have a cluster A with ``min_size`` set to 5 and its current size is
7. If the new capacity value is 4 and option :option:`--strict` is set to
@@ -391,40 +389,41 @@ Suppose we have a cluster A with ``min_size`` set to 5 and its current size is
capacity value is 4 and the option :option:`--strict` is not set, Senlin will
try resize the cluster to 5 nodes.
Along with the :command:`cluster-resize` command, you can specify the new size
constraints using either the option :option:`--min-size` (or :option:`-n`) or
the option :option:`--max-size` (or :option:`-m`) or both.
Along with the :command:`openstack cluster resize` command, you can specify
the new size constraints using either the option :option:`--min-size` or
the option :option:`--max-size` or both.
``cluster-scale-in`` and ``cluster-scale-out``
----------------------------------------------
``openstack cluster shrink`` and ``openstack cluster expand``
-------------------------------------------------------------
The :command:`cluster-scale-in` command and the :command:`cluster-scale-out`
command are provided for convenience when you want to add specific number of
nodes to a cluster or remove specific number of nodes from a cluster,
respectively. These two commands both take an argument ``<COUNT>`` which is a
positive integer giving the number of nodes to add or remove. For example, the
following command adds two nodes to the ``web_servers`` cluster::
The :command:`openstack cluster shrink` command and the
:command:`openstack cluster expand` command are provided for convenience when
you want to remove a specific number of nodes from a cluster or add a specific
number of nodes to a cluster, respectively. These two commands both take an
argument ``<COUNT>`` which is a positive integer representing the number of
nodes to add or remove. For example, the following command adds two nodes to
the ``web_servers`` cluster::
$ senlin cluster-scale-out -c 2 web_servers
$ openstack cluster expand --count 2 web_servers
The following command removes two nodes from the ``web_servers`` cluster::
$ senlin cluster-scale-in -c 2 web_servers
$ openstack cluster shrink --count 2 web_servers
The option :option:`--count <COUNT>` (:option:`-c <COUNT>`) is optional. If
this option is specified, Senlin will use it for cluster size change, even
when there are scaling policies attached to the cluster. If this option is
omitted, however, Senlin will treat it as implicitly set to value 1.
The option :option:`--count <COUNT>` is optional. If this option is specified,
Senlin will use it for cluster size change, even when there are scaling
policies attached to the cluster. If this option is omitted, however, Senlin
will treat it as implicitly set to value 1.
Deleting a Cluster
~~~~~~~~~~~~~~~~~~
A cluster can be deleted using the command :command:`cluster-delete`, for
example::
A cluster can be deleted using the :command:`openstack cluster delete`
command, for example::
$ senlin cluster-delete my_cluster
$ openstack cluster delete mycluster
Note that in this command you can use the name, the ID or the "short ID" to
specify the cluster object you want to delete. If the specified criteria

40
doc/source/user/events.rst
View File

@@ -48,7 +48,7 @@ Listing Events
The following command lists the events by the Senlin engine::
$ senlin event-list
$ openstack cluster event list
+----------+---------------------+---------------+----------+----------------------------+-----------------------+-----------+--------------------------------+-------+
| id | timestamp | obj_type | obj_id | obj_name | action | status | status_reason | level |
+----------+---------------------+---------------+----------+----------------------------+-----------------------+-----------+--------------------------------+-------+
@@ -64,24 +64,23 @@ The following command lists the events by the Senlin engine::
| fe2fc810 | 2015-12-17T15:41:49 | CLUSTERACTION | 0be70b0f | attach_policy_7171861e | CLUSTER_ATTACH_POLICY | SUCCEEDED | Policy attached. | 20 |
+----------+---------------------+---------------+----------+----------------------------+-----------------------+-----------+--------------------------------+-------+
The :program:`senlin` command line supports various options when listing the
events.
The :program:`openstack cluster event list` command line supports various
options when listing the events.
Sorting the List
----------------
You can specify the sorting keys and sorting direction when list events,
using the option :option:`--sort` (or :option:`-o`). The :option:`--sort`
option accepts a string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``,
where the keys used are event properties and the dirs can be one of ``asc``
and ``desc``. When omitted, Senlin sorts a given key using ``asc`` as the
default direction.
using the option :option:`--sort`. The :option:`--sort` option accepts a
string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``, where the keys used
are event properties and the dirs can be one of ``asc`` and ``desc``. When
omitted, Senlin sorts a given key using ``asc`` as the default direction.
For example, the following command instructs the :program:`senlin` command
line to sort events using the ``timestamp`` property in descending order::
For example, the following command sorts the events using the ``timestamp``
property in descending order::
$ senlin event-list -o timestamp:desc
$ openstack cluster event list --sort timestamp:desc
When sorting the list of events, you can use one of ``timestamp``, ``level``,
``obj_type``, ``obj_name``, ``user``, ``action`` and ``status``.
@@ -90,11 +89,10 @@ When sorting the list of events, you can use one of ``timestamp``, ``level``,
Filtering the List
------------------
You can filter the list of events using the :option:`--filters`` (or
:option:`-f`). For example, the following command filters the event list by
the ``obj_type`` property::
You can filter the list of events using the :option:`--filters``. For example,
the following command filters the event list by the ``obj_type`` property::
$ senlin action-list -f obj_type=NODE
$ openstack cluster event list --filters obj_type=NODE
The option :option:`--filters` accepts a list of key-value pairs separated by
semicolon (``;``), where each pair is expected to be of format ``key=val``.
@@ -107,17 +105,17 @@ Paginating the Query results
In case you have a huge collection of events (which is highly likely the case),
you can limit the number of events returned using the option
:option:`--limit <LIMIT>` (or :option:`--l <LIMIT>`). For example::
:option:`--limit <LIMIT>`. For example::
$ senlin event-list -l 10
$ openstack cluster event list --limit 10
Another option you can specify is the ID of an event after which you want to
see the returned list starts. In other words, you don't want to see those
events with IDs that is or come before the one you specify. You can use the
option :option:`--marker <ID>` (or :option:`-m <ID>`) for this purpose. For
example::
option :option:`--marker <ID>` for this purpose. For example::
$ senlin event-list -l 20 -m 2959122e-11c7-4e82-b12f-f49dc5dac270
$ openstack cluster event list --limit 20 \
--marker 2959122e-11c7-4e82-b12f-f49dc5dac270
At most 20 action records will be returned in this example and its UUID comes
after the the one specified from the command line.
@@ -135,7 +133,7 @@ more than one event matching it.
An example is shown below::
$ senlin event-show 19ba155a
$ openstack cluster event show 19ba155a
+---------------+--------------------------------------+
| Property | Value |
+---------------+--------------------------------------+

64
doc/source/user/membership.rst
View File

@@ -31,11 +31,11 @@ cluster membership after the cluster and and the node have been created.
Listing Nodes in a Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~
Using the command :command:`cluster-node-list`, you can list the nodes that
are members of a specific cluster. For example, to list nodes in cluster
``c3``, you can use the following command::
Using the command :command:`openstack cluster member list`, you can list the
nodes that are members of a specific cluster. For example, to list nodes in
cluster ``c3``, you can use the following command::
$ senlin cluster-node-list c3
$ openstack cluster member list c3
+----------+--------+-------+--------+-------------+---------------------+
| id | name | index | status | physical_id | created_at |
+----------+--------+-------+--------+-------------+---------------------+
@@ -50,9 +50,9 @@ or it matches more than one cluster, you will get an error message.
From the list, you can see the ``index``, ``status``, ``physical_id`` of each
node in this cluster. Note that the ``id`` field and the ``physical_id`` field
are shown as "short ID"s by default. If you want to see the full IDs, you can
specify the :option:`--full-id` (or :option:`-F`) option to indicate that::
specify the :option:`--full-id` option to indicate that::
$ senlin cluster-node-list -F c3
$ openstack cluster member list --full-id c3
+------------...-+--------+-------+--------+-------------+-----------..-+
| id | name | index | status | physical_id | created_at |
+------------...-+--------+-------+--------+-------------+-----------..-+
@@ -60,51 +60,43 @@ specify the :option:`--full-id` (or :option:`-F`) option to indicate that::
| 4be10a88-e3... | stack2 | -1 | ACTIVE | 7c87... | 2015-07-07.. |
+------------...-+--------+-------+--------+-------------+-----------..-+
In cases where you want to list nodes that have been soft-deleted, you can add
the option :option:`--show-deleted` (or :option:`-D`) for this purpose. For
example, the following command will list all nodes that were members of the
``webservers`` cluster, no matter the nodes are soft-deleted or not::
$ senlin cluster-node-list -D webservers
If the cluster size is very large, you may want to list the nodes in pages.
This can be achieved by using the :option:`--marker` (or :option:`-m`) option
together with the :option:`--limit` (or :option:`-l`) option. The ``marker``
option value specifies a node ID after which you want the resulted list to
start; and the ``limit`` option value specifies the number of nodes you want
to include in the resulted list. For example, the following command lists the
nodes starting behind a specific node ID with the length of the list set to 10::
This can be achieved by using the :option:`--marker` option together with the
:option:`--limit` option. The ``marker`` option value specifies a node ID
after which you want the resulted list to start; and the ``limit`` option
value specifies the number of nodes you want to include in the resulted list.
For example, the following command lists the nodes starting after a specific
node ID with the length of the list set to 10::
$ senlin cluster-node-list -m b28692a5 -l 10 webservers
$ openstack cluster member list --marker b28692a5 --limit 10 webservers
Another useful option for listing nodes is the :option:`--filters <FILTERS>`
(or :option:`-f <FILTERS>`) option. The option value accepts a string of
format "``K1=V1;K2=V2...``", where "``K1``" and "``K2``" are node properties
for checking, "``V1``" and "``V2``" are values for filtering. The acceptable
properties for filtering are ``name`` and ``status``. For example, the
following command lists cluster nodes from a cluster based on whether a node's
status is "``ACTIVE``"::
option. The option value accepts a string of format "``K1=V1;K2=V2...``",
where "``K1``" and "``K2``" are node properties for checking, "``V1``" and
"``V2``" are values for filtering. The acceptable properties for filtering are
``name`` and ``status``. For example, the following command lists cluster
nodes from a cluster based on whether a node's status is "``ACTIVE``"::
$ senlin cluster-node-list -f status=ACTIVE webservers
$ openstack cluster member list --filters status=ACTIVE webservers
Specify the Cluster When Creating a Node
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are several ways to make a node a member of a cluster. When creating a
node using command :command:`node-create`, you can specify the option
:option:`--cluster` (or :option:`-c`) to tell Senlin to which cluster the new
node belongs. Please refer to :ref:`guide-nodes` for detailed instructions.
node using command :command:`openstack cluster node create`, you can specify
the option :option:`--cluster` to tell Senlin to which cluster the new node
belongs. Please refer to :ref:`guide-nodes` for detailed instructions.
Adding Node(s) to A Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~
When you already have some nodes and some clusters, you can add some specified
nodes to a specified cluster using the command :command:`cluster-node-add`.
For example, the following command adds two nodes to a cluster::
nodes to a specified cluster using the :command:`openstack cluster member add`
command. For example, the following command adds two nodes to a cluster::
$ senlin cluster-node-add -n node3,node4 cluster1
$ openstack cluster member add --nodes node3,node4 cluster1
You can use the name, the ID or the "short ID" to name the node(s) to be
added, you can also use the name, the ID or the "short ID" to specify the
@@ -123,14 +115,14 @@ that can be used to uniquely identify them within the cluster.
Removing Node(s) from a Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :program:`senlin` command line also provides command
:command:`cluster-node-del` to remove node(s) from a cluster. In this case,
The :program:`openstack cluster` command line also provides command
:command:`cluster member del` to remove node(s) from a cluster. In this case,
you can use the name, the ID or the "short ID" to specify the node(s) and the
cluster. The identifier specified must uniquely identifies a node or a cluster
object, or else you will get an error message indicating that the request was
rejected. The following command removes two nodes from a cluster::
$ senlin cluster-node-del -n node21,node22 webservers
$ openstack cluster member del --nodes node21,node22 webservers
When performing this operation, Senlin engine will check if the specified
nodes are actually members of the specified cluster. If any node from the

118
doc/source/user/nodes.rst
View File

@@ -37,9 +37,9 @@ Listing Nodes
~~~~~~~~~~~~~
To list nodes that are managed by the Senlin service, you will use the command
:command:`node-list`. For example::
:command:`openstack cluster node list`. For example::
$ senlin node-list
$ openstack cluster node list
+----------+--------+--------+----------+-------------+---------+...
| id | name | status | cluster | physical_id | profile |
+----------+--------+--------+----------+-------------+---------+...
@@ -52,23 +52,22 @@ To list nodes that are managed by the Senlin service, you will use the command
Note that some columns in the output table are *short ID* of objects. Senlin
command line use short IDs to save real estate on screen so that more useful
information can be shown on a single line. To show the *full ID* in the list,
you can add the option :option:`--full-id` (or :option:`-F`) to the command.
you can add the option :option:`--full-id` to the command.
Sorting the List
----------------
You can specify the sorting keys and sorting direction when list nodes,
using the option :option:`--sort` (or :option:`-o`). The :option:`--sort`
option accepts a string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``,
where the keys used are node properties and the dirs can be one of ``asc``
and ``desc``. When omitted, Senlin sorts a given key using ``asc`` as the
default direction.
using the option :option:`--sort`. The :option:`--sort` option accepts a
string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``, where the keys used
are node properties and the dirs can be one of ``asc`` and ``desc``. When
omitted, Senlin sorts a given key using ``asc`` as the default direction.
For example, the following command instructs the :program:`senlin` command
line to sort nodes using the ``status`` property in descending order::
For example, the following command sorts the nodes using the ``status``
property in descending order::
$ senlin node-list -o status:desc
$ openstack cluster node list --sort status:desc
When sorting the list of nodes, you can use one of ``index``, ``name``,
``status``, ``init_at``, ``created_at`` and ``updated_at``.
@@ -77,11 +76,10 @@ When sorting the list of nodes, you can use one of ``index``, ``name``,
Filtering the List
------------------
You can specify the option :option:`--cluster <CLUSTER>` (or :option:`-c
<CLUSTER>`) to list nodes that are members of a specific cluster. For
example::
You can specify the option :option:`--cluster <CLUSTER>` to list nodes that
are members of a specific cluster. For example::
$ senlin node-list --cluster c3
$ openstack cluster node list --cluster c3
+----------+---------+--------+----------+-------------+---------+...
| id | name | status | cluster | physical_id | profile |
+----------+---------+--------+----------+-------------+---------+...
@@ -90,12 +88,12 @@ example::
+----------+---------+--------+----------+-------------+---------+...
Besides these two options, you can add the option :option:`--filters
<K1=V1;K2=V2...>` (or :option:`-f`) to the command :command:`node-list` to
<K1=V1;K2=V2...>` to the command :command:`openstack cluster node list` to
specify keys (node property names) and values you want to filter the list.
The valid keys for filtering are ``name`` and ``status``. For example, the
command below filters the list by node status ``ACTIVE``::
$ senlin node-list -f status=ACTIVE
$ openstack cluster node list --filters status=ACTIVE
Paginating the List
@@ -103,17 +101,16 @@ Paginating the List
In case you have a large number of nodes, you can limit the number of nodes
returned from Senlin server each time, using the option :option:`--limit
<LIMIT>` (or :option:`--l <LIMIT>`). For example::
<LIMIT>`. For example::
$ senlin node-list --limit 1
$ openstack cluster node list --limit 1
Another option you can specify is the ID of a node after which you want to
see the returned list starts. In other words, you don't want to see those
nodes with IDs that is or come before the one you specify. You can use the
option :option:`--marker <ID>` (or :option:`-m <ID>`) for this purpose. For
example::
option :option:`--marker <ID>` for this purpose. For example::
$ senlin node-list --marker <NODE ID HERE>
$ openstack node-list --marker 765385ed-f480-453a-8601-6fb256f512fc
With option :option:`--marker` and option :option:`--limit`, you will be able
to control how many node records you will get from each request.
@@ -126,7 +123,7 @@ To create a node, you need to specify the ID or name of the profile to be
used. For example, the following example creates a node named ``test_node``
using a profile named ``pstack``::
$ senlin node-create -p pstack test_node
$ openstack cluster node create --profile pstack test_node
+---------------+--------------------------------------+
| Property | Value |
+---------------+--------------------------------------+
@@ -156,41 +153,41 @@ will receive an error message.
Note that the ``index`` property of the new node is -1. This is because we
didn't specify the owning cluster for the node. To join a node to an existing
cluster, you can either use the command :command:`cluster-node-add` (see
:ref:`guide-membership`) after the node is created, or specify the owning
cluster upon node creation, as shown by the following example::
cluster, you can either use the :command:`openstack cluster member add`
command (:ref:`guide-membership`) after the node is created, or specify the
owning cluster upon node creation, as shown by the following example::
$ senlin node-create -p pstack -c c1 test_node
$ openstack cluster node create --profile pstack --cluster c1 test_node
The command above creates a new node using profile ``pstack`` and makes it a
member of the cluster ``c1``, specified using the option :option:`--cluster`
(or :option:`-c`). When a node becomes a member of a cluster, it will get a
value for its ``index`` property that uniquely identifies itself within the
owning cluster.
member of the cluster ``c1``, specified using the option :option:`--cluster`.
When a node becomes a member of a cluster, it will get a value for its
``index`` property that uniquely identifies itself within the owning cluster.
When the owning cluster is specified, Senlin engine will verify if the cluster
specified is referencing a profile that has the same :term:`profile type` as
that of the new node. If the profile types don't match, you will receive an
error message from the :command:`senlin` command.
error message from the :command:`openstack cluster` command.
Another argument that could be useful when creating a new node is the
:option:`--role <ROLE>` (or :option:`-r <ROLE>`) option. The value could be
used by a profile type implementation to treat nodes differently. For example,
the following command creates a node with a ``master`` role::
Another argument that could be useful when creating a new node is the option
:option:`--role <ROLE>`. The value could be used by a profile type
implementation to treat nodes differently. For example, the following command
creates a node with a ``master`` role::
$ senlin node-create -p pstack -c c1 -r master master_node
$ openstack cluster node create --profile pstack --cluster c1 \
--role master master_node
A profile type implementation may check this role value when operating the
physical object that backs the node. It is okay for a profile type
implementation to ignore this value.
The last argument you can specify when creating a new node is the option
:option:`--metadata <K1=V1;K2=V2...>` (or :option:`-M <K1=V1;K2=V2..>`). The
value for this option is a list of key-value pairs seprated by a semicolon
('``;``'). These key-value pairs are attached to the node and can be used for
whatever purposes. For example::
:option:`--metadata <K1=V1;K2=V2...>`. The value for this option is a list of
key-value pairs seprated by a semicolon ('``;``'). These key-value pairs are
attached to the node and can be used for whatever purposes. For example::
$ senlin node-create -p pstack -M owner=JohnWhite test_node
$ openstack cluster node create --profile pstack \
--metadata owner=JohnWhite test_node
Showing Details of a Node
@@ -203,7 +200,7 @@ no node matching the identifier or if more than one node matching it.
An example is shown below::
$ senlin node-show test_node
$ openstack cluster node show test_node
+---------------+--------------------------------------+
| Property | Value |
+---------------+--------------------------------------+
@@ -232,38 +229,38 @@ ID of an object that is of certain type. For example, if the profile type used
is "``os.heat.stack``", this means the Heat stack ID; if the profile type used
is "``os.nova.server``", it gives the Nova server ID.
An useful argument for the command :command:`node-show` is the option
:option:`--details` (or :option:`-D`). When specified, you will get the
details about the physical object that backs the node. For example::
An useful argument for the command :command:`openstack cluster node show` is
the option :option:`--details`. When specified, you will get the details about
the physical object that backs the node. For example::
$ senlin node-show -D test_node
$ openstack cluster node show --details test_node
Updating a Node
~~~~~~~~~~~~~~~
Once a node has been created, you can change its properties using the command
:command:`node-update`. For example, to change the name of a node, you can use
the option :option:`--name` (or :option:`-n`), as shown by the following
:command:`openstack cluster node update`. For example, to change the name of a
node, you can use the option :option:`--name` , as shown by the following
command::
$ senlin node-update -n new_node_name old_node_name
$ openstack cluster node update --name new_node_name old_node_name
Similarly, you can modify the ``role`` property of a node using the option
:option:`--role` (or :option:`-r`). For example::
:option:`--role`. For example::
$ senlin node-update -r slave master_node
$ openstack cluster node update --role slave master_node
You can change the metadata associated with a node using the option
:option:`--metadata` (or :option:`-M`)::
:option:`--metadata`::
$ senlin node-update -M version=2.1 my_node
$ openstack cluster node update --metadata version=2.1 my_node
Using the :command:`node-update` command, you can change the profile used by
a node. The following example updates a node for switching to use a different
profile::
Using the :command:`openstack cluster node update` command, you can change the
profile used by a node. The following example updates a node for switching to
use a different profile::
$ senlin node-update -p fedora21_server fedora20_server
$ openstack cluster node update --profile fedora21_server fedora20_server
Suppose the node ``fedora20_server`` is now using a profile of type
``os.nova.server`` where a Fedora 20 image is used, the command above will
@@ -278,9 +275,10 @@ process.
Deleting a Node
~~~~~~~~~~~~~~~
A node can be deleted using the command :command:`node-delete`, for example::
A node can be deleted using the :command:`openstack cluster node delete`
command, for example::
$ senlin node-delete my_node
$ openstack cluster node delete my_node
Note that in this command you can use the name, the ID or the "short ID" to
specify the node you want to delete. If the specified criteria cannot match

64
doc/source/user/policies.rst
View File

@@ -35,11 +35,11 @@ details.
Listing Policies
~~~~~~~~~~~~~~~~
The :program:`senlin` command line provides a command :command:`policy-list`
that can be used to enumerate policy objects known to the service. For
example::
The :program:`openstack cluster` command line provides a sub-command
:command:`openstack cluster policy list` that can be used to enumerate policy
objects known to the service. For example::
$ senlin policy-list
$ openstack cluster policy list
+----------+------+-----------------------------+---------------------+
| id | name | type | created_at |
+----------+------+-----------------------------+---------------------+
@@ -50,24 +50,22 @@ example::
Note that the first column in the output table is a *short ID* of a policy
object. Senlin command line use short IDs to save real estate on screen so
that more useful information can be shown on a single line. To show the *full
ID* in the list, you can add the :option:`-F` (or :option:`--full-id`) option
to the command.
ID* in the list, you can add the :option:`--full-id` option to the command.
Sorting the List
----------------
You can specify the sorting keys and sorting direction when list policies,
using the option :option:`--sort` (or :option:`-o`). The :option:`--sort`
option accepts a string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``,
where the keys used are policy properties and the dirs can be one of ``asc``
and ``desc``. When omitted, Senlin sorts a given key using ``asc`` as the
default direction.
using the option :option:`--sort`. The :option:`--sort` option accepts a
string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``, where the keys used
are policy properties and the dirs can be one of ``asc`` and ``desc``. When
omitted, Senlin sorts a given key using ``asc`` as the default direction.
For example, the following command instructs the :program:`senlin` command
line to sort policies using the ``name`` property in descending order::
For example, the following command sorts the policies using the ``name``
property in descending order::
$ senlin policy-list -o name:desc
$ openstack cluster policy list --sort name:desc
When sorting the list of policies, you can use one of ``type``, ``name``,
``created_at`` and ``updated_at``.
@@ -77,10 +75,10 @@ Paginating the List
-------------------
In case you have a huge collection of policy objects, you can limit the number
of policies returned from Senlin server, using the option :option:`--limit` (or
(or `-l`). For example::
of policies returned from Senlin server, using the option :option:`--limit`.
For example::
$ senlin policy-list -l 1
$ openstack cluster policy list --limit 1
+----------+------+----------------------------+---------------------+
| id | name | type | created_at |
+----------+------+----------------------------+---------------------+
@@ -90,20 +88,20 @@ of policies returned from Senlin server, using the option :option:`--limit` (or
Yet another option you can specify is the ID of a policy object after which
you want to see the list starts. In other words, you don't want to see those
policies with IDs that is or come before the one you specify. You can use the
option :option:`--marker <ID>` (or option:`-m <ID>`) for this purpose. For
example::
option :option:`--marker <ID>` for this purpose. For example::
$ senlin policy-list -l 1 -m 239d7212-6196-4a89-9446-44d28717d7de
$ openstack cluster policy list --limit 1 \
--marker 239d7212-6196-4a89-9446-44d28717d7de
Combining the :option:`-m` and the :option:`-l` enables you to do pagination
on the results returned from the server.
Combining the :option:`--marker` option and the :option:`--limit` option
enables you to do pagination on the results returned from the server.
Creating a Policy
~~~~~~~~~~~~~~~~~
When creating a new policy object, you need a "spec" file in YAML format. You
may want to check the :command:`policy-type-show` command in
may want to check the :command:`openstack cluster policy type show` command in
:ref:`guide-policy-types` for the property names and types for a specific
:term:`policy type`. For example, the following is a spec for the policy type
``senlin.policy.deletion`` (the source can be found in the
@@ -132,7 +130,7 @@ The properties in this spec file are specific to the ``senlin.policy.deletion``
policy type. To create a policy object using this "spec" file, you can use the
following command::
$ senlin policy-create -s deletion_policy.yaml dp01
$ opentack cluster policy create --spec deletion_policy.yaml dp01
+------------+-----------------------------------------------------------+
| Property | Value |
+------------+-----------------------------------------------------------+
@@ -158,12 +156,12 @@ following command::
Showing the Details of a Policy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use the :command:`policy-show` command to show the properties of a
policy. You need to provide an identifier to the :program:`senlin` command
You can use the :command:`openstack cluster policy show` command to show the
properties of a policy. You need to provide an identifier to the command
line to indicate the policy object you want to examine. The identifier can be
the ID, the name or the "short ID" of a policy object. For example::
$ senlin policy-show dp01
$ openstack cluster policy show dp01
+------------+------------------------------------------------------------+
| Property | Value |
+------------+------------------------------------------------------------+
@@ -193,12 +191,12 @@ get an error message as well.
Updating a Policy
~~~~~~~~~~~~~~~~~
After a policy object is created, you may want to change some properties of it.
You can use the :command:`policy-update` to change the "name" of a policy. For
example, the following command renames a policy object from "``dp01``" to
"``dp01_bak``"::
After a policy object is created, you may want to change some properties of
it. You can use the :command:`openstack cluster policy update` to change the
"``name``" of a policy. For example, the following command renames a policy
object from "``dp01``" to "``dp01_bak``"::
$ senlin policy-update -n dp01_bak dp01
$ openstack cluster policy update --name dp01_bak dp01
If the named policy object could not be found or the parameter value fails the
validation, you will get an error message.
@@ -210,7 +208,7 @@ Deleting a Policy
When there are no clusters referencing a policy object, you can delete it from
the Senlin database using the following command::
$ senlin policy-delete dp01
$ openstack cluster policy delete dp01
Note that in this command you can use the name, the ID or the "short ID" to
specify the policy object you want to delete. If the specified criteria

6
doc/source/user/policy_types.rst
View File

@@ -58,7 +58,7 @@ Listing Policy Types
Senlin server comes with some built-in policy types. You can check the list
of policy types using the following command::
$ senlin policy-type-list
$ openstack cluster policy type list
+--------------------------------+
| name |
+--------------------------------+
@@ -82,7 +82,7 @@ that describes the names and types of the properties that can be accepted. To
show the schema of a specific policy type along with other properties, you can
use the following command::
$ senlin policy-type-show senlin.policy.deletion
$ openstack cluster policy type show senlin.policy.deletion
name: senlin.policy.deletion
schema:
criteria:
@@ -132,7 +132,7 @@ The default output from the :command:`policy-type-show` command is in YAML
format. You can choose to show the spec schema in JSON format by specifying
the the :option:`-F json` option as shown below::
$ senlin policy-type-show -F json senlin.policy.deletion
$ openstack cluster policy type show -F json senlin.policy.deletion
For information on how to manage the relationship between a policy and a
cluster, please refer to :ref:`guide-bindings`.

24
doc/source/user/profile_types.rst
View File

@@ -77,13 +77,13 @@ Listing Profile Types
Senlin server comes with some built-in profile types. You can check the list
of profile types using the following command::
$ senlin profile-type-list
+----------------+
| name |
+----------------+
| os.heat.stack |
| os.nova.server |
+----------------+
$ openstack cluster profile type list
+--------------------+
| name |
+--------------------+
| os.heat.stack-1.0 |
| os.nova.server-1.0 |
+--------------------+
The output is a list of profile types supported by the Senlin server.
@@ -96,7 +96,7 @@ that describes the names and the types of properties that can be accepted. To
show the schema of a specific profile type along with other properties, you
can use the following command::
$ senlin profile-type-show os.heat.stack
$ openstack cluster profile type show os.heat.stack
name: os.heat.stack
schema:
context:
@@ -131,11 +131,11 @@ Here, each property has the following attributes:
property usually doesn't have a ``default`` value.
- ``type``: one of ``String``, ``Integer``, ``Boolean``, ``Map`` or ``List``.
The default output from the :command:`profile-type-show` command is in YAML
format. You can choose to show the spec schema in JSON format by specifying
the the :option:`-F json` option as exemplified below::
The default output from the :command:`openstack cluster profile type show`
command is in YAML format. You can choose to show the spec schema in JSON
format by specifying the the :option:`-f json` option as exemplified below::
$ senlin profile-type-show -F json os.heat.stack
$ openstack cluster profile type show -f json os.heat.stack
{
"name": "os.heat.stack",
"schema": {

85
doc/source/user/profiles.rst
View File

@@ -38,7 +38,7 @@ Listing Profiles
To examine the list of profile objects supported by the Senlin engine, you can
use the following command::
$ senlin profile-list
$ openstack cluster profile list
+----------+----------+--------------------+---------------------+
| id | name | type | created_at |
+----------+----------+--------------------+---------------------+
@@ -50,10 +50,9 @@ use the following command::
Note that the first column in the output table is a *short ID* of a profile
object. Senlin command line use short IDs to save real estate on screen so
that more useful information can be shown on a single line. To show the *full
ID* in the list, you can add the :option:`-F` (or :option:`--full-id`) option
to the command::
ID* in the list, you can add the :option:`--full-id` option to the command::
$ senlin profile-list -F
$ openstack cluster profile list --full-id
+-------------------+----------+--------------------+---------------------+
| id | name | type | created_at |
+-------------------+----------+--------------------+---------------------+
@@ -68,16 +67,15 @@ Sorting the List
----------------
You can specify the sorting keys and sorting direction when list profiles,
using the option :option:`--sort` (or :option:`-o`). The :option:`--sort`
option accepts a string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``,
where the keys used are profile properties and the dirs can be one of ``asc``
and ``desc``. When omitted, Senlin sorts a given key using ``asc`` as the
default direction.
using the option :option:`--sort`. The :option:`--sort` option accepts a
string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``, where the keys used
are profile properties and the dirs can be one of ``asc`` and ``desc``. When
omitted, Senlin sorts a given key using ``asc`` as the default direction.
For example, the following command instructs the :program:`senlin` command
line to sort profiles using the ``name`` property in descending order::
For example, the following command sorts the profiles using the ``name``
property in descending order::
$ senlin profile-list -o name:desc
$ openstack cluster profile list --sort name:desc
When sorting the list of profiles, you can use one of ``type``, ``name``,
``created_at`` and ``updated_at``.
@@ -87,10 +85,10 @@ Paginating the List
-------------------
In case you have a huge collection of profile objects, you can limit the
number of profiles returned from Senlin server, using the option :option:`-l
<LIMIT>` (or :option:`--limit <LIMIT>`). For example::
number of profiles returned from Senlin server, using the option
:option:`--limit <LIMIT>`. For example::
$ senlin profile-list -l 1
$ openstack cluster profile list --limit 1
+----------+----------+--------------------+---------------------+
| id | name | type | created_at |
+----------+----------+--------------------+---------------------+
@@ -99,10 +97,11 @@ number of profiles returned from Senlin server, using the option :option:`-l
Yet another option you can specify is the ID of a profile object after which
you want to see the list starts. In other words, you don't want to see those
profiles with IDs is or come before the one you specify. You can use the option
:option:`-m <ID>` (or :option:`--marker <ID>`) for this purpose. For example::
profiles with IDs is or come before the one you specify. You can use the
option :option:`--marker <ID>` for this purpose. For example::
$ senlin profile-list -l 1 -m ceda64bd-70b7-4711-9526-77d5d51241c5
$ openstack cluster profile list --limit 1 \
--marker ceda64bd-70b7-4711-9526-77d5d51241c5
+----------+--------+-------------------+---------------------+
| id | name | type | created_at |
+----------+--------+-------------------+---------------------+
@@ -137,7 +136,9 @@ decide which properties to use based on your requirements.
Now you can create a profile using the following command::
$ cd /opt/stack/senlin/examples/profiles
$ senlin profile-create -s heat_stack_random_string.yaml my_stack
$ openstack cluster profile create \
--spec heat_stack_random_string.yaml \
my_stack
+--------------+-----------------------------------------------------------+
| Property | Value |
+--------------+-----------------------------------------------------------+
@@ -205,13 +206,15 @@ generated. The ``spec`` property is dumped for the purpose of verification.
Optionally, you can attach some key-value pairs to the new profile when
creating it. This data is referred to as the *metadata* for the profile::
$ senlin profile-create -s heat_stack_random_string.yaml \
-M "author=Tom;version=1.0" \
my_stack
$ openstack cluster profile create \
--spec heat_stack_random_string.yaml \
--metadata "author=Tom;version=1.0" \
my_stack
$ senlin profile-create -s heat_stack_random_string.yaml \
-M author=Tom -M version=1.0 \
my_stack
$ openstack cluster profile create \
--spec heat_stack_random_string.yaml \
--metadata author=Tom --metadata version=1.0 \
my_stack
Showing the Details of a Profile
@@ -220,7 +223,7 @@ Showing the Details of a Profile
Once there are profile objects in Senlin database, you can use the following
command to show the properties of a profile::
$ senlin profile-show myserver
$ openstack cluster profile show myserver
+------------+---------------------------------------------------------+
| Property | Value |
+------------+---------------------------------------------------------+
@@ -248,29 +251,29 @@ command to show the properties of a profile::
| type | os.nova.server-1.0 |
+------------+---------------------------------------------------------+
Note that :program:`senlin` command line accepts one of the following values
when retrieving a profile object:
Note that :program:`openstack cluster` command line accepts one of the
following values when retrieving a profile object:
- name: the name of a profile;
- ID: the UUID of a profile;
- short ID: an "abbreviated version" of the profile UUID.
Since Senlin doesn't require a profile name to be unique, specifying profile
name for the :command:`profile-show` command won't guarantee that a profile
object is returned. You may get a ``MultipleChoices`` exception if more than
one profile object match the name.
name for the :command:`openstack cluster profile show` command won't guarantee
that a profile object is returned. You may get a ``MultipleChoices`` exception
if more than one profile object match the name.
As another option, when retrieving a profile (or in fact any other objects,
e.g. a cluster, a node, a policy etc.), you can specify the leading sub-string
of an UUID as the "short ID" for query. For example::
$ senlin profile-show 560a8f9d
$ openstack cluster profile show 560a8f9d
+----------+----------+--------------------+---------------------+
| id | name | type | created_at |
+----------+----------+--------------------+---------------------+
| 560a8f9d | myserver | os.nova.server-1.0 | 2015-05-05T13:26:00 |
+----------+----------+--------------------+---------------------+
$ senlin profile-show 560a
$ openstack cluster profile show 560a
+----------+----------+--------------------+---------------------+
| id | name | type | created_at |
+----------+----------+--------------------+---------------------+
@@ -288,19 +291,19 @@ Updating a Profile
In general, a profile object should not be updated after creation. This is a
restriction to keep cluster and node status consistent at any time. However,
considering that there are cases where a user may want to change some
properties of a profile, :program:`senlin` command line does support the
:command:`profile-update` command. For example, the following command changes
the name of a profile to ``new_server``::
properties of a profile, :program:`openstack cluster` command line does
support the :command:`profile update` sub-command. For example, the following
command changes the name of a profile to ``new_server``::
$ senlin profile-update -n new_server myserver
$ openstack cluster profile update --name new_server myserver
The following command creates or updates the metadata associated with the given
profile::
$ senlin profile-update -M version=2.2 myserver
$ openstack cluster profile update --metadata version=2.2 myserver
Changing the "spec" of a profile is not allowed. The only way to make a change
is to create a new profile using the :command:`profile-create` command.
is to create a new profile using the :command:`profile create` sub-command.
Deleting a Profile
@@ -309,7 +312,7 @@ Deleting a Profile
When there are no clusters or nodes referencing a profile object, you can
delete it from the Senlin database using the following command::
$ senlin profile-delete myserver
$ openstack cluster profile delete myserver
Note that in this command you can use the name, the ID or the "short ID" to
specify the profile object you want to delete. If the specified criteria
@@ -317,7 +320,7 @@ cannot match any profiles, you will get a ``ProfileNotFound`` exception.
If more than one profile matches the criteria, you will get a
``MultipleChoices`` exception. For example::
$ senlin profile-delete my
$ openstack cluster profile delete my
ERROR(404): The profile (my) could not be found.
Failed to delete any of the specified profile(s).

63
doc/source/user/receivers.rst
View File

@@ -26,27 +26,26 @@ a receiver can change the size of a specified cluster.
Listing Receivers
~~~~~~~~~~~~~~~~~
The :program:`senlin` command line provides a command :command:`receiver-list`
that can be used to enumerate receiver objects known to the service. For
example::
The :program:`opentack cluster ` command line provides a sub-command
:command:`receiver list` that can be used to enumerate receiver objects known
to the service. For example::
$ senlin receiver-list
$ openstack cluster receiver list
Sorting the List
----------------
You can specify the sorting keys and sorting direction when list receivers,
using the option :option:`--sort` (or :option:`-o`). The :option:`--sort`
option accepts a string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``,
where the keys used are receiver properties and the dirs can be one of ``asc``
and ``desc``. When omitted, Senlin sorts a given key using ``asc`` as the
default direction.
using the option :option:`--sort`. The :option:`--sort` option accepts a
string of format ``key1[:dir1],key2[:dir2],key3[:dir3]``, where the keys used
are receiver properties and the dirs can be one of ``asc`` and ``desc``. When
omitted, Senlin sorts a given key using ``asc`` as the default direction.
For example, the following command instructs the :program:`senlin` command
line to sort receivers using the ``name`` property in descending order::
For example, the following command sorts the receivers using the ``name``
property in descending order::
$ senlin receiver-list -o name:desc
$ openstack cluster receiver list --sort name:desc
When sorting the list of receivers, you can use one of ``type``, ``name``,
``action``, ``cluster_id``, ``created_at``.
@@ -57,20 +56,20 @@ Paginating the List
In case you have a huge collection of receiver objects, you can limit the
number of receivers returned from Senlin server, using the option
:option:`--limit` (or (or `-l`). For example::
:option:`--limit`. For example::
$ senlin receiver-list -l 1
$ openstack cluster receiver list --limit 1
Yet another option you can specify is the ID of a receiver object after which
you want to see the list starts. In other words, you don't want to see those
receivers with IDs that is or come before the one you specify. You can use the
option :option:`--marker <ID>` (or option:`-m <ID>`) for this purpose. For
example::
option :option:`--marker <ID>` for this purpose. For example::
$ senlin receiver-list -l 1 -m 239d7212-6196-4a89-9446-44d28717d7de
$ openstack cluster receiver list \
--limit 1 --marker 239d7212-6196-4a89-9446-44d28717d7de
Combining the :option:`-m` and the :option:`-l` enables you to do pagination
on the results returned from the server.
Combining the :option:`--marker` option and the :option:`--limit` option
enables you to do pagination on the results returned from the server.
Creating a Receiver
@@ -81,28 +80,32 @@ Creating a Receiver
::
senlin cluster-create -p $PROFILE_ID -c 2 -n 1 -m 5 test-cluster
$ openstack cluster create --profile $PROFILE_ID \
--desired-capacity 2 --min-size 1 --max-size 5 \
test-cluster
2. Attach a ScalingPolicy to the cluster:
::
senlin cluster-policy-attach -p $POLICY_ID test-cluster
$ opentack cluster policy attach --policy $POLICY_ID test-cluster
3. Create a receiver, use the option :option:`-c` to specify `test-cluster` as
the targeted cluster and use the option :option:`-a` to specify
`CLUSTER_SCALE_OUT` or `CLUSTER_SCALE_IN` as the action name. By default,
the :program:`senlin` command line creates a receiver of type
:term:`webhook`, for example:::
3. Create a receiver, use the option :option:`--cluster` to specify
"``test-cluster``" as the targeted cluster and use the option
:option:`--action` to specify "``CLUSTER_SCALE_OUT``" or
"``CLUSTER_SCALE_IN``" as the action name. By default, the
:program:`openstack cluster receiver create` command line creates a
receiver of type :term:`webhook`, for example:::
senlin receiver-create -c test-cluster \
-a CLUSTER_SCALE_OUT \
$ openstack cluster receiver create \
--cluster test-cluster \
--action CLUSTER_SCALE_OUT \
test-receiver
Senlin service will return the receiver information with its channel ready
to receive signals. For a webhook receiver, this means you can check the
``alarm_url`` field of the ``channel`` property. You can use this url to
trigger the action you specified.
"``alarm_url``" field of the "``channel``" property. You can use this url
to trigger the action you specified.
4. Trigger the receiver by sending a ``POST`` request to its URL, for example: