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
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.
Requirements¶
- Python 2.6 or 2.7 (boto currently has incomplete python3 support)
- Python VirtualEnv and
pip
(recommended installation method; your OS/distribution should have packages for these) - boto
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¶
awslimitchecker does nothing with AWS credentials, it leaves that to boto itself. You must either have your credentials configured in one of boto’s supported config files, or set as environment variables. See the boto configuration documentation for further information.
The recommended way of handling multiple accounts is to use one of the
credential configuration files
(~/.aws/credentials
is recommended, as it should be supported by all AWS SDKs and tools),
define a section per account,
and then export AWS_PROFILE=section_name
to tell boto which section to use.
Regions¶
At this time, AWS Limit Checker has no knowledge of AWS regions. As most (all?)
limits are calculated on a per-region basis, this isn’t a major issue. To check
multiple regions, simply run awslimitchecker multiple times, once for each
region, using a different AWS_PROFILE
environment variable setting, and
entries in ~/.aws/credentials
like:
[myuser-us-east-1] region = us-east-1 aws_access_key_id = <your access key> aws_secret_access_key = <your secret key>
[myuser-us-west-2] region = us-west-2 aws_access_key_id = <your access key> aws_secret_access_key = <your secret key>
Support for setting the region, or multiple regions, directly through awslimitchecker will be implemented in the future depending on demand; it shouldn’t be too complicated to retrofit into the existing code.
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.