How secretagentnull/runboat-helm works
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