awslimitchecker.checker module

class awslimitchecker.checker.AwsLimitChecker(warning_threshold=80, critical_threshold=99, profile_name=None, account_id=None, account_role=None, region=None, external_id=None, mfa_serial_number=None, mfa_token=None, ta_refresh_mode=None, ta_refresh_timeout=None, check_version=True)[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
  • 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.
  • check_version (bool) – Whether or not to check for latest version of awslimitchecker on PyPI during instantiation.
__dict__ = dict_proxy({'set_threshold_overrides': <function set_threshold_overrides>, '__module__': 'awslimitchecker.checker', 'get_service_names': <function get_service_names>, 'set_threshold_override': <function set_threshold_override>, 'remove_services': <function remove_services>, '_boto_conn_kwargs': <property object>, 'check_thresholds': <function check_thresholds>, '__dict__': <attribute '__dict__' of 'AwsLimitChecker' objects>, '_get_sts_token': <function _get_sts_token>, '__weakref__': <attribute '__weakref__' of 'AwsLimitChecker' objects>, '__init__': <function __init__>, 'set_limit_override': <function set_limit_override>, 'get_required_iam_policy': <function get_required_iam_policy>, 'get_version': <function get_version>, 'find_usage': <function find_usage>, 'get_limits': <function get_limits>, 'set_limit_overrides': <function set_limit_overrides>, '__doc__': None, 'get_project_url': <function get_project_url>})
__init__(warning_threshold=80, critical_threshold=99, profile_name=None, account_id=None, account_role=None, region=None, external_id=None, mfa_serial_number=None, mfa_token=None, ta_refresh_mode=None, ta_refresh_timeout=None, check_version=True)[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
  • 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.
  • check_version (bool) – Whether or not to check for latest version of awslimitchecker on PyPI during instantiation.
__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
_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:string
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:string
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 (string) – the name of the service to override limit for
  • limit_name (string) – 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 (string) – the name of the service to override limit for
  • limit_name (string) – 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