working on docs for PR #64

CHANGES.rst

@@ -7,6 +7,11 @@ Pre-release (develop branch)
 * Update trove classifier Development Status in setup.py to Beta
 * Fix markup formatting issue in ``docs/source/getting_started.rst``
 * temporarily disable py26 testenv in Travis; failing due to upstream bug https://github.com/pytest-dev/pytest/issues/1035
+* `PR #64 <https://github.com/jantman/awslimitchecker/pull/64>`_ and `#68 <https://github.com/jantman/awslimitchecker/issues/68>`_ -
+  support [STS](http://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html) and regions
+  * Add support for passing in a region to connect to via ``-r`` / ``--region``
+  * Add support for using STS to check resources in another account, including support for ``external_id``
+  * Major refactor of how service classes connect to AWS API
 
 0.1.2 (2015-08-13)
 ------------------

README.rst

@@ -63,9 +63,8 @@ Full project documentation is available at `http://awslimitchecker.readthedocs.o
 Status
 ------
 
-This project is currently in very early development. At this time please consider it alpha code and not reliable;
-furthermore its API may be changing rapidly. I hope to have this stabilized soon. I wouldn't call it ready for
-use, but contributions are certainly welcome.
+This project is currently in very early development. At this time please consider it beta code and not fully tested in all situations;
+furthermore its API may be changing rapidly. I hope to have this stabilized soon.
 
 What It Does
 ------------
@@ -77,6 +76,8 @@ What It Does
   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
+- Supports explicitly setting the AWS region
+- Supports using `STS <http://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html>`_ to assume roles in other accounts, including using ``external_id``.
 
 Requirements
 ------------
@@ -101,14 +102,18 @@ system-wide, you can (using sudo).
 Credentials
 -----------
 
-awslimitchecker does nothing with AWS credentials, it leaves that to boto itself.
+Aside from STS, 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
 `boto config <http://docs.pythonboto.org/en/latest/boto_config_tut.html>`_
 and
 `this project's documentation <http://awslimitchecker.readthedocs.org/en/latest/getting_started.html#credentials>`_
 for further information.
 
+When using STS, you will need to specify the ``-r`` / ``--region`` option as well as the ``-A`` / ``--sts-account-id``
+and ``-R`` / ``--sts-account-role`` options to specify the Account ID that you want to assume a role in, and the
+name of the role you want to assume. If an external ID is required, you can specify it with ``-E`` / ``--external-id``.
+
 Usage
 -----
 

docs/source/cli_usage.rst.template

@@ -139,3 +139,35 @@ permissions for it to perform all limit checks. This can be viewed with the
 
 For the current IAM Policy required by this version of awslimitchecker,
 see :ref:`IAM Policy <iam_policy>`.
+
+Connect to a Specific Region
+++++++++++++++++++++++++++++
+
+To connect to a specific region (i.e. ``us-west-2``), simply specify the region
+name with the ``-r`` or ``--region`` options:
+
+.. code-block:: console
+
+   (venv)$ awslimitchecker -r us-west-2
+
+Assume a Role in Another Account with STS
++++++++++++++++++++++++++++++++++++++++++
+
+To assume the "foobar" role in account 123456789012 in region us-west-1,
+specify the ``-r`` / ``--region`` option as well as the ``-A`` / ``--sts-account-id``
+and ``-R`` / ``--sts-account-role`` options:
+
+.. code-block:: console
+
+   (venv)$ awslimitchecker -r us-west-1 -A 123456789012 -R foobar
+
+If you also need to specify an ``external_id`` of "myid", you can do that with the
+``-E`` / ``--external-id`` options:
+
+.. code-block:: console
+
+   (venv)$ awslimitchecker -r us-west-1 -A 123456789012 -R foobar -E myid
+
+Please note that this assumes that you already have STS configured and working
+between your account and the 123456789012 destination account; see the
+`documentation <http://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html>`_ for further information.

docs/source/getting_started.rst

@@ -15,6 +15,8 @@ What It Does
   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
+- Supports explicitly setting the AWS region
+- Supports using `STS <http://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html>`_ to assume roles in other accounts, including using ``external_id``.
 
 .. _getting_started.nomenclature:
 
@@ -73,44 +75,26 @@ can be whatever you want):
 Credentials
 -----------
 
-awslimitchecker does nothing with AWS credentials, it leaves that to boto itself.
+Aside from STS, 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 <http://docs.pythonboto.org/en/latest/boto_config_tut.html>`_
+`boto config <http://docs.pythonboto.org/en/latest/boto_config_tut.html>`_
+and
+`this project's documentation <http://awslimitchecker.readthedocs.org/en/latest/getting_started.html#credentials>`_
 for further information.
 
-The recommended way of handling multiple accounts is to use one of the
-`credential configuration files <http://boto.readthedocs.org/en/latest/boto_config_tut.html#details>`_
-(``~/.aws/credentials`` is recommended, as it should be supported by all AWS SDKs and tools),
-define a `section per account <http://boto.readthedocs.org/en/latest/boto_config_tut.html#credentials>`_,
-and then export ``AWS_PROFILE=section_name`` to tell boto which section to use.
+When using STS, you will need to specify the ``-r`` / ``--region`` option as well as the ``-A`` / ``--sts-account-id``
+and ``-R`` / ``--sts-account-role`` options to specify the Account ID that you want to assume a role in, and the
+name of the role you want to assume. If an external ID is required, you can specify it with ``-E`` / ``--external-id``.
 
 .. _getting_started.regions:
 
 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:
-
-.. code-block:: ini
-
-    [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.
+To specify the region that ``awslimitchecker`` connects to, use the ``-r`` / ``--region``
+command line option. At this time awslimitchecker can only connect to one region at a time;
+to check limits in multiple regions, simply run the script multiple times, once per region.
 
 .. _getting_started.permissions:
 

docs/source/index.rst

@@ -66,9 +66,8 @@ Advisor where available), notifying you when you are approaching or at your limi
 Status
 -------
 
-This project is currently in very early development. At this time please consider it alpha code and not reliable;
-furthermore its API may be changing rapidly. I hope to have this stabilized soon. I wouldn't call it ready for
-use, but contributions are certainly welcome.
+This project is currently in very early development. At this time please consider it beta code and not fully tested in all situations;
+furthermore its API may be changing rapidly. I hope to have this stabilized soon.
 
 What It Does
 ------------
@@ -80,6 +79,8 @@ What It Does
   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
+- Supports explicitly setting the AWS region
+- Supports using `STS <http://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html>`_ to assume roles in other accounts, including using ``external_id``.
 
 Requirements
 ------------

docs/source/python_usage.rst

@@ -31,14 +31,49 @@ We also import :py:mod:`pprint` to make the output nicer.
 
 .. code-block:: pycon
 
-   >>> import pprint
    >>> import logging
    >>> logging.basicConfig()
    >>> logger = logging.getLogger()
    >>> 
    >>> from awslimitchecker.checker import AwsLimitChecker
    >>> c = AwsLimitChecker()
 
+Specifying a Region
++++++++++++++++++++
+
+To specify a region ("us-west-2" in this example), specify it as the ``region`` string
+parameter to the class constructor:
+
+.. code-block:: pycon
+
+   >>> import logging
+   >>> logging.basicConfig()
+   >>> logger = logging.getLogger()
+   >>> 
+   >>> from awslimitchecker.checker import AwsLimitChecker
+   >>> c = AwsLimitChecker(region='us-west-2')
+
+Assuming a Role with STS
+++++++++++++++++++++++++
+
+To check limits for another account using a Role assumed via `STS <http://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html>`_,
+specify the ``region``, ``account_id`` and ``account_role`` parameters to the class constructor. If an external ID is needed,
+this can be specified by the ``external_id`` parameter. All are strings:
+
+.. code-block:: pycon
+
+   >>> import logging
+   >>> logging.basicConfig()
+   >>> logger = logging.getLogger()
+   >>>
+   >>> from awslimitchecker.checker import AwsLimitChecker
+   >>> c = AwsLimitChecker(
+   >>>     region='us-west-2',
+   >>>     account_id='012345678901',
+   >>>     account_role='myRoleName',
+   >>>     external_id='myid'
+   >>> )
+
 Setting a Limit Override
 +++++++++++++++++++++++++