issue #14 - docs on Trusted Advisor

README.rst

@@ -60,7 +60,7 @@ What It Does
 - 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
-- Coming Soon: where possible, pull current limits from Trusted Advisor API
+- where possible, pull current limits from Trusted Advisor API
 
 Requirements
 ------------

docs/build_generated_docs.py

@@ -93,13 +93,13 @@ def build_iam_policy(checker):
 
 def build_limits(checker):
     logger.info("Beginning build of limits.rst")
-    # get the policy dict
+    ta_limits = {}
     logger.info("Getting Limits")
-    ta_info = 'TBD; Trusted Advisor support is `not yet implemented <https://github.com/jantman/awslimitchecker/issues/14>`_'  # @TODO trusted advisor data
     limit_info = ''
     limits = checker.get_limits()
     # this is a bit of a pain, because we need to know string lengths to build the table
     for svc_name in sorted(limits):
+        ta_limits[svc_name] = []
         limit_info += svc_name + "\n"
         limit_info += ('+' * (len(svc_name)+1)) + "\n"
         limit_info += "\n"
@@ -109,13 +109,16 @@ def build_limits(checker):
         max_name = 0
         max_default_limit = 0
         for limit in limits[svc_name].values():
+            lname = limit.name
+            if limit.ta_limit is not None:
+                lname += ' :sup:`(TA)`'
+                ta_limits[svc_name].append(limit.name)
+            slimits[lname] = str(limit.default_limit)
             # update max string length for table formatting
-            if len(limit.name) > max_name:
-                max_name = len(limit.name)
+            if len(lname) > max_name:
+                max_name = len(lname)
             if len(str(limit.default_limit)) > max_default_limit:
                 max_default_limit = len(str(limit.default_limit))
-            # @TODO trusted advisor, use :sup:`[TA]`
-            slimits[limit.name] = str(limit.default_limit)
         # create the format string
         sformat = '{name: <' + str(max_name) + '} ' \
                   '{limit: <' + str(max_default_limit) + '}\n'
@@ -131,6 +134,22 @@ def build_limits(checker):
         # footer
         limit_info += sep
 
+    # TA limit list
+    ta_info = """
+    So long as the Service and Limit names used by Trusted Advisor (and returned
+    in its API responses) exactly match those shown below, all limits listed in
+    Trusted Advisor "Service Limit" checks should be automatically used by
+    awslimitchecker. The following service limits have been confirmed as being
+    updated from Trusted Advisor:
+    """
+    ta_info = dedent(ta_info) + "\n\n"
+    for sname in sorted(ta_limits.keys()):
+        if len(ta_limits[sname]) < 1:
+            continue
+        ta_info += '* {s}\n\n'.format(s=sname)
+        for lname in sorted(ta_limits[sname]):
+            ta_info += '  * {l}\n\n'.format(l=lname)
+
     doc = """
     .. -- WARNING -- WARNING -- WARNING
        This document is automatically generated by
@@ -155,7 +174,8 @@ def build_limits(checker):
     ---------------
 
     The section below lists every limit that this version of awslimitchecker knows
-    how to check, and its hard-coded default value (per AWS documentation).
+    how to check, and its hard-coded default value (per AWS documentation). Limits
+    marked with :sup:`(TA)` are comfirmed as being updated by Trusted Advisor.
 
     {limit_info}
 

docs/source/development.rst

@@ -98,10 +98,14 @@ using the :py:mod:`abc` module.
 
 .. _development.adding_ta:
 
-Adding Trusted Advisor Checks
-------------------------------
+Trusted Advisor Checks
+-----------------------
 
-Currently not implemented; see `issue #14 <https://github.com/jantman/awslimitchecker/issues/14>`_
+So long as the ``Service`` and ``Limit`` name strings returned by the Trusted Advisor (Support) API exactly match
+how they are set on the corresponding :py:class:`~._AwsService` and :py:class:`~.AwsLimit` objects, no code changes
+are needed to support new limit checks from TA.
+
+For further information, see :ref:`Internals / Trusted Advisor <internals.trusted_advisor>`.
 
 .. _development.tests:
 

docs/source/getting_started.rst

@@ -14,7 +14,7 @@ What It Does
 - 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
-- Coming Soon: where possible, pull current limits from Trusted Advisor API
+- Where possible, pull current limits from Trusted Advisor API
 
 .. _getting_started.nomenclature:
 

docs/source/internals.rst

@@ -29,3 +29,32 @@ string Service Name to the Service Class instance. These instances are used for
 So, once an instance of :py:class:`~awslimitchecker.checker.AwsLimitChecker` is created, we should have instant access
 to the services and limits without any connection to AWS. This is utilized by the ``--list-services`` and
 ``--list-defaults`` options for the :ref:`command line client <_cli>`.
+
+.. _internals.trusted_advisor:
+
+Trusted Advisor
+-----------------
+
+When :py:class:`~awslimitchecker.checker.AwsLimitChecker` is initialized, it also initializes an instance of
+:py:class:`~awslimitchecker.trustedadvisor.TrustedAdvisor`. In :py:meth:`~.AwsLimitchecker.get_limits`,
+:py:meth:`~.AwsLimitchecker.find_usage` and :py:meth:`~.AwsLimitchecker.check_thresholds`, when called with
+``use_ta == True`` (the default), :py:meth:`~.TrustedAdvisor.update_limits` is called on the TrustedAdvisor
+instance.
+
+:py:meth:`~.TrustedAdvisor.update_limits` polls Trusted Advisor data is from the Support API via
+:py:meth:`~.TrustedAdvisor._poll`; this will retrieve the limits for all "flaggedResources" items in the
+``Service Limits`` Trusted Advisor check result for the current AWS account. It then calls
+:py:meth:`~.TrustedAdvisor._update_services`, passing in the Trusted Advisor check results and the
+dict of :py:class:`~._AwsService` objects it was called with (from :py:class:`~.AwsLimitChecker`).
+
+:py:meth:`~.TrustedAdvisor._update_services` iterates over the Services in the Trusted Advisor check result
+and attempts to find a matching :py:class:`~._AwsService` (by string service name) in the dict passed
+in from :py:class:`~.AwsLimitChecker`. If a match is found, it iterates over all limits for that service
+in the TA result and attempts to call the ``Service``'s :py:meth:`~._AwsService._set_ta_limit` method.
+If a matching Service is not found, or if ``_set_ta_limit`` raises a ValueError (matching Limit not found
+for that Service), an error is logged.
+
+Using this methodology, no additional code is needed to support new/additional Trusted Advisor limit checks;
+*so long as* the Service and Limit name strings match between the Trusted Advisor API response and their
+corresponding :py:class:`~._AwsService` and :py:class:`~.AwsLimit` instances, the TA limits will be automatically
+added to the corresponding ``AwsLimit``.

docs/source/limits.rst

@@ -14,25 +14,44 @@ Supported Limits
 Trusted Advisor Data
 ---------------------
 
-TBD; Trusted Advisor support is `not yet implemented <https://github.com/jantman/awslimitchecker/issues/14>`_
+
+So long as the Service and Limit names used by Trusted Advisor (and returned
+in its API responses) exactly match those shown below, all limits listed in
+Trusted Advisor "Service Limit" checks should be automatically used by
+awslimitchecker. The following service limits have been confirmed as being
+updated from Trusted Advisor:
+
+
+* AutoScaling
+
+  * Auto Scaling groups
+
+  * Launch configurations
+
+* VPC
+
+  * VPCs
+
+
 
 .. _limits.checks:
 
 Current Checks
 ---------------
 
 The section below lists every limit that this version of awslimitchecker knows
-how to check, and its hard-coded default value (per AWS documentation).
+how to check, and its hard-coded default value (per AWS documentation). Limits
+marked with :sup:`(TA)` are comfirmed as being updated by Trusted Advisor.
 
 AutoScaling
 ++++++++++++
 
-===================== ===
-Limit                 Default
-===================== ===
-Auto Scaling groups   20 
-Launch configurations 100
-===================== ===
+================================= ===
+Limit                             Default
+================================= ===
+Auto Scaling groups :sup:`(TA)`   20 
+Launch configurations :sup:`(TA)` 100
+================================= ===
 EC2
 ++++
 
@@ -113,7 +132,7 @@ Network ACLs per VPC    200
 Route tables per VPC    200
 Rules per network ACL   20 
 Subnets per VPC         200
-VPCs                    5  
+VPCs :sup:`(TA)`        5  
 ======================= ===
 
 

docs/source/python_usage.rst

@@ -125,6 +125,16 @@ crossed the critical threshold:
    ... 
    vpc-c300b9a6=100
 
+Disabling Trusted Advisor
+++++++++++++++++++++++++++
+
+To disable querying Trusted Advisor for limit information, simply call :py:meth:`~.AwsLimitChecker.get_limits`
+or :py:meth:`~.AwsLimitChecker.check_thresholds` with ``use_ta=False``:
+
+.. code-block:: pycon
+
+   >>> result = c.check_thresholds(use_ta=False)
+
 Advanced Examples
 ------------------