Policies

updated: None

Policies

Policies¶

Concept¶

A Policy is an object instantiated from a Policy Type. Once created, it can be dynamically attached to or detached from a cluster. Such a policy usually contains rules to be checked/enforced when certain action is about to be executed or has been executed.

One policy can be attached to many clusters, and one cluster can be attached with many policies. In addition to this, a policy on a cluster can be dynamically enabled or disabled. Please refer to Cluster-Policy Bindings for details.

Listing Policies¶

The senlin command line provides a command policy-list that can be used to enumerate policy objects known to the service. For example:

$ senlin policy-list
+----------+------+-----------------------------+---------------------+
| id       | name | type                        | created_at          |
+----------+------+-----------------------------+---------------------+
| 239d7212 | dp01 | senlin.policy.deletion-1.0  | 2015-07-11T04:24:34 |
| 7ecfd026 | lb01 | senlin.policy.placement-1.0 | 2015-07-11T04:25:28 |
+----------+------+-----------------------------+---------------------+

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 -F (or --full-id) option to the command.

Sorting the List¶

You can specify the sorting keys and sorting direction when list policies, using the option --sort (or -o). The --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 senlin command line to sort policies using the name property in descending order:

$ senlin policy-list -o name:desc

When sorting the list of policies, you can use one of type, name, created_at and updated_at.

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 --limit (or (or -l). For example:

$ senlin policy-list -l 1
+----------+------+----------------------------+---------------------+
| id       | name | type                       | created_at          |
+----------+------+----------------------------+---------------------+
| 239d7212 | dp01 | senlin.policy.deletion-1.0 | 2015-07-11T04:24:34 |
+----------+------+----------------------------+---------------------+

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 --marker (or option:-m <ID>) for this purpose. For example:

$ senlin policy-list -l 1 -m 239d7212-6196-4a89-9446-44d28717d7de

Combining the -m and the -l 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 policy-type-show command in Policy Types for the property names and types for a specific policy type. For example, the following is a spec for the policy type senlin.policy.deletion (the source can be found in the examples/policies/deletion_policy.yaml file):

# Sample deletion policy that can be attached to a cluster.
type: senlin.policy.deletion
version: 1.0
properties:
  # The valid values include:
  # OLDEST_FIRST, OLDEST_PROFILE_FIRST, YOUNGEST_FIRST, RANDOM
  criteria: OLDEST_FIRST

  # Whether deleted node should be destroyed
  destroy_after_deletion: True

  # Length in number of seconds before the actual deletion happens
  # This param buys an instance some time before deletion
  grace_period: 60

  # Whether the deletion will reduce the desired capability of
  # the cluster as well.
  reduce_desired_capacity: False

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
+------------+-----------------------------------------------------------+
| Property   | Value                                                     |
+------------+-----------------------------------------------------------+
| created_at | None                                                      |
| id         | c2e3cd74-bb69-4286-bf06-05d802c8ec12                      |
| name       | dp01                                                      |
| spec       | {                                                         |
|            |   "version": 1.0,                                         |
|            |   "type": "senlin.policy.deletion",                       |
|            |   "description": "A policy for choosing victim node(s).", |
|            |   "properties": {                                         |
|            |     "destroy_after_deletion": true,                       |
|            |     "grace_period": 60,                                   |
|            |     "reduce_desired_capacity": false,                     |
|            |     "criteria": "OLDEST_FIRST"                            |
|            |   }                                                       |
|            | }                                                         |
| type       | None                                                      |
| updated_at | None                                                      |
+------------+-----------------------------------------------------------+

Showing the Details of a Policy¶

You can use the policy-show command to show the properties of a policy. You need to provide an identifier to the senlin 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
+------------+------------------------------------------------------------+
| Property   | Value                                                      |
+------------+------------------------------------------------------------+
| created_at | 2015-07-11T04:24:34                                        |
| id         | c2e3cd74-bb69-4286-bf06-05d802c8ec12                       |
| name       | dp01                                                       |
| spec       | {                                                          |
|            |   "version": 1.0,                                          |
|            |   "type": "senlin.policy.deletion",                        |
|            |   "description": "A policy for choosing victim node(s).",  |
|            |   "properties": {                                          |
|            |     "destroy_after_deletion": true,                        |
|            |     "grace_period": 60,                                    |
|            |     "reduce_desired_capacity": false,                      |
|            |     "criteria": "OLDEST_FIRST"                             |
|            |   }                                                        |
|            | }                                                          |
| type       | None                                                       |
| updated_at | None                                                       |
+------------+------------------------------------------------------------+

When there is no policy object matching the identifier, you will get an error message. When there are more than one object matching the identifier, you will 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 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

If the named policy object could not be found or the parameter value fails the validation, you will get an error message.

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

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 cannot match any policy objects, you will get a PolicyNotFound exception. If more than one policy matches the criteria, you will get an error message.