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
orint
orNone
) – 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
orNone
) – Ifta_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__
= mappingproxy({'set_threshold_override': <function AwsLimitChecker.set_threshold_override>, 'get_required_iam_policy': <function AwsLimitChecker.get_required_iam_policy>, 'set_limit_overrides': <function AwsLimitChecker.set_limit_overrides>, 'remove_services': <function AwsLimitChecker.remove_services>, '_boto_conn_kwargs': <property object>, '_get_sts_token': <function AwsLimitChecker._get_sts_token>, 'get_version': <function AwsLimitChecker.get_version>, 'check_thresholds': <function AwsLimitChecker.check_thresholds>, 'get_limits': <function AwsLimitChecker.get_limits>, '__module__': 'awslimitchecker.checker', '__dict__': <attribute '__dict__' of 'AwsLimitChecker' objects>, 'set_threshold_overrides': <function AwsLimitChecker.set_threshold_overrides>, 'set_limit_override': <function AwsLimitChecker.set_limit_override>, 'get_service_names': <function AwsLimitChecker.get_service_names>, '__weakref__': <attribute '__weakref__' of 'AwsLimitChecker' objects>, 'get_project_url': <function AwsLimitChecker.get_project_url>, 'find_usage': <function AwsLimitChecker.find_usage>, '__init__': <function AwsLimitChecker.__init__>, '__doc__': None})¶
-
__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
orint
orNone
) – 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
orNone
) – Ifta_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 usingself.account_id
andself.account_role
(and optionallyself.external_id
,self.mfa_serial_number
,self.mfa_token
). Return the resultingConnectableCredentials
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()
andget_criticals()
).See
AwsLimit.check_thresholds()
.Parameters: Returns: dict of service name (string) to nested dict of limit name (string) to limit (
AwsLimit
)Return type:
-
find_usage
(service=None, use_ta=True)[source]¶ For each limit in the specified service (or all services if
service
isNone
), query the AWS API viaboto3
and find the current usage amounts for that limit.This method updates the
current_usage
attribute of theAwsLimit
objects for each service, which can then be queried usingget_limits()
.Parameters: - service (
None
, orlist
service names to get) – list of_AwsService
name(s), orNone
to check all services. - use_ta (bool) – check Trusted Advisor for information on limits
- service (
-
get_limits
(service=None, use_ta=True)[source]¶ Return all
AwsLimit
objects for the given service name, or for all services ifservice
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: Returns: dict of service name (string) to nested dict of limit name (string) to limit (
AwsLimit
)Return type:
-
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
-
remove_services
(services_to_remove=[])[source]¶ Remove all service names specified in
services_to_remove
fromself.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()
andcheck_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 toFalse
.Parameters: 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 toFalse
.Parameters: 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