Introduction

The AWS Cloud Development Kit (CDK) is an excellent tool for defining cloud infrastructure as code, and automating deployments with GitHub Actions can make the process even smoother. But there’s one challenge: securely managing AWS credentials. Storing long-term access keys in a repository introduces significant security risks.

In this article, we’ll guide you through how to connect GitHub Actions to AWS CDK without sharing or storing keys. By using OpenID Connect (OIDC), GitHub can securely assume an AWS role, allowing CDK deployments without access keys. We’ll also detail the IAM policy needed to assume CDK roles and highlight how CDK bootstrap automatically handles most of the permissions setup.

For a detailed guide on CDK bootstrap, which creates essential roles and permissions, check out this blog post on CDK Bootstrap.

Key Takeaways

GitHub OIDC Integration: Securely authenticate GitHub Actions with AWS using OpenID Connect for CDK deployments.
CDK Roles Created by Bootstrap: Learn how the CDK bootstrap process sets up the required permissions and roles automatically.
No Access Keys: Eliminate the need to store or share long-term AWS access keys in GitHub repositories.
Enhanced Security: Use fine-grained IAM policies and roles for secure CDK deployments.

Setting Up GitHub Actions with AWS CDK

Step 1: Creating an IAM Role for GitHub with CDK Permissions

To securely connect GitHub Actions to AWS CDK, you first need an IAM role that GitHub can assume via OIDC. This role will rely on permissions established by the CDK bootstrap process.

Log in to AWS: Access the IAM section in the AWS Management Console.
Create a Role:

Navigate to Roles and click Create Role.
Choose Web Identity as the role type, and select GitHub as the identity provider.
Set the provider URL as: https://token.actions.githubusercontent.com.
Specify sts.amazonaws.com under Audience.

Add CDK Permissions:
The CDK bootstrap command automatically creates the roles and permissions needed for deploying CDK stacks. To allow GitHub Actions to assume these roles, apply the following IAM policy:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "AssumeCDKRoles",
         "Effect": "Allow",
         "Action": "sts:AssumeRole",
         "Resource": "*",
         "Condition": {
           "StringEquals": {
             "iam:ResourceTag/aws-cdk:bootstrap-role": [
               "image-publishing",
               "file-publishing",
               "deploy",
               "lookup"
             ]
           }
         }
       }
     ]
   }

This policy ensures that GitHub Actions can assume the necessary CDK roles by checking for the aws-cdk:bootstrap-role tag.

Set the Trust Relationship:
Update the trust relationship in the IAM role so GitHub Actions can assume the role using OIDC:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
             "token.actions.githubusercontent.com:sub": "repo:YOUR_GITHUB_USERNAME/YOUR_REPOSITORY:ref:refs/heads/main"
           }
         }
       }
     ]
   }

Step 2: Configuring GitHub Actions for AWS CDK Deployments

Now, let’s configure GitHub Actions to use the IAM role created above to deploy AWS CDK stacks.

Create or Modify Workflow:
Create a workflow file at .github/workflows/cdk-deploy.yml in your GitHub repository.
OIDC Role Assumption:
In your workflow, replace any hardcoded AWS credentials with role assumption using OIDC. Below is an example workflow that installs CDK, synthesizes the infrastructure, and deploys the stack:

   name: CDK Deploy

   on:
     push:
       branches:
         - main

   jobs:
     deploy:
       runs-on: ubuntu-latest
       permissions:
         id-token: write
         contents: read

       steps:
         - name: Checkout repository
           uses: actions/checkout@v2

         - name: Configure AWS Credentials
           uses: aws-actions/configure-aws-credentials@v2
           with:
             role-to-assume: arn:aws:iam::YOUR_ACCOUNT_ID:role/YOUR_ROLE_NAME
             aws-region: YOUR_REGION

         - name: Install AWS CDK
           run: npm install -g aws-cdk

         - name: Install dependencies
           run: npm install

         - name: Synthesize CDK Stack
           run: cdk synth

         - name: Deploy CDK Stack
           run: cdk deploy --require-approval never

Temporary Credentials with OIDC:
GitHub will use OIDC to securely request temporary credentials from AWS to assume the IAM role. No long-term credentials are needed.

Step 3: Verifying the Workflow

Push your changes to the GitHub repository, triggering the GitHub Actions workflow. Check the logs to ensure that the CDK stack is synthesized and deployed correctly using the IAM role created for GitHub Actions.

Step 4: Best Practices

Use CDK Bootstrap: The CDK bootstrap command handles most of the permission setup for you, creating essential roles and resources needed for deployment. For more details on how bootstrap works, refer to this blog post about CDK bootstrap.
Restrict Role Assumption: Fine-tune the trust relationship and conditions to restrict which repositories or branches can assume the IAM role, enhancing security.
Monitor Deployments: Use AWS CloudTrail to monitor role assumption and AWS CloudWatch to track CDK deployments.

Essential CDK Permissions (Created by CDK Bootstrap)

When you run the CDK bootstrap command, AWS automatically creates several roles with the necessary permissions for CDK operations. These roles include:

Deploy Role: Used for deploying AWS resources.
Image Publishing Role: Needed for publishing Docker images to Amazon ECR.
File Publishing Role: Required for uploading assets (like Lambda packages) to S3.
Lookup Role: Used by CDK for context lookups (e.g., checking existing resources during stack synthesis).

CDK bootstrap also configures these roles with the appropriate tags, such as aws-cdk:bootstrap-role, which are essential for restricting access to specific resources and tasks.

For a comprehensive guide on setting up CDK bootstrap, visit this blog post about CDK bootstrap.

Conclusion

By integrating GitHub Actions with AWS CDK using OpenID Connect (OIDC), you can automate deployments securely without storing AWS access keys. The CDK bootstrap process simplifies permission management by setting up the required IAM roles automatically, and using OIDC ensures secure role assumption during deployments.

For more detailed information on CDK bootstrap and its role in setting up permissions, be sure to check out this blog post on CDK Bootstrap.

FAQs

What does CDK bootstrap do?
The CDK bootstrap command sets up the necessary AWS resources and IAM roles for deploying CDK stacks. It automatically creates roles with the required permissions for operations like file publishing, image publishing, and resource deployment. Learn more in this blog post about CDK bootstrap.

Why is OIDC better than storing AWS keys in GitHub Actions?
OIDC allows GitHub to securely request temporary credentials from AWS without needing to store long-term credentials in the repository, reducing the risk of credential exposure.

What are the key roles created by CDK bootstrap?
CDK bootstrap creates roles like the Deploy Role, Image Publishing Role, File Publishing Role, and Lookup Role, each with specific permissions necessary for CDK operations.

Can I limit the repositories or branches that assume the IAM role?
Yes, you can configure the trust relationship in the IAM role to restrict role assumption based on the repository, branch, or specific GitHub events.

Securely Automate AWS CDK Deployments with GitHub Actions—No Access Keys Needed!