A simple utility for easily executing AWS cli commands with an assumed role.

For more information about the motiviation behind developing this utility, please read our blog post Assuming roles in AWS with sudo-like agility.

awsudo [-h|--help] [-v|--verbose] arn:aws:iam::[AWS_ACCOUNT_ID]:role/[role name] [aws command]

awsudo can be installed as a global utility to use alongside the AWS cli for day-to-day operations, local troubleshooting, etc:

npm install -g awsudo

awsudo can also be installed for use by specific Node.js projects (i.e. as part of a CI/CD build process) by adding it as a dependency like any other:

npm install --save-dev awsudo

npm will place it in the execution PATH for any scripts defined in it package.json that it runs (e.g. start, test).

awsudo can also be used from its official Docker image, which packages it along with its dependencies and the AWS cli.

docker pull awsudo/awsudo

The Docker image can be used as a direct command (remember to mount your AWS configuration as a volume in the container):

docker run -v ~/.aws:/root/.aws awsudo/awsudo awsudo arn:aws:iam::[AWS_ACCOUNT_ID]:role/[role name] [aws command]

or it can be launched as an environment for running multiple commands interactively:

docker run -it -v ~/.aws:/root/.aws awsudo/awsudo awsudo /bin/bash

Basic usage when awsudo is on the PATH:

awsudo arn:aws:iam::123456789012:role/S3Access aws s3 cp ./some/directory s3://some-bucket

when using with Docker as a command (i.e. not within the container):

docker run -v ~/.aws:/root/.aws awsudo/awsudo awsudo arn:aws:iam::123456789012:role/S3Access aws s3 cp ./some/directory s3://some-bucket

The Docker image can also be used with CI/CD tools like Drone or CircleCI.

Here is an example Drone pipeline step which uses the awsudo Docker image to deploy into AWS:

  deploy:
    image: awsudo/awsudo:latest
    commands:
      # Copy build artifacts to publicly-readable S3 bucket
      - awsudo arn:aws:iam::${AWS_ACCOUNT_ID}:role/S3Access aws s3 cp ./build s3://some-bucket --acl public-read --recursive
    environment:
      - AWS_DEFAULT_REGION=us-east-1
    secrets:
      - aws_access_key_id
      - aws_account_id
      - aws_secret_access_key

• The awscli must be configured OR appropriate environment variables are set

For npm-based installations:

• This is a bash based package and must therefore be run in a bash environment
• The awscli must be available on the system.

The maintainer of this repository is the AWS sudo open source maintainers at Meltwater, please send us any questions.