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] [-P PROFILE_NAME]
[-A STS_ACCOUNT_ID] [-R STS_ACCOUNT_ROLE]
[-E EXTERNAL_ID] [-M MFA_SERIAL_NUMBER] [-T MFA_TOKEN]
[-r REGION] [--skip-ta]
[--ta-refresh-wait | --ta-refresh-trigger | --ta-refresh-older TA_REFRESH_OLDER]
[--ta-refresh-timeout TA_REFRESH_TIMEOUT] [--no-color]
[-v] [-V]
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
-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
-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
--skip-ta do not attempt to pull *any* information on limits
from Trusted Advisor
--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
-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
CloudFormation
EBS
EC2
ELB
(...)
RDS
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
AutoScaling/Auto Scaling groups 20
AutoScaling/Launch configurations 100
CloudFormation/Stacks 200
EBS/Active snapshots 10000
EBS/Active volumes 5000
(...)
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 800 (API)
AutoScaling/Launch configurations 1000 (API)
CloudFormation/Stacks 1300 (API)
EBS/Active snapshots 20000 (TA)
EBS/Active volumes 10000 (TA)
(...)
VPC/Rules per network ACL 20
VPC/Subnets per VPC 200
VPC/VPCs 1000 (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 800 (API)
AutoScaling/Launch configurations 1000 (API)
CloudFormation/Stacks 1300 (API)
EBS/Active snapshots 10000
EBS/Active volumes 5000
(...)
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 601
AutoScaling/Launch configurations 701
CloudFormation/Stacks 979
EBS/Active snapshots 17500
EBS/Active volumes 5527
(...)
VPC/Rules per network ACL max: acl-bde47dd9=6 (acl-4bd96a2e=4, acl-a082 (...)
VPC/Subnets per VPC max: vpc-c89074a9=40 (vpc-7bcef71f=1, vpc-e2e (...)
VPC/VPCs 12
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
CloudFormation/Stacks 1300 (API)
EBS/Active snapshots 20000 (TA)
EBS/Active volumes 10000 (TA)
(...)
VPC/Rules per network ACL 20
VPC/Subnets per VPC 200
VPC/VPCs 1000 (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 20000) WARNING: 17500
EC2/Security groups per VPC (limit 500) CRITICAL: vpc-c89074a9=996
EC2/VPC security groups per elastic network interface (limit 5) WARNING: eni-63c2c58f=4, eni-65290b (...)
ElastiCache/Clusters (limit 50) CRITICAL: 61
ElastiCache/Nodes (limit 50) CRITICAL: 61
ElasticBeanstalk/Application versions (limit 500) CRITICAL: 2078
ElasticBeanstalk/Applications (limit 25) CRITICAL: 146
ElasticBeanstalk/Environments (limit 200) CRITICAL: 451
IAM/Instance profiles (limit 1000) WARNING: 817
S3/Buckets (limit 100) CRITICAL: 293
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/Security groups per VPC (limit 500) CRITICAL: vpc-c89074a9=996
ElastiCache/Clusters (limit 50) CRITICAL: 61
ElastiCache/Nodes (limit 50) CRITICAL: 61
ElasticBeanstalk/Application versions (limit 500) CRITICAL: 2078
ElasticBeanstalk/Applications (limit 25) CRITICAL: 146
ElasticBeanstalk/Environments (limit 200) CRITICAL: 451
S3/Buckets (limit 100) CRITICAL: 293
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.