From 1df2713d71be2faa71167ba630842cdf7b38b2e1 Mon Sep 17 00:00:00 2001 From: Bjorn Olsen Date: Wed, 11 Dec 2024 10:41:53 +0200 Subject: [PATCH] fix: Fix README and provide more details on custom image (#53) --- README.md | 50 +++++++++++++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 3060228..ef0e1f7 100644 --- a/README.md +++ b/README.md @@ -8,31 +8,30 @@ Deploy GitHub Action runners in your AWS Account. Uses AWS CodeBuild to manage e --- [![Maintenance](https://img.shields.io/badge/Maintained-yes-green.svg)](https://github.com/cloudandthings/terraform-aws-github-runners/graphs/commit-activity) -[![Test Status](https://github.com/cloudandthings/terraform-aws-github-runners/actions/workflows/main.yml/badge.svg)](https://github.com/cloudandthings/terraform-aws-github-runners/actions/workflows/main.yml) ![Terraform Version](https://img.shields.io/badge/tf-%3E%3D0.13.0-blue) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit) ## Why? -Deploying self-hosted GitHub runner should be simple. +Deploying self-hosted GitHub runners should be simple and cheap. It shouldn't need a long setup process or a lot of infrastructure. -This module additionally does not require public inbound traffic, and can be easily customised if needed. +#### Features -## Features +- Simple. See the examples for a quick-start. +- Serverless. No EC2 instances that need to be maintained. +- Cost-effective. You are billed only when a CodeBuild project is running your GitHub workflow. Projects are billed per build minute. +- Scalable. Runners are subject to [AWS CodeBuild quotas](https://docs.aws.amazon.com/codebuild/latest/userguide/limits.html) -- Simple! See the provided examples for a quick-start. -- Serverless. No EC2 instances that need to be maintained -- Cost-effective. Only billed for when CodeBuild project is running as projects are billed per build minute. -- Scalable. By default one runner process and 20GB storage is provided per vCPU per EC2 instance. +For many projects, CI/CD is run infrequently and there are long periods of time when no CI/CD runs occur. Using AWS CodeBuild means that GitHub runners are always available, billed only when used, and cost nothing when idle. -For many projects, CI/CD is run infrequently and there are long periods of time when no CI/CD runs occur. Using CodeBuild means that GitHub runners are always available, and cost nothing when idle. +This module additionally does not require public inbound traffic, and it can be easily customised if needed. ## Previous version notice Previously, this module used EC2 spot instances with configurable AutoScaling. -Should you wish to continue to use this older approach, the code has been moved to (terraform-aws-github-runners-ec2)[https://github.com/cloudandthings/terraform-aws-github-runners-ec2]. +Should you wish to continue to use this older approach, the code has been moved to [terraform-aws-github-runners-ec2](https://github.com/cloudandthings/terraform-aws-github-runners-ec2) ## Known limitations @@ -43,10 +42,12 @@ This is because some of the GitHub `uses` actions do not work by default. # How it works - + + An AWS CodeBuild Project and a webhook is created in a specific GitHub repo. The webhook is used to trigger the build project when a Github Action is triggered. The CodeBuild project run will self-configure as a GitHub runner, and run the job commands in the repo's workflow file. Steps execute arbitrary commands, defined by your repo workflows. @@ -61,19 +62,38 @@ For example: ## 1. Setup authentication to GitHub There are several ways to set up authentication to GitHub. -Follow the guide [here](/docs/GITHUB-AUTH-SETUP.md). +Follow the guide [here](https://github.com/cloudandthings/terraform-aws-github-runners/blob/main/docs/GITHUB-AUTH-SETUP.md). ## 2. Configure this module Configure and deploy this module using Terraform. See examples below. -## 3. (Optional) create a custom Docker image +## 3. (Optional) Use a custom Docker image + +You may want the runner to execute in a pre-configured environment. + +The value of `environment_image` is used to specify a Docker image for this purpose. + +Valid values include: + +- Docker images provided by CodeBuild, e.g `aws/codebuild/amazonlinux2-x86_64-standard:4.0` +- Docker Hub images, e.g. `hashicorp/terraform:latest` +- Full Docker repository URIs, such as those for Amazon ECR, e.g. `137112412989.dkr.ecr.us-west-2.amazonaws.com/amazonlinux:latest` + +Logic in the module is used to determine the final image to be used. + +- Whenever you specify a value for `var.environment_image` then your specified value is used. +- If no value was specified for `var.environment_image` and you are not using Amazon ECR, then a default CodeBuild image is used - specifically `aws/codebuild/amazonlinux2-x86_64-standard:5.0`. +- If no value was specified for `var.environment_image` and you are using Amazon ECR, then an image with a `latest` tag is assumed to exist in your Amazon ECR repo and the module will try to use it. + +To use Amazon ECR you may either provide the name of an existing ECR repository, or use this module to create one for you. +You will need to ensure an image is created in the ECR repository with a `latest` tag, or you can specify a different tag by using a specific value for `environment_image` as described above. -If you want the runner to execute in a pre-configured environment you can build and push your own Docker image for it to use. +The final value of `environment_image` is provided as an output variable so you can view and use it. # More info -- Found an issue? Want to help? See the [contribution guide](/CONTRIBUTING.md). +- Found an issue? Want to help? See [CONTRIBUTING.md](https://github.com/cloudandthings/terraform-aws-github-runners/blob/main/CONTRIBUTING.md).