Using the App Autoscaler CLI

Page last updated:

This topic explains how to use the App Autoscaler Command-Line Interface (CLI).

Overview of the App Autoscaler CLI

The App Autoscaler CLI is an extension of the Cloud Foundry Command-Line Interface (cf CLI) that allows you to configure and control Autoscaler from your local command line.

Note: The return output from the App Autoscaler CLI may 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 Plugin

Before you can run App Autoscaler CLI commands, you must install the App Autoscaler CLI Plugin.

To install the plugin:

  1. Download the VMware Tanzu App Autoscaler CLI Plugin from VMware Tanzu Network.

    Note: 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.

  2. 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 plugins, see Install a Plugin 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:

  1. In a terminal window, target the space in which the app you want to scale is deployed 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.
  2. 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.
  3. Bind the Autoscaler service instance you created in the previous 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.

Note: 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 Allowed 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:

  1. 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.
  2. 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 allow autoscaling for an app:

  1. Run:

    cf enable-autoscaling APP-NAME
    

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

    For example, running the following command 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
    

Note: 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 below.

Disallow Autoscaling

To disallow autoscaling for an app:

  1. Run:

    cf disable-autoscaling APP-NAME
    

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

    For example, running the following command disallows Autoscaler from scaling example-app:

    cf disable-autoscaling example-app
    

    The above command returns output similar to the following example:

    Disabled 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:

  1. 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, running the following command 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:

  1. 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, running the following command 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.

Autoscaling Rules and Scaling Metrics

To configure autoscaling rules for Autoscaler to use when making scaling decisions for an app, see the sections below:

For more information about scaling metrics for which you can configure autoscaling rules, see Scaling Metrics in Using App Autoscaler in Production.

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

View All Autoscaling Rules

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

  1. 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, running the following command returns a list of all autoscaling rules that are configured for example-app:

    cf autoscaling-rules example-app
    

    The above 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:

  1. 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.
      Notes:
      • 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.
      • 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 latency is calculated from the Gorouter to the app and back to the Gorouter. HTTP 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.

For more information about configuring Autoscaler to use HTTP latency as the scaling metric for an app, see Using HTTP 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.

Delete an Autoscaling Rule

To delete an autoscaling rule for an app:

  1. 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 above.

  2. From the Guid column of the terminal output, record the global unique identifier (GUID) of the autoscaling rule you want to delete.

  3. 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.

      For example, running the following command deletes 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
    
  4. When prompted, enter y to delete the autoscaling rule.

Delete All Autoscaling Rules

To delete all autoscaling rules for an app:

  1. 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.

    For example, running the following command deletes all autoscaling rules for example-app:

    cf delete-autoscaling-rules example-app
    
  2. 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:

  1. Run:

    cf autoscaling-events APP-NAME
    

    Where APP-NAME is the name of your app.

    For example, running the following command returns a list of all recent autoscaling events that Autoscaler has recorded for example-app:

    cf autoscaling-events example-app
    

    The above 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 sections below:

For more information about scheduled limit changes, see Scheduled Limit Changes.

View All Scheduled Limit Changes

To view all scheduled limit changes for an app:

  1. 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:

  1. 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.
      Notes:
      • 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 may change during the year.
    • 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 above command.

      For example, running the following command configures 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 above 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   Max 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:

  1. 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 above.

  2. From the Guid column of the terminal output, record the GUID of the scheduled limit change you want to delete.

  3. 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.

      For example, running the following command deletes 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
    
  4. When prompted, enter y to delete the scheduled limit change.

Configure Autoscaler 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:

  1. 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
    

    Where:

    • 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.
    • (Optional) If you include a rules block:
    • 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.
    • (Optional) If you include a scheduled_limit_changes block:
      • 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.

        Note: 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 may 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.

        You must include both a rules block and a scheduled_limit_changes block must be present in your Autoscaler manifest. If you do not want to configure autoscaling rules for an app, include an empty rules block. If you do not want to configure scheduled limit changes for an app, include an empty scheduled-limit-changes block.
  2. 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.

      For example, running the following command applies 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