Using the App Autoscaler CLI for your TAS for VMs deployment

You can use the App Autoscaler Command-Line Interface (CLI) to control scaling apps in your TAS for VMs deployment.

The App Autoscaler CLI is an extension of the Cloud Foundry Command-Line Interface (cf CLI). You can configure and control Autoscaler from your local CLF to scale apps in your TAS for VMs deployment.

Important The return output from the App Autoscaler CLI might include odd characters in Windows shells that do not support text color. To prevent this error, run SET CF_COLOR=false in your Windows shell pane before you use the App Autoscaler CLI. Some Windows shells do not support the CF_COLOR environment variable.

Install the App Autoscaler CLI plug-in

Before you can run App Autoscaler CLI commands, you must install the App Autoscaler CLI Plug-in.

To install the plug-in:

Download the Tanzu App Autoscaler CLI plug-in from VMware Tanzu Network.

Important There are two versions of the App Autoscaler CLI. If you install the wrong version, you cannot use it with the Autoscaler instance in your TAS for VMs deployment. For more information, see App Autoscaler for Cloud Foundry Does Not Work with TAS for VMs in Troubleshooting App Autoscaler.

In a terminal window, run:
```
cf install-plugin LOCATION-OF-PLUGIN
```
Where LOCATION-OF-PLUGIN is the path to the binary file you downloaded from VMware Tanzu Network. For example:
```
cf install-plugin ~/Downloads/autoscaler-for-pcf-cliplugin-macosx64-binary-2.0.91
```
For more information about installing cf CLI plug-ins, see Install a plug-in in Using cf CLI Plugins.

Create and bind an Autoscaler service instance

Before you can use Autoscaler, you must create a service instance of Autoscaler and bind it to your app. For more information about service instances, see Managing service instances with the cf CLI.

To create and bind an Autoscaler service instance:

In a terminal window, target the space in which the app you want to scale by running:
```
cf target -o ORG-NAME -s SPACE-NAME
```
Where:
- ORG-NAME is the name of the org containing the space in which the app you want to scale is deployed.
- SPACE-NAME is the name of the space in which the app you want to scale is deployed.
Create an Autoscaler service instance by running:
```
cf create-service app-autoscaler PLAN-NAME SERVICE-NAME
```
Where:
- PLAN-NAME is the name of the service plan you want to use for the Autoscaler service instance.
- SERVICE-INSTANCE-NAME is the name you want to give the Autoscaler service instance. For example, autoscaler.
Bind the Autoscaler service instance you created in the eariler step to the app you want to scale by running:
```
cf bind-service APP-NAME SERVICE-INSTANCE-NAME
```
Where:
- APP-NAME is the name of the app you want to scale.
- SERVICE-INSTANCE-NAME is the name of the Autoscaler service instance in the previous step.

Only one service instance of Autoscaler can exist in each space in an org. If you try to create more than one Autoscaler service instance in a space, the App Autoscaler CLI returns an error message. For more information, see One Autoscaler Service Instance Per Space in Troubleshooting App Autoscaler.

View apps bound to Autoscaler

To view a list of all the apps that are bound to an Autoscaler service instance in a space:

In a terminal window, target the space in which you want to view apps bound to an Autoscaler service instance by running:
```
cf target -o ORG-NAME -s SPACE-NAME
```
Where:
- ORG-NAME is the name of the org containing the space in which the apps you want to view are deployed.
- SPACE-NAME is the name of the space in which the apps you want to view are deployed.

Run:

cf autoscaling-apps

The above command returns a list of apps that are bound to Autoscaler, whether autoscaling is configured for those apps, and the autoscaling limits and scaling factors that are configured for them, similar to the following example:

Presenting autoscaler apps in org example-org / space example-space as user
Name                  Guid                                      Enabled   Min Instances   Max Instances   Scale Up Factor   Scale Down Factor
example-app              d0077dc5-34bd-42c7-b377-e0fcb14d67f3      true      1               4               1                 1
example-app-2            3f8c6e84-0b6e-4ec9-9335-0aad3979d672      false     10              40              5                 2
OK

Allow autoscaling

To set Autoscale for your app:

Run:
```
cf enable-autoscaling APP-NAME
```
Where APP-NAME is the name of the app for which you want to allow autoscaling.

For example, if you run this command, it allows Autoscaler to scale example-app:
```
cf enable-autoscaling example-app
```
The above command returns output similar to the following example:
```
Enabled autoscaling for app example-app for org example-org / space example-space as user
OK
```

By default, the upper and lower autoscaling limits for an app are -1. Before Autoscaler can scale an app, you must update these upper and lower autoscaling limits. For more information, see Configure Autoscaling Limits.

Disallow autoscaling

To disallow autoscaling for an app:

Run:
```
cf disable-autoscaling APP-NAME
```
Where APP-NAME is the name of the app for which you want to disallow autoscaling.

For example, if you run the following, it disallows Autoscaler from scaling example-app:
```
cf disable-autoscaling example-app
```
The above command returns output similar to the following example:
```
Deactivated autoscaling for app example-app for org example-org / space example-space as user
OK
```

Configure autoscaling limits

To configure the upper and lower autoscaling limits for an app:

In a terminal window, run:
```
cf update-autoscaling-limits APP-NAME LOWER-SCALING-LIMIT UPPER-SCALING-LIMIT
```
Where:
- APP-NAME is the name of the app for which you want to configure autoscaling limits.
- LOWER-SCALING-LIMIT is the minimum number of instances you want Autoscaler to create for the app.
- UPPER-SCALING-LIMIT is the maximum number of instances you want Autoscaler to create for the app.
For example, if you run the following, it sets the lower scaling limit for example-app to 20 and the upper scaling limit to 100:
```
cf update-autoscaling-limits example-app 20 100
```
The above command returns output similar to the following example:
```
Updated autoscaling instance limits for app example-app for org example-org / space example-space as user
OK
```

For more information about autoscaling limits, see Autoscaling limits in Using App Autoscaler in production.

Configure scaling factors

To configure scaling factors for an app:

In a terminal window, run:
```
cf update-autoscaling-factors APP-NAME SCALE-UP-FACTOR SCALE-DOWN-FACTOR
```
Where:
- APP-NAME is the name of the app for which you want to configure scaling factors.
- SCALE-UP-FACTOR is the number of app instances by which you want Autoscaler to scale up at a time.
- SCALE-DOWN-FACTOR is the number of app instances by which you want Autoscaler to scale down at a time.
Run the following to configure Autoscaler to scale example-app up by 20 instances at a time and down by 10 instances at a time:
```
cf update-autoscaling-factors example-app 20 10
```
The above command returns output similar to the following example:
```
Updated autoscaling factors for app hello-app in org example-org / space example-space as user
OK
```

For more information about scaling factors, see Scaling factors in Using App Autoscaler in production.

Autoscaling rules and scaling metrics

For information about the scaling metrics you can use when defining autoscaling rules for Autoscaler, see Default metrics for scaling rules and Custom App Metrics for scaling rules in About App Autoscaler.

View all autoscaling rules

To view all autoscaling rules that are configured for an app:

Run:

cf autoscaling-rules APP-NAME

Where APP-NAME is the name of the app for which you want to view all autoscaling rules.

For example, if you run the following, it returns a list of all autoscaling rules that are configured for example-app:

cf autoscaling-rules example-app

The preceding command returns output similar to the following example:

Presenting autoscaler rules for app example-app for org example-org / space example-space as user
Guid                                    Type             Metric   Sub Type   Service Instance   Min Threshold   Max Threshold
45870b7f-f5c9-403f-9150-e79314f62f06    cpu                                                     10              20
10a581c5-8fb4-48a2-b4de-8bc834aac146    http_throughput                                         20              30
OK

Create an autoscaling rule

To create a new autoscaling rule for an app:

Run:
```
cf create-autoscaling-rule APP-NAME RULE-TYPE MINIMUM-THRESHOLD MAXIMUM-THRESHOLD --subtype SUBTYPE --metric METRIC-NAME --comparison-metric COMPARISON-METRIC-NAME --rabbitmq-instance SERVICE-INSTANCE-NAME
```
Where:
- APP-NAME is the name of the app for which you want to create an autoscaling rule.
- RULE-TYPE is the rule type of the autoscaling rule you want to create. Valid values are compare, CPU, custom, http_latency, http_throughput, memory, or rabbitmq.
  Note
  - http_latency threshold units are in milliseconds. In general, the value for MAXIMUM-THRESHOLD should be at least twice the value for MINIMUM-THRESHOLD to avoid excessive cycling. HTTP Request Latency is calculated from the Gorouter to the app and back to the Gorouter. HTTP Request Latency is not calculated between the user and the app.
  - If you specify http_latency as the rule type, you must also specify a rule subtype using the --subtype or -s parameter.
  - If you specify compare as the rule type, you must also specify a scaling metric using the --metric or -m parameter and a comparison metric using the --comparison-metric or -c parameter.
  - If you specify custom as the rule type, you must also specify a scaling metric using the --metric or -m parameter.
- MINIMUM-THRESHOLD is the minimum threshold for the scaling metric.
- MAXIMUM-THRESHOLD is the maximum threshold for the scaling metric.
- (Optional) Include the --subtype or -s parameter to specify a rule subtype, where SUBTYPE is the rule subtype you want to specify. For an http_latency rule, valid values are avg_99th or avg_95th. For a rabbitmq rule, a valid value is the name of the RabbitMQ queue you want Autoscaler to monitor. This queue must be on a RabbitMQ service instance that is bound to the app you want to scale.
- (Optional) Include the --metric or -m parameter to specify a scaling metric for a compare or custom rule, where METRIC-NAME is the name of the scaling metric.
- (Optional) Include the --comparison-metric or -c parameter to specify a comparison metric for a compare rule, where COMPARISON-METRIC-NAME is the name of the metric you want to compare to the scaling metric.
- (Optional) Include the --rabbitmq-instance or -r parameter to specify a RabbitMQ service instance for a rabbitmq rule, where SERVICE-INSTANCE-NAME is the name of the RabbitMQ service instance you want Autoscaler to query. Defining this parameter ensures that Autoscaler does not unnecessarily query other RabbitMQ service instances that are bound to the app.

Delete an autoscaling rule

To delete an autoscaling rule for an app:

View all autoscaling rules for the app for which you want to delete an autoscaling rule by following the procedure in View all Autoscaling rules.
From the Guid column of the terminal output, record the global unique identifier (GUID) of the autoscaling rule you want to delete.
Run:
```
cf delete-autoscaling-rule APP-NAME RULE-GUID
```
Where:
- APP-NAME is the name of the app for which you want to delete an autoscaling rule.
- RULE-GUID is the GUID of the autoscaling rule you want to delete.
Run the following to delete the autoscaling rule with a GUID of 10a581c5-8fb4-48a2-b4de-8bc834aac146 for example-app:
```
cf delete-autoscaling-rule example-app 10a581c5-8fb4-48a2-b4de-8bc834aac146
```
When prompted, enter y to delete the autoscaling rule.

Delete all autoscaling rules

To delete all autoscaling rules for an app:

Run:
```
cf delete-autoscaling-rules APP-NAME
```
Where APP-NAME is the name of the app for which you want to delete all autoscaling rules.

Run the following command to delete all autoscaling rules for example-app:
```
cf delete-autoscaling-rules example-app
```
When prompted, enter y to delete all autoscaling rules for the app.

View autoscaling events

To view a list of autoscaling events that Autoscaler has recorded for an app:

Run:
```
cf autoscaling-events APP-NAME
```
Where APP-NAME is the name of your app.

Run the following command to return a list of all recent autoscaling events that Autoscaler has recorded for example-app:
```
cf autoscaling-events example-app
```
The preceding command returns output similar to the following example:
```
Time                  Description
2032-01-01T00:00:00Z  Scaled up from 3 to 4 instances. Current cpu of 20 is above upper threshold of 10.
```

Scheduled limit changes

To configure scheduled limit changes for Autoscaler, see the following sections.

View all scheduled limit changes

To view all scheduled limit changes for an app:

Run:

cf autoscaling-slcs APP-NAME

Where APP-NAME is the name of the app for which you want to view all scheduled limit changes.

For example, running the following returns a list of all scheduled limit changes configured for example-app:

cf autoscaling-slcs example-app

The above command returns output similar to the following example:

Guid                                      First Execution        Min Instances   Max Instances   Recurrence
f08f9803-6e5d-4519-abc3-fea640300d01      2018-06-12T22:00:00Z   0               1               Mo,Tu,We,Th,Fr

Create a scheduled limit change

To create a scheduled limit change for an app:

Run:
```
cf create-autoscaling-slc APP-NAME TIME LOWER-SCALING-LIMIT UPPER-SCALING-LIMIT --recurrence DAY-1,DAY-2,DAY-3
```
Where:
- APP-NAME is the name of the app.
- TIME is the time, in UTC timestamp format, at which you want Autoscaler to apply the scheduled limit change. For example, 2032-01-01T20:00:00Z.
- You can only configure times for scheduled limit changes in UTC time.
- If the value that you configure for TIME is your local time converted to UTC time, and Daylight Saving Time is observed in your time zone, the UTC offset for your time zone might change during the year.
```
</div>
```
LOWER-SCALING-LIMIT is the minimum number of instances you want Autoscaler to create for the app during the scheduled limit change. If the current number of app instances is fewer than this number at the time of the scheduled limit change, Autoscaler scales the number of app instances up to this number.
UPPER-SCALING-LIMIT is the maximum number of instances you want Autoscaler to create for the app during the scheduled limit change. If the current number of app instances is greater than this number at the time of the scheduled limit change, Autoscaler scales the number of app instances down to this number.
(Optional) Include the --recurrence parameter to specify the days of the week on which you want Autoscaler to re-apply the scheduled limit change, where DAY-1, DAY-2, DAY-3, and so on are the days you want to specify. Valid values are Mo, Tu, We, Th, Fr, Sa, or Su. For example, if you want Autoscaler to re-apply the scheduled limit change on Monday, Wednesday, Friday, and Saturday, include --recurrence Mo,We,Fr,Sa in the preceding command.

Run the following command to configure Autoscaler to create a minimum of one instance and a maximum of two instances of example-app for the first time at 2018-06-14T15:00:00Z UTC and the same time every Saturday afterward:

cf create-autoscaling-slc example-app 2018-06-14T15:00:00Z 1 2 --recurrence Sa

The command returns output similar to the following example:

Created scheduled autoscaler instance limit change for app example-app in org example-org / space example-space as user
OK
Guid                                      First Execution        Min Instances   Maximum Instances   Recurrence
7a19a8a2-e435-4c67-b038-cc4add8be686      2018-06-14T15:00:00Z   1               2               Sa

Delete a scheduled limit change

To delete a scheduled limit change for an app:

View all scheduled limit changes for the app for which you want to delete a scheduled limit change by following the procedure in View all scheduled limit changes.
From the Guid column of the terminal output, record the GUID of the scheduled limit change you want to delete.
Run:
```
cf delete-autoscaling-slc APP-NAME SLC-GUID [--force]
```
Where:
- APP-NAME is the name of the app for which you want to delete a scheduled limit change.
- SLC-GUID is the GUID of the scheduled instance limit change that you recorded in the previous step.
Run the following to delete the scheduled limit change with a GUID of d0077dc5-34bd-42c7-b377-e0fcb14d67f3 for example-app:
```
cf delete-autoscaling-slc example-app d0077dc5-34bd-42c7-b377-e0fcb14d67f3
```
When prompted, enter y to delete the scheduled limit change.

Configure Autoscaler by using a manifest file

You can configure autoscaling rules, scaling limits, and scheduled limit changes for Autoscaler declaratively through a manifest file. This manifest file only configures Autoscaler, and does not interfere with any other existing app manifest files in your TAS for VMs deployment.

To configure Autoscaler using a manifest file:

Create a YAML file that includes the following configuration parameters:
```
---
instance_limits:
  min: LOWER-SCALING-LIMIT
  max: UPPER-SCALING-LIMIT
rules:
- rule_type: RULE-TYPE
  threshold:
    min: MINIMUM-METRIC-THRESHOLD
    max: MAXIMUM-METRIC-THRESHOLD
scheduled_limit_changes:
- recurrence: RECURRENCE
  executes_at: "TIME"
  instance_limits:
    min: SCHEDULED-LOWER-SCALING-LIMIT
    max: SCHEDULED-UPPER-SCALING-LIMIT
scaling_factors:
 up: SCALE-UP-FACTOR
 down: SCALE-DOWN-FACTOR
```
Where:
- instance_limits
- rules (Optional)
  - If you do not want to configure autoscaling rules for an app, omit the block or include an empty one: rules: []. Any pre-existing rules will be deleted when applying the manifest.
  - RULE-TYPE is the type of autoscaling rule you want Autoscaler to use for autoscaling decisions. For more information about configuring autoscaling rules using a manifest file, see Using HTTP Request Latency as a scaling metric, Using RabbitMQ queue depth as a scaling metric, and Using custom scaling metrics.
  - MINIMUM-METRIC-THRESHOLD is the minimum scaling metric threshold. If the average value of the scaling metric falls below this number, Autoscaler scales the number of app instances down.
  - MAXIMUM-METRIC-THRESHOLD is the maximum custom scaling metric threshold. If the average custom scaling metric rises above this number, Autoscaler scales the number of app instances up.
- scheduled_limit_changes (Optional)
  - If you do not want to configure scheduled limit changes for an app, omit the block or include an empty one: scheduled_limit_changes: []. Any pre-existing scheduled limit changes will be deleted when applying the manifest.
  - RECURRENCE is the calculated value of the bitmasked days of the week on which you want Autoscaler to re-apply the scheduled limit change. For more information, see Calculating a recurrence schedule value in Scheduled limit changes.
  - TIME is the time, in UTC timestamp format, at which you want Autoscaler to apply the scheduled limit change. For example, 2032-01-01T20:00:00Z. If the value that you configure for TIME is your local time converted to UTC time, and Daylight Saving Time is observed in your time zone, the UTC offset for your time zone might change during the year.
  - SCHEDULED-LOWER-SCALING-LIMIT is the minimum number of instances you want Autoscaler to create for the app during the scheduled limit change. If the current number of app instances is fewer than this number at the time of the scheduled limit change, Autoscaler scales the number of app instances up to this number.
  - SCHEDULED-UPPER-SCALING-LIMIT is the maximum number of instances you want Autoscaler to create for the app during the scheduled limit change. If the current number of app instances is greater than this number at the time of the scheduled limit change, Autoscaler scales the number of app instances down to this number.
- scaling_factors (Optional)
  - If you do not want to configure scaling factors for an app, omit the block or include an empty one: scaling_factors: {}. Any pre-existing scaling factors will be reset to the default values of 1 and 1 when applying the manifest.
  - SCALE-UP-FACTOR is the number of app instances by which you want Autoscaler to scale up at a time.
  - SCALE-DOWN-FACTOR is the number of app instances by which you want Autoscaler to scale down at a time.
Apply the manifest file you configured in the previous step to the app you want to scale by running:
```
cf configure-autoscaling APP-NAME MANIFEST-FILENAME
```
Where:
- APP-NAME is the name of the app.
- MANIFEST-FILENAME is the filename of the manifest file you created in the previous step. For example, autoscaler.yml.
Run the following command to apply the autoscaler.yml manifest file to example-app:
```
cf configure-autoscaling example-app autoscaler-manifest.yml
```
The above command returns output similar to the following example:
```
Setting autoscaler settings for app example-app for org example-org / space example-space as user
OK
```