# meshekar51/self-hosted-runners-k8s architecture

> Architecture diagram of the GitHub repository meshekar51/self-hosted-runners-k8s, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/meshekar51/self-hosted-runners-k8s
- Repository: https://github.com/meshekar51/self-hosted-runners-k8s

## Overview

This repository is a lab guide and configuration bundle for deploying Actions Runner Controller (ARC) on an existing Amazon EKS cluster. The workflow is: an operator uses PowerShell and the supplied configuration to prepare namespaces, authenticate ARC to GitHub, and install a runner scale set; GitHub job demand then drives temporary runner pods, which execute jobs and are cleaned up. The README documents these runtime relationships, but no source excerpts were provided, and the listed test workflow is not present in the supplied tree.

Main entry points: [`scripts/New-ArcGitHubSecret.ps1`](https://github.com/meshekar51/self-hosted-runners-k8s/blob/main/scripts/New-ArcGitHubSecret.ps1) (PowerShell setup), [`k8s/arc/namespaces.yaml`](https://github.com/meshekar51/self-hosted-runners-k8s/blob/main/k8s/arc/namespaces.yaml) (Namespaces), [`k8s/arc/runner-values.yaml`](https://github.com/meshekar51/self-hosted-runners-k8s/blob/main/k8s/arc/runner-values.yaml) (Runner settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and configuration"]
  node_powershell["PowerShell setup"]
  node_namespaces["Namespaces<br/>[namespaces.yaml]"]
  node_runner_config["Runner settings<br/>[runner-values.yaml]"]
  node_github_secret[("GitHub token Secret")]
end

subgraph group_arc["ARC runtime"]
  node_controller["ARC controllers"]
  node_listener["ARC listener"]
end

subgraph group_jobs["GitHub jobs"]
  node_github["GitHub Actions"]
  node_test_workflow["Scale test workflow"]
  node_runner_pods["Ephemeral runners"]
end

node_operator(("Operator"))
node_eks["EKS cluster"]
node_kube_api["Kubernetes API"]

node_operator -->|"runs setup"| node_powershell
node_powershell -->|"creates Secret"| node_github_secret
node_operator -->|"applies config"| node_namespaces
node_operator -->|"installs scale set"| node_runner_config
node_operator -->|"uses kubectl"| node_kube_api
node_operator -->|"connects with AWS"| node_eks
node_namespaces -->|"creates namespaces"| node_kube_api
node_runner_config -->|"configures scale set"| node_listener
node_github_secret -->|"authenticates"| node_listener
node_listener -->|"receives job notices"| node_github
node_listener -->|"patches replicas"| node_kube_api
node_controller -->|"reconciles resources"| node_kube_api
node_kube_api -->|"schedules pods"| node_runner_pods
node_operator -->|"triggers test"| node_test_workflow
node_test_workflow -->|"runs jobs"| node_github
node_runner_pods -->|"returns results"| node_github

click node_powershell "https://github.com/meshekar51/self-hosted-runners-k8s/blob/main/scripts/New-ArcGitHubSecret.ps1"
click node_namespaces "https://github.com/meshekar51/self-hosted-runners-k8s/blob/main/k8s/arc/namespaces.yaml"
click node_runner_config "https://github.com/meshekar51/self-hosted-runners-k8s/blob/main/k8s/arc/runner-values.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_powershell,node_namespaces,node_runner_config,node_github_secret toneBlue
class node_controller,node_listener toneAmber
class node_github,node_test_workflow,node_runner_pods,node_kube_api toneMint
class node_operator,node_eks toneIndigo
```

## Components

### Setup and configuration

- [PowerShell setup](https://github.com/meshekar51/self-hosted-runners-k8s/blob/main/scripts/New-ArcGitHubSecret.ps1): `scripts/New-ArcGitHubSecret.ps1`
- [Namespaces](https://github.com/meshekar51/self-hosted-runners-k8s/blob/main/k8s/arc/namespaces.yaml): `k8s/arc/namespaces.yaml`
- [Runner settings](https://github.com/meshekar51/self-hosted-runners-k8s/blob/main/k8s/arc/runner-values.yaml): `k8s/arc/runner-values.yaml`
- **GitHub token Secret**

### ARC runtime

- **ARC controllers**
- **ARC listener**

### GitHub jobs

- **GitHub Actions**
- **Scale test workflow**
- **Ephemeral runners**

### Other components

- **Operator**
- **EKS cluster**
- **Kubernetes API**

## Connections

- Operator → PowerShell setup: runs setup (evidence: `README.md`)
- PowerShell setup → GitHub token Secret: creates Secret (evidence: `README.md`)
- Operator → Namespaces: applies config (evidence: `README.md`)
- Operator → Runner settings: installs scale set (evidence: `README.md`)
- Operator → Kubernetes API: uses kubectl (evidence: `README.md`)
- Operator → EKS cluster: connects with AWS (evidence: `README.md`)
- Namespaces → Kubernetes API: creates namespaces (evidence: `README.md`)
- Runner settings → ARC listener: configures scale set (evidence: `README.md`)
- GitHub token Secret → ARC listener: authenticates (evidence: `README.md`)
- ARC listener → GitHub Actions: receives job notices (evidence: `README.md`)
- ARC listener → Kubernetes API: patches replicas (evidence: `README.md`)
- ARC controllers → Kubernetes API: reconciles resources (evidence: `README.md`)
- Kubernetes API → Ephemeral runners: schedules pods (evidence: `README.md`)
- Operator → Scale test workflow: triggers test (evidence: `README.md`)
- Scale test workflow → GitHub Actions: runs jobs (evidence: `README.md`)
- Ephemeral runners → GitHub Actions: returns results (evidence: `README.md`)
