Getting Started¶
What It Does¶
- Check current AWS resource usage against AWS Service Limits
- Show and inspect current usage
- Override default Service Limits (for accounts with increased limits)
- Compare current usage to limits; return information about limits that exceed thresholds, and (CLI wrapper) exit non-0 if thresholds are exceeded
- Define custom thresholds per-limit
- Where possible, pull current limits from Trusted Advisor API
- Supports explicitly setting the AWS region
- Supports using STS to assume roles in other accounts, including using
external_id
.
Nomenclature¶
- Service
- An AWS Service or Product, such as EC2, VPC, RDS or ElastiCache. More specifically, Services in AwsLimitChecker correspond to distinct APIs for AWS Services.
- Limit
- An AWS-imposed maximum usage for a certain resource type in AWS. See AWS Service Limits.
Limits are generally either account-wide or per-region. They have AWS global default values, but can be increased by AWS Support. “Limit” is also the term used
within this documentation to describe
AwsLimit
objects, which describe a specific AWS Limit within this program. - Usage
- “Usage” refers to your current usage of a specific resource that has a limit. Usage values/amounts (some integer or floating point number, such as number of VPCs
or GB of IOPS-provisioned storage) are represented by instances of the
AwsLimitUsage
class. Limits that are measured as a subset of some “parent” resource, such as “Subnets per VPC” or “Read Replicas per Master” have their usage tracked per parent resource, so you can easily determine which ones are problematic. - Threshold
- The point at which AwsLimitChecker will consider the current usage for a limit to be problematic. Global thresholds default to usage >= 80% of limit for “warning” severity,
and usage >= 99% of limit for “critical” severity. Limits which have reached or exceeded their threshold will be reported separately for warning and critical (we generally
consider “warning” to be something that will require human intervention in the near future, and “critical” something that is an immediate problem, i.e. should block
automated processes). The
awslimitchecker
command line wrapper can override the default global thresholds. TheAwsLimitChecker
class can both override global percentage thresholds, as well as specify per-limit thresholds as a percentage, a fixed usage value, or both. For more information on overriding thresholds, see Python Usage / Setting a Threshold Override as well as the documentation forAwsLimitChecker.check_thresholds()
andAwsLimitChecker.set_threshold_override()
.
Requirements¶
- Python 2.6 through 3.5 (it should work, but is no longer tested, with PyPy and PyPy3).
- Python VirtualEnv and
pip
(recommended installation method; your OS/distribution should have packages for these) - boto3 >= 1.2.3
Installing¶
It’s recommended that you install into a virtual environment (virtualenv / venv). See the virtualenv usage documentation for more details, but the gist is as follows (the virtualenv name, “limitchecker” here, can be whatever you want):
virtualenv limitchecker
source limitchecker/bin/activate
pip install awslimitchecker
Credentials¶
Aside from STS, awslimitchecker does nothing with AWS credentials, it leaves that to boto itself.
You must either have your credentials configured in one of boto3’s supported config
files or set as environment variables. If your credentials are in the cross-SDK
credentials file (~/.aws/credentials
) under a named profile section, you can
use credentials from that profile by specifying the -P
/ --profile
command
lint option. See
boto3 config
and
this project’s documentation
for further information.
Please note that version 0.3.0 of awslimitchecker moved from using boto
as its AWS API client to using
boto3
. This change is mostly transparent, but there is a minor change in how AWS credentials are handled. In
boto
, if the AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
environment variables were set, and the
region was not set explicitly via awslimitchecker, the AWS region would either be taken from the AWS_DEFAULT_REGION
environment variable or would default to us-east-1, regardless of whether a configuration file (~/.aws/credentials
or ~/.aws/config
) was present. With boto3, it appears that the default region from the configuration file will be
used if present, regardless of whether the credentials come from that file or from environment variables.
When using STS, you will need to specify the -r
/ --region
option as well as the -A
/ --sts-account-id
and -R
/ --sts-account-role
options to specify the Account ID that you want to assume a role in, and the
name of the role you want to assume. If an external ID is required, you can specify it with -E
/ --external-id
.
In addition, when assuming a role STS, you can use a MFA device. simply
specify the device’s serial number with the -M
/ --mfa-serial-number
option and a token generated by the device
with the -T
/ --mfa-token
option. STS credentials will be cached for the lifetime of the program.
Important Note on Session and Federation (Temporary) Credentials: The temporary credentials granted by the AWS IAM GetFederationToken and GetSessionToken API calls will throw errors when trying to access the IAM API (except for Session tokens, which will work for IAM API calls only if an MFA token is used). Furthermore, Federation tokens cannot make use of the STS AssumeRole functionality. If you attempt to use awslimitchecker with credentials generated by these APIs (commonly used by organizations to hand out limited-lifetime credentials), you will likely encounter errors.
Regions¶
To specify the region that awslimitchecker
connects to, use the -r
/ --region
command line option. At this time awslimitchecker can only connect to one region at a time;
to check limits in multiple regions, simply run the script multiple times, once per region.
Required Permissions¶
You can view a sample IAM policy listing the permissions required for awslimitchecker to function properly either via the CLI client:
awslimitchecker --iam-policy
Or as a python dict:
from awslimitchecker.checker import AwsLimitChecker
c = AwsLimitChecker()
iam_policy = c.get_required_iam_policy()
You can also view the required permissions for the current version of awslimitchecker at Required IAM Permissions.