# agynio/k8s-runner architecture

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

- Interactive diagram: https://gitdiagram.com/agynio/k8s-runner
- Repository: https://github.com/agynio/k8s-runner

## Overview

k8s-runner is a Kubernetes-backed implementation of the RunnerService gRPC API. A caller’s workload requests are served by the runner-core runtime and this repository’s backend, which creates and manages Kubernetes workloads and related resources; workload state is watched and reported back to the platform. The repository also advertises catalog and capability support, including Docker sidecars, and its Helm chart can install workload egress policy. Some server modules were not excerpted, so their internal call relationships are left unasserted.

Main entry points: [`internal/server/server.go`](https://github.com/agynio/k8s-runner/blob/main/internal/server/server.go) (Runner Backend), [`cmd/k8s-runner/main.go`](https://github.com/agynio/k8s-runner/blob/main/cmd/k8s-runner/main.go) (Runner Entry), [`internal/config/config.go`](https://github.com/agynio/k8s-runner/blob/main/internal/config/config.go) (Runtime Config), [`internal/config/catalog.go`](https://github.com/agynio/k8s-runner/blob/main/internal/config/catalog.go) (Catalog Mapping)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runner Runtime"]
  node_entry["Runner Entry<br/>[main.go]"]
  node_kubeclient["Kubernetes Client<br/>[client.go]"]
  node_backend["Runner Backend<br/>[server.go]"]
end

subgraph group_workloads["Workload Management"]
  node_workloadops["Workload Lifecycle<br/>[workload.go]"]
  node_capabilities["Docker Capability<br/>[capabilities.go]"]
  node_flavors["Flavor Sizing<br/>[flavor.go]"]
  node_queries["Workload Queries<br/>[query.go]"]
  node_storage["Storage Operations<br/>[storage.go]"]
  node_streaming["Workload Streaming<br/>[streaming.go]"]
end

subgraph group_support["Runner Support"]
  node_configuration["Runtime Config<br/>[config.go]"]
  node_catalog["Catalog Mapping<br/>[catalog.go]"]
  node_reporting["State Reporting<br/>[reporter.go]"]
end

subgraph group_deployment["Cluster Networking"]
  node_egresspolicy["Egress Policy"]
end

node_caller(("API Caller"))
node_kubernetes["Kubernetes API"]
node_platform(("Runner Platform"))

node_caller -.->|"invokes API"| node_entry
node_entry -->|"loads config"| node_configuration
node_entry -->|"creates client"| node_kubeclient
node_entry -->|"constructs backend"| node_backend
node_entry -->|"starts runtime"| node_platform
node_entry -->|"reports catalog"| node_catalog
node_backend -->|"manages resources"| node_kubernetes
node_backend -->|"watches state"| node_reporting
node_reporting -->|"reports transitions"| node_platform
node_backend -.->|"dispatches workload RPCs"| node_workloadops
node_backend -.->|"configures sidecars"| node_capabilities
node_backend -.->|"resolves sizing"| node_flavors
node_backend -.->|"handles queries"| node_queries
node_backend -.->|"handles storage"| node_storage
node_backend -.->|"streams sessions"| node_streaming
node_configuration -->|"loads catalog"| node_catalog
node_configuration -->|"configures backend"| node_backend
node_catalog -->|"advertises offerings"| node_platform
node_egresspolicy -->|"installs policy"| node_kubernetes

click node_entry "https://github.com/agynio/k8s-runner/blob/main/cmd/k8s-runner/main.go"
click node_configuration "https://github.com/agynio/k8s-runner/blob/main/internal/config/config.go"
click node_catalog "https://github.com/agynio/k8s-runner/blob/main/internal/config/catalog.go"
click node_kubeclient "https://github.com/agynio/k8s-runner/blob/main/internal/kube/client.go"
click node_backend "https://github.com/agynio/k8s-runner/blob/main/internal/server/server.go"
click node_workloadops "https://github.com/agynio/k8s-runner/blob/main/internal/server/workload.go"
click node_capabilities "https://github.com/agynio/k8s-runner/blob/main/internal/server/capabilities.go"
click node_flavors "https://github.com/agynio/k8s-runner/blob/main/internal/server/flavor.go"
click node_queries "https://github.com/agynio/k8s-runner/blob/main/internal/server/query.go"
click node_storage "https://github.com/agynio/k8s-runner/blob/main/internal/server/storage.go"
click node_streaming "https://github.com/agynio/k8s-runner/blob/main/internal/server/streaming.go"
click node_reporting "https://github.com/agynio/k8s-runner/blob/main/internal/reporter/reporter.go"
click node_egresspolicy "https://github.com/agynio/k8s-runner/blob/main/charts/k8s-runner/templates/workload-egress-networkpolicy.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_entry,node_kubeclient,node_backend toneBlue
class node_workloadops,node_capabilities,node_flavors,node_queries,node_storage,node_streaming toneAmber
class node_configuration,node_catalog,node_reporting,node_caller,node_kubernetes toneMint
class node_egresspolicy toneRose
class node_platform toneIndigo
```

## Components

### Runner Runtime

- [Runner Entry](https://github.com/agynio/k8s-runner/blob/main/cmd/k8s-runner/main.go): `cmd/k8s-runner/main.go`
- [Kubernetes Client](https://github.com/agynio/k8s-runner/blob/main/internal/kube/client.go): `internal/kube/client.go`
- [Runner Backend](https://github.com/agynio/k8s-runner/blob/main/internal/server/server.go): `internal/server/server.go`

### Workload Management

- [Workload Lifecycle](https://github.com/agynio/k8s-runner/blob/main/internal/server/workload.go): `internal/server/workload.go`
- [Docker Capability](https://github.com/agynio/k8s-runner/blob/main/internal/server/capabilities.go): `internal/server/capabilities.go`
- [Flavor Sizing](https://github.com/agynio/k8s-runner/blob/main/internal/server/flavor.go): `internal/server/flavor.go`
- [Workload Queries](https://github.com/agynio/k8s-runner/blob/main/internal/server/query.go): `internal/server/query.go`
- [Storage Operations](https://github.com/agynio/k8s-runner/blob/main/internal/server/storage.go): `internal/server/storage.go`
- [Workload Streaming](https://github.com/agynio/k8s-runner/blob/main/internal/server/streaming.go): `internal/server/streaming.go`

### Runner Support

- [Runtime Config](https://github.com/agynio/k8s-runner/blob/main/internal/config/config.go): `internal/config/config.go`
- [Catalog Mapping](https://github.com/agynio/k8s-runner/blob/main/internal/config/catalog.go): `internal/config/catalog.go`
- [State Reporting](https://github.com/agynio/k8s-runner/blob/main/internal/reporter/reporter.go): `internal/reporter/reporter.go`

### Cluster Networking

- [Egress Policy](https://github.com/agynio/k8s-runner/blob/main/charts/k8s-runner/templates/workload-egress-networkpolicy.yaml): `charts/k8s-runner/templates/workload-egress-networkpolicy.yaml`

### Other components

- **API Caller**
- **Kubernetes API**
- **Runner Platform**

## Connections

- API Caller → Runner Entry: invokes API (evidence: `README.md`)
- Runner Entry → Runtime Config: loads config (evidence: `cmd/k8s-runner/main.go`)
- Runner Entry → Kubernetes Client: creates client (evidence: `cmd/k8s-runner/main.go`)
- Runner Entry → Runner Backend: constructs backend (evidence: `cmd/k8s-runner/main.go`)
- Runner Entry → Runner Platform: starts runtime (evidence: `cmd/k8s-runner/main.go`)
- Runner Entry → Catalog Mapping: reports catalog (evidence: `cmd/k8s-runner/main.go`)
- Runner Backend → Kubernetes API: manages resources (evidence: `internal/server/server.go`)
- Runner Backend → State Reporting: watches state (evidence: `internal/server/server.go`)
- State Reporting → Runner Platform: reports transitions (evidence: `internal/reporter/reporter.go`)
- Runner Backend → Workload Lifecycle: dispatches workload RPCs
- Runner Backend → Docker Capability: configures sidecars
- Runner Backend → Flavor Sizing: resolves sizing
- Runner Backend → Workload Queries: handles queries
- Runner Backend → Storage Operations: handles storage
- Runner Backend → Workload Streaming: streams sessions
- Runtime Config → Catalog Mapping: loads catalog (evidence: `internal/config/config.go`)
- Runtime Config → Runner Backend: configures backend
- Catalog Mapping → Runner Platform: advertises offerings
- Egress Policy → Kubernetes API: installs policy (evidence: `README.md`)