Wondering what’s next for npm?Check out our public roadmap! »

    awsudo

    1.4.2 • Public • Published

    awsudo

    Build Status

    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.

    Usage

    awsudo [-d|--duration] [-n|--session-name] [-e|--external-id] [-v|--verbose]
    [-m|--mfa-token-arn] [-t|--mfa-token] <arn> <command..>
     
    Assume an IAM role for the duration of a command
     
    Positionals:
      arn      ARN to assume                                                [string]
      command  Command to run
     
    Options:
      --help               Show help                                       [boolean]
      --version            Show version number                             [boolean]
      -d, --duration       The duration to assume this role in seconds. See
                           https://docs.aws.amazon.com/STS/latest/APIReference/API_A
                           ssumeRole.html#API_AssumeRole_RequestParameters
                                                             [number] [default: 900]
      -n, --session-name   The role session name to use
                                                   [string] [default: "RoleSession"]
      -e, --external-id    The external id string used to authenticate role
                           assumption                      [string] [default: false]
      -v, --verbose        Show debug information         [boolean] [default: false]
      -t, --mfa-token      Current MFA token [Must also supply mfa-token-arn]
                                                           [string] [default: false]
      -m, --mfa-token-arn  ARN for users MFA [Must also supply mfa-token]
                                                           [string] [default: false]

    Install

    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

    Node

    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).

    Docker

    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

    deb and rpm packages

    In addition to the native npm package and Docker image, there are .deb and .rpm packages avaialble.

    Warning: You must install Node.js separately, because these packages are not marked as dependent on Node.js within the Debian or Red Hat ecosystems. This facilitates portability across distributions and better accomodates the multitude of ways Node.js can be installed (e.g. using nvm).

    These can be downloaded from

    1. the releases tab in your browser

    2. the command-line:

      Latest .deb

      curl -LO $(curl -s https://api.github.com/repos/meltwater/awsudo/releases/latest | grep -Eo 'https://github\.com/meltwater/awsudo/releases/download/v.*\.deb')

      Latest .rpm

      curl -LO $(curl -s https://api.github.com/repos/meltwater/awsudo/releases/latest | grep -Eo 'https://github\.com/meltwater/awsudo/releases/download/v.*\.rpm')

    Example usages

    Command

    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

    Docker-based CI/CD

    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

    Prerequisites

    Contributing

    Gitpod ready-to-code

    Do we accept contributions? YES! (see our policy for details)

    Thank you to everyone who has been one of our contributors!

    Questions/Contact?

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

    Install

    npm i awsudo

    DownloadsWeekly Downloads

    870

    Version

    1.4.2

    License

    MIT

    Unpacked Size

    22.8 kB

    Total Files

    15

    Last publish

    Collaborators

    • avatar