Configure AWS credentials

Configure Amazon Web Services Identity and Access Management (IAM) credentials, Amazon Elastic Container Registry (ECR) credentials, and Amazon Elastic Kubernetes Service (EKS) credentials for use in CloudBees workflows.

The configure-aws-credentials action implements the AWS SDK credential resolution chain and sets configuration and credential files for other CloudBees actions. Configuration and credential files are detected by both the AWS SDKs and the AWS CLI for AWS API calls. ECR and EKS credential actions both require AWS credentials to be configured first.

About `aws-session-token`

CloudBees recommends using this token only when OpenID Connect (OIDC) authentication is not possible.

The aws-session-token is used when temporary session credentials are needed. Use OpenID Connect (OIDC) authentication instead where possible, as it simplifies credential management and avoids manually updating session tokens. The aws-session-token is best suited for complex workflows where OIDC authentication is not an option.

If using a long-term IAM user, a session token is not necessary. CloudBees recommends using a dedicated AWS IAM user with minimal permissions only when OIDC integration is not possible. For such use cases, assign an IAM policy similar to the following to allow the creation of long-term credentials:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:CreateAccessKey",
        "iam:DeleteAccessKey",
        "iam:UpdateAccessKey",
        "iam:ListAccessKeys"
      ],
      "Resource": "arn:aws:iam::account-id:user/username"
    }
  ]
}▼

Replace account-id with your AWS account ID and username with the name of the IAM user.

AssumeRole with static IAM credentials

The following example assumes a role using static IAM credentials stored in secrets:

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-2
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          role-external-id: ${{ secrets.AWS_ROLE_EXTERNAL_ID }}
          role-duration-seconds: 1200
          role-session-name: MySessionName▼

Authenticate as a user with static IAM credentials

The following example authenticates directly as an IAM user using static credentials stored in secrets:

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-2▼

AssumeRole using previous credentials

This method allows role chaining for complex workflows that require switching roles.

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-2

    # ...

      - name: Configure other AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
          aws-region: us-east-2
          role-to-assume: arn:aws:iam::987654321000:role/my-second-role
          role-session-name: MySessionName
          role-chaining: true▼

Use an inline session policy

You can use an IAM policy in stringified JSON format as an inline session policy. Code the JSON as either a single line or formatted.

Single-line JSON:

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
           inline-session-policy: '{"Version":"2012-10-17","Statement":[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:List*","Resource":"*"}]}'▼

Formatted JSON:

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
           inline-session-policy: >-
            {
             "Version": "2012-10-17",
             "Statement": [
              {
               "Sid":"Stmt1",
               "Effect":"Allow",
               "Action":"s3:List*",
               "Resource":"*"
              }
             ]
            }▼

Use managed session policies

You can use Amazon Resource Names (ARNs) of IAM managed policies as managed session policies. The policies must exist in the same account as the role.

Pass a single managed policy:

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
          managed-session-policies: arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess▼

Pass multiple managed policies:

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
           managed-session-policies: |
            arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess
            arn:aws:iam::aws:policy/AmazonS3OutpostsReadOnlyAccess▼

Inputs

Table 1. Input details
Input name	Data type	Required?	Description
`aws-access-key-id`	String	Yes	The AWS access key ID.
`aws-secret-access-key`	String	Yes	The AWS secret key.
`aws-session-token`	String	No	The AWS session token to use. Required for temporary credentials and most common authentication setups.
`aws-region`	String	Yes	The AWS region.
`role-to-assume`	String	No	The AWS role to assume.
`role-external-id`	String	No	The AWS role external ID.
`role-duration-seconds`	String	No	The AWS role duration, in seconds.
`role-session-name`	String	No	The AWS role session name.
`role-chaining`	Boolean	No	Whether there is chaining of the AWS roles. Default value is `false`, specifying no chaining.
`inline-session-policy`	JSON	No	The AWS inline role session policy.
`managed-session-policy`	String	No	The AWS managed role session policy.

Configure Amazon ECR credentials

The configure-ecr-credentials action logs in to one or more ECR private registries or to an ECR public registry.

Before using this action, add the following steps to your workflow:

      - name: Check out repo
        uses: actions/checkout@v1

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::123456789012:role/my-cloudbees-actions-role
          aws-region: your-aws-region▼

Refer to the AssumeRole with static IAM credentials or Authenticate as a user with static IAM credentials sections above for details.

Log in to ECR and push a container image

The following example logs in to an ECR private registry, then builds, tags, and pushes a container image to it:

      - name: Log in to ECR
        id: login-ecr
        uses: https://github.com/cloudbees-io/configure-ecr-credentials@v1

      - name: Build, tag, and push a container image to ECR
        uses: https://github.com/cloudbees-io/kaniko@v1
        with:
          destination: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-ecr-repo:latest▼

Build and publish container images

Log in to ECR and push a Helm chart

The following example logs in to an ECR private registry, then packages and pushes a Helm chart to it:

      - name: Log in to ECR
        id: login-ecr
        uses: https://github.com/cloudbees-io/configure-ecr-credentials@v1

      - name: Package and push helm chart to ECR
        env:
          REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          REPOSITORY: my-ecr-repo
        uses: docker://alpine/helm:latest
        run: |
          helm package my-ecr-repo
          helm push my-ecr-repo-0.1.0.tgz oci://123456789012.dkr.ecr.us-east-1.amazonaws.com▼

Helm and Kaniko use the same credential store, so you can use the same credentials for both.

Log in to ECR on multiple AWS accounts

The following example configures AWS credentials and then provides cross-account access:

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::123456789012:role/my-cloudbees-actions-role
          aws-region: eu-west-2

      - name: Log in to ECR
        id: login-ecr
        uses: https://github.com/cloudbees-io/configure-ecr-credentials@v1
        with:
          registries: "123456789012,998877665544"▼

The repository on account 998877665544 must explicitly grant access to the arn:aws:iam::123456789012:role/my-cloudbees-actions-role role for cross-account access to work.

Refer to AWS documentation on allowing secondary account access for how to correctly configure ECR policies.

Log in to ECR in multiple regions

By default, only the current AWS region is configured. To configure multiple regions, provide a comma-separated list of regions:

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::123456789012:role/my-cloudbees-actions-role
          aws-region: us-east-1
      - name: Log in to ECR
        id: login-ecr
        uses: https://github.com/cloudbees-io/configure-ecr-credentials@v1
        with:
          regions: eu-west-2,ap-south-2,ap-southeast-2▼

Inputs

Table 2. Input details
Input name	Data type	Required?	Description
`registries`	String	No	The registry ID.

Configure Amazon EKS credentials

The configure-eks-credentials action updates ~/.kube/config with credentials for connecting to an Amazon Elastic Kubernetes Service cluster.

Before using this action, add the following steps to your workflow:

      - name: Check out repo
        uses: actions/checkout@v1

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::123456789012:role/my-cloudbees-actions-role
          aws-region: your-aws-region▼

Refer to the AssumeRole with static IAM credentials or Authenticate as a user with static IAM credentials sections above for details.

Authenticate with the current credentials role

The following example authenticates to Amazon Elastic Kubernetes Service with the current credentials role:

      - name: Login to Amazon EKS
        uses: https://github.com/cloudbees-io/configure-eks-credentials@v1
        with:
          name: my-eks-cluster-name

      - name: Do some things with the cluster
        uses: docker://alpine/k8s:latest
        run: |
          kubectl apply -k ...▼

Assume a different role

To get correct credentials for Amazon Elastic Kubernetes Service, you may need to assume a role different from your current role.

The current Amazon Web Services credentials must be able to assume the role.

      - name: Log in to Amazon EKS
        uses: https://github.com/cloudbees-io/configure-eks-credentials@v1
        with:
          name: my-eks-cluster-name
          role-to-assume: my-eks-admin-role

      - name: Do some things with the cluster
        uses: docker://alpine/k8s:latest
        run: |
          helm install ...▼

To assume a different role, use the role-session-name and role-external-id inputs from the AWS credentials inputs.

Connect to multiple clusters

Merge credentials into ~/.kube/config by chaining multiple configure-eks-credentials steps. This lets you authenticate to multiple EKS clusters or switch between different authentications for the same cluster.

The workflow always sets the current context, so the last one takes precedence.

      - name: Log in to Amazon EKS as admin
        uses: https://github.com/cloudbees-io/configure-eks-credentials@v1
        with:
          name: my-eks-cluster-name
          role-to-assume: my-eks-admin-role
          user-alias: admin
          alias: cluster-with-admin

      - name: Log in to Amazon EKS as regular user
        uses: https://github.com/cloudbees-io/configure-eks-credentials@v1
        with:
          name: my-eks-cluster-name
          user-alias: standard
          alias: cluster-without-admin

      - name: Do some things with the cluster
        uses: docker://alpine/k8s:latest
        run: |
          helm --kubecontext cluster-with-admin install ...
          kubectl --context cluster-without-admin get pods ...
          kubectl --context cluster-with-admin patch ...▼

Connect to a cluster in a different region

To authenticate to AWS, you must specify the region to connect to. By default, the cluster must be in the same region as the configured AWS region. If you specify the region input on the EKS action, you can connect to a cluster in a different region without updating the AWS-configured region.

Combine this with the Connect to multiple clusters approach to apply operations across multiple regions.

      - name: Configure AWS credentials
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::123456789012:role/my-cloudbees-actions-role
          aws-region: eu-west-2
      - name: Log in to Amazon EKS cluster in a different region
        uses: https://github.com/cloudbees-io/configure-eks-credentials@v1
        with:
          name: my-eks-cluster-name
          region: us-east-2▼

Inputs

Table 3. Input details
Input name	Data type	Required?	Description
`name`	String	Yes	The EKS cluster name.
`role-to-assume`	String	No	The EKS role to assume.
`user-alias`	String	No	The user alias.
`alias`	String	No	The EKS alias.

Configure AWS credentials

About aws-session-token

AssumeRole with static IAM credentials

Authenticate as a user with static IAM credentials

AssumeRole using previous credentials

Use an inline session policy

Use managed session policies

Inputs

Configure Amazon ECR credentials

Log in to ECR and push a container image

Log in to ECR and push a Helm chart

Log in to ECR on multiple AWS accounts

Log in to ECR in multiple regions

Inputs

Configure Amazon EKS credentials

Authenticate with the current credentials role

Assume a different role

Connect to multiple clusters

Connect to a cluster in a different region

Inputs

Related pages

About `aws-session-token`