Metadata-Version: 1.1
Name: iam-starter
Version: 0.2.3
Summary: A CLI which starts your program in the context of an assumed AWS IAM Role
Home-page: https://github.com/billtrust/iam-starter
Author: Doug Kerwin
Author-email: dwkerwin@gmail.com
License: MIT
Description: IAM-Starter
        ===========
        
        A CLI which starts your program with AWS IAM credentials in the
        environment by assuming a role or a profile
        
        Installation
        ------------
        
        .. code:: shell
        
           $ pip install iam-starter
        
        Usage
        -----
        
        A few examples:
        
        .. code:: shell
        
           # start a program given an IAM Role (assumes default creds can assume role)
           $ iam-starter --role myrole --command ./my-program.sh
        
           # start a program with a profile
           $ iam-starter --profile myprofile --command ./my-program.sh
        
           # start a program with an IAM Role using a profile to assume that role
           $ iam-starter --role myrole --profile dev --command ./my-program.sh
        
           # get export commands to paste into shell to assume the role manually
           $ iam-starter --role myrole
           export AWS_ACCESS_KEY_ID="ASIAI....UOCA"
           export AWS_SECRET_ACCESS_KEY="DWYnQ....h93k"
           export AWS_SESSION_TOKEN="KMWSz...8wX=="
        
           # note that these two are equivalent:
           $ iam-starter --profile myprofile --command aws s3 ls
           $ aws s3 ls --profile myprofile
        
           # you can use iamx as shorthand for iam-starter (less typing)
           $ iamx --role myrole --command aws s3 ls
        
        Motivation
        ----------
        
        The desire was to be able to easily run programs that need AWS
        credentials locally the same way you can run them in AWS, and to do so
        without requiring code changes or complex logic to support multiple
        methods of obtaining AWS credentials. On EC2 you simply attach an IAM
        role to the instance and then anything you do on that instance is
        automatically in the context of that IAM role. Locally it isn’t quite as
        easy to run things in the context of a role, you have to setup an AWS
        profile (already something you don’t do inside AWS) to assume your role,
        then your program has to support using the named profile when
        authenticating to AWS, which isn’t always an option (not all tools
        correctly/fully support using AWS profiles).
        
        If you care to execute your app with the context of a role rather than
        running everything with your full admin developer credentials and
        waiting to find out in production that you have an IAM permissions
        issue, you are probably using named profiles
        (``aws configure --profile profilename``). However when running your app
        locally in order for your AWS API calls to use that profile it requires
        a code change to specify the profile name to the AWS SDK. That sounds
        okay at first until you realize that those profiles will not exist when
        deployed into AWS, so code that “works on your machine” doesn’t work in
        production.
        
        If you haven’t already given up on trying to be a good citizen and
        run/test your app locally with the limited IAM policy you defined for
        it, this causes you to have to do unfortunate stuff like this all over
        your code:
        
        .. code:: python
        
           # how annoying that I have to pass an optional profile name here
           def do_something_with_aws(profile=None)
               if profile:
                   # this is what will happen on my laptop
                   session = boto3.Session(profile_name=profile)
                   client = session.client('s3')
               else:
                   # this is what will happen when running on EC2
                   client = boto3.client('s3')
        
        (a python example but this is true of the AWS SDK for any language or
        the AWS CLI)
        
        IAM-Starter makes it easy for you to run locally and in AWS using roles
        or named profiles, via the same credential method – environment
        variables, which are the most universally supported credential method.
        
        .. code:: python
        
           def do_something_with_aws()
               # yay, simple and the same everywhere!
               client = boto3.client('s3')
        
        Use with Docker
        ---------------
        
        This is primarily intended to be used outside Docker. To run a Docker
        container with an assumed IAM Role, you are probably better off using
        `IAM-Docker-Run <https://github.com/billtrust/iam-docker-run>`__.
        
        Use with SSM-Starter
        --------------------
        
        This can be chained with
        `SSM-Starter <https://github.com/billtrust/ssm-starter>`__. The
        following example starts a program with the given IAM role and loads the
        SSM parameters for the given path into the environment, then runs your
        program which now has the benefit of the IAM role and the configuration
        loaded into the environment.
        
        .. code:: shell
        
           $ export AWS_REGION=us-east-1 # needed for ssm-starter
           $ iam-starter --role myrole --profile dev --command ssm-starter --ssm-name /myssmprefix/ --command ./my-program.sh
        
        Limitations
        -----------
        
        **This is a development workflow tool, not designed to run production
        applications.**
        
        Temporary credentials expire within 1 hour and do not auto renew. This
        tool was designed to be used with development, adhoc, or witih build/CI
        environments where execution time is short.
        
        Publishing Updates to PyPi
        --------------------------
        
        For the maintainer - to publish an updated version of ssm-search,
        increment the version number in version.py and run the following:
        
        .. code:: shell
        
           docker build -f ./Dockerfile.buildenv -t iam-starter:build .
           docker run --rm -it --entrypoint make iam-starter:build publish
        
        At the prompts, enter the username and password to the pypi.org repo.
        
        Testing
        -------
        
        Test execution in a container by inserting your local AWS credentials
        into the container.
        
        .. code:: shell
        
           docker build -f ./Dockerfile.buildenv -t iam-starter:build .
           docker run -it -v $(cd ~/.aws; pwd):/root/.aws iam-starter:build
           # then, inside the container
           pip install awscli
           # assumes a local profile named "dev" which has access to list S3 buckets
           iam-starter --profile dev --command aws s3 ls
        
Keywords: aws-iam,aws-iam-role
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
