DocsBook a demo

Platform

Platform overviewArchitectureWorkflow orchestrationGitOps configurationGovernance and AAAAI and MCPKnowledge and contextRuntime and executionEvidence and monitoring

Use cases

All use casesProduction incidentRelease preparationHotfix to productionSecurity scan triage
Why NopsAIIntegrationsSecurity

Resources

All resourcesAI agent governanceMCP governanceMCP securitySelf-hosted platforms
PricingGitHub

Company

How a run worksAboutContactBook a demo

Kubernetes and Helm deployment

Cluster deployment, generated install artifacts, and the service accounts that separate platform from workload.

How-toAdministratorOperator

Key points

  • The chart deploys PostgreSQL, API, AAA, dispatcher, git-bot, UI, Gotenberg, and the Kubernetes runner.
  • Install the CLI from the latest GitHub Release assets before running nopsai install kubernetes; remove the downloaded archive after extraction.
  • nopsai install kubernetes generates non-secret values, installation.md, and a separate Secret manifest.
  • The runner Deployment and agent pods use an RBAC-bearing runner ServiceAccount; step pods use a separate no-RBAC workload ServiceAccount.
  • topology.dispatcherGRPCAddress defaults to dispatcher:9090 and is injected into API and runner pods.
  • Cross-namespace runners normally need dispatcher.<platform-namespace>.svc.cluster.local:9090.
  • Private registries work through explicit imagePullSecrets.
  • The chart version is the only version to change: NopsAI image tags resolve from global.releaseVersion, and an empty value falls back to the chart appVersion. Per-image tag and digest values stay available as intentional overrides.

Before you start

Cluster access
A namespace you can install intokubectl auth can-i create deployment -n nopsai
Helm
Helm 3helm version --short
Secrets
The platform secrets available as Kubernetes secrets rather than a local .env
Registry access
Pull access to the platform images from the cluster, with imagePullSecrets where the registry is private

Steps

  1. 01

    Render before you apply

    Plan mode renders the manifests without touching the cluster, which is the cheapest way to catch a bad value file.

    Render the chartbash
    helm template nopsai deploy/helm/nopsai --values my-values.yaml
    Replace before running
    • my-values.yaml carries the topology, image, and secret references for the target cluster.
    Expected result
    • Rendered manifests for the API, AAA, dispatcher, git-bot, UI, and supporting services.
  2. 02

    Install or upgrade

    The same command does both, which keeps the first install and every later one on one path.

    Install the releasebash
    helm upgrade --install nopsai deploy/helm/nopsai \
  --namespace nopsai --create-namespace \
  --values my-values.yaml --wait
    Verify
    • kubectl get pods -n nopsai
  3. 03

    Confirm the dispatcher is reachable by runners

    Runners dial out, so the dispatcher address in the values must be resolvable from wherever the runners live — cross-namespace runners need the fully qualified service name.

    Check the servicebash
    kubectl get svc dispatcher -n nopsai
    Expected result
    • The dispatcher answers on port 9090, which is the port DISPATCHER_GRPC_ADDRESS must point at.
  4. 04

    Install a Kubernetes runner

    Generate the runner install from the dispatcher workspace rather than hand-writing a manifest, so identity, scopes, and TLS material come from the control plane.

    Verify
    • The runner registers and appears in the fleet view with its scopes.

How it works

Keeping step pods on a no-RBAC service account is what stops workload code from calling the Kubernetes API. Do not merge the two accounts to simplify a chart values file.

Managed PostgreSQL is supported by disabling the bundled StatefulSet and replacing the generated database URL.

The Kubernetes runner gives each run an agent-owned PVC-backed workspace rather than an emptyDir, so the workspace survives step pod churn within the run.

System Logs on Kubernetes use read-only pods and pods/log RBAC instead of the Docker socket proxy.

Field reference

RUNTIME_POOLSkubernetes runnermapOptionalNone

Named Kubernetes runtime pools selectable through pipeline or step runtime_pool.

Example

RUNTIME_POOLS=gpu:node-role=gpu

Evidence

config/config.go

KUBERNETES_NAMESPACEkubernetes runnerstringOptionalRunner namespace

Namespace where the runner creates agent pods, step pods, and workspace PVCs.

Example

KUBERNETES_NAMESPACE=nopsai-runners

Evidence

config/config.go

KUBERNETES_SERVICE_ACCOUNTkubernetes runnerstringOptionalChart-managed runner service account

RBAC-bearing service account used by the runner Deployment and agent pods.

Example

KUBERNETES_SERVICE_ACCOUNT=nopsai-runner

Evidence

deploy/helm/nopsai

KUBERNETES_WORKLOAD_SERVICE_ACCOUNTkubernetes runnerstringOptionalChart-managed no-RBAC service account

Separate service account for step pods, deliberately without cluster permissions.

Example

KUBERNETES_WORKLOAD_SERVICE_ACCOUNT=nopsai-workload

Security

Keeping step pods on a no-RBAC account is what stops workload code from calling the Kubernetes API.

Evidence

deploy/helm/nopsai

KUBERNETES_IMAGE_PULL_SECRETSkubernetes runnerstring[]OptionalNone

Infrastructure-owned pull secrets attached to runner and step pods for private registries.

Example

KUBERNETES_IMAGE_PULL_SECRETS=regcred

Evidence

config/config.go

KUBERNETES_STORAGE_CLASSkubernetes runnerstringOptionalCluster default

Storage class used for the agent-owned workspace PVC.

Example

KUBERNETES_STORAGE_CLASS=fast-ssd

KUBERNETES_DEFAULT_WORKSPACE_SIZEkubernetes runnerstringOptionalChart default

Requested size of the run workspace PVC.

Example

KUBERNETES_DEFAULT_WORKSPACE_SIZE=20Gi

KUBERNETES_AFFINITY_ENABLEDkubernetes runnerbooleanOptionalChart default

Whether step pods in a run are scheduled onto the same node by default.

Example

KUBERNETES_AFFINITY_ENABLED=true

Overridden by

pipeline affinity_enabled

KUBERNETES_CLEANUP_FINISHED_PODSkubernetes runnerbooleanOptionalChart default

Whether finished step pods are deleted after their status is reported.

Example

KUBERNETES_CLEANUP_FINISHED_PODS=true

Examples

Generate install artifacts for a pinned versionbash
nopsai install kubernetes --version 1.4.2
Result

Non-secret Helm values, installation.md, and a separate Secret manifest to apply directly or seal.

Limits

Current behavior
  • The repository documents no HPA/autoscaling implementation and no Kubernetes NetworkPolicy set.
  • Helm does not manage PostgreSQL beyond the bundled StatefulSet.

Implementation evidence

  • deploy/helm/nopsai/values.yaml

    Chart values including topology and service accounts.

  • doc/kubernetes-runner.md

    Runner runtime, PVC workspace behavior, affinity, and manifests.