Package: iam-starter
A CLI which starts your program with AWS IAM credentials in the
environment by assuming a role or a profileInstallation$pipinstalliam-starterUsageA few examples:# start a program given an IAM Role (assumes default creds can assume role)$iam-starter--rolemyrole--command./my-program.sh# start a program with a profile$iam-starter--profilemyprofile--command./my-program.sh# start a program with an IAM Role using a profile to assume that role$iam-starter--rolemyrole--profiledev--command./my-program.sh# get export commands to paste into shell to assume the role manually$iam-starter--rolemyroleexportAWS_ACCESS_KEY_ID="ASIAI....UOCA"exportAWS_SECRET_ACCESS_KEY="DWYnQ....h93k"exportAWS_SESSION_TOKEN="KMWSz...8wX=="# note that these two are equivalent:$iam-starter--profilemyprofile--commandawss3ls$awss3ls--profilemyprofile# you can use iamx as shorthand for iam-starter (less typing)$iamx--rolemyrole--commandawss3lsMotivationThe 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--profileprofilename). 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:# how annoying that I have to pass an optional profile name heredefdo_something_with_aws(profile=None)ifprofile:# this is what will happen on my laptopsession=boto3.Session(profile_name=profile)client=session.client('s3')else:# this is what will happen when running on EC2client=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.defdo_something_with_aws()# yay, simple and the same everywhere!client=boto3.client('s3')Use with DockerThis is primarily intended to be used outside Docker. To run a Docker
container with an assumed IAM Role, you are probably better off usingIAM-Docker-Run.Use with SSM-StarterThis can be chained withSSM-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.$exportAWS_REGION=us-east-1# needed for ssm-starter$iam-starter--rolemyrole--profiledev--commandssm-starter--ssm-name/myssmprefix/--command./my-program.shLimitationsThis 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 PyPiFor the maintainer - to publish an updated version of ssm-search,
increment the version number in version.py and run the following:dockerbuild-f./Dockerfile.buildenv-tiam-starter:build.dockerrun--rm-it--entrypointmakeiam-starter:buildpublishAt the prompts, enter the username and password to the pypi.org repo.TestingTest execution in a container by inserting your local AWS credentials
into the container.dockerbuild-f./Dockerfile.buildenv-tiam-starter:build.dockerrun-it-v$(cd~/.aws;pwd):/root/.awsiam-starter:build# then, inside the containerpipinstallawscli# assumes a local profile named "dev" which has access to list S3 bucketsiam-starter--profiledev--commandawss3ls