feat!: Allow custom ECR, rename var.use_ecr_image, and cleanup

.pre-commit-config.yaml

@@ -14,7 +14,7 @@
 exclude: '^modules/external/.*$'
 
 repos:
-# TERRAFORM
+  # TERRAFORM
   # If running tf-docs it must be run first to avoid race condition relating to version constraints.
   # BUG: terraform_docs hook conflicts when used more than once.
   # Workaround with Python
@@ -54,7 +54,8 @@ repos:
       - id: terraform_checkov
         # Configure checkov by creating and updating the config file below.
         args: ['--args=--config-file __GIT_WORKING_DIR__/.checkov-config.yml']
-# Python
+
+  # PYTHON
   - repo: https://github.com/psf/black
     rev: 22.6.0
     hooks:
@@ -63,7 +64,8 @@ repos:
     rev: 5.0.4
     hooks:
     - id: flake8
-# PRECOMMIT - GENERAL
+
+  # PRECOMMIT - GENERAL
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
@@ -91,6 +93,15 @@ repos:
         args: ['--branch', 'develop', '--branch', 'main', '--branch', 'master']
       - id: requirements-txt-fixer
       - id: trailing-whitespace
+
+  # CODESPELL
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+    - id: codespell
+      args: ['--write-changes']
+
+  # LOCAL
   - repo: local
     hooks:
     -   id: no-vanilla-readme

docs/GITHUB-AUTH-SETUP.md

@@ -0,0 +1,46 @@
+# Setting up authentication to GitHub
+
+## 1. Decide on how to authenticate to GitHub
+
+Here we focus on setting up a personal access token to authenticate to GitHub.
+OAuth is also supported but not implemented / documented here.
+
+<!-- TODO OAuth -->
+
+### GitHub access token
+
+Note that CodeBuild only supports 1 GitHub token to be configured for all CodeBuild projects in the same AWS Account and Region.
+
+Therefore, when using multiple CodeBuild projects, you can configure the token once per region (not once per project).
+
+There are a few approaches that you could take, choose one from the below.
+
+#### 2. Create your GitHub token
+
+Create a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).
+Make sure that the fine grained token has [these](https://docs.aws.amazon.com/codebuild/latest/userguide/access-tokens-github.html#access-tokens-github-prereqs) permissions.
+
+
+#### 2a. Add the token to CodeBuild separately.
+
+You would add the token as [documented here](https://docs.aws.amazon.com/codebuild/latest/userguide/access-tokens-github.html)
+This is recommended if you do not want to maintain the token in Terraform.
+
+#### 2b. Provide the token as an input Terraform variable
+
+Note that although the variable is sensitive, the value will still be stored in Terraform state.
+
+#### 2c. Use AWS Parameter Store
+
+<!-- TODO there seems to be a SecretsManager option in the link above - worth investigating -->
+
+Add the token to AWS Systems Manager Parameter Store, and configure this module to read it.
+The module will add the token to Codebuild for you.
+
+This is recommended if you have only a single project.
+
+### Adding your token to Parameter Store (Optional)
+
+Add it to AWS Systems Manager Parameter Store with the `SecureString` type.
+
+[![Parameter Store configuration](https://github.com/cloudandthings/terraform-aws-github-runners/blob/main/docs/images/ssm.png)](https://github.com/cloudandthings/terraform-aws-github-runners/blob/main/docs/images/ssm.png )

examples/addition-iam-policies/README.md

@@ -10,8 +10,12 @@ module "runners" {
 
   github_personal_access_token_ssm_parameter = var.github_personal_access_token_ssm_parameter
 
+  # Environment image is not specified so it will default to:
+  # "aws/codebuild/amazonlinux2-x86_64-standard:5.0"
+
   vpc_id     = var.vpc_id
   subnet_ids = var.subnet_ids
+
   iam_role_policies = {
     "allow_secrets_manager" = aws_iam_policy.secrets_manager.arn,
     "s3_managed_policy"     = "arn:aws:iam::aws:policy/AmazonS3FullAccess",

examples/addition-iam-policies/main.tf

@@ -6,8 +6,12 @@ module "runners" {
 
   github_personal_access_token_ssm_parameter = var.github_personal_access_token_ssm_parameter
 
+  # Environment image is not specified so it will default to:
+  # "aws/codebuild/amazonlinux2-x86_64-standard:5.0"
+
   vpc_id     = var.vpc_id
   subnet_ids = var.subnet_ids
+
   iam_role_policies = {
     "allow_secrets_manager" = aws_iam_policy.secrets_manager.arn,
     "s3_managed_policy"     = "arn:aws:iam::aws:policy/AmazonS3FullAccess",

examples/advanced/README.md

@@ -51,13 +51,18 @@ module "github_runner" {
   # Naming for all created resources
   name = "github-runner-codebuild-test"
 
+  # Environment image is not specified so it will default to:
+  # "${local.aws_account_id}.dkr.ecr.${local.aws_region}.amazonaws.com/${local.ecr_repository_name}:latest"
+  # Because an ECR repo is used
+
   vpc_id     = "vpc-0ffaabbcc1122"
   subnet_ids = ["subnet-0123", "subnet-0456"]
+
   # Optional parameters
   ################################
+  create_ecr_repository = true
 
   security_group_ids         = [aws_security_group.this.id]
-  use_ecr_image              = true
   cloudwatch_logs_group_name = "/some/log/group"
 }
 ```

examples/advanced/main.tf

@@ -47,12 +47,17 @@ module "github_runner" {
   # Naming for all created resources
   name = "github-runner-codebuild-test"
 
+  # Environment image is not specified so it will default to:
+  # "${local.aws_account_id}.dkr.ecr.${local.aws_region}.amazonaws.com/${local.ecr_repository_name}:latest"
+  # Because an ECR repo is used
+
   vpc_id     = "vpc-0ffaabbcc1122"
   subnet_ids = ["subnet-0123", "subnet-0456"]
+
   # Optional parameters
   ################################
+  create_ecr_repository = true
 
   security_group_ids         = [aws_security_group.this.id]
-  use_ecr_image              = true
   cloudwatch_logs_group_name = "/some/log/group"
 }

examples/basic/README.md

@@ -11,6 +11,9 @@ module "github_runner" {
   name            = "github-runner-codebuild-test"
   source_location = "https://github.com/my-org/my-repo.git"
 
+  # Environment image is not specified so it will default to:
+  # "aws/codebuild/amazonlinux2-x86_64-standard:5.0"
+
   # Optional parameters
   ############################
   github_personal_access_token = "example"

examples/basic/main.tf

@@ -7,6 +7,9 @@ module "github_runner" {
   name            = "github-runner-codebuild-test"
   source_location = "https://github.com/my-org/my-repo.git"
 
+  # Environment image is not specified so it will default to:
+  # "aws/codebuild/amazonlinux2-x86_64-standard:5.0"
+
   # Optional parameters
   ############################
   github_personal_access_token = "example"

examples/multiple-runners/README.md

@@ -7,12 +7,14 @@ module "runners" {
 
   source = "../../"
 
-  name = "${each.value.source_name}-github-runner"
-
+  name            = "${each.value.source_name}-github-runner"
   source_location = each.value.source_location
 
   github_personal_access_token_ssm_parameter = var.github_personal_access_token_ssm_parameter
 
+  # Environment image is not specified so it will default to:
+  # "aws/codebuild/amazonlinux2-x86_64-standard:5.0"
+
   vpc_id     = var.vpc_id
   subnet_ids = var.subnet_ids
 }

examples/multiple-runners/main.tf

@@ -3,12 +3,14 @@ module "runners" {
 
   source = "../../"
 
-  name = "${each.value.source_name}-github-runner"
-
+  name            = "${each.value.source_name}-github-runner"
   source_location = each.value.source_location
 
   github_personal_access_token_ssm_parameter = var.github_personal_access_token_ssm_parameter
 
+  # Environment image is not specified so it will default to:
+  # "aws/codebuild/amazonlinux2-x86_64-standard:5.0"
+
   vpc_id     = var.vpc_id
   subnet_ids = var.subnet_ids
 }

iam.tf

@@ -1,5 +1,7 @@
+################################################################################
+# Cloudwatch permissions
+################################################################################
 data "aws_iam_policy_document" "cloudwatch_required" {
-  # Cloudwatch permissions
   statement {
     sid    = "AllowCreateLogGroup"
     effect = "Allow"
@@ -26,9 +28,11 @@ resource "aws_iam_role_policy" "cloudwatch_required" {
   policy = data.aws_iam_policy_document.cloudwatch_required.json
 }
 
+################################################################################
+# VPC permissions
+################################################################################
 data "aws_iam_policy_document" "networking_required" {
   count = local.has_vpc_config ? 1 : 0
-  # VPC permissions
   statement {
     sid    = "AllowNetworkingDescribe"
     effect = "Allow"
@@ -74,8 +78,10 @@ resource "aws_iam_role_policy" "networking_required" {
   policy = data.aws_iam_policy_document.networking_required[0].json
 }
 
+################################################################################
+# S3 permissions
+################################################################################
 data "aws_iam_policy_document" "s3_required" {
-  # S3 permissions
   count = local.has_s3_log_bucket ? 1 : 0
   statement {
     effect  = "Allow"
@@ -94,9 +100,11 @@ resource "aws_iam_role_policy" "s3_required" {
   policy = data.aws_iam_policy_document.s3_required[0].json
 }
 
+################################################################################
+# ECR permissions
+################################################################################
 data "aws_iam_policy_document" "ecr_required" {
-  count = var.use_ecr_image ? 1 : 0
-  # ECR permissions
+  count = local.use_ecr_repository ? 1 : 0
   statement {
     effect = "Allow"
     actions = [
@@ -106,7 +114,7 @@ data "aws_iam_policy_document" "ecr_required" {
       "ecr:GetAuthorizationToken"
     ]
     resources = [
-      aws_ecr_repository.this[0].arn,
+      "arn:aws:ecr:${local.aws_region}:${local.aws_account_id}:repository/${local.ecr_repository_name}",
     ]
   }
 
@@ -120,7 +128,7 @@ data "aws_iam_policy_document" "ecr_required" {
 }
 
 resource "aws_iam_role_policy" "ecr_required" {
-  count  = var.use_ecr_image ? 1 : 0
+  count  = local.use_ecr_repository ? 1 : 0
   name   = "${var.name}-ecr"
   role   = local.create_iam_role ? aws_iam_role.this[0].name : var.iam_role_name
   policy = data.aws_iam_policy_document.ecr_required[count.index].json
@@ -140,13 +148,19 @@ data "aws_iam_policy_document" "assume_role" {
   }
 }
 
+################################################################################
+# Create role
+################################################################################
 resource "aws_iam_role" "this" {
   count                = local.create_iam_role ? 1 : 0
   name                 = var.name
   assume_role_policy   = data.aws_iam_policy_document.assume_role[0].json
   permissions_boundary = var.iam_role_permissions_boundary == null ? null : var.iam_role_permissions_boundary
 }
 
+################################################################################
+# Custom permissions
+################################################################################
 resource "aws_iam_role_policy_attachment" "additional" {
   for_each = var.iam_role_policies
 

locals.tf

@@ -13,12 +13,6 @@ locals {
 
   subnet_arns = [for subnet_id in var.subnet_ids : "arn:aws:ec2:${local.aws_region}:${local.aws_account_id}:subnet/${subnet_id}"]
 
-  security_group_ids = (
-    length(var.security_group_ids) == 0
-    ? try([aws_security_group.codebuild[0].id], [])
-    : concat(try([aws_security_group.codebuild[0].id], []), var.security_group_ids)
-  )
-
   create_iam_role = var.iam_role_name == null
 
   cloudwatch_logs_group_arn = (