Command Line Usage

awslimitchecker ships with a command line script for use outside of Python environments. awslimitchecker is installed as a setuptools entry point, and will be available wherever you install the package (if you install in a virtual environment as recommended, it will be in the venv’s bin/ directory).

The command line script provides simple access to the most common features, though not full access to all configuration possibilities. In addition, when checking usage, the script will exit 0 of everything is OK, 1 if there are warnings, and 2 if there are critical thresholds exceeded (though the output is not currently suitable for direct use as a Nagios-compatible plugin).

(venv)$ awslimitchecker --help
usage: awslimitchecker [-h] [-S [SERVICE ...]] [--skip-service SKIP_SERVICE]
                       [--skip-check SKIP_CHECK] [-s] [-l] [--list-defaults]
                       [-L LIMIT] [--limit-override-json LIMIT_OVERRIDE_JSON]
                       [--threshold-override-json THRESHOLD_OVERRIDE_JSON]
                       [-u] [--iam-policy] [-W WARNING_THRESHOLD]
                       [-C CRITICAL_THRESHOLD] [-P PROFILE_NAME]
                       [-A STS_ACCOUNT_ID] [-R STS_ACCOUNT_ROLE]
                       [-E EXTERNAL_ID] [-M MFA_SERIAL_NUMBER] [-T MFA_TOKEN]
                       [-r REGION] [--role-partition ROLE_PARTITION]
                       [--ta-api-region TA_API_REGION] [--skip-ta]
                       [--skip-quotas]
                       [--ta-refresh-wait | --ta-refresh-trigger | --ta-refresh-older TA_REFRESH_OLDER]
                       [--ta-refresh-timeout TA_REFRESH_TIMEOUT] [--no-color]
                       [--no-check-version] [-v] [-V]
                       [--list-metrics-providers]
                       [--metrics-provider METRICS_PROVIDER]
                       [--metrics-config METRICS_CONFIG]
                       [--list-alert-providers]
                       [--alert-provider ALERT_PROVIDER]
                       [--alert-config ALERT_CONFIG]
Report on AWS service limits and usage via boto3, optionally warn about any
services with usage nearing or exceeding their limits. For further help, see
<http://awslimitchecker.readthedocs.org/>
optional arguments:
  -h, --help            show this help message and exit
  -S [SERVICE ...], --service [SERVICE ...]
                        perform action for only the specified service name;
                        see -s|--list-services for valid names
  --skip-service SKIP_SERVICE
                        avoid performing actions for the specified service
                        name; see -s|--list-services for valid names
  --skip-check SKIP_CHECK
                        avoid performing actions for the specified check name
  -s, --list-services   print a list of all AWS service types that
                        awslimitchecker knows how to check
  -l, --list-limits     print all AWS effective limits in
                        "service_name/limit_name" format
  --list-defaults       print all AWS default limits in
                        "service_name/limit_name" format
  -L LIMIT, --limit LIMIT
                        override a single AWS limit, specified in
                        "service_name/limit_name=value" format; can be
                        specified multiple times.
  --limit-override-json LIMIT_OVERRIDE_JSON
                        Absolute or relative path, or s3:// URL, to a JSON
                        file specifying limit overrides. See docs for expected
                        format.
  --threshold-override-json THRESHOLD_OVERRIDE_JSON
                        Absolute or relative path, or s3:// URL, to a JSON
                        file specifying threshold overrides. See docs for
                        expected format.
  -u, --show-usage      find and print the current usage of all AWS services
                        with known limits
  --iam-policy          output a JSON serialized IAM Policy listing the
                        required permissions for awslimitchecker to run
                        correctly.
  -W WARNING_THRESHOLD, --warning-threshold WARNING_THRESHOLD
                        default warning threshold (percentage of limit);
                        default: 80
  -C CRITICAL_THRESHOLD, --critical-threshold CRITICAL_THRESHOLD
                        default critical threshold (percentage of limit);
                        default: 99
  -P PROFILE_NAME, --profile PROFILE_NAME
                        Name of profile in the AWS cross-sdk credentials file
                        to use credentials from; similar to the corresponding
                        awscli option
  -A STS_ACCOUNT_ID, --sts-account-id STS_ACCOUNT_ID
                        for use with STS, the Account ID of the destination
                        account (account to assume a role in)
  -R STS_ACCOUNT_ROLE, --sts-account-role STS_ACCOUNT_ROLE
                        for use with STS, the name of the IAM role to assume
  -E EXTERNAL_ID, --external-id EXTERNAL_ID
                        External ID to use when assuming a role via STS
  -M MFA_SERIAL_NUMBER, --mfa-serial-number MFA_SERIAL_NUMBER
                        MFA Serial Number to use when assuming a role via STS
  -T MFA_TOKEN, --mfa-token MFA_TOKEN
                        MFA Token to use when assuming a role via STS
  -r REGION, --region REGION
                        AWS region name to connect to; required for STS
  --role-partition ROLE_PARTITION
                        AWS partition name to use for account_role when
                        connecting via STS; see documentation for more
                        information (default: "aws")
  --ta-api-region TA_API_REGION
                        Region to use for Trusted Advisor / Support API
                        (default: us-east-1)
  --skip-ta             do not attempt to pull *any* information on limits
                        from Trusted Advisor
  --skip-quotas         Do not attempt to connect to Service Quotas service or
                        use its data for current limits
  --ta-refresh-wait     If applicable, refresh all Trusted Advisor limit-
                        related checks, and wait for the refresh to complete
                        before continuing.
  --ta-refresh-trigger  If applicable, trigger refreshes for all Trusted
                        Advisor limit-related checks, but do not wait for them
                        to finish refreshing; trigger the refresh and continue
                        on (useful to ensure checks are refreshed before the
                        next scheduled run).
  --ta-refresh-older TA_REFRESH_OLDER
                        If applicable, trigger refreshes for all Trusted
                        Advisor limit-related checks with results more than
                        this number of seconds old. Wait for the refresh to
                        complete before continuing.
  --ta-refresh-timeout TA_REFRESH_TIMEOUT
                        If waiting for TA checks to refresh, wait up to this
                        number of seconds before continuing on anyway.
  --no-color            do not colorize output
  --no-check-version    do not check latest version at startup
  -v, --verbose         verbose output. specify twice for debug-level output.
  -V, --version         print version number and exit.
  --list-metrics-providers
                        List available metrics providers and exit
  --metrics-provider METRICS_PROVIDER
                        Metrics provider class name, to enable sending metrics
  --metrics-config METRICS_CONFIG
                        Specify key/value parameters for the metrics provider
                        constructor. See documentation for further
                        information.
  --list-alert-providers
                        List available alert providers and exit
  --alert-provider ALERT_PROVIDER
                        Alert provider class name, to enable sending
                        notifications
  --alert-config ALERT_CONFIG
                        Specify key/value parameters for the alert provider
                        constructor. See documentation for further
                        information.
awslimitchecker is AGPLv3-licensed Free Software. Anyone using this program,
even remotely over a network, is entitled to a copy of the source code. Use
`--version` for information on the source code location.

Examples

In the following examples, output has been truncated to simplify documentation. When running with all services enabled, awslimitchecker will provide many lines of output. (...) has been inserted in the output below to denote removed or truncated lines.

Listing Supported Services

View the AWS services currently supported by awslimitchecker with the -s or --list-services option.

(venv)$ awslimitchecker -s
ApiGateway
AutoScaling
CloudFormation
CloudTrail
Directory Service
(...)
Route53
S3
SES
VPC

Listing Default Limits

To show the hard-coded default limits, ignoring any limit overrides or Trusted Advisor data, run with --list-defaults:

(venv)$ awslimitchecker --list-defaults
ApiGateway/API keys per account                                           500
ApiGateway/Client certificates per account                                60
ApiGateway/Custom authorizers per API                                     10
ApiGateway/Documentation parts per API                                    2000
ApiGateway/Edge APIs per account                                          120
(...)
Lambda/Function Count                                                     None
(...)
VPC/Subnets per VPC                                                       200
VPC/VPCs                                                                  5
VPC/Virtual private gateways                                              5

Viewing Limits

View the limits that awslimitchecker currently knows how to check, and what the limit value is set as (if you specify limit overrides, they will be used instead of the default limit) by specifying the -l or --list-limits option. Limits followed by (TA) have been obtained from Trusted Advisor and limits followed by (API) have been obtained from the service’s API.

(venv)$ awslimitchecker -l
ApiGateway/API keys per account                                           500.0 (Quotas)
ApiGateway/Client certificates per account                                60.0 (Quotas)
ApiGateway/Custom authorizers per API                                     10
ApiGateway/Documentation parts per API                                    2000
ApiGateway/Edge APIs per account                                          120.0 (Quotas)
(...)
AutoScaling/Auto Scaling groups                                           200 (API)
(...)
Lambda/Function Count                                                     None
(...)
VPC/Subnets per VPC                                                       200.0 (Quotas)
VPC/VPCs                                                                  5.0 (Quotas)
VPC/Virtual private gateways                                              5

Disabling Service Quotas service

Using the --skip-quotas option will disable attempting to query limit information from the Service Quotas service.

(venv)$ awslimitchecker -l --skip-quotas
ApiGateway/API keys per account                                           500
ApiGateway/Client certificates per account                                60
ApiGateway/Custom authorizers per API                                     10
ApiGateway/Documentation parts per API                                    2000
ApiGateway/Edge APIs per account                                          120
(...)
AutoScaling/Auto Scaling groups                                           200 (API)
(...)
Lambda/Function Count                                                     None
(...)
VPC/Subnets per VPC                                                       200
VPC/VPCs                                                                  5
VPC/Virtual private gateways                                              5

Disabling Trusted Advisor Checks

Attention

Trusted Advisor support in awslimitchecker is deprecated outside of the China and GovCloud regions, and now defaults to disabled/skipped in standard AWS, as the information available from TA can now be retrieved faster and more accurately via other means. See 10.0.0 (2020-12-07) for further information.

Using the --skip-ta option will disable attempting to query limit information from Trusted Advisor for all commands.

(venv)$ awslimitchecker -l --skip-ta
ApiGateway/API keys per account                                           500.0 (Quotas)
ApiGateway/Client certificates per account                                60.0 (Quotas)
ApiGateway/Custom authorizers per API                                     10
ApiGateway/Documentation parts per API                                    2000
ApiGateway/Edge APIs per account                                          120.0 (Quotas)
(...)
AutoScaling/Auto Scaling groups                                           200 (API)
(...)
Lambda/Function Count                                                     None
(...)
VPC/Subnets per VPC                                                       200.0 (Quotas)
VPC/VPCs                                                                  5.0 (Quotas)
VPC/Virtual private gateways                                              5

Disabling Specific Services

The --skip-service option can be used to completely disable the specified service name(s) (as shown by -s / --list-services) for services that are problematic or you do not wish to query at all.

For example, you can check usage of all services _except_ for Firehose and EC2:

(venv)$ awslimitchecker --skip-service=Firehose --skip-service EC2
 WARNING:awslimitchecker.checker:Skipping service: Firehose
 WARNING:awslimitchecker.checker:Skipping service: EC2
 ... normal output ...

Disabling Specific Checks

The --skip-check option can be used to completely disable the specified check name(s).

For example, you can run all the EC2 service checks except the Max launch specifications per spot fleet check with the following command:

(venv)$ awslimitchecker --skip-check='EC2/Max launch specifications per spot fleet'
 ... normal output ...
 EC2/Max launch specifications per spot fleet  (limit 50) WARNING: sfr-98e516f0-62f8-47ad-ada6-444da23fe6c5=42
(venv)$ echo $?
2

# With --skip-check
(venv)$ awslimitchecker --skip-check='EC2/Max launch specifications per spot fleet'
 ... normal output ...
(venv)$ echo $?
0

Checking Usage

The -u or --show-usage options to awslimitchecker show the current usage for each limit that awslimitchecker knows about. It will connect to the AWS API and determine the current usage for each limit. In cases where limits are per-resource instead of account-wide (i.e. “Rules per VPC security group” or “Security groups per VPC”), the usage will be reported for each possible resource in resource_id=value format (i.e. for each VPC security group and each VPC, respectively, using their IDs).

(venv)$ awslimitchecker -u
ApiGateway/API keys per account                                           2
ApiGateway/Client certificates per account                                0
ApiGateway/Custom authorizers per API                                     max: 2d7q4kzcmh=2 (2d7q4kz (...)
ApiGateway/Documentation parts per API                                    max: 2d7q4kzcmh=2 (2d7q4kz (...)
ApiGateway/Edge APIs per account                                          9
(...)
VPC/Subnets per VPC                                                       max: vpc-f4279a92=6 (vpc-f (...)
VPC/VPCs                                                                  2
VPC/Virtual private gateways                                              1

Overriding Limits

In cases where you’ve been given a limit increase by AWS Support, you can override the default limits with custom ones. Currently, to do this from the command line, you can either specify each limit that you want to override separately using the -L or --limit options, or you can specify a JSON file at either a local path or an S3 URL using the --limit-override-json option (the set_limit_overrides() Python method accepts a dict for easy bulk overrides of limits). Limits for the -L / --limit option are specified in a service_name/limit_name=value format, and must be quoted if the limit name contains spaces.

For example, to override the limits of EC2’s “EC2-Classic Elastic IPs” and “EC2-VPC Elastic IPs” from their defaults of 5, to 10 and 20, respestively:

(venv)$ awslimitchecker -L "AutoScaling/Auto Scaling groups"=321 --limit="AutoScaling/Launch configurations"=456 -l
ApiGateway/API keys per account                                           500.0 (Quotas)
ApiGateway/Client certificates per account                                60.0 (Quotas)
ApiGateway/Custom authorizers per API                                     10
ApiGateway/Documentation parts per API                                    2000
ApiGateway/Edge APIs per account                                          120.0 (Quotas)
(...)
CloudFormation/Stacks                                                     200 (API)
(...)
Lambda/Function Count                                                     None
(...)
VPC/Subnets per VPC                                                       200.0 (Quotas)
VPC/VPCs                                                                  5.0 (Quotas)
VPC/Virtual private gateways                                              5

This example simply sets the overrides, and then prints the limits for confirmation.

You could also set the same limit overrides using a JSON file stored at limit_overrides.json, following the format documented for awslimitchecker.checker.AwsLimitChecker.set_limit_overrides():

{
    "AutoScaling": {
        "Auto Scaling groups": 321,
        "Launch configurations": 456
    }
}

Using a command like:

(venv)$ awslimitchecker --limit-override-json=limit_overrides.json -l
ApiGateway/API keys per account                                           500.0 (Quotas)
ApiGateway/Client certificates per account                                60.0 (Quotas)
ApiGateway/Custom authorizers per API                                     10
ApiGateway/Documentation parts per API                                    2000
ApiGateway/Edge APIs per account                                          120.0 (Quotas)
(...)
VPC/Subnets per VPC                                                       200.0 (Quotas)
VPC/VPCs                                                                  5.0 (Quotas)
VPC/Virtual private gateways                                              5

Check Limits Against Thresholds

The default mode of operation for awslimitchecker (when no other action-specific options are specified) is to check the usage of all known limits, compare them against the configured limit values, and then output a message and set an exit code depending on thresholds. The limit values used will be (in order of precedence) explicitly-set overrides, Trusted Advisor data, and hard-coded defaults.

Currently, the awslimitchecker command line script only supports global warning and critical thresholds, which default to 80% and 99% respectively. If any limit’s usage is greater than or equal to 80% of its limit value, this will be included in the output and the program will exit with return code 1. If any limit’s usage is greater than or equal to 99%, it will include that in the output and exit 2. When determining exit codes, critical takes priority over warning. The output will include the specifics of which limits exceeded the threshold, and for limits that are per-resource, the resource IDs.

The Python class allows setting thresholds per-limit as either a percentage, or an integer usage value, or both; this functionality is not currently present in the command line wrapper.

To check all limits against their thresholds (in this example, one limit has crossed the warning threshold only, and another has crossed the critical threshold):

(venv)$ awslimitchecker --no-color
CloudFormation/Stacks                                  (limit 4000) WARNING: 3396
DynamoDB/Local Secondary Indexes                       (limit 5) CRITICAL: some_app_name (...)
DynamoDB/Tables Per Region                             (limit 256) CRITICAL: 554
EBS/Active snapshots                                   (limit 40000.0) WARNING: 33387
EC2/Rules per VPC security group                       (limit 50) CRITICAL: sg-aaaaaaaa=50, sg-bbbb (...)
(...)
VPC/Entries per route table                            (limit 50) WARNING: rtb-aaaaaaaa=43, rtb-bbbb (...)
VPC/NAT Gateways per AZ                                (limit 5) CRITICAL: us-east-1d=5, us-east-1c= (...)
VPC/Virtual private gateways                           (limit 5) WARNING: 4

Set Custom Thresholds

To set the warning threshold of 50% and a critical threshold of 75% when checking limits:

(venv)$ awslimitchecker -W 97 --critical=98 --no-color
DynamoDB/Local Secondary Indexes                       (limit 5) CRITICAL: some_app_name (...)
DynamoDB/Tables Per Region                             (limit 256) CRITICAL: 554
EC2/Rules per VPC security group                       (limit 50) CRITICAL: sg-cccccccc=49, sg-eeeee (...)
EC2/Security groups per VPC                            (limit 500) CRITICAL: vpc-dddddddd=726, vpc-c (...)
(...)
RDS/VPC Security Groups                                (limit 5) CRITICAL: 5
S3/Buckets                                             (limit 100) CRITICAL: 946
VPC/NAT Gateways per AZ                                (limit 5) CRITICAL: us-east-1d=5, us-east-1c= (...)

You can also set custom thresholds on a per-limit basis using the --threshold-override-json CLI option, which accepts the path to a JSON file (local or an s3:// URL) matching the format described in awslimitchecker.checker.AwsLimitChecker.set_threshold_overrides(), for example:

{
    "S3": {
        "Buckets": {
            "warning": {
                "percent": 97
            },
            "critical": {
                "percent": 99
            }
        }
    },
    "EC2": {
        "Security groups per VPC": {
            "warning": {
                "percent": 80,
                "count": 800
            },
            "critical": {
                "percent": 90,
                "count": 900
            }
        },
        "VPC security groups per elastic network interface": {
            "warning": {
                "percent": 101
            },
            "critical": {
                "percent": 101
            }
        }
    }
}

Using a command like:

(venv)$ awslimitchecker -W 97 --critical=98 --no-color --threshold-override-json=s3://bucketname/path/overrides.json
DynamoDB/Local Secondary Indexes                       (limit 5) CRITICAL: some_app_name (...)
DynamoDB/Tables Per Region                             (limit 256) CRITICAL: 554
EC2/Rules per VPC security group                       (limit 50) CRITICAL: sg-cccccccc=49, sg-eeeee (...)
EC2/Security groups per VPC                            (limit 500) CRITICAL: vpc-dddddddd=726, vpc-c (...)
(...)
RDS/VPC Security Groups                                (limit 5) CRITICAL: 5
S3/Buckets                                             (limit 100) CRITICAL: 946
VPC/NAT Gateways per AZ                                (limit 5) CRITICAL: us-east-1d=5, us-east-1c= (...)

Enable Metrics Provider

awslimitchecker is capable of sending metrics for the overall runtime of checking thresholds, as well as the current limit values and current usage, to various metrics stores. The list of metrics providers supported by your version of awslimitchecker can be seen with the --list-metrics-providers option:

(venv)$ awslimitchecker --list-metrics-providers
Available metrics providers:
Datadog
Dummy

The configuration options required by each metrics provider are specified in the providers’ documentation:

For example, to use the Datadog metrics provider which requires an api_key paramater (also accepted as an environment variable) and an optional extra_tags parameter:

(venv)$ awslimitchecker \
    --metrics-provider=Datadog \
    --metrics-config=api_key=123456 \
    --metrics-config=extra_tags=foo,bar,baz:blam

Metrics will be pushed to the provider only when awslimitchecker is done checking all limits.

Enable Alerts Provider

awslimitchecker is capable of sending alerts for either warning-level threshold breaches, or critical-level threshold breaches and exceptions checking thresholds, to various alert providers. The list of alert providers supported by your version of awslimitchecker can be seen with the --list-alert-providers option:

(venv)$ awslimitchecker --list-alert-providers
Available alert providers:
Dummy
PagerDutyV1

The configuration options required by each alert provider are specified in the providers’ documentation:

For example, to use the PagerDutyV1 alert provider which requires a critical_service_key paramater (also accepted as an environment variable) and an optional account_alias parameter:

(venv)$ awslimitchecker \
    --alert-provider=PagerDutyV1 \
    --alert-config=critical_service_key=012345 \
    --alert-config=account_alias=myacct

Alerts will be pushed to the provider only when awslimitchecker is done checking all limits, or when an exception is encountered during the checking process.

Required IAM Policy

awslimitchecker can also provide the user with an IAM Policy listing the minimum permissions for it to perform all limit checks. This can be viewed with the --iam-policy option:

(venv)$ awslimitchecker --iam-policy
{
  "Statement": [
    {
      "Action": [
        "apigateway:GET",
(...)
    }
  ],
  "Version": "2012-10-17"
}

For the current IAM Policy required by this version of awslimitchecker, see IAM Policy.

Important

The required IAM policy output by awslimitchecker includes only the permissions required to check limits and usage. If you are loading limit overrides and/or threshold overrides from S3, you will need to run awslimitchecker with additional permissions to access those objects.

Connect to a Specific Region

To connect to a specific region (i.e. us-west-2), simply specify the region name with the -r or --region options:

(venv)$ awslimitchecker -r us-west-2

Assume a Role in Another Account with STS

To assume the “foobar” role in account 123456789012 in region us-west-1, specify the -r / --region option as well as the -A / --sts-account-id and -R / --sts-account-role options:

(venv)$ awslimitchecker -r us-west-1 -A 123456789012 -R foobar

If you also need to specify an external_id of “myid”, you can do that with the -E / --external-id options:

(venv)$ awslimitchecker -r us-west-1 -A 123456789012 -R foobar -E myid

Please note that this assumes that you already have STS configured and working between your account and the 123456789012 destination account; see the documentation for further information.

Partitions and Trusted Advisor Regions

Attention

Trusted Advisor support in awslimitchecker is deprecated outside of the China and GovCloud regions, and now defaults to disabled/skipped in standard AWS, as the information available from TA can now be retrieved faster and more accurately via other means. See 10.0.0 (2020-12-07) for further information.

awslimitchecker currently supports operating against non-standard partitions, such as GovCloud and AWS China (Beijing). Partition names, as seen in the partition field of ARNs, can be specified with the --role-partition option to awslimitchecker, like --role-partition=aws-cn for the China (Beijing) partition. Similarly, the region name to use for the support API for Trusted Advisor can be specified with the --ta-api-region option, like --ta-api-region=us-gov-west-1.

Handling Throttling and Rate Limiting

In some very large and busy AWS accounts, from time to time awslimitchecker might die on unhandled Throttling or RateExceeded exceptions. botocore, the underlying low-level AWS API client library that we use, automatically catches these exceptions and retries them up to a per-AWS-API default number of times (generally four for most APIs) with an exponential backoff. In very busy accounts, it may be desirable to increase the default number of retries.

This can be accomplished on a per-API basis (where the API name is the service_name that would be sent to boto3.session.Session.client() and is set as the api_name attribute on each _AwsService subclass) by setting an environment variable BOTO_MAX_RETRIES_<api_name> to the maximum number of attempts you’d like for that service.

For example, if you have issues with rate limiting of the cloudformation:DescribeStacks still failing after the default of four attempts, and you’d like to use ten (10) attempts instead, you could export BOTO_MAX_RETRIES_cloudformation=10 before running awslimitchecker.