awslimitchecker.checker module¶

class awslimitchecker.checker.AwsLimitChecker(warning_threshold=80, critical_threshold=99, profile_name=None, account_id=None, account_role=None, role_partition='aws', region=None, external_id=None, mfa_serial_number=None, mfa_token=None, ta_refresh_mode=None, ta_refresh_timeout=None, ta_api_region='us-east-1', check_version=True, skip_quotas=False)[source]¶

Bases: object

Main AwsLimitChecker class - this should be the only externally-used portion of awslimitchecker.

Constructor builds self.services as a dict of service_name (str) to _AwsService instance, and sets limit thresholds.

Parameters:

warning_threshold (int) – the default warning threshold, as an integer percentage, for any limits without a specifically-set threshold.
critical_threshold (int) – the default critical threshold, as an integer percentage, for any limits without a specifically-set threshold.
profile_name (str) – The name of a profile in the cross-SDK shared credentials file for boto3 to retrieve AWS credentials from.
account_id (str) – AWS Account ID (12-digit string, currently numeric) for the account to connect to (destination) via STS
account_role (str) – the name of an IAM Role (in the destination account) to assume
region (str) – AWS region name to connect to
role_partition (str) – AWS role partition for the account_role to connect via STS
external_id (str) – (optional) the External ID string to use when assuming a role via STS.
mfa_serial_number (str) – (optional) the MFA Serial Number string to use when assuming a role via STS.
mfa_token (str) – (optional) the MFA Token string to use when assuming a role via STS.
ta_refresh_mode (str or int or None) – How to handle refreshing Trusted Advisor checks; this is either None (do not refresh at all), the string “wait” (trigger refresh of all limit-related checks and wait for the refresh to complete), the string “trigger” (trigger refresh of all limit-related checks but do not wait for the refresh to complete), or an integer, which causes any limit-related checks more than this number of seconds old to be refreshed, waiting for the refresh to complete. Note that “trigger” will likely result in the current run getting stale data, but the check being refreshed in time for the next run.
ta_refresh_timeout (int or None) – If ta_refresh_mode is “wait” or an integer (any mode that will wait for the refresh to complete), if this parameter is not None, only wait up to this number of seconds for the refresh to finish before continuing on anyway.
ta_api_region (str) – The AWS region used for calls to the TrustedAdvisor API. This is always us-east-1 for non GovCloud accounts.
check_version (bool) – Whether or not to check for latest version of awslimitchecker on PyPI during instantiation.
skip_quotas (bool) – If set to True, do not connect to Service Quotas service or use it to obtain current limits.

__dict__ = mappingproxy({'__module__': 'awslimitchecker.checker', '__init__': <function AwsLimitChecker.__init__>, '_check_python_version': <function AwsLimitChecker._check_python_version>, '_boto_conn_kwargs': <property object>, 'get_version': <function AwsLimitChecker.get_version>, 'get_project_url': <function AwsLimitChecker.get_project_url>, 'remove_services': <function AwsLimitChecker.remove_services>, 'get_limits': <function AwsLimitChecker.get_limits>, 'get_service_names': <function AwsLimitChecker.get_service_names>, '_get_sts_token': <function AwsLimitChecker._get_sts_token>, 'find_usage': <function AwsLimitChecker.find_usage>, 'set_limit_overrides': <function AwsLimitChecker.set_limit_overrides>, 'set_limit_override': <function AwsLimitChecker.set_limit_override>, 'set_threshold_overrides': <function AwsLimitChecker.set_threshold_overrides>, 'set_threshold_override': <function AwsLimitChecker.set_threshold_override>, 'check_thresholds': <function AwsLimitChecker.check_thresholds>, 'get_required_iam_policy': <function AwsLimitChecker.get_required_iam_policy>, 'region_name': <property object>, '__dict__': <attribute '__dict__' of 'AwsLimitChecker' objects>, '__weakref__': <attribute '__weakref__' of 'AwsLimitChecker' objects>, '__doc__': None})¶

__init__(warning_threshold=80, critical_threshold=99, profile_name=None, account_id=None, account_role=None, role_partition='aws', region=None, external_id=None, mfa_serial_number=None, mfa_token=None, ta_refresh_mode=None, ta_refresh_timeout=None, ta_api_region='us-east-1', check_version=True, skip_quotas=False)[source]¶

Main AwsLimitChecker class - this should be the only externally-used portion of awslimitchecker.

Constructor builds self.services as a dict of service_name (str) to _AwsService instance, and sets limit thresholds.

Parameters:

warning_threshold (int) – the default warning threshold, as an integer percentage, for any limits without a specifically-set threshold.
critical_threshold (int) – the default critical threshold, as an integer percentage, for any limits without a specifically-set threshold.
profile_name (str) –
The name of a profile in the cross-SDK shared credentials file for boto3 to retrieve AWS credentials from.
account_id (str) –
AWS Account ID (12-digit string, currently numeric) for the account to connect to (destination) via STS
account_role (str) –
the name of an IAM Role (in the destination account) to assume
region (str) – AWS region name to connect to
role_partition (str) –
AWS role partition for the account_role to connect via STS
external_id (str) –
(optional) the External ID string to use when assuming a role via STS.
mfa_serial_number (str) – (optional) the MFA Serial Number string to use when assuming a role via STS.
mfa_token (str) – (optional) the MFA Token string to use when assuming a role via STS.
ta_refresh_mode (str or int or None) – How to handle refreshing Trusted Advisor checks; this is either None (do not refresh at all), the string “wait” (trigger refresh of all limit-related checks and wait for the refresh to complete), the string “trigger” (trigger refresh of all limit-related checks but do not wait for the refresh to complete), or an integer, which causes any limit-related checks more than this number of seconds old to be refreshed, waiting for the refresh to complete. Note that “trigger” will likely result in the current run getting stale data, but the check being refreshed in time for the next run.
ta_refresh_timeout (int or None) – If ta_refresh_mode is “wait” or an integer (any mode that will wait for the refresh to complete), if this parameter is not None, only wait up to this number of seconds for the refresh to finish before continuing on anyway.
ta_api_region (str) – The AWS region used for calls to the TrustedAdvisor API. This is always us-east-1 for non GovCloud accounts.
check_version (bool) – Whether or not to check for latest version of awslimitchecker on PyPI during instantiation.
skip_quotas (bool) – If set to True, do not connect to Service Quotas service or use it to obtain current limits.

__module__ = 'awslimitchecker.checker'¶

__weakref__¶: list of weak references to the object (if defined)

_boto_conn_kwargs¶

Generate keyword arguments for boto3 connection functions.

If self.account_id is defined, this will call _get_sts_token() to get STS token credentials using boto3.STS.Client.assume_role and include those credentials in the return value.

If self.profile_name is defined, this will call boto3.Session() <http://boto3.readthedocs.io/en/latest/reference/core/session.html> with that profile and include those credentials in the return value.

Returns:	keyword arguments for boto3 connection functions
Return type:	dict

_check_python_version()[source]¶: Check that we are running under a supported Python version, and emit a warning otherwise.

_get_sts_token()[source]¶

Assume a role via STS and return the credentials.

First connect to STS via boto3.client(), then assume a role using boto3.STS.Client.assume_role using self.account_id and self.account_role (and optionally self.external_id, self.mfa_serial_number, self.mfa_token). Return the resulting ConnectableCredentials object.

Returns:	STS assumed role credentials
Return type:	`ConnectableCredentials`

check_thresholds(service=None, use_ta=True)[source]¶

Check all limits and current usage against their specified thresholds; return all AwsLimit instances that have crossed one or more of their thresholds.

If service is specified, the returned dict has one element, the service name, whose value is a nested dict as described below; otherwise it includes all known services.

The returned AwsLimit objects can be interrogated for their limits (get_limit()) as well as the details of usage that crossed the thresholds (get_warnings() and get_criticals()).

See AwsLimit.check_thresholds().

Parameters:	service (list) – the name(s) of one or more service(s) to return results for use_ta (bool) – check Trusted Advisor for information on limits
Returns:	dict of service name (string) to nested dict of limit name (string) to limit (`AwsLimit`)
Return type:	dict

find_usage(service=None, use_ta=True)[source]¶

For each limit in the specified service (or all services if service is None), query the AWS API via boto3 and find the current usage amounts for that limit.

This method updates the current_usage attribute of the AwsLimit objects for each service, which can then be queried using get_limits().

Parameters:	service (`None`, or `list` service names to get) – list of `_AwsService` name(s), or `None` to check all services. use_ta (bool) – check Trusted Advisor for information on limits

get_limits(service=None, use_ta=True)[source]¶

Return all AwsLimit objects for the given service name, or for all services if service is None.

If service is specified, the returned dict has one element, the service name, whose value is a nested dict as described below.

Parameters:	service (list) – the name(s) of one or more services to return limits for use_ta (bool) – check Trusted Advisor for information on limits
Returns:	dict of service name (string) to nested dict of limit name (string) to limit (`AwsLimit`)
Return type:	dict

get_project_url()[source]¶

Return the URL for the awslimitchecker project.

Returns:	URL of where to find awslimitchecker
Return type:	str

get_required_iam_policy()[source]¶

Return an IAM policy granting all of the permissions needed for awslimitchecker to fully function. This returns a dict suitable for json serialization to a valid IAM policy.

Internally, this calls required_iam_permissions() on each _AwsService instance.

Returns:	dict representation of IAM Policy
Return type:	dict

get_service_names()[source]¶

Return a list of all known service names

Returns:	list of service names
Return type:	list

get_version()[source]¶

Return the version of awslimitchecker currently running.

Returns:	current awslimitchecker version
Return type:	str

region_name¶

Return the name of the AWS region that we’re checking.

Returns:	AWS region name
Return type:	str

remove_services(services_to_remove=[])[source]¶

Remove all service names specified in services_to_remove from self.services. This allows explicitly removing certain services from ever being checked or otherwise handled.

By default, the various methods that work on Services (i.e. get_limits(), find_usage() and check_thresholds()) operate on either all known services, or one specified service name at a time. This method allows you to remove one or more problematic or undesirable services from the dict of all services, and then operate on the remaining ones.

Parameters:	services_to_remove – the name(s) of one or more services to permanently exclude from future calls to this instance

set_limit_override(service_name, limit_name, value, override_ta=True)[source]¶

Set a manual override on an AWS service limits, i.e. if you had limits increased by AWS support.

This method calls _AwsService.set_limit_override() on the corresponding _AwsService instance.

Explicitly set limit overrides using this method will take precedence over default limits. They will also take precedence over limit information obtained via Trusted Advisor, unless override_ta is set to False.

Parameters:	service_name (str) – the name of the service to override limit for limit_name (str) – the name of the limit to override: value (int) – the new (overridden) limit value) override_ta (bool) – whether or not to use this value even if Trusted Advisor supplies limit information
Raises:	`ValueError` if limit_name is not known to the service instance

set_limit_overrides(override_dict, override_ta=True)[source]¶

Set manual overrides on AWS service limits, i.e. if you had limits increased by AWS support. This takes a dict in the same form as that returned by get_limits(), i.e. service_name (str) keys to nested dict of limit_name (str) to limit value (int) like:

{
    'EC2': {
      'Running On-Demand t2.micro Instances': 1000,
      'Running On-Demand r3.4xlarge Instances': 1000,
    }
}

Internally, for each limit override for each service in override_dict, this method calls _AwsService.set_limit_override() on the corresponding _AwsService instance.

Explicitly set limit overrides using this method will take precedence over default limits. They will also take precedence over limit information obtained via Trusted Advisor, unless override_ta is set to False.

Parameters:	override_dict (dict) – dict of overrides to default limits override_ta (bool) – whether or not to use this value even if Trusted Advisor supplies limit information
Raises:	`ValueError` if limit_name is not known to the service instance

set_threshold_override(service_name, limit_name, warn_percent=None, warn_count=None, crit_percent=None, crit_count=None)[source]¶

Set a manual override on the threshold (used for determining warning/critical status) for a specific limit. See AwsLimitChecker for information on Warning and Critical thresholds.

See AwsLimit.set_threshold_override().

Parameters:

service_name (str) – the name of the service to override limit for
limit_name (str) – the name of the limit to override:
warn_percent (int) – new warning threshold, percentage used
warn_count (int) – new warning threshold, actual count/number
crit_percent (int) – new critical threshold, percentage used
crit_count (int) – new critical threshold, actual count/number

set_threshold_overrides(override_dict)[source]¶

Set manual overrides on the threshold (used for determining warning/critical status) a dict of limits. See AwsLimitChecker for information on Warning and Critical thresholds.

Dict is composed of service name keys (string) to dict of limit names (string), to dict of threshold specifications. Each threhold specification dict can contain keys ‘warning’ or ‘critical’, each having a value of a dict containing keys ‘percent’ or ‘count’, to an integer value.

Example:

{
    'EC2': {
        'SomeLimit': {
            'warning': {
                'percent': 80,
                'count': 8,
            },
            'critical': {
                'percent': 90,
                'count': 9,
            }
        }
    }
}

See AwsLimit.set_threshold_override().

Parameters:	override_dict (dict) – nested dict of threshold overrides