Skip to content

GitLab Runner Architecture

EKS Kubernetes runners are the primary CI/CD execution system since 2026-02-26. Legacy Fleeting runners are paused.

EKS Kubernetes Runners (Primary)

Cluster Details

Property Value
Cluster cwiq-dev-eks-cluster
Kubernetes 1.31
Autoscaler Karpenter v1.1.1
System node group 1x t3.medium (cwiq-dev-eks-system), desired_size=1
kubectl access Ansible server only (ansible-shared-cwiq-io)

Runner Tiers

Runner GitLab ID Tag Use Case Instance Types
k8s-small 19 small Default jobs t3.small/medium
k8s-medium 20 medium UI Kaniko builds t3.large (8GB RAM required)
k8s-large 21 large Executor Nuitka + rpmbuild t3.xlarge

Network Constraints

No Tailscale in runner pods

Pods use VPC CNI and get IPs in 10.1.34.0/24 and 10.1.35.0/24. Tailscale is not available inside pods.

Deploy-dev jobs must use VPC private IPs

DEV_SERVER_IP is set at GitLab group level (group 9) to the VPC private IP of the dev server (10.1.35.46). Target servers must allow SSH (port 22) ingress from the EKS cluster security group.

Known Configuration Issues

runAsNonRoot defaults to true

GitLab Runner defaults to runAsNonRoot: true for all pods. This must be overridden in the runner TOML config for jobs that require root access.

Karpenter ec2:RunInstances IAM constraint

Karpenter's ec2:RunInstances permission cannot use the aws:RequestTag condition. Remove that condition from the IAM policy if Karpenter node provisioning fails.

S3 Cache

Property Value
Bucket cwiq-dev-gitlab-runner-cache (DEV account: 686123185567)
Requirement BOTH a bucket policy in DEV AND an IAM policy in Shared (308188966547)

The cross-account setup is necessary because the shared-services GitLab instance (308188966547) uses runners that write to a cache bucket in the dev account (686123185567).

System Node Group Behavior

With desired_size=1, one Karpenter replica shows Pending — this is expected behavior. Scale the system node group to 2 when more users onboard.

The launch template tags EC2 instances with Name: cwiq-dev-eks-system.

Legacy Fleeting Runners (Paused)

Paused since 2026-02-27

These runners are inactive. The Runner Manager EC2 is stopped.

Runner GitLab ID Status
dev-small 16 Paused
dev-medium 17 Paused
dev-large 18 Paused

Runner Manager EC2: i-0af3f2d4bf8a4f1d2 — stopped. Can be restarted if needed.

Phase 4 cleanup remaining: Terminate the Runner Manager instance and delete runners 16–18 from GitLab.

Checking Runner Status

TOKEN=$(grep GITLAB_PERSONAL_ACCESS_TOKEN .claude-env | cut -d= -f2 | tr -d '"' | tr -d "'" | tr -d ' ')

# List all runners
curl -s "https://gitlab.shared.cwiq.io/api/v4/runners?private_token=$TOKEN" | \
  python3 -c "import sys,json; [print(r['id'], r['status'], r.get('tag_list')) for r in json.load(sys.stdin)]"