Modern DevOps practices often involve leveraging GitHub Actions for CI/CD workflows and Amazon Elastic Kubernetes Service (EKS) for container orchestration. To minimize the reliance on static credentials and improve security, integrating GitHub Actions with AWS via OpenID Connect (OIDC) provides a robust solution.

This guide will walk you through securely accessing an Amazon EKS cluster from GitHub Actions using OIDC.

Why Use OpenID Connect?

Traditionally, GitHub Actions access AWS resources through static credentials stored as secrets. While effective, this method carries risks if credentials are accidentally exposed. OIDC eliminates the need for static credentials by leveraging short-lived, dynamically generated tokens. This approach improves security and simplifies credential management.

Prerequisites

An AWS account with an EKS cluster set up.
A GitHub repository configured for your project.
The AWS CLI installed locally for initial setup with proper permissions.

Step 1: Enable OIDC in Your AWS Account

1. Add the GitHub OIDC Identity Provider: Run the following AWS CLI command to establish a trust relationship with GitHub’s OIDC provider:

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com \
  --thumbprint-list $(openssl s_client -servername token.actions.githubusercontent.com -connect token.actions.githubusercontent.com:443 2>/dev/null | openssl x509 -fingerprint -noout -sha1 | awk -F= '{print $2}' | tr -d ':')

2. Verify the OIDC Provider: Check that the OIDC provider was successfully created:

aws iam list-open-id-connect-providers

Step 2: Create an IAM Role for GitHub Actions

1. Define the Trust Policy: Create a JSON file named trust-policy.json with the following content:

{
  "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": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:<OWNER>/<REPO>:ref:refs/heads/<BRANCH>"
        }
      }
    }
  ]
}

Replace <AWS_ACCOUNT_ID>,<OWNER>,<REPO> and <BRANCH> with your AWS account ID, GitHub repository owner, repository name, and branch name.

2. Create the Role: Use the AWS CLI to create the IAM role:

aws iam create-role --role-name GitHubActionsEKSRole --assume-role-policy-document file://trust-policy.json

3. Attach a Policy for EKS Access: Attach the necessary permissions to the role. For example, to allow access to EKS, attach the AmazonEKSClusterPolicy and AmazonEKSWorkerNodePolicy

aws iam attach-role-policy --role-name GitHubActionsEKSRole --policy-arn arn:aws:iam::aws:policy/AmazonEKSClusterPolicy
aws iam attach-role-policy --role-name GitHubActionsEKSRole --policy-arn arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy

Step 3: Associate access entry

1. Add your role to the cluster: Update the cluster access entry to attach the GitHubActionsEKSRole role

aws eks create-access-entry --cluster-name <EKS_CLUSTER_NAME> --principal-arn arn:aws:iam::<AWS_ACCOUNT_ID>:role/GitHubActionsEKSRole --type STANDARD

Replace <AWS_ACCOUNT_ID>,<EKS_CLUSTER_NAME> with your AWS account ID and cluster name.

For additional configuration options: click here

2. Assign policies to the role: Add policies to the GitHubActionsEKSRole based on your requirements.

aws eks associate-access-policy --cluster-name <EKS_CLUSTER_NAME> --principal-arn arn:aws:iam::<AWS_ACCOUNT_ID>:role/GitHubActionsEKSRole \
  --access-scope type=cluster --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy

Replace <AWS_ACCOUNT_ID>,<EKS_CLUSTER_NAME> with your AWS account ID and cluster name.

For additional configuration options: click here

Step 4: Update GitHub Actions Workflow

1. Configure Permissions in Workflow File: Update your GitHub Actions workflow YAML file to use OIDC authentication. Below is an example:

name: Deploy to EKS

on:
  push:
    branches:
      - main

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v3
        with:
          role-to-assume: arn:aws:iam::<AWS_ACCOUNT_ID>:role/GitHubActionsEKSRole
          aws-region: <AWS_REGION>

      - name: Deploy to EKS
        run: |
          aws eks update-kubeconfig --name <EKS_CLUSTER_NAME> --region <AWS_REGION>
          kubectl apply -f deployment.yaml

Replace <AWS_ACCOUNT_ID>,<AWS_REGION>, and <EKS_CLUSTER_NAME> with your AWS account ID, region, and EKS cluster name. Also you can retrieve those values from github secrets.

Step 5: Test the Workflow

Push the updated workflow file to your repository and monitor the GitHub Actions workflow execution. Ensure that the deployment step successfully accesses the EKS cluster without errors.

Step 6: Secure Your Setup

Restrict Role Permissions: Minimize the permissions associated with the IAM role to adhere to the principle of least privilege.

Audit Usage: Regularly audit IAM roles and policies to ensure compliance and security.

Conclusion

By integrating GitHub Actions with Amazon EKS using OpenID Connect, you eliminate the need for static credentials, enhancing the security and simplicity of your CI/CD workflows. This setup aligns with modern DevOps best practices, providing a scalable and secure way to manage access to AWS resources.

Securely access Amazon EKS with GitHub Actions and OpenID Connect