Skip to content

Commit 64df9c3

Browse files
zillemarcokayman-mk
zillemarco
and
kayman-mk
authored
docs: add example configuration for Windows-based runners (#1268)
Added an example configuration to use the module to set up Windows-based runners and an example on how to create a custom Windows AMI usable with the configuration. --------- Co-authored-by: Matthias Kay <matthias.kay@hlag.com>
1 parent e02cbe4 commit 64df9c3

File tree

9 files changed

+485
-2
lines changed

9 files changed

+485
-2
lines changed

‎.cspell.json

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
"version": "0.2",
33
"language": "en",
44
"ignoreWords": [
5+
"advfirewall",
56
"alltrue",
67
"amazonec",
78
"anytrue",
@@ -13,6 +14,7 @@
1314
"buildx",
1415
"certdir",
1516
"checkmarx",
17+
"choco",
1618
"concat",
1719
"containerd",
1820
"devskim",
@@ -23,13 +25,16 @@
2325
"formatlist",
2426
"glrt",
2527
"glrunners",
28+
"HKLM",
2629
"hmarr",
2730
"icmpv6",
2831
"instancelifecycle",
2932
"keyrings",
3033
"kics",
3134
"joho",
3235
"jsonencode",
36+
"localip",
37+
"ltsc",
3338
"markdownlint",
3439
"matchDatasources",
3540
"mypy",
@@ -40,9 +45,12 @@
4045
"pylint",
4146
"pylintrc",
4247
"pyright",
48+
"remoteip",
49+
"servercore",
4350
"setsubtract",
4451
"shuf",
4552
"signum",
53+
"Sizekb",
4654
"stretchr",
4755
"subkey",
4856
"substr",
@@ -52,6 +60,7 @@
5260
"terrascan",
5361
"terratest",
5462
"tfenv",
63+
"Timeoutms",
5564
"tflint",
5665
"tftpl",
5766
"tfsec",
@@ -63,9 +72,12 @@
6372
"trimprefix",
6473
"trivy",
6574
"usermod",
75+
"useraccount",
6676
"userns",
6777
"vcpu",
78+
"windowsfeatures",
6879
"xanzy",
80+
"xlarge",
6981
"xvda"
7082
],
7183
"words": [
@@ -81,6 +93,7 @@
8193
"cpus",
8294
"cpuset",
8395
"gitter",
96+
"netsh",
8497
"Niek",
8598
"oxsecurity",
8699
"rebalance",

‎examples/runner-windows/.terraform-version

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
1.3.0

‎examples/runner-windows/README.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Example - AWS Fleeting Plugin with Windows runners
2+
3+
This example shows how to deploy a GitLab Runner using the [AWS Fleeting Plugin](https://docs.gitlab.com/runner/configuration/autoscale.html)
4+
with on Windows, allowing usage of Docker and spot instances.
5+
6+
This examples shows:
7+
8+
- You can log into the instance via SSM (Session Manager).
9+
- register the Runner manually in GitLab
10+
- Auto scaling Windows runners using AWS Fleeting Plugin.
11+
12+
Multi region deployment is, of course, possible. Just instantiate the module multiple times with different AWS providers. In case
13+
you use the cache, make sure to have one cache per region.
14+
15+
Attention: You **must** to built your own AMI before. See the [README.md](../../packer_images/README.md#windows-server-2022-ami) for more information.
16+
17+
## Prerequisite
18+
19+
The Terraform version is managed using [tfenv](https://github.com/Zordrak/tfenv). If you are not using `tfenv` please
20+
check `.terraform-version` for the tested version.
21+
22+
<!-- markdownlint-disable -->
23+
<!-- cSpell:disable -->
24+
<!-- markdown-link-check-disable -->
25+
26+
<!-- BEGIN_TF_DOCS -->
27+
## Requirements
28+
29+
| Name | Version |
30+
|------|---------|
31+
| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.3 |
32+
| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 5.78.0 |
33+
| <a name="requirement_local"></a> [local](#requirement\_local) | >= 2.5.2 |
34+
| <a name="requirement_null"></a> [null](#requirement\_null) | >= 3.2.3 |
35+
| <a name="requirement_random"></a> [random](#requirement\_random) | >= 3.6.3 |
36+
| <a name="requirement_tls"></a> [tls](#requirement\_tls) | >= 4.0.6 |
37+
38+
## Providers
39+
40+
| Name | Version |
41+
|------|---------|
42+
| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 5.78.0 |
43+
44+
## Modules
45+
46+
| Name | Source | Version |
47+
|------|--------|---------|
48+
| <a name="module_runner"></a> [runner](#module\_runner) | ../../ | n/a |
49+
| <a name="module_vpc"></a> [vpc](#module\_vpc) | terraform-aws-modules/vpc/aws | >= 5.16.0 |
50+
| <a name="module_vpc_endpoints"></a> [vpc\_endpoints](#module\_vpc\_endpoints) | terraform-aws-modules/vpc/aws//modules/vpc-endpoints | >= 5.16.0 |
51+
52+
## Resources
53+
54+
| Name | Type |
55+
|------|------|
56+
| [aws_availability_zones.available](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/availability_zones) | data source |
57+
| [aws_security_group.default](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/security_group) | data source |
58+
59+
## Inputs
60+
61+
| Name | Description | Type | Default | Required |
62+
|------|-------------|------|---------|:--------:|
63+
| <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | AWS region. | `string` | `"eu-west-1"` | no |
64+
| <a name="input_environment"></a> [environment](#input\_environment) | A name that identifies the environment, will used as prefix and for tagging. | `string` | `"runners-default"` | no |
65+
| <a name="input_gitlab_url"></a> [gitlab\_url](#input\_gitlab\_url) | URL of the gitlab instance to connect to. | `string` | `"https://gitlab.com"` | no |
66+
| <a name="input_preregistered_runner_token_ssm_parameter_name"></a> [preregistered\_runner\_token\_ssm\_parameter\_name](#input\_preregistered\_runner\_token\_ssm\_parameter\_name) | The name of the SSM parameter to read the preregistered GitLab Runner token from. | `string` | n/a | yes |
67+
| <a name="input_runner_name"></a> [runner\_name](#input\_runner\_name) | Name of the runner, will be used in the runner config.toml | `string` | `"default-auto"` | no |
68+
| <a name="input_timezone"></a> [timezone](#input\_timezone) | Name of the timezone that the runner will be used in. | `string` | `"Europe/Amsterdam"` | no |
69+
70+
## Outputs
71+
72+
No outputs.
73+
<!-- END_TF_DOCS -->

‎examples/runner-windows/main.tf

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
data "aws_availability_zones" "available" {
2+
state = "available"
3+
}
4+
5+
data "aws_security_group" "default" {
6+
name = "default"
7+
vpc_id = module.vpc.vpc_id
8+
}
9+
10+
# VPC Flow logs are not needed here
11+
# kics-scan ignore-line
12+
module "vpc" {
13+
source = "terraform-aws-modules/vpc/aws"
14+
version = ">= 5.16.0"
15+
16+
name = "vpc-${var.environment}"
17+
cidr = "10.0.0.0/16"
18+
19+
azs = [data.aws_availability_zones.available.names[0]]
20+
private_subnets = ["10.0.1.0/24"]
21+
public_subnets = ["10.0.101.0/24"]
22+
map_public_ip_on_launch = false
23+
24+
enable_nat_gateway = true
25+
single_nat_gateway = true
26+
27+
tags = {
28+
Environment = var.environment
29+
}
30+
}
31+
32+
module "vpc_endpoints" {
33+
source = "terraform-aws-modules/vpc/aws//modules/vpc-endpoints"
34+
version = ">= 5.16.0"
35+
36+
vpc_id = module.vpc.vpc_id
37+
38+
endpoints = {
39+
s3 = {
40+
service = "s3"
41+
tags = { Name = "s3-vpc-endpoint" }
42+
}
43+
}
44+
45+
tags = {
46+
Environment = var.environment
47+
}
48+
}
49+
50+
module "runner" {
51+
source = "../../"
52+
53+
environment = var.environment
54+
55+
vpc_id = module.vpc.vpc_id
56+
subnet_id = element(module.vpc.private_subnets, 0)
57+
58+
runner_instance = {
59+
collect_autoscaling_metrics = ["GroupDesiredCapacity", "GroupInServiceCapacity"]
60+
name = var.runner_name
61+
ssm_access = true
62+
private_address_only = false
63+
}
64+
65+
runner_networking = {
66+
allow_incoming_ping_security_group_ids = [data.aws_security_group.default.id]
67+
}
68+
69+
runner_gitlab = {
70+
url = var.gitlab_url
71+
72+
preregistered_runner_token_ssm_parameter_name = var.preregistered_runner_token_ssm_parameter_name
73+
}
74+
75+
runner_worker = {
76+
type = "docker-autoscaler"
77+
max_jobs = 10
78+
use_private_key = true
79+
80+
environment_variables = [
81+
"FF_USE_POWERSHELL_PATH_RESOLVER=1"
82+
]
83+
}
84+
85+
runner_worker_gitlab_pipeline = {
86+
pre_build_script = <<EOT
87+
'''
88+
echo 'multiline 1'
89+
echo 'multiline 2'
90+
'''
91+
EOT
92+
post_build_script = "\"echo 'single line'\""
93+
}
94+
95+
runner_worker_docker_autoscaler = {
96+
fleeting_plugin_version = "1.0.0"
97+
connector_config_user = "Administrator"
98+
}
99+
100+
runner_worker_docker_autoscaler_ami_owners = ["self"] # FIXME Leave to self or change to your AWS account ID
101+
runner_worker_docker_autoscaler_ami_id = "<windows-ami-id>"
102+
103+
runner_worker_docker_autoscaler_instance = {
104+
monitoring = true
105+
private_address_only = false
106+
}
107+
108+
runner_worker_docker_autoscaler_asg = {
109+
subnet_ids = module.vpc.private_subnets
110+
types = ["m6a.medium", "m6i.medium"] # FIXME change these to what best fits your needs, keeping in mind that Windows runners need bigger instances
111+
enable_mixed_instances_policy = true
112+
113+
# FIXME These settings enable windows runners to scale down to zero if no jobs are running but you can change it to fit your needs
114+
on_demand_base_capacity = 0
115+
on_demand_percentage_above_base_capacity = 0
116+
max_growth_rate = 10
117+
spot_allocation_strategy = "price-capacity-optimized"
118+
spot_instance_pools = 0
119+
}
120+
121+
runner_worker_docker_autoscaler_autoscaling_options = [
122+
{
123+
periods = ["* * * * *"]
124+
timezone = "Europe/Berlin"
125+
idle_count = 0
126+
idle_time = "0s"
127+
scale_factor = 2
128+
},
129+
{
130+
periods = ["* 7-19 * * mon-fri"]
131+
timezone = "Europe/Berlin"
132+
idle_count = 3
133+
idle_time = "30m"
134+
scale_factor = 2
135+
}
136+
]
137+
138+
runner_worker_docker_options = {
139+
volumes = ["C:/cache"]
140+
privileged = false
141+
}
142+
143+
tags = {
144+
"tf-aws-gitlab-runner:example" = "runner-default"
145+
"tf-aws-gitlab-runner:instancelifecycle" = "spot:yes"
146+
}
147+
}

‎examples/runner-windows/providers.tf

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
provider "aws" {
2+
region = var.aws_region
3+
}
4+
5+
provider "local" {}
6+
7+
provider "null" {}
8+
9+
provider "tls" {}
10+
11+
provider "random" {}

‎examples/runner-windows/variables.tf

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
variable "aws_region" {
2+
description = "AWS region."
3+
type = string
4+
default = "eu-west-1"
5+
}
6+
7+
variable "environment" {
8+
description = "A name that identifies the environment, will used as prefix and for tagging."
9+
type = string
10+
default = "runners-default"
11+
}
12+
13+
variable "runner_name" {
14+
description = "Name of the runner, will be used in the runner config.toml"
15+
type = string
16+
default = "default-auto"
17+
}
18+
19+
variable "gitlab_url" {
20+
description = "URL of the gitlab instance to connect to."
21+
type = string
22+
default = "https://gitlab.com"
23+
}
24+
25+
variable "preregistered_runner_token_ssm_parameter_name" {
26+
description = "The name of the SSM parameter to read the preregistered GitLab Runner token from."
27+
type = string
28+
}
29+
30+
variable "timezone" {
31+
description = "Name of the timezone that the runner will be used in."
32+
type = string
33+
default = "Europe/Amsterdam"
34+
}

‎examples/runner-windows/versions.tf

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
2+
terraform {
3+
required_version = ">= 1.3"
4+
5+
required_providers {
6+
aws = {
7+
source = "hashicorp/aws"
8+
version = ">= 5.78.0"
9+
}
10+
local = {
11+
source = "hashicorp/local"
12+
version = ">= 2.5.2"
13+
}
14+
null = {
15+
source = "hashicorp/null"
16+
version = ">= 3.2.3"
17+
}
18+
tls = {
19+
source = "hashicorp/tls"
20+
version = ">= 4.0.6"
21+
}
22+
random = {
23+
source = "hashicorp/random"
24+
version = ">= 3.6.3"
25+
}
26+
}
27+
}

0 commit comments

Comments
 (0)