Clusters¶

Sorting the List¶

You can specify the sorting keys and sorting direction when list clusters, 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 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 senlin command line to sort clusters using the name property in descending order:

$ senlin cluster-list -o name:desc

When sorting the list of clusters, you can use one of name, status, init_at, created_at and updated_at.

Filtering the List¶

The senlin command line also provides options for filtering the cluster list at the server side. The option --filters (or -f) can be used for this purpose. For example, the following command filters clusters by the status field:

$ senlin cluster-list -f status=ACTIVE
+----------+------+--------+---------------------+
| id       | name | status | created_at          |
+----------+------+--------+---------------------+
| 2959122e | c1   | ACTIVE | 2015-05-05T13:27:28 |
| 092d0955 | c2   | ACTIVE | 2015-05-05T13:27:48 |
+----------+------+--------+---------------------+

The option --filters accepts a list of key-value pairs separated by semicolon (;), where each key-value pair is expected to be of format <key>=<value>. The valid keys for filtering include: status, name, project and user.

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

$ senlin cluster-list -l 1
+----------+------+--------+---------------------+
| id       | name | status | created_at          |
+----------+------+--------+---------------------+
| 2959122e | c1   | ACTIVE | 2015-05-05T13:27:28 |
+----------+------+--------+---------------------+

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

$ senlin cluster-list -l 1 -m 2959122e-11c7-4e82-b12f-f49dc5dac270
+----------+------+--------+---------------------+
| id       | name | status | created_at          |
+----------+------+--------+---------------------+
| 092d0955 | c2   | ACTIVE | 2015-05-05T13:27:48 |
+----------+------+--------+---------------------+

Only 1 cluster record is returned in this example and its UUID comes after the the one specified from the command line.

Controlling Cluster Capacity¶

When creating a cluster, by default senlin will create a cluster with no nodes, i.e. the desired_capacity will be set to 0. However, you can specify the desired capacity of the cluster, the maximum size and/or the minimum size of the cluster. The default value for min_size is 0 and the default value for max_size is -1, meaning that there is no upper bound for the cluster size.

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

Senlin API and Senlin engine will validate the settings for these capacity arguments when receiving this request. An error message will be returned if the arguments fail to pass this validation, or else the cluster creation request will be queued as an action for execution.

When desired_capacity is not specified and min_size is not specified, Senlin engine will create an empty cluster. When either desired_capacity or min_size is specified, Senlin will start the process of creating nodes immediately after the cluster object is created.

Other Properties¶

You can use the option --metadata (or -M) to associate some key-value pairs to the cluster to be created. These data are referred to 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 senlin command line tool, you can use the option --timeout (or -t) to specify the default time out in number of seconds. This value would be the global setting for the cluster.

cluster-resize¶

The command 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 senlin 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 operation cannot be fully realized due to some restrictions, this argument tells Senlin engine whether it is still expected to partially realize the resize operation.

You can specify one and only one of the following options for the cluster-resize command:

• use --capacity (-c) to specify the exact value of the new cluster size;
• use --adjustment (-a) to specify the relative number of nodes to add/remove;
• use --percentage (-p) to specify the percentage of cluster size change.

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 --capacity (or -c), where <CAPACITY> is the new size of the cluster:

$ senlin cluster-resize -c 2 test_cluster

Another way to resize a cluster is by specifying the --adjustment (or -a) 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

The following command removes two nodes from the specified cluster:

$ senlin cluster-resize -a -2 test_cluster

Yet another way to resize a cluster is by specifying the size change in percentage. You will use the option --percentage (or -p 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

The following command decreases the cluster size by 25%:

$ senlin cluster-resize -p -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 constraints (i.e. the min_size and the max_size properties).

When computing the new capacity for the cluster, senlin engine will determine the value based on the following rules:

• If the value of new capacity is greater than 1.0 or less than -1.0, it will be rounded to the integer part of the value. For example, 3.4 will be rounded to 3, -1.9 will be rounded to -1;
• If the value of the new capacity is between 0 and 1, Senlin will round it up to 1;
• 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 --strict (or -s) 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 --min-step (or -t) 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 --strict` (or -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 --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 --strict is set to True, the request will be rejected with an error message. If the new capacity value is 4 and the option --strict is not set, Senlin will try resize the cluster to 5 nodes.

Along with the cluster-resize command, you can specify the new size constraints using either the option --min-size (or -n) or the option --max-size (or -m) or both.

cluster-scale-in and cluster-scale-out¶

The cluster-scale-in command and the 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:

$ senlin cluster-scale-out -c 2 web_servers

The following command removes two nodes from the web_servers cluster:

$ senlin cluster-scale-in -c 2 web_servers

The option --count (-c) 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.