Merge branch 'release/3.7.0'

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+
+## 3.7.0 - 2019-07-17
+- Changed
+ - Creation of multiple instances of the runner is now supported. Cache is therefor moved to an internal module. Pleas see the example `runner-public` for a concrete sample. The change should have no effect if you apply the state migration script `migragations/migration-state-3.7.x.sh`.
+ - Examples are more generic by removing the time zone and AZ zone to variables. @@theBenForce
+
 ## 3.6.0 - 2019-07-04
 - Changed
  - Add option to specify pull policy for docker images by the runner. @roock
@@ -138,7 +144,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Update default AMI's to The latest Amazon Linux AMI 2017.09.1 - released on 2018-01-17.
 - Minor updates in the example
 
-[Unreleased]: https://github.com/npalm/terraform-aws-gitlab-runner/compare/3.5.0...HEAD
+[Unreleased]: https://github.com/npalm/terraform-aws-gitlab-runner/compare/3.7.0...HEAD
+[3.7.0]: https://github.com/npalm/terraform-aws-gitlab-runner/compare/3.6.0...3.7.0
+[3.6.0]: https://github.com/npalm/terraform-aws-gitlab-runner/compare/3.5.0...3.6.0
 [3.5.0]: https://github.com/npalm/terraform-aws-gitlab-runner/compare/3.4.0...3.5.0
 [3.4.0]: https://github.com/npalm/terraform-aws-gitlab-runner/compare/3.3.0...3.4.0
 [3.3.0]: https://github.com/npalm/terraform-aws-gitlab-runner/compare/3.2.0...3.3.0

README.md

@@ -4,21 +4,41 @@
 
 > *WIP*: Work in progress, conversion to Terraform 0.12 \#73. Feel free to checkout branch [Terraform 0.12](https://github.com/npalm/terraform-aws-gitlab-runner/tree/feature/terraform-0.12).
 
-> *NEW*: The runner will register itself automatically to GitLab. No need to register the runner first, see also the [examples](./examples)
+> *NEW*: Multiple instnaces of the runner can be created that share the same cache. See [example](./examples/runner-public) *MIGRATIONS*: Since 3.7 the runner cache is handled by sub module. To avoid re-creation of the bucket while upgrading a state migration is need. Please see the migration script `./migrations/migration-state-3.7.x.sh`
 
-This repo contains a Terraform module and examples to run a [GitLab CI multi runner](https://docs.gitlab.com/runner/) on AWS Spot instances. See the blog post at [040code](https://040code.github.io/2017/12/09/runners-on-the-spot/) for a detailed description of the setup.
+This [Terraform](https://www.terraform.io/) modules creates a [GitLab CI runner](https://docs.gitlab.com/runner/). A blog post describes the original version of the the runner. See the post at [040code](https://040code.github.io/2017/12/09/runners-on-the-spot/). The original setup of the module is based on the blog post: [Auto scale GitLab CI runners and save 90% on EC2 costs](https://about.gitlab.com/2017/11/23/autoscale-ci-runners/).
 
-![GitLab Runners](https://github.com/npalm/assets/raw/master/images/2017-12-06_gitlab-multi-runner-aws.png)
+The runners created by the module using by default spot instances for running the builds using the `docker+machine` executor.
 
-The setup is based on the blog post: [Auto scale GitLab CI runners and save 90% on EC2 costs](https://about.gitlab.com/2017/11/23/autoscale-ci-runners/) The gitlab-ci runners that this project creates will be configured to use a shared cache via S3 by default. Additionally their logs will be streamed to CloudWatch. The s3 stored cache expiration is configurable and is set to expire in X days by default. Logging can be disabled. The accompanying post mentions that you have to register the the runner before running the Terraform scripts. Since version 3+ this is no longer required. You can simply define the runner configuration, including the runner registration token, via terraform.
+ - Shared cache in S3 with life cycle management to clear objects after x days.
+ - Logs streamed to CloudWatch.
+ - Runner agents registered automatically.
 
-In addition to the auto scaling option (docker+machine executor) the docker executor is supported for a single node.
+The runner support 3 main scenario's:
+
+### GitLab CI docker-machine runner - one runner agent
+
+In this scenario the runner agent is running on a single EC2 node and runners are created by [docker machine](https://docs.gitlab.com/runner/configuration/autoscale.html) using spot instances. Runners will scale automatically based on configuration. The module creates by default a S3 cache that is shared cross runners (spot instances).
+
+![runners-default](https://github.com/npalm/assets/raw/master/images/terraform-aws-gitlab-runner/runner-default.png)
+
+### GitLab CI docker-machine runner - multiple runner agents
+
+In this scenario the multiple runner agents can be created with different configuration by instantiating the module multiple times. Runners will scale automatically based on configuration. The S3 cache can be shared cross runners by managing the cache outside the module.
+
+![runners-cache](https://github.com/npalm/assets/raw/master/images/terraform-aws-gitlab-runner/runner-cache.png)
+
+### GitLab Ci docker runner
+
+In this scenario *not* docker machine is used but docker to schedule the builds. Builds will run on the same EC2 instance as the agent. No auto scaling is supported.
+
+![runners-docker](https://github.com/npalm/assets/raw/master/images/terraform-aws-gitlab-runner/runner-docker.png)
 
 ## Prerequisites
 
 ### Terraform
 
-Ensure you have Terraform installed, see `.terraform-version` for the used version. A handy tool to mange your Terraform version is [tfenv](https://github.com/kamatama41/tfenv).
+Ensure you have Terraform installed the modules is based on Terraform 0.11, see `.terraform-version` for the used version. A handy tool to mange your Terraform version is [tfenv](https://github.com/kamatama41/tfenv).
 
 On macOS it is simple to install `tfenv` using brew.
 
@@ -34,16 +54,11 @@ tfenv install <version>
 
 ### AWS
 
-Export your AWS Security Credentials:
-
-``` sh
-export AWS_ACCESS_KEY_ID=...
-export AWS_SECRET_ACCESS_KEY=...
-```
+Ensure you have setup you AWS credentials. The module requires access to IAM, EC2, CloudWatch, S3 and SSM.
 
 ### Service linked roles
 
-The gitlab runner EC2 instance requires the following service linked roles:
+The GitLab runner EC2 instance requires the following service linked roles:
 
  - AWSServiceRoleForAutoScaling
  - AWSServiceRoleForEC2Spot
@@ -93,6 +108,12 @@ Once you have created the parameter, you must remove the variable `runners_token
 
 Finally, the runner still supports the manual runner creation. No changes are required. Please keep in mind that this setup will be removed in future releases.
 
+### GitLab runner cache
+
+By default the module creates a a cache for the runner in S3. Old objects are automatically remove via a configurable life cycle policy on the bucket.
+
+Creation of the bucket can be disabled and managed outside this module. A good use case is for sharing the cache cross multiple runners. For this purpose the cache is implemented as sub module. For more details see the [cache module](./cache). An example implementation of this use case can be find in the [runner-public](./examples/runner-public) example.
+
 ## Usage
 
 ### Configuration
@@ -109,61 +130,56 @@ The base image used to host the GitLab Runner agent is the latest available Amaz
 
 ### Usage module
 
+Below a basic examples of usages of the module. The dependencies such as a VPC, and SSH keys have a look at the [default example](./examples/runner-default).
+
 ``` hcl
+
 module "runner" {
  source = "npalm/gitlab-runner/aws"
- version = "3.2.0"
+ version = "3.6.0"
 
- aws_region = "${var.aws_region}"
- environment = "${var.environment}"
- ssh_public_key = "${file("${var.ssh_key_file}")}"
+ aws_region = "eu-west-1"
+ environment = "spot-runners"
+
+ ssh_public_key = "${local_file.public_ssh_key.content}"
 
  vpc_id = "${module.vpc.vpc_id}"
  subnet_ids_gitlab_runner = "${module.vpc.private_subnets}"
  subnet_id_runners = "${element(module.vpc.private_subnets, 0)}"
 
- runners_name = "my-spot-runner"
- runners_gitlab_url = "https://www.gitlab.com"
+ runners_name = "aws-spot-instance-runner"
+ runners_gitlab_url = "https://gitlab.com"
 
  gitlab_runner_registration_config = {
- registration_token = "<YOUR_TOKEN>"
+ registration_token = "${var.registration_token}"
  tag_list = "docker_spot_runner"
- description = "Docker AWS Spot runner"
+ description = "runner default - auto"
  locked_to_project = "true"
  run_untagged = "false"
  maximum_timeout = "3600"
  }
-
- runners_off_peak_timezone = "Europe/Amsterdam"
- runners_off_peak_idle_count = 0
- runners_off_peak_idle_time = 60
-
- # working 9 to 5 :)
- runners_off_peak_periods = "[\"* * 0-9,17-23 * * mon-fri *\", \"* * * * * sat,sun *\"]"
 }
 ```
 
-## Example
+## Examples
 
-A few [examples](examples) are provided. Use the following steps to deploy. Ensure your AWS and Terraform environment is set up correctly. All commands below should be run from the `terraform-aws-gitlab-runner/examples` directory.
+A few [examples](examples) are provided. Use the following steps to deploy. Ensure your AWS and Terraform environment is set up correctly. All commands below should be run from the `terraform-aws-gitlab-runner/examples/<example-dir>` directory.
 
-### AWS keys
+### SSH keys
 
 SSH keys are generated by Terraform and stored in the `generated` directory of each example directory.
 
-### Configure GitLab
+### Versions
 
-*This step is not needed anymore* Configure you runner via `gitlab_runner_registration_config`. Configuring GitLab via the step below is only needed when you choose to create the token manually and set the `runners_token` variable.
+THe version of Terraform is locked down via tfenv, see the `.terraform-version` file for the expected versions. Providers are locked down as will in the `providers.tf` file.
 
-Register a new runner:
+### Configure
 
-``` sh
-docker run -it --rm gitlab/gitlab-runner register
-```
+The examples are configured with defaults that should wrk in general. THe samples are in general configured for the region Ireland `eu-west-1`. The only parameter that needs to be provided is the GitLab registration token. The token can be find in GitLab in the runner section (global, group or repo scope). Create a file `terrafrom.tfvars` and the registration token.
 
-Once done, lookup the token in GitLab and update the `terraform.tfvars` file.
+ registration_token = "MY_TOKEN"
 
-## Create runner
+### Run
 
 Run `terraform init` to initialize Terraform. Next you can run `terraform plan` to inspect the resources that will be created.
 
@@ -188,6 +204,7 @@ terraform destroy
 | ami\_owners | The list of owners used to select the AMI of Gitlab runner agent instances. | list | `<list>` | no |
 | aws\_region | AWS region. | string | n/a | yes |
 | aws\_zone | AWS availability zone (typically 'a', 'b', or 'c'). | string | `"a"` | no |
+| cache\_bucket | Configuration to control the creation of th the cache bucket. By default the bucket will be crated and used as shared cache. To use the same cache cross multiple runners disable the cration of the cache and provice a policy and bucket name. See the public runner example for more details. | map | `<map>` | no |
 | cache\_bucket\_prefix | Prefix for s3 cache bucket name. | string | `""` | no |
 | cache\_bucket\_versioning | Boolean used to enable versioning on the cache bucket, false by default. | string | `"false"` | no |
 | cache\_expiration\_days | Number of days before cache objects expires. | string | `"1"` | no |