Using the App Autoscaler CLI
- Install the App Autoscaler CLI Plugin
- Create and Bind the Autoscaling Service
- View Apps
- Update Instance Limits
- Enable Autoscaling
- Disable Autoscaling
- View Rules
- Create a Rule
- Valid Rule Types and Subtypes
- Delete a Rule
- Delete All Rules
- View Autoscaling Events
- View Autoscaler Scheduled Instance Limit Changes
- Create Autoscaler Scheduled Instance Limit Change
- Delete Autoscaler Scheduled Instance Limit Change
- Configure with a Manifest
- App Autoscaler CLI Known Issues
Page last updated:
Warning: Pivotal Cloud Foundry (PCF) v2.4 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.
This topic explains how to use the App Autoscaler command-line interface (CLI).
The App Autoscaler automatically scales Cloud Foundry apps in response to demand. The App Autoscaler CLI lets you control the App Autoscaler from your local command line by extending the Cloud Foundry command-line interface (cf CLI).
Install the App Autoscaler CLI Plugin
Before you can run App Autoscaler CLI commands on your local machine, you must install the App Autoscaler CLI plugin.
To install the plugin, do the following:
Download the plugin from Pivotal Network.
Note: Ensure that you download the App Autoscaler CLI plugin v2.0 or later. In addition, the plugin requires Pivotal Application Service v2.2 or later.
To install the App Autoscaler CLI plugin, run the following command:
cf install-plugin LOCATION-OF-PLUGIN
Where
LOCATION-OF-PLUGIN
is the path to the binary file you downloaded from Pivotal Network. For example:$ cf install-plugin ~/Downloads/autoscaler-for-pcf-cliplugin-macosx64-binary-2.0.91
For more information about installing cf CLI plugins, see Installing a Plugin.
Create and Bind the Autoscaling Service
Before you can use the App Autoscaler, you must create an Autoscaling service and bind that service to your app. See the Managing Service Instances with the cf CLI topic for more information.
View Apps
Run cf autoscaling-apps
to view all the apps that are bound to an autoscaler service instance in a space, their instance limits, and whether or not they are enabled.
$ cf autoscaling-apps
Presenting autoscaler apps in org my-org / my-space autoscaling as user Name Guid Enabled Min Instances Max Instances test-app guid true 1 4 test-app-2 guid-2 false 10 40 OK
Update Instance Limits
Run cf update-autoscaling-limits APP-NAME MIN-INSTANCE-LIMIT MAX-INSTANCE-LIMIT
to update the upper and lower app instance limits. The App Autoscaler will not attempt to scale beyond these limits. Replace APP-NAME
with the name of your app. Replace MIN-INSTANCE-LIMIT
with the minimum number of apps, and MAX-INSTANCE-LIMIT
with the maximum number of apps.
$ cf update-autoscaling-limits test-app 10 40
Updated autoscaling instance limits for app test-app for org my-org / my-space testing as admin OK
Enable Autoscaling
Run cf enable-autoscaling APP-NAME
to enable autoscaling on your app. Replace APP-NAME
with the name of your app.
$ cf enable-autoscaling test-app-2
Enabled autoscaling for app test-app-2 for org my-org / my-space testing as admin OK
Note: By default, instance limits are set to Min Instances:-1
and Max Instances:-1
. To enable autoscaling, you must first Update Instance Limits.
Disable Autoscaling
Run cf disable-autoscaling APP-NAME
to disable autoscaling on your app. Replace APP-NAME
with the name of your app.
$ cf disable-autoscaling test-app
Disabled autoscaling for app test-app for org my-org / my-space testing as admin OK
View Rules
Run cf autoscaling-rules APP-NAME
to view the rules that the App Autoscaler uses to determine when to scale your app. Replace APP-NAME
with the name of your app.
$ cf autoscaling-rules test-app
Presenting autoscaler rules for app test-app for org my-org / my-space autoscaling as user Rule Guid Rule Type Rule Sub Type Min Threshold Max Threshold guid cpu 10 20 guid-2 http_throughput 20 30 OK
Create a Rule
Run cf create-autoscaling-rule APP-NAME RULE-TYPE MIN-THRESHOLD MAX-THRESHOLD [--subtype SUBTYPE] [--metric METRIC] [--comparison-metric COMPARISON-METRIC]
to create a new autoscaling rule.
Replace the placeholders as follows:
APP-NAME
is the name of your app.RULE-TYPE
is the type of your scaling rule.MIN-THRESHOLD
is the minimum threshold for the metric.MAX-THRESHOLD
is the maximum threshold for the metric.
You can use the following command options:
--metric
,-m
is the metric for a Custom rule.--comparison-metric
,-c
is the comparison metric for a Compare rule.--subtype
,-s
is the rule subtype.
For example:
$ cf create-autoscaling-rule test-app http_latency 10 20 -s avg_99th
Created autoscaler rule for app test-app for org my-org / space my-space as user Rule Guid Rule Type Rule Sub Type Min Threshold Max Threshold guid-3 http_latency avg_99th 10 20
$ cf create-autoscaling-rule test-app custom 9380 9381 --metric jvm.classes.loaded Created autoscaler rule for app test-app in org my-org / space my-space as user OK Guid Type Metric Sub Type Min Threshold Max Threshold guid-7 custom jvm.classes.loaded 9380.00 9381.00
$ cf create-autoscaling-rule test-app compare .79 .8 --metric jvm.memory.used --comparison-metric jvm.memory.max Created autoscaler rule for app test-app in org my-org / space my-space as user OK Guid Type Metric Sub Type Min Threshold Max Threshold guid-8 compare jvm.memory.used / jvm.memory.max 0.79 0.80
Valid Rule Types and Subtypes
For a list of valid types and subtypes, see the following:
- type
CPU
- type
memory
- type
http_throughput
- type
http_latency
- sub_type
avg_99th
oravg_95th
Note:
http_latency
requires a rulesubtype
.Note:
http_latency
threshold units are in ms.
- sub_type
- type
rabbitmq
- sub_type
YOUR-QUEUE-NAME
- sub_type
- type
custom
- metric
METRIC-NAME
- metric
- type
compare
- metric
METRIC-NAME
- comparison_metric
METRIC-NAME
- metric
Delete a Rule
Run cf delete-autoscaling-rule APP-NAME RULE-GUID [--force]
to delete a single autoscaling rule. Replace APP-NAME
with the name of your app, and replace RULE-GUID
with the GUID.
$ cf delete-autoscaling-rule test-app guid-2
Really delete rule guid-2 for app test-app?> [yN]:y Deleted rule guid-2 for autoscaler app test-app for org my-org / space my-space as admin OK
Delete All Rules
Run cf delete-autoscaling-rules APP-NAME [--force]
to delete all autoscaling rules. Replace APP-NAME
with the name of your app.
$ cf delete-autoscaling-rules test-app
Really delete ALL rules for app test-app?> [yN]:y Deleted rules for autoscaler app test-app for org my-org / space my-space as admin OK
View Autoscaling Events
Run cf autoscaling-events APP-NAME
to view recent events related to autoscaling for your app. Replace APP-NAME
with the name of your app.
$ cf autoscaling-events test-app
Time Description 2032-01-01T00:00:00Z Scaled up from 3 to 4 instances. Current cpu of 20 is above upper threshold of 10.
View Autoscaler Scheduled Instance Limit Changes
Run cf autoscaling-slcs APP-NAME
to view all scheduled instance limit changes. Replace APP-NAME
with the name of your app.
For example:
$ cf autoscaling-slcs test-app
Guid First Execution Min Instances Max Instances Recurrence guid-5 2018-06-12T22:00:00Z 0 1 Mo,Tu,We,Th,Fr
Create Autoscaler Scheduled Instance Limit Change
Run cf create-autoscaling-slc APP-NAME DATE-TIME MIN-INSTANCES MAX-INSTANCES [--recurrence RECURRENCE]
to create a new scheduled instance limit change.
Replace the placeholders as follows:
APP-NAME
is the name of your app.DATE-TIME
is the date and time of the change.MIN-INSTANCES
andMAX-INSTANCES
are the minimum and maximum values of the range within which App Autoscaler can change the instance count for an app.RECURRENCE
(optional) is the day of the week for which you want to repeat the change.
For example:
$ cf create-autoscaling-slc test-app 2018-06-14T15:00:00Z 1 2 --recurrence Sa
Created scheduled autoscaler instance limit change for app test-app in org my-org / space my-space as user OK Guid First Execution Min Instances Max Instances Recurrence guid-6 2018-06-14T15:00:00Z 1 2 Sa
Delete Autoscaler Scheduled Instance Limit Change
Run cf delete-autoscaling-slc APP-NAME SLC-GUID [--force]
to delete a scheduled instance limit change.
Replace APP-NAME
with the name of your app and SLC-GUID
with the GUID of your scheduled instance limit change.
For example:
$ cf delete-autoscaling-slc test-app slc-guid
Really delete scheduled limit change slc-guid for app test-app?> [yN]:y Deleted scheduled limit change slc-guid for app test-app in org my-org / space my-space as user OK
Configure with a Manifest
Run cf configure-autoscaling APP-NAME MANIFEST-FILE-PATH
to use a service manifest to configure your rules, add instance limits, and set scheduled limit changes at the same time. Replace APP-NAME
with the name of your app, and replace MANIFEST-FILE-PATH
with the path and name of your Autoscaler manifest.
An example manifest:
--- instance_limits: min: 1 max: 2 rules: - rule_type: "http_latency" rule_sub_type: "avg_99th" threshold: min: 10 max: 20 scheduled_limit_changes: - recurrence: 10 executes_at: "2032-01-01T00:00:00Z" instance_limits: min: 10 max: 20
$ cf configure-autoscaling test-app autoscaler-manifest.yml
Setting autoscaler settings for app test-app for org my-org / space my-space as user OK
A rules
block must be present in your Autoscaler manifest. If your app does not require any rules changes, include an empty block:
--- instance_limits: min: 1 max: 1 rules: [] scheduled_limit_changes: - recurrence: 365 executes_at: "2032-01-01T00:00:00Z" instance_limits: min: 0 max: 0
A scheduled_limit_changes
block must be present in your Autoscaler manifest. If your app does not require any scheduled instance limit changes, include an empty block:
--- instance_limits: min: 1 max: 2 rules: - rule_type: "http_latency" rule_sub_type: "avg_99th" threshold: min: 10 max: 20 scheduled_limit_changes: []
App Autoscaler CLI Known Issues
The App Autoscaler CLI has the following known issues:
The CLI returns an error message if you have more than one instance of the App Autoscaler service running in the same space.
- To prevent this error, delete all but one App Autoscaler service instance from any space that the App Autoscaler service runs in.
The CLI may output 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 run App Autoscaler CLI commands. - Note that some Windows shells do not support the
CF_COLOR
setting.
- To prevent this error, run