AWS

To use Terrateam with AWS, authentication and authorization need to be configured against your AWS account. Setup only takes a minute.

OpenID Connect (OIDC)

What is OIDC

OpenID Connect (OIDC) allows your GitHub Actions workflows to access resources in AWS, without having to store any credentials as long-lived GitHub secrets.

A Terraform module and a CloudFormation template are available to easily create all of the AWS resources that Terrateam requires. Choose the setup method you’re most comfortable with.

Terraform

1. main.tf

   Note

   Replace GITHUB_ORG with your GitHub organization name. This is case-sensitive.

   module "terraform_aws_terrateam_setup" {
     source               = "github.com/terrateamio/terraform-aws-terrateam-setup"
     github_org           = "GITHUB_ORG"
     aws_policy_arn       = "arn:aws:iam::aws:policy/PowerUserAccess"
     aws_iam_role_name    = "terrateam"
     create_oidc_provider = true
   }

2. Apply Changes

   terraform apply

AWS CLI

Create the terrateam-setup Stack

Note

Replace GITHUB_ORG with your GitHub organization name. This is case-sensitive.

aws cloudformation create-stack \
--stack-name terrateam-setup \
--template-url https://terrateam-io-public.s3.us-east-2.amazonaws.com/terrateam-setup-cloudformation.yml \
--parameters ParameterKey=GithubOrg,ParameterValue=GITHUB_ORG \
ParameterKey=RoleArn,ParameterValue=arn:aws:iam::aws:policy/PowerUserAccess \
ParameterKey=CreateGithubOIDCProvider,ParameterValue=true \
ParameterKey=RoleName,ParameterValue=terrateam \
--capabilities CAPABILITY_NAMED_IAM

AWS Console

1. Create the terrateam-setup Stack

   Navigate to CloudFormation in the AWS Console to create the stack.

   Note

   Input the Terrateam CloudFormation template Amazon S3 URL:

   https://terrateam-io-public.s3.us-east-2.amazonaws.com/terrateam-setup-cloudformation.yml

   

2. Specify Stack Details

   Note

   Specify GithubOrg (case-sensitive) and set RoleArn to arn:aws:iam::aws:policy/PowerUserAccess, or choose another IAM policy that suits your needs.

   

3. Configure Stack Options

   Note

   Additional stack options aren’t required for Terrateam.

   

4. Review and Create the Stack

   

Configure Terrateam for OIDC

Create the .terrateam/config.yml configuration file at the root of your Terraform repository.

Note

Replace AWS_ACCOUNT_ID with your AWS account ID.

hooks:
  all:
    pre:
      - type: oidc
        provider: aws
        role_arn: "arn:aws:iam::AWS_ACCOUNT_ID:role/terrateam"

Did you know?

You can utilize distinct ARNs for various environments and operations. For more details, read the Cloud Credentials documentation.

Manual Instructions

Follow the instructions below to manually configure AWS for Terrateam authentication and authorization.

Expand for step-by-step OIDC and static credentials instructions

OIDC

1. Create the OIDC provider in AWS

   aws iam create-open-id-connect-provider \
   --url https://token.actions.githubusercontent.com \
   --client-id-list sts.amazonaws.com --thumbprint-list \
   6938fd4d98bab03faadb97b34396831e3780aea1 \
   1c58a3a8518e8759bf075b76b750d4f2df264fcd

2. Create a local file on your workstation named trustpolicy.json

   This file will define the policy to be used to allow AWS to trust GitHub’s OIDC as a federated identity. You must update the example file below with your own values. Replace AWS_ACCOUNT_ID and GITHUB_ORG (case-sensitive).

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Federated": "arn:aws:iam::AWS_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringLike": {
             "token.actions.githubusercontent.com:sub":
               "repo:GITHUB_ORG/*"
           },
           "StringEquals": {
             "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
           }
         }
       }
     ]
   }

   • Example trustpolicy.json that grants access to a single repository
   • Example trustpolicy.json that grants access to multiple repositories

3. Create a terrateam IAM role using the newly created trustpolicy.json

   aws iam create-role \
   --role-name terrateam \
   --assume-role-policy-document file://trustpolicy.json

4. Attach the PowerUserAccess IAM policy or another policy of your choosing

   aws iam attach-role-policy \
   --policy-arn arn:aws:iam::aws:policy/PowerUserAccess \
   --role-name terrateam

5. Configure Terrateam for OIDC

Static Credentials

1. Create a terrateam IAM user

   aws iam create-user --user-name terrateam

2. Attach the PowerUserAccess IAM policy

   aws iam attach-user-policy \
   --policy-arn arn:aws:iam::aws:policy/PowerUserAccess \
   --user-name terrateam

3. Create an access key for the terrateam user

   aws iam create-access-key --user-name terrateam

4. Export your Terraform organization/repo combination as an environment variable.

   export REPO="<OWNER/REPO>"

5. Create the AWS Access Key ID GitHub Secret

   gh secret --repo "$REPO" set AWS_ACCESS_KEY_ID

6. Create the AWS Secret Access Key GitHub Secret

   gh secret --repo "$REPO" set AWS_SECRET_ACCESS_KEY

You are now able to use Terrateam for plan and apply operations against AWS resources.