docs(examples): add a new example to use manual ssm parameters option

examples/manual-ssm-parameters/README.md

@@ -0,0 +1,77 @@
+# Amazon Linux X64 (default)
+
+This module shows how to create GitHub action runners. Lambda release will be downloaded from GitHub.
+
+The only difference compared to [`default`](../default/README.md) is that you need to create SSM parameters manually so their values are not stored in the state (see `create_ssm_parameters_github_app` variable).
+
+## Usages
+
+Before all, manually create the SSM parameters for the GitHub App ID, base64-encoded private key and webhook secret. Then refer their name and arn through the [`github_app_ssm_parameters` variable](./variables.tf).
+
+Steps for the full setup, such as creating a GitHub app can be found in the root module's [README](https://github.com/philips-labs/terraform-aws-github-runner). First download the Lambda releases from GitHub. Alternatively you can build the lambdas locally with Node or Docker, there is a simple build script in `<root>/.ci/build.sh`. In the `main.tf` you can simply remove the location of the lambda zip files, the default location will work in this case.
+
+> The default example assumes local built lambda's available. Ensure you have built the lambda's. Alternativly you can downlowd the lambda's. The version needs to be set to a GitHub release version, see https://github.com/philips-labs/terraform-aws-github-runner/releases
+
+```bash
+cd ../lambdas-download
+terraform init
+terraform apply -var=module_version=<VERSION>
+cd -
+```
+
+Before running Terraform, ensure the GitHub app is configured. See the [configuration details](https://github.com/philips-labs/terraform-aws-github-runner#usages) for more details.
+
+```bash
+terraform init
+terraform apply
+```
+
+The example will try to update the webhook of your GitHub. In case the update fails the apply will not fail. You can receive the webhook details by running:
+
+```bash
+terraform output -raw webhook_secret
+```
+
+<!-- BEGIN_TF_DOCS -->
+
+## Requirements
+
+| Name                                                                     | Version  |
+| ------------------------------------------------------------------------ | -------- |
+| <a name="requirement_terraform"></a> [terraform](#requirement_terraform) | >= 1.3.0 |
+| <a name="requirement_aws"></a> [aws](#requirement_aws)                   | ~> 5.27  |
+| <a name="requirement_local"></a> [local](#requirement_local)             | ~> 2.0   |
+| <a name="requirement_random"></a> [random](#requirement_random)          | ~> 3.0   |
+
+## Providers
+
+No providers.
+
+## Modules
+
+| Name                                                     | Source  | Version |
+| -------------------------------------------------------- | ------- | ------- |
+| <a name="module_base"></a> [base](#module_base)          | ../base | n/a     |
+| <a name="module_runners"></a> [runners](#module_runners) | ../../  | n/a     |
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name                                                                                                         | Description                                                                     | Type                                                                                                                                                                                                                                                             | Default       | Required |
+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | :------: |
+| <a name="input_aws_region"></a> [aws_region](#input_aws_region)                                              | AWS region.                                                                     | `string`                                                                                                                                                                                                                                                         | `"eu-west-1"` |    no    |
+| <a name="input_environment"></a> [environment](#input_environment)                                           | Environment name, used as prefix.                                               | `string`                                                                                                                                                                                                                                                         | `null`        |    no    |
+| <a name="input_github_app_ssm_parameters"></a> [github_app_ssm_parameters](#input_github_app_ssm_parameters) | SSM parameters details for the GitHub App, that you've created manually on AWS. | <pre>object({<br> key_base64 = optional(object({<br> arn = string<br> name = string<br> }))<br> id = optional(object({<br> arn = string<br> name = string<br> }))<br> webhook_secret = optional(object({<br> arn = string<br> name = string<br> }))<br> })</pre> | `{}`          |    no    |
+
+## Outputs
+
+| Name                                                                                | Description |
+| ----------------------------------------------------------------------------------- | ----------- |
+| <a name="output_runners"></a> [runners](#output_runners)                            | n/a         |
+| <a name="output_webhook_endpoint"></a> [webhook_endpoint](#output_webhook_endpoint) | n/a         |
+| <a name="output_webhook_secret"></a> [webhook_secret](#output_webhook_secret)       | n/a         |
+
+<!-- END_TF_DOCS -->

examples/manual-ssm-parameters/main.tf

@@ -0,0 +1,164 @@
+locals {
+  environment = var.environment != null ? var.environment : "default"
+  aws_region  = var.aws_region
+}
+
+# resource "random_id" "random" {
+#   byte_length = 20
+# }
+
+module "base" {
+  source = "../base"
+
+  prefix     = local.environment
+  aws_region = local.aws_region
+}
+
+module "runners" {
+  source                          = "../../"
+  create_service_linked_role_spot = true
+  aws_region                      = local.aws_region
+  vpc_id                          = module.base.vpc.vpc_id
+  subnet_ids                      = module.base.vpc.private_subnets
+
+  prefix = local.environment
+  tags = {
+    Project = "ProjectX"
+  }
+  create_ssm_parameters_github_app = false
+  github_app_ssm_parameters        = var.github_app_ssm_parameters
+
+
+  # configure the block device mappings, default for Amazon Linux2
+  # block_device_mappings = [{
+  #   device_name           = "/dev/xvda"
+  #   delete_on_termination = true
+  #   volume_type           = "gp3"
+  #   volume_size           = 10
+  #   encrypted             = true
+  #   iops                  = null
+  # }]
+
+  # When not explicitly set lambda zip files are grapped from the module requiring lambda build.
+  # Alternatively you can set the path to the lambda zip files here.
+  #
+  # For example grab zip files via lambda_download
+  # webhook_lambda_zip                = "../lambdas-download/webhook.zip"
+  # runner_binaries_syncer_lambda_zip = "../lambdas-download/runner-binaries-syncer.zip"
+  # runners_lambda_zip                = "../lambdas-download/runners.zip"
+
+  enable_organization_runners = true
+  runner_extra_labels         = ["default", "example"]
+
+  # enable access to the runners via SSM
+  enable_ssm_on_runners = true
+
+  # use S3 or KMS SSE to runners S3 bucket
+  # runner_binaries_s3_sse_configuration = {
+  #   rule = {
+  #     apply_server_side_encryption_by_default = {
+  #       sse_algorithm = "AES256"
+  #     }
+  #   }
+  # }
+
+  # enable S3 versioning for runners S3 bucket
+  # runner_binaries_s3_versioning = "Enabled"
+
+  # Uncommet idle config to have idle runners from 9 to 5 in time zone Amsterdam
+  # idle_config = [{
+  #   cron      = "* * 9-17 * * *"
+  #   timeZone  = "Europe/Amsterdam"
+  #   idleCount = 1
+  # }]
+
+  # Let the module manage the service linked role
+  # create_service_linked_role_spot = true
+
+  instance_types = ["m7a.large", "m5.large"]
+
+  # override delay of events in seconds
+  delay_webhook_event   = 5
+  runners_maximum_count = 2
+
+  # override scaling down
+  scale_down_schedule_expression = "cron(* * * * ? *)"
+
+  enable_user_data_debug_logging_runner = true
+
+  # prefix GitHub runners with the environment name
+  runner_name_prefix = "${local.environment}_"
+
+  # by default eventbridge is used, see multi-runner example. Here we disable the eventbridge
+  eventbridge = {
+    enable = false
+  }
+
+  # Enable debug logging for the lambda functions
+  # log_level = "debug"
+
+  # tracing_config = {
+  #   mode                  = "Active"
+  #   capture_error         = true
+  #   capture_http_requests = true
+  # }
+
+  enable_ami_housekeeper = true
+  ami_housekeeper_cleanup_config = {
+    ssmParameterNames = ["*/ami-id"]
+    minimumDaysOld    = 10
+    amiFilters = [
+      {
+        Name   = "name"
+        Values = ["*al2023*"]
+      }
+    ]
+  }
+
+  instance_termination_watcher = {
+    enable = true
+  }
+
+  # enable metric creation  (experimental)
+  # metrics = {
+  #   enable = true
+  #   metric = {
+  #     enable_spot_termination_warning = true
+  #     enable_job_retry                = false
+  #     enable_github_app_rate_limit    = false
+  #   }
+  # }
+
+  # enable job_retry feature. Be careful with this feature, it can lead to you hitting API rate limits.
+  # job_retry = {
+  #   enable           = true
+  #   max_attempts     = 1
+  #   delay_in_seconds = 180
+  # }
+
+  # enable CMK instead of aws managed key for encryptions
+  # kms_key_arn = aws_kms_key.github.arn
+}
+
+# ❌ When creating SSM parameters manually to avoid having them in the state, you shouldn't manage the github app settings in the state neither!
+# module "webhook_github_app" {
+#   source     = "../../modules/webhook-github-app"
+#   depends_on = [module.runners]
+
+#   github_app = {
+#     key_base64     = var.github_app.key_base64
+#     id             = var.github_app.id
+#     webhook_secret = random_id.random.hex
+#   }
+#   webhook_endpoint = module.runners.webhook.endpoint
+# }
+
+# enable CMK instead of aws managed key for encryptions
+# resource "aws_kms_key" "github" {
+#   is_enabled = true
+# }
+
+# resource "aws_kms_alias" "github" {
+#   name          = "alias/github/action-runners"
+#   target_key_id = aws_kms_key.github.key_id
+# }

examples/manual-ssm-parameters/outputs.tf

@@ -0,0 +1,15 @@
+output "runners" {
+  value = {
+    lambda_syncer_name = module.runners.binaries_syncer.lambda.function_name
+  }
+}
+
+output "webhook_endpoint" {
+  value = module.runners.webhook.endpoint
+}
+
+output "webhook_secret" {
+  sensitive = true
+  value     = random_id.random.hex
+}
+

examples/manual-ssm-parameters/providers.tf

@@ -0,0 +1,9 @@
+provider "aws" {
+  region = local.aws_region
+
+  default_tags {
+    tags = {
+      Example = local.environment
+    }
+  }
+}

examples/manual-ssm-parameters/variables.tf

@@ -0,0 +1,32 @@
+variable "github_app_ssm_parameters" {
+  description = "SSM parameters details for the GitHub App, that you've created manually on AWS."
+  type = object({
+    key_base64 = optional(object({
+      arn  = string
+      name = string
+    }))
+    id = optional(object({
+      arn  = string
+      name = string
+    }))
+    webhook_secret = optional(object({
+      arn  = string
+      name = string
+    }))
+  })
+  default = {}
+}
+
+variable "environment" {
+  description = "Environment name, used as prefix."
+
+  type    = string
+  default = null
+}
+
+variable "aws_region" {
+  description = "AWS region."
+
+  type    = string
+  default = "eu-west-1"
+}