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.
Before you can run App Autoscaler CLI commands, you must install the App Autoscaler CLI Plug-in.
To install the plug-in:
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 Broadcom Support. 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.
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.
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
This 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:
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 Cooldown Period example-app d0077dc5-34bd-42c7-b377-e0fcb14d67f3 true 1 4 1 1 1m30s example-app-2 3f8c6e84-0b6e-4ec9-9335-0aad3979d672 false 10 40 5 2 0s OK
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.
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
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 command, 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.
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.For example, if you run the following command, it configures 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.
Apps may benefit from a cooldown period after scaling, during which no further automatic scaling occurs. This cooldown period only applies to actions performed by App Autoscaler, not to manual scaling via cf push
or cf scale
commands. By default, apps have no cooldown period, so the CLI command cf autoscaling-apps
will show a value of 0s
.
Consider an app configured with a cooldown period of 60s
and the default 35-second scaling interval. If App Autoscaler scales the app up, the next potential scaling decision (35 seconds later) is skipped because the cooldown period hasn’t elapsed. However, at the second interval (70 seconds after the initial scale-up), App Autoscaler reevaluates scaling since the cooldown period has ended.
In addition to the relationship between the startup time for an app and its configured cooldown period, also consider the metric interval for the app. Because the metric interval looks into the past from the time of a scaling interval, it may consider the metrics for an app still starting up in the first scaling interval after a cooldown period. Consider setting cooldown period in accordance with the metric interval to ensure an app with a long startup time does not trigger a false scaling decision based on metrics for an app that was still starting up.
To configure the cooldown period for an app:
In a terminal window, run:
cf update-autoscaling-cooldown APP-NAME COOLDOWN-PERIOD
Where:
APP-NAME
is the name of the app for which you want to configure scaling factors.COOLDOWN-PERIOD
is the time duration (45s
, 3m
, 25m30s
) to wait after scaling, during which no further automatic scaling occurs.For example, the following command configures App Autoscaler to only consider example-app
for further scaling at least two minutes after an autoscaling action is performed:
cf update-autoscaling-cooldown example-app 2m
The output looks similar to this:
Updated cooldown period for app example-app in org example-org / space example-space as admin OK
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.
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
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
.
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.http_latency
as the rule type, you must also specify a rule subtype using the --subtype
or -s
parameter.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.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.--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.--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.--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.--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.See also:
For information about configuring Autoscaler to use HTTP Request Latency as the scaling metric for an app, see Using HTTP Request Latency as a scaling metric.
For more information about configuring Autoscaler to use RabbitMQ queue depth as the scaling metric for an app, see Using RabbitMQ queue depth as a scaling metric.
For more information about configuring Autoscaler to use a custom scaling metric as the scaling metric for an app, see Using custom scaling metrics.
For information about configuring Autoscaler to use CPU Entitlement Usage as the scaling metric for an app, see Using CPU Entitlement Utilization as a scaling metric.
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.
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.
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.
To configure scheduled limit changes for Autoscaler, see the following sections.
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
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
. 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.--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
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.
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
cooldown_period: COOLDOWN-PERIOD
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
LOWER-SCALING-LIMIT
is the minimum number of instances that you want Autoscaler to create for the app by default.UPPER-SCALING-LIMIT
is the maximum number of instances that you want Autoscaler to create for the app by default.rules
(Optional)
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.cooldown_period
(Optional)
0s
when applying the manifest.COOLDOWN-PERIOD
is the time duration (45s
, 3m
, 25m30s
) to wait after scaling, during which no further automatic scaling occurs.scheduled_limit_changes
(Optional)
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)
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