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] [-s] [-l] [--list-defaults]
                       [-L LIMIT] [-u] [--iam-policy] [-W WARNING_THRESHOLD]
                       [-C CRITICAL_THRESHOLD] [-A STS_ACCOUNT_ID]
                       [-R STS_ACCOUNT_ROLE] [-E EXTERNAL_ID]
                       [-M MFA_SERIAL_NUMBER] [-T MFA_TOKEN] [-r REGION]
                       [--skip-ta] [--no-color] [-v] [-V]
Report on AWS service limits and usage via boto, 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
  -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.
  -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
  -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
  --skip-ta             do not attempt to pull *any* information on limits
                        from Trusted Advisor
  --no-color            do not colorize output
  -v, --verbose         verbose output. specify twice for debug-level output.
  -V, --version         print version number and exit.
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
AutoScaling
EBS
EC2
ELB
ElastiCache
RDS
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
AutoScaling/Auto Scaling groups                        20
AutoScaling/Launch configurations                      100
EBS/Active snapshots                                   10000
EBS/Active volumes                                     5000
EBS/General Purpose (SSD) volume storage (GiB)         20480
(...)
VPC/Rules per network ACL                              20
VPC/Subnets per VPC                                    200
VPC/VPCs                                               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
AutoScaling/Auto Scaling groups                        500 (API)
AutoScaling/Launch configurations                      500 (API)
EBS/Active snapshots                                   13000 (TA)
EBS/Active volumes                                     5000 (TA)
EBS/General Purpose (SSD) volume storage (GiB)         163840 (TA)
(...)
VPC/Rules per network ACL                              20
VPC/Subnets per VPC                                    200
VPC/VPCs                                               20 (TA)

Disabling Trusted Advisor Checks

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

(venv)$ awslimitchecker -l --skip-ta
AutoScaling/Auto Scaling groups                        500 (API)
AutoScaling/Launch configurations                      500 (API)
EBS/Active snapshots                                   10000
EBS/Active volumes                                     5000
EBS/General Purpose (SSD) volume storage (GiB)         20480
(...)
VPC/Rules per network ACL                              20
VPC/Subnets per VPC                                    200
VPC/VPCs                                               5

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
AutoScaling/Auto Scaling groups                        351
AutoScaling/Launch configurations                      399
EBS/Active snapshots                                   11749
EBS/Active volumes                                     3018
EBS/General Purpose (SSD) volume storage (GiB)         29592
(...)
VPC/Rules per network ACL                              max: acl-bde47dd9=6 (acl-4bd96a2e=4, acl-8190 (...)
VPC/Subnets per VPC                                    max: vpc-c89074a9=25 (vpc-ae7bc5cb=1, vpc-1e5 (...)
VPC/VPCs                                               8

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 must specify each limit that you want to override separately (the set_limit_overrides() Python method accepts a dict for easy bulk overrides of limits) using the -L or --limit options. Limits 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
AutoScaling/Auto Scaling groups                        321
AutoScaling/Launch configurations                      456
EBS/Active snapshots                                   13000 (TA)
EBS/Active volumes                                     5000 (TA)
EBS/General Purpose (SSD) volume storage (GiB)         163840 (TA)
(...)
EC2/Elastic IP addresses (EIPs)                        40 (API)
(...)
VPC/Rules per network ACL                              20
VPC/Subnets per VPC                                    200
VPC/VPCs                                               20 (TA)

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

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
EBS/Active snapshots                                   (limit 13000) WARNING: 11749
EC2/Running On-Demand m1.small instances               (limit 20) CRITICAL: 63
EC2/Running On-Demand m3.large instances               (limit 20) CRITICAL: 26
EC2/Security groups per VPC                            (limit 100) CRITICAL: vpc-c89074a9=820
EC2/VPC security groups per elastic network interface  (limit 5) CRITICAL: eni-2751546e=5 WARNING: e (...)
RDS/DB parameter groups                                (limit 50) WARNING: 42
RDS/Reserved Instances                                 (limit 40) WARNING: 32
RDS/Subnet Groups                                      (limit 20) CRITICAL: 84

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
EC2/Running On-Demand m1.small instances               (limit 20) CRITICAL: 63
EC2/Running On-Demand m3.large instances               (limit 20) CRITICAL: 26
EC2/Security groups per VPC                            (limit 100) CRITICAL: vpc-c89074a9=820
EC2/VPC security groups per elastic network interface  (limit 5) CRITICAL: eni-2751546e=5
RDS/Subnet Groups                                      (limit 20) CRITICAL: 84

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": [
        "autoscaling:DescribeAccountLimits",
(...)
    }
  ],
  "Version": "2012-10-17"
}

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

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.