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.

   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.

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

   

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"

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.

   {
     "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.