fix: add docs and tag olso non jit instances

Author: npalm

mkdocs.yaml

@@ -46,6 +46,11 @@ markdown_extensions:
   - admonition
   - pymdownx.details
   - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
 
 nav:
   - Introduction: index.md

modules/runners/README.md

@@ -18,6 +18,8 @@ The scale up lambda is triggered by events on a SQS queue. Events on this queue
 
 The scale down lambda is triggered via a CloudWatch event. The event is triggered by a cron expression defined in the variable `scale_down_schedule_expression` (https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html). For scaling down GitHub does not provide a good API yet, therefore we run the scaling down based on this event every x minutes. Each time the lambda is triggered it tries to remove all runners older than x minutes (configurable) managed in this deployment. In case the runner can be removed from GitHub, which means it is not executing a workflow, the lambda will terminate the EC2 instance.
 
+--8<-- "modules/runners/scale-down-state-diagram.md:mkdocs_scale_down_state_diagram"
+
 ## Lambda Function
 
 The Lambda function is written in [TypeScript](https://www.typescriptlang.org/) and requires Node 12.x and yarn. Sources are located in [./lambdas/runners]. Two lambda functions share the same sources, there is one entry point for `scaleDown` and another one for `scaleUp`.

modules/runners/policies-runner.tf

@@ -57,6 +57,12 @@ resource "aws_iam_role_policy" "describe_tags" {
   policy = file("${path.module}/policies/instance-describe-tags-policy.json")
 }
 
+resource "aws_iam_role_policy" "create_tag" {
+  name   = "runner-create-tags"
+  role   = aws_iam_role.runner.name
+  policy = templatefile("${path.module}/policies/instance-create-tags-policy.json", {})
+}
+
 resource "aws_iam_role_policy_attachment" "managed_policies" {
   count      = length(var.runner_iam_role_managed_policy_arns)
   role       = aws_iam_role.runner.name

modules/runners/templates/start-runner.ps1

@@ -1,6 +1,44 @@
 
 ## Retrieve instance metadata
 
+function Tag-InstanceWithRunnerId {
+    Write-Host "Checking for .runner file to extract agent ID"
+
+    $runnerFilePath = "$pwd\.runner"
+    if (-not (Test-Path $runnerFilePath)) {
+        Write-Host "Warning: .runner file not found"
+        return $true
+    }
+
+    Write-Host "Found .runner file, extracting agent ID"
+    try {
+        $runnerConfig = Get-Content $runnerFilePath | ConvertFrom-Json
+        $agentId = $runnerConfig.agentId
+
+        if (-not $agentId -or $agentId -eq $null) {
+            Write-Host "Warning: Could not extract agent ID from .runner file"
+            return $true
+        }
+
+        Write-Host "Tagging instance with GitHub runner agent ID: $agentId"
+        $tagResult = aws ec2 create-tags --region "$Region" --resources "$InstanceId" --tags "Key=ghr:github_runner_id,Value=$agentId" 2>&1
+
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host "Successfully tagged instance with agent ID: $agentId"
+            return $true
+        } else {
+            Write-Host "Warning: Failed to tag instance with agent ID - $tagResult"
+            return $true
+        }
+    }
+    catch {
+        Write-Host "Warning: Error processing .runner file - $($_.Exception.Message)"
+        return $true
+    }
+}
+
+## Retrieve instance metadata
+
 Write-Host  "Retrieving TOKEN from AWS API"
 $token=Invoke-RestMethod -Method PUT -Uri "http://169.254.169.254/latest/api/token" -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "180"}
 if ( ! $token ) {
@@ -122,6 +160,9 @@ if ($enable_jit_config -eq "false" -or $agent_mode -ne "ephemeral") {
   $configCmd = ".\config.cmd --unattended --name $runner_name_prefix$InstanceId --work `"_work`" $runnerExtraOptions $config"
   Write-Host "Configure GH Runner (non ephmeral / no JIT) as user $run_as"
   Invoke-Expression $configCmd
+
+  # Tag instance with GitHub runner agent ID for non-JIT runners
+  Tag-InstanceWithRunnerId
 }
 
 $jsonBody = @(

modules/runners/templates/start-runner.sh

@@ -58,6 +58,36 @@ create_xray_error_segment() {
   echo "$SEGMENT_DOC"
 }
 
+tag_instance_with_runner_id() {
+  echo "Checking for .runner file to extract agent ID"
+
+  if [[ ! -f "/opt/actions-runner/.runner" ]]; then
+    echo "Warning: .runner file not found"
+    return 0
+  fi
+
+  echo "Found .runner file, extracting agent ID"
+  local agent_id
+  agent_id=$(jq -r '.agentId' /opt/actions-runner/.runner 2>/dev/null || echo "")
+
+  if [[ -z "$agent_id" || "$agent_id" == "null" ]]; then
+    echo "Warning: Could not extract agent ID from .runner file"
+    return 0
+  fi
+
+  echo "Tagging instance with GitHub runner agent ID: $agent_id"
+  if aws ec2 create-tags \
+    --region "$region" \
+    --resources "$instance_id" \
+    --tags Key=ghr:github_runner_id,Value="$agent_id"; then
+    echo "Successfully tagged instance with agent ID: $agent_id"
+    return 0
+  else
+    echo "Warning: Failed to tag instance with agent ID"
+    return 0
+  fi
+}
+
 cleanup() {
   local exit_code="$1"
   local error_location="$2"
@@ -225,6 +255,9 @@ if [[ "$enable_jit_config" == "false" || $agent_mode != "ephemeral" ]]; then
       extra_flags=""
   fi
   sudo --preserve-env=RUNNER_ALLOW_RUNASROOT -u "$run_as" -- ./config.sh $${extra_flags} --unattended --name "$runner_name_prefix$instance_id" --work "_work" $${config}
+
+  # Tag instance with GitHub runner agent ID for non-JIT runners
+  tag_instance_with_runner_id
 fi
 
 create_xray_success_segment "$SEGMENT"