Using the App Autoscaler CLI

Page last updated:

This topic explains how to use the App Autoscaler command-line interface (CLI).

The App Autoscaler automatically scales VMware Tanzu Application Service for VMs (TAS for VMs) 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:

  1. Download the plugin from VMware Tanzu Network.

  2. 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 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 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. For more information, see Managing Service Instances with the cf CLI.

View Apps

Run cf autoscaling-apps to view 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 / space my-space as user
Name                  Guid                                      Enabled   Min Instances   Max Instances   Scale Up Factor   Scale Down Factor
test-app              d0077dc5-34bd-42c7-b377-e0fcb14d67f3      true      1               4               1                 1
test-app-2            3f8c6e84-0b6e-4ec9-9335-0aad3979d672      false     10              40              5                 2
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 does 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 / space my-space as user
OK

Update Scaling Factors

Run cf update-autoscaling-factors APP-NAME SCALE-UP-FACTOR SCALE-DOWN-FACTOR to update the app scaling factors. The App Autoscaler uses these factors to decide how many instances of your app to scale up or down. Replace APP-NAME with the name of your app. Replace SCALE-UP-FACTOR with the number of instances to scale up at a time, and SCALE-DOWN-FACTOR with the number of instances to scale down at a time.

$ cf update-autoscaling-factors test-app 3 2

Updated autoscaling factors for app hello-app in org my-org / space my-space as user
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 / space my-space as user
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. See Update Instance Limits above.

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 / space my-space as user
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 / space my-space as user
Rule Guid                               Rule Type         Rule Sub Type   Min Threshold   Max Threshold
45870b7f-f5c9-403f-9150-e79314f62f06    cpu                               10              20
10a581c5-8fb4-48a2-b4de-8bc834aac146    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 500 1000 -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
a4a1292f-6f1d-486b-96f7-fc5b4bb9b27d    http_latency      avg_99th        500             1000

$ 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
59365c9d-6fe7-4195-b8c1-0f5b07afd636    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
93c4b831-0155-4771-8842-3247816e71df    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 custom
    • metric METRIC-NAME
  • type CPU
  • type memory
  • type http_throughput

    Note: VMware does not recommend using http_throughput as a scaling rule when logging volume is high in the system. For more information, see HTTP throughput based Autoscaling rules do not fire in the Knowledge Base.

  • type http_latency
    • sub_type avg_99th or avg_95th

      Note: http_latency requires a rule subtype.

      Note: http_latency threshold units are in ms.
      In general, the value for MAX-THRESHOLD should be at least twice the value for MIN-THRESHOLD to avoid excessive cycling. Latency is calculated from the Gorouter to the app and back to the Gorouter. Latency is not calculated between the user and the app.

  • type rabbitmq
    • sub_type YOUR-QUEUE-NAME
  • type compare
    • metric METRIC-NAME
    • comparison_metric METRIC-NAME

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 10a581c5-8fb4-48a2-b4de-8bc834aac146

Really delete rule 10a581c5-8fb4-48a2-b4de-8bc834aac146 for app test-app?> [yN]:y
Deleted rule 10a581c5-8fb4-48a2-b4de-8bc834aac146 for autoscaler app test-app for org my-org / space my-space as user
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 user
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 App 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
f08f9803-6e5d-4519-abc3-fea640300d01      2018-06-12T22:00:00Z   0               1               Mo,Tu,We,Th,Fr

Create App 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 and MAX-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
7a19a8a2-e435-4c67-b038-cc4add8be686      2018-06-14T15:00:00Z   1               2               Sa

Note: App Autoscaler only supports times in UTC. App Autoscaler does not support setting alternate timezones or Daylight Saving Time

Delete App 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 d0077dc5-34bd-42c7-b377-e0fcb14d67f3

Really delete scheduled limit change d0077dc5-34bd-42c7-b377-e0fcb14d67f3 for app test-app?> [yN]:y
Deleted scheduled limit change d0077dc5-34bd-42c7-b377-e0fcb14d67f3 for app test-app in org my-org / space my-space as user
OK

Configure Autoscaling 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 App Autoscaler manifest.

An example manifest:

---
instance_limits:
  min: 1
  max: 2
scaling_factors:
  up: 3
  down: 2
rules:
- rule_type: "http_latency"
  rule_sub_type: "avg_99th"
  threshold:
    min: 500
    max: 1000
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 App 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: 42
  executes_at: "2032-01-01T00:00:00Z"
  instance_limits:
    min: 0
    max: 0

A scheduled_limit_changes block must be present in your App 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: 500
     max: 1000
scheduled_limit_changes: []

Create a Scheduled Limit Change

To create a scheduled limit change using the App Autoscaler manifest, you must understand how scheduled limit changes are constructed. App Autoscaler uses the executes at value in two ways:

  1. App Autoscaler uses date and time to set the first (or only) occurrence of a scheduled limit change.
  2. App Autoscaler then uses the time component to set the time of day in UTC for each recurrence. App Autoscaler uses this time of day for all subsequent scheduled limit changes.

When setting a recurrence schedule, the days of the week are bitmasked.

To instruct App Autoscaler when to execute a scheduled limit change, add together the bitmasked values for each of the day(s) of the week that you wish to trigger the scheduled limit change using this table.

Day Su Mo Tu We Th Fr Sa
Value 64 32 16 8 4 2 1

Then set the recurrence field to that value.

Examples of Recurrence Specification

The following are examples of how to calculate a value for the recurrence field of a scheduled limit change:

  • To schedule on weekdays, you add (32+16+8+4+2)=62. Set recurrence: 62.
  • To schedule on weekends, you add (64+1)=54. Set recurrence: 65.
  • To schedule every day, you add (64+32+16+8+4+2+1)=127. Set recurrence: 127.
  • To schedule on Monday, Wednesday, and Friday, you add (32+8+2)=42. Set recurrence: 42.

The following is an example manifest to scale down every Friday at 8pm and back up every Monday at 4am assuming a UTC timezone:

---
instance_limits:
  min: 6
  max: 12
scaling_factors:
  up: 3
  down: 2
rules:
- rule_type: "http_latency"
  rule_sub_type: "avg_99th"
  threshold:
    min: 500
    max: 1000
scheduled_limit_changes:
- recurrence: 32
  executes_at: "2032-01-01T20:00:00Z"
  instance_limits:
    min: 1
    max: 3
- recurrence: 2
  executes_at: "2032-01-01T04:00:00Z"
  instance_limits:
    min: 6
    max: 12

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.