Terraform module for configuring authentication between GitHub Actions and AWS, using OpenID Connect.
This module creates two IAM roles for GitHub Actions workflows to authenticate with AWS using OpenID Connect (OIDC).
The module needs to know the following:
- GitHub owner, repository name and trunk branch name: The trunk branch is granted permissions to assume a more permissive IAM role, while non-trunk branches are granted permissions to assume a more restrictive one.
- S3 bucket name and state files: The created IAM roles will be granted permissions to read and write to these Terraform state files.
- IAM policy documents: The IAM policy documents for the admin and reader roles, which define the permissions required to manage the particular remote resources for the project, such as ECS clusters, Lambda functions, etc.
flowchart LR
subgraph github[GitHub]
subgraph branches[Branches]
trunk[main]
non_trunk[feat-392/add-cluster-node]
end
subgraph gha_workflows[Workflows]
wf_release[release.yml]
wf_tests[tests.yml]
end
end
subgraph aws[AWS]
subgraph iam_roles[IAM Roles]
admin_role[Admin Role]
reader_role[Reader Role]
end
subgraph resources[Resources]
lambda_functions[Lambda Function]
ecs_cluster[ECS Cluster]
end
end
%% trunk
push[$ git push] --> trunk -- trigger --> wf_release
wf_release -- assumes --> admin_role
wf_release -- reads/writes --> resources
%% non-trunk
push --> non_trunk -- trigger --> wf_tests
wf_tests -- assumes --> reader_role
wf_tests -- reads --> resources
sequenceDiagram
participant wf as GitHub Actions Workflow
participant oidc as OpenID Connect Provider
participant sts as AWS Security Token Service
participant resources as AWS Resources
wf->>oidc: Pass JWT
oidc->>wf: Return access token
wf->> sts: Assume role with access token
sts ->> wf: Return temporary credentials
wf ->> resources: Manage AWS Resources
| Name | Version |
|---|---|
| terraform | >= 1.11.0 |
| aws | >= 6.0 |
| tls | >= 4.0 |
| Name | Version |
|---|---|
| aws | >= 6.0 |
| tls | >= 4.0 |
| Name | Type |
|---|---|
| aws_iam_openid_connect_provider.github | resource |
| aws_iam_policy.terraform_state_management | resource |
| aws_iam_role.admin | resource |
| aws_iam_role.read | resource |
| aws_iam_role_policy.admin | resource |
| aws_iam_role_policy.reader | resource |
| aws_iam_role_policy_attachment.admin_tfstate_mgmt | resource |
| aws_iam_role_policy_attachment.reader_tfstate_mgmt | resource |
| aws_partition.this | data source |
| tls_certificate.github | data source |
| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| admin_policy_document | The IAM policy document for the admin role assumed from trunk branch workflows. | object({ Version = string Statement = list(object({ Effect = string Action = list(string) Resource = string })) }) |
n/a | yes |
| github | The GitHub configuration used for configuring the OIDC provider. | object({ owner = string repo = string trunk_branch = string }) |
n/a | yes |
| name_prefix | The name prefix used for the resources created by this module. | string |
n/a | yes |
| read_policy_document | The IAM policy document for the reader role assumed from non-trunk branch workflows. | object({ Version = string Statement = list(object({ Effect = string Action = list(string) Resource = string })) }) |
n/a | yes |
| tfstate_config | The Terraform state backend configuration, to which the provider will provide access. | object({ bucket_name = string state_files = list(string) }) |
n/a | yes |
| Name | Description |
|---|---|
| admin_role | The IAM Role used for trunk branch deployments, providing full access to the remote resources. |
| reader_role | The IAM Role used for non-trunk branch deployments, providing read access to the remote resources. |