# secretagentnull/runboat-helm architecture

> Architecture diagram of the GitHub repository secretagentnull/runboat-helm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/secretagentnull/runboat-helm
- Repository: https://github.com/secretagentnull/runboat-helm

## Overview

##### Project type + purpose (what you’re diagramming)
- The Kubernetes resources this chart creates (namespace, deployment, service, ingress, config, secrets, RBAC).
- The runtime dependencies Runboat needs (notably **PostgreSQL**, plus allowed Git repos, API admin creds).
- The request/data flows (client → ingress → service → controller pod → PostgreSQL, etc.).
- The security boundaries (Secrets, ServiceAccount/Roles, namespace separation).

Top-level chart indicators:
- `Chart.yaml` / `values.yaml`: chart metadata + configuration surface area (what operators set).
- `templates/*.yaml`: the actual K8s resources.

- `templates/deployment.yaml` → **Runboat Controller Deployment** (Pods)
- `templates/service.yaml` → **Service** fronting the controller Pods
- `templates/ingress.yaml` → **Ingress** (optional; disabled by default per README)
- `templates/configmap.yaml` + `templates/env.yaml` → **Configuration** injected into Pods (env vars/config files)
- `templates/secret-controller.yaml`, `templates/secret-builds.yaml` → **Secrets** (API admin creds, repo allowlist, DB creds, etc.)
- `templates/serviceaccount.yaml` → **ServiceAccount** used by controller Pods
- `templates/rolebinding.yaml` → **RBAC binding** (controller permissions in cluster/namespace)
- `templates/namespace-builds.yaml` → **Builds Namespace** (separate namespace for runboat builds)
- `templates/tests/test-connection.yaml` → Helm test Pod (post-install connectivity check)

##### Pull key runtime dependencies from README (must appear
- `controllerenv.runboatBuildEnv`: explicitly says **Postgres connection details** are required → **External PostgreSQL** is a first-class node.
- `runboatSecret.repos`: list of allowed repositories → Runboat likely talks to **Git hosting** (GitHub/GitLab/etc.). Even if abstract, show “Allowed Git Repos (external)”.
- `ingress.host`: external entrypoint hostname → show **DNS/Host → Ingress**.
- `runboatSecret.apiAdminUser` / `runboatSecret.apiAdminPasswd`: **admin API auth** → show these as Kubernetes Secret feeding the controller.

Shows external actors + major systems:
- User/Admin (or CI) accessing Runboat UI/API
- Kubernetes cluster hosting Runboat
- PostgreSQL
- Git providers (repos)

This is the core for this repo. It should show:
- Namespaces
- Deployment → Pod(s)
- Service
- Ingress (optional)
- ConfigMap/Secrets → mounted/injected into Pod
- ServiceAccount + RoleBinding relationships
- Any “builds namespace” resource separation

Use these as your canonical component list:

**Cluster / Namespaces**
- Namespace: `runboat-controller` (implied by README install command `-n runboat-controller`)
- Namespace: “builds” namespace from `namespace-builds.yaml` (name likely configurable; label it “Runboat Builds Namespace”)

**Runboat Controller stack**
- Ingress (optional)
- Service (stable endpoint)
- Deployment (Runboat Controller)
- Pod(s): Runboat controller container(s)

**Configuration & Secrets**
- ConfigMap (non-sensitive config)
- Secret: Controller/API admin creds + allowed repos + other controller secrets
- Secret: Builds secrets (whatever build namespace needs; keep generic if not sure)

**RBAC**
- ServiceAccount used by controller Pods
- RoleBinding (binding permissions; show “K8s API access” path from Pod → API Server, gated by RBAC)

**External services**
- PostgreSQL (required)
- Git Repositories / SCM provider(s) (required by allowlist)
- Clients (browser/CLI) hitting `ingress.host`

**Optional lifecycle**
- GitHub Actions workflow “release-helm” → OCI registry `ghcr.io/...` (since install uses `oci://ghcr.io/...`)

**Ingress path (when enabled)**
- User/Client → (DNS: `ingress.host`) → Ingress → Service → Runboat Controller Pod

**Controller dependencies**
- Runboat Controller Pod → PostgreSQL (SQL/TCP)
- Runboat Controller Pod → Git provider / repos (HTTPS Git/HTTP APIs)
- Runboat Controller Pod → Kubernetes API Server (control plane)
Tie this to ServiceAccount/RoleBinding.

**Configuration injection**
- ConfigMap → Pod (env/config)
- Secrets → Pod (env/volume)
Specifically label:
- “DB credentials”
- “API admin username/password”
- “Allowed repos allowlist”

**Build isolation**
- Controller (in controller namespace) → manages resources in “builds namespace”

**Helm test**
- Helm test Pod → Service endpoint (connection check)

##### Technologies/frameworks to label explicitly
- Helm (chart + values)
- Kubernetes resources: Deployment, Service, Ingress, ConfigMap, Secret, Namespace, ServiceAccount, RoleBinding
- PostgreSQL (external)
- OCI registry (ghcr.io) for chart distribution (if including CI/CD)

##### Don’t overthink: maximize component separation
- Two namespaces (controller + builds)
- RBAC chain (Pod → ServiceAccount → RoleBinding → K8s API)
- Secrets vs ConfigMaps
- Optional ingress
- External Postgres + SCM

## Diagram (Mermaid)

```mermaid
flowchart TD

  %% =========================
  %% Actors / External Systems
  %% =========================
  subgraph "External Actors & Systems"
    direction TB
    User["User/Admin Client\n(Browser/CLI)"]:::actor
    DNS["DNS / Hostname\n(ingress.host)"]:::external

    Git["Allowed Git Repositories\n(SCM Provider: GitHub/GitLab/etc.)"]:::external
    PG[("External PostgreSQL\n(required)")]:::database

    Registry["OCI Registry\n(ghcr.io)"]:::external
  end

  %% =========================
  %% Delivery (CI/CD)
  %% =========================
  subgraph "Delivery Pipeline (Lifecycle)"
    direction TB
    GHActions["GitHub Actions\nRelease Helm Chart"]:::cicd
    Chart["Helm Chart Artifact\n(OCI package)"]:::cicd
    Helm["Helm\n(install/upgrade)"]:::tool
  end

  GHActions -->|"pushes_chart"| Registry
  Registry -->|"pulls_chart"| Helm
  Helm -->|"renders_templates"| K8s

  %% =========================
  %% Kubernetes Cluster
  %% =========================
  subgraph K8s["Kubernetes Cluster"]
    direction TB

    APIServer["Kubernetes API Server\n(Control Plane)"]:::controlplane
    IngressCtrl["Cluster Ingress Controller\n(NGINX/Traefik/etc.)"]:::controlplane

    subgraph "Namespace: runboat-controller"
      direction TB

      Ingress["Ingress (optional)\nDisabled by default"]:::optional
      Service["Service\n(Stable endpoint)"]:::service

      subgraph "Runboat Controller"
        direction TB
        Deploy["Deployment\nRunboat Controller"]:::workload
        Pod["Pod(s)\nRunboat Controller Container"]:::workload
      end

      CM["ConfigMap\n(non-sensitive config)"]:::config
      EnvTpl["Env Wiring Template\n(env vars injection)"]:::config

      SecretCtrl["Secret\n(controller)\n- DB credentials\n- API admin user/pass\n- Allowed repos allowlist"]:::secret
      SA["ServiceAccount\n(for controller Pods)"]:::rbac
      RB["RoleBinding\n(controller permissions)"]:::rbac

      TestPod["Helm Test Pod (optional)\nconnectivity check"]:::optional
    end

    subgraph "Namespace: runboat-builds (isolated)"
      direction TB
      BuildsNS["Build Workloads/Resources\n(created & monitored by controller)"]:::namespace
      SecretBuilds["Secret\n(builds-related)"]:::secret
    end
  end

  %% =========================
  %% Runtime Request/Data Flows
  %% =========================
  User -->|"HTTPS"| DNS
  DNS -->|"routes_to"| IngressCtrl
  IngressCtrl -->|"HTTP(S)\n(optional)"| Ingress
  Ingress -->|"routes_to"| Service
  Service -->|"forwards_to"| Pod

  %% Controller dependencies
  Pod -->|"SQL/TCP"| PG
  Pod -->|"HTTPS (git/api)"| Git
  Pod -->|"K8s_API\ncreate/monitor_builds"| APIServer
  APIServer -->|"manages_resources_in"| BuildsNS

  %% Config & Secrets injection
  CM -->|"mount/env"| Pod
  EnvTpl -->|"templates_env"| Pod
  SecretCtrl -->|"env/volume\nsensitive"| Pod
  SecretBuilds -->|"used_by_builds"| BuildsNS

  %% RBAC chain
  SA -->|"bound_by"| RB
  Pod -->|"uses"| SA
  RB -->|"authorizes"| APIServer

  %% Helm test flow
  TestPod -.->|"connects_to"| Service

  %% Chart metadata/config surface (operator inputs)
  subgraph "Chart Inputs & Templates"
    direction TB
    ChartYaml["Chart.yaml\n(metadata)"]:::doc
    ValuesYaml["values.yaml\n(default configuration surface)"]:::doc
    Readme["README.md\n(required values & guidance)"]:::doc
    Helpers["_helpers.tpl\n(naming/labels helpers)"]:::doc
  end

  Helm -->|"uses_values"| ValuesYaml
  Helm -->|"reads_docs"| Readme
  Helm -->|"chart_metadata"| ChartYaml
  Helm -->|"template_helpers"| Helpers

  %% =========================
  %% Click Events (component mapping)
  %% =========================
  click ChartYaml "https://github.com/secretagentnull/runboat-helm/blob/main/Chart.yaml"
  click ValuesYaml "https://github.com/secretagentnull/runboat-helm/blob/main/values.yaml"
  click Readme "https://github.com/secretagentnull/runboat-helm/blob/main/README.md"
  click Helpers "https://github.com/secretagentnull/runboat-helm/blob/main/templates/_helpers.tpl"

  click Deploy "https://github.com/secretagentnull/runboat-helm/blob/main/templates/deployment.yaml"
  click Service "https://github.com/secretagentnull/runboat-helm/blob/main/templates/service.yaml"
  click Ingress "https://github.com/secretagentnull/runboat-helm/blob/main/templates/ingress.yaml"

  click CM "https://github.com/secretagentnull/runboat-helm/blob/main/templates/configmap.yaml"
  click EnvTpl "https://github.com/secretagentnull/runboat-helm/blob/main/templates/env.yaml"

  click SecretCtrl "https://github.com/secretagentnull/runboat-helm/blob/main/templates/secret-controller.yaml"
  click SecretBuilds "https://github.com/secretagentnull/runboat-helm/blob/main/templates/secret-builds.yaml"

  click SA "https://github.com/secretagentnull/runboat-helm/blob/main/templates/serviceaccount.yaml"
  click RB "https://github.com/secretagentnull/runboat-helm/blob/main/templates/rolebinding.yaml"

  click BuildsNS "https://github.com/secretagentnull/runboat-helm/blob/main/templates/namespace-builds.yaml"
  click TestPod "https://github.com/secretagentnull/runboat-helm/blob/main/templates/tests/test-connection.yaml"

  click GHActions "https://github.com/secretagentnull/runboat-helm/blob/main/.github/workflows/release-helm.yaml"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#E3F2FD,stroke:#1565C0,stroke-width:1px,color:#0D47A1
  classDef external fill:#F1F8E9,stroke:#33691E,stroke-width:1px,color:#1B5E20
  classDef database fill:#FFF3E0,stroke:#E65100,stroke-width:1px,color:#BF360C
  classDef controlplane fill:#E8EAF6,stroke:#283593,stroke-width:1px,color:#1A237E
  classDef service fill:#E0F7FA,stroke:#006064,stroke-width:1px,color:#004D40
  classDef workload fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px,color:#1B5E20
  classDef config fill:#FFFDE7,stroke:#F9A825,stroke-width:1px,color:#F57F17
  classDef secret fill:#FFEBEE,stroke:#C62828,stroke-width:1px,color:#B71C1C
  classDef rbac fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px,color:#4A148C
  classDef namespace fill:#ECEFF1,stroke:#455A64,stroke-width:1px,color:#263238
  classDef optional fill:#FAFAFA,stroke:#616161,stroke-width:1px,stroke-dasharray:5 4,color:#424242
  classDef cicd fill:#E0F2F1,stroke:#00796B,stroke-width:1px,color:#004D40
  classDef tool fill:#F5F5F5,stroke:#424242,stroke-width:1px,color:#212121
```
