Kubernetes and OpenShift

Install 2501 from a verified release chart and your own values.yaml. Use oc in place of kubectl on OpenShift.

Install

Use one namespace per installation. For an existing installation, follow Upgrade or Move from the CLI.

Download the build

From installation releases, download and verify 2501-<build>.tgz and values.example.yaml.

Prepare image access

Configure access to 2501’s registry, or copy the build’s images into your registry.

Prepare the namespace

Set NS=ai-2501 in your shell, then run kubectl create namespace "$NS".

Configure the installation

Write your values and create the required secrets below.

Apply and verify

Choose the kubectl, Helm or ArgoCD path below, then complete Check.

Write your values.yaml

Copy values.example.yaml to values.yaml. This minimal example uses Kubernetes, a supplied PostgreSQL database and a certificate secret:

target: kubernetes
global:
  imageRegistry: 605134458542.dkr.ecr.eu-west-3.amazonaws.com/2501.ai/release
commandCenter:
  host: 2501.example.com
  tls:
    mode: secret
database:
  managed: true
elasticsearch:
  mode: none

Decision	Value
OpenShift	`target: openshift` and `database.managed: false`
TLS terminates at your load balancer	`commandCenter.tls.mode: upstream`
Your registry	`global.imageRegistry` and `global.imagePullSecrets`
First LLM	Set `llm.provider`, `llm.baseUrl` and `llm.model` together, with its key secret
Log level	`sizing.logLevel`: `debug`, `info` (default) or `warn`
Log retention	`elasticsearch.retentionDays`: days to keep engine and Command Center logs in Elasticsearch; default `30`

Value	Meaning	Default
`identity.tenant`, `identity.organizations`, `identity.admin.email`	The first tenant, its organizations and the first administrator’s email	Tenant and organization `Default`, administrator `admin@2501.ai`

Without LLM settings, add the model in Command Center after installation. Identity and LLM settings initialize the first installation; change them in Command Center afterwards. See the configuration reference for all values. When initializing the first model, set optional llm.contextLength to its supported context size. Change an existing model in Command Center after installation.

Images from your registry, or no internet access

Copy the images of the build into your registry under the same paths, then point the chart at it, with its login secret if it needs one. The chart keeps naming each image by its digest, which is the same in every registry; the executor images the engine starts come from the same place:

global:
  imageRegistry: registry.bank.internal:5000/2501.ai/release
  imagePullSecrets: [registry-pull]
connectivity: offline          # refuses an LLM on a public service the site cannot reach

Create the secrets

Create each secret once, in the namespace, and never put its value in Git. The pods wait until every secret they read exists. helm install ai2501 ./2501-<build>.tgz -n "$NS" -f values.yaml --dry-run=client prints the commands for your values, installing nothing; these are for the defaults:

kubectl create namespace "$NS"
rand() { openssl rand -hex 32; }
for s in credential-key-v1 engine-api-key-v1 auth-secret-v1 log-encryption-key-v1; do
  kubectl -n "$NS" create secret generic "$s" --from-literal="$s=$(rand)"
done
kubectl -n "$NS" create secret generic admin-password-v1 --from-literal=admin-password-v1='<first admin password>'
kubectl -n "$NS" create secret tls cc-tls --cert=<your host>.crt --key=<its key>
# With the LLM settings only: its API key.
kubectl -n "$NS" create secret generic llm-api-key-v1 --from-literal=llm-api-key-v1='<LLM API key>'
# With the PostgreSQL 2501 provides:
kubectl -n "$NS" create secret generic postgres-password-v1 --from-literal=postgres-password-v1="$(rand)"
# OpenShift, or your own PostgreSQL:
oc -n "$NS" create secret generic pg-connection-v1 \
  --from-literal=DATABASE_URL='postgresql://USER:PASSWORD@HOST:5432/DB?sslmode=verify-full' \
  --from-literal=DIRECT_URL='<the same, bypassing any connection pooler>'

Print the commands for your chosen values without installing anything:

helm install ai2501 ./2501-<build>.tgz -n "$NS" -f values.yaml --dry-run=client

Replace the placeholders and run the printed secret commands once. Include the certificate for commandCenter.host when using tls.mode: secret. Your secret manager can create the same names and keys instead. Pods wait for missing secrets. The default names and keys are:

Secret	Keys	When needed
`cc-tls`	`tls.crt`, `tls.key`	Certificate for `commandCenter.host` with `tls.mode: secret`
`credential-key-v1`	`credential-key-v1`	Every installation
`engine-api-key-v1`	`engine-api-key-v1`	Every installation
`auth-secret-v1`	`auth-secret-v1`	Every installation
`log-encryption-key-v1`	`log-encryption-key-v1`	Every installation
`admin-password-v1`	`admin-password-v1`	Initial administrator password
`llm-api-key-v1`	`llm-api-key-v1`	Initial LLM settings
`postgres-password-v1`	`postgres-password-v1`	Supplied PostgreSQL database
`pg-connection-v1`	`DATABASE_URL`, `DIRECT_URL`	External PostgreSQL database

Use the printed commands for the chosen values if these defaults change. See the secret reference for other optional secrets.

Keep secret values out of Git. Preserve the installation’s encryption keys and database credentials across upgrades; replacing them can make existing data inaccessible.

Apply

Render, review and apply the complete file. The same pruning flags make removed resources visible in the diff:

helm template ai2501 ./2501-<build>.tgz -n "$NS" -f values.yaml > manifests.yaml
prune=(--prune
  -l 'app.kubernetes.io/part-of=2501,app.kubernetes.io/instance=ai2501'
  --prune-allowlist=core/v1/ConfigMap
  --prune-allowlist=core/v1/Service
  --prune-allowlist=core/v1/ServiceAccount
  --prune-allowlist=apps/v1/Deployment
  --prune-allowlist=batch/v1/Job
  --prune-allowlist=networking.k8s.io/v1/Ingress
  --prune-allowlist=networking.k8s.io/v1/NetworkPolicy
  --prune-allowlist=rbac.authorization.k8s.io/v1/Role
  --prune-allowlist=rbac.authorization.k8s.io/v1/RoleBinding
)
kubectl -n "$NS" diff -f manifests.yaml "${prune[@]}"
kubectl -n "$NS" apply -f manifests.yaml "${prune[@]}"

Review deletions before applying. This allowlist excludes volume claims and secrets. Repeat the render, review and apply after changing values.

With Helm or ArgoCD

The chart is also available at oci://ghcr.io/2501-ai/charts/2501. Verify the chart before installing it.

Select an exact build, such as 0.20.0-r1. Helm and ArgoCD skip pre-release builds in ordinary version ranges such as 0.20.x. They also skip them when no version is specified.

Helm
ArgoCD

Use the same namespace, values and pre-created secrets:

helm upgrade --install ai2501 ./2501-<build>.tgz -n "$NS" -f values.yaml --wait

To install the verified build from the registry instead:

helm upgrade --install ai2501 oci://ghcr.io/2501-ai/charts/2501 --version <build> -n "$NS" -f values.yaml --wait

Unpack the verified chart into your Git repository beside values.yaml:

spec:
  source:
    repoURL: <your-git-repository>
    targetRevision: <branch>
    path: <path>/2501
    helm:
      releaseName: ai2501
      valueFiles: [../values.yaml]
  destination: { namespace: <namespace> }
  syncPolicy:
    automated: { prune: true }

The chart protects its data volumes from pruning. Keep secret values outside this repository.Or point ArgoCD at the chart in the registry, with values.yaml from your Git repository. Declare ghcr.io/2501-ai/charts as a Helm repository with enableOCI: "true", and name the build exactly in targetRevision:

spec:
  sources:
    - repoURL: ghcr.io/2501-ai/charts
      chart: "2501"
      targetRevision: <build>
      helm:
        releaseName: ai2501
        valueFiles: [$values/<path>/values.yaml]
    - repoURL: <your-git-repository>
      targetRevision: <branch>
      ref: values
  destination: { namespace: <namespace> }
  syncPolicy:
    automated: { prune: true }

Your site’s values

Apply changes through values.yaml so they survive upgrades. Expand the relevant recipe; the configuration reference lists the remaining options.

HTTP proxy

proxy:
  url: http://proxy.bank.internal:3128
  noProxy: [.bank.internal]

The installation’s own services bypass the proxy. Executors inherit these settings.

Corporate CA

Create a ConfigMap with your PEM certificate, then set caBundle: corporate-ca:

kubectl -n "$NS" create configmap corporate-ca --from-file=ca.crt=corporate-ca.pem

HTTPS to the engine

The engine serves plain HTTP, reached only inside the cluster through its Service. To serve it over HTTPS only, create its certificate once. It must name ai-2501-engine, ai-2501-engine.<namespace>.svc and ai-2501-engine.<namespace>.svc.cluster.local (<stackName>-engine with another stackName): one your CA issues, or a self-signed one:

openssl req -x509 -newkey rsa:3072 -sha256 -nodes -days 825 \
  -subj "/CN=ai-2501-engine" -keyout engine-tls.key -out engine-tls.crt \
  -addext "subjectAltName=DNS:ai-2501-engine,DNS:ai-2501-engine.$NS.svc,DNS:ai-2501-engine.$NS.svc.cluster.local"
kubectl -n "$NS" create secret tls engine-tls --cert=engine-tls.crt --key=engine-tls.key

engine:
  tls:
    existingSecret: engine-tls

Command Center trusts this certificate. Restart both services after renewal.

Your PostgreSQL

Create pg-connection-v1 with DATABASE_URL and DIRECT_URL; the latter bypasses any connection pooler. Use your database’s connection strings with TLS verification.

database:
  managed: false
  existingSecret: pg-connection-v1
  sslmode: verify-full
  caBundle: database-ca

Supply database-ca as a ConfigMap with ca.crt when your database needs a corporate CA. Otherwise omit caBundle.

Your Elasticsearch

Create es-credentials with ELASTICSEARCH_USERNAME and ELASTICSEARCH_PASSWORD:

elasticsearch:
  mode: external
  url: https://es.bank.internal:9200
  existingSecret: es-credentials
  environment: production

Trust a corporate certificate with caBundle. For an existing installation, also enable Elasticsearch in Command Center as described in Operations.

Storage and sizing

For the volumes of the PostgreSQL and Elasticsearch 2501 provides:

storageClass: fast-ssd
database:
  size: 10Gi
elasticsearch:
  size: 30Gi

Set storageClass, database.size and elasticsearch.size before creating volumes. Bound claims cannot change storage class or shrink. Choose sizing.preset for the installation’s capacity; reserve additional namespace capacity for task and plugin containers.

Executors in another namespace

To give executor and hosted MCP server pods their own quotas and network rules, create the namespace, then:

executors:
  namespace: bank-executors

Create the namespace and its image pull secrets, then set executors.namespace. The chart places executor permissions and the hosted MCP policy there. With this setting, rendered objects name their namespaces: omit -n "$NS" from the file’s diff and apply commands.

Additional installation settings

Put non-secret settings in engine.extraEnv. For secret values, create an engine-extra-env Secret and restart the engine after changing it. For example, MCP_OAUTH_ALLOW_PRIVATE_PROVIDERS: "true" allows OAuth identity providers on private addresses, still over HTTPS. Put them in engine.extraEnv in your values.yaml, which works on Docker Swarm too, or, for a secret value, in a Secret named engine-extra-env in the namespace. The engine reads that Secret when it starts and the chart never writes it. Create or change it, then restart the engine:

kubectl -n "$NS" create secret generic engine-extra-env \
  --from-literal=MCP_OAUTH_ALLOW_PRIVATE_PROVIDERS=true \
  --dry-run=client -o yaml | kubectl apply -f -
kubectl -n "$NS" rollout restart deploy/engine

Check

kubectl -n "$NS" rollout status deploy/engine
kubectl -n "$NS" rollout status deploy/command-center
kubectl -n "$NS" get jobs -l app.kubernetes.io/component=bootstrap
kubectl -n "$NS" logs "job/$(kubectl -n "$NS" get jobs -l app.kubernetes.io/component=bootstrap --sort-by=.metadata.creationTimestamp -o name | tail -1 | cut -d/ -f2)"   # the newest bootstrap Job

The bootstrap log should show successful database migration and initialization. Investigate repeated failures before signing in at https://<your host>. The bootstrap Job has backoffLimit: 10. After it reaches that limit, fix the cause shown in the logs and delete the failed Job:

kubectl -n "$NS" delete job <failed-bootstrap-job>

Then repeat your deployment method: render and apply the manifests, run Helm upgrade, or sync ArgoCD. Check the new bootstrap Job’s logs before signing in.

Signal	Meaning
`/health` returns 200	Command Center is running
`/ready` returns 503 on a new pod	Required migrations are missing, unfinished, failed, or awaiting a database check
`/ready` returns 200	This pod has confirmed the migrations its version requires

Command Center keeps previous pods serving during the rollout until new pods become ready. The /ready endpoint checks the database once at startup to confirm the required migrations. The engine is replaced during upgrades, so allow running work to finish first.

Windows targets using gMSA require Docker Swarm. They are not supported by this Kubernetes deployment.

The chart gives the engine the engine-executor service account and a Role in the executor namespace. The Role grants these permissions:

Resource	Verbs
`pods`	`create`, `get`, `list`, `watch`, `delete`
`pods/attach`	`create`, `get`
`pods/status`, `pods/log`	`get`
`events`	`list`
`secrets`	`create`

At startup, the engine checks pods create/get/list/delete, pods/attach create/get and secrets create permissions. Missing permissions stop startup. If the cluster does not answer within 10 seconds, the engine logs a warning and starts without the check. A timed-out check is not proof of access. In the executor namespace, verify pod access, pods/attach create/get and Secret creation:

# Set EXEC_NS when executors.namespace differs from NS.
kubectl -n "${EXEC_NS:-$NS}" auth can-i create secrets --as="system:serviceaccount:${NS}:engine-executor"
kubectl -n "${EXEC_NS:-$NS}" auth can-i create pods/attach --as="system:serviceaccount:${NS}:engine-executor"
kubectl -n "${EXEC_NS:-$NS}" auth can-i get pods/attach --as="system:serviceaccount:${NS}:engine-executor"

Each executor pod receives only its own secret environment variables. The engine creates the Secret with its create-only API permission. The engine selects kube when it runs in Kubernetes and docker otherwise. Set EXECUTOR_MCP_BACKEND to kube or docker to force a backend. Executor MCP handshakes allow 20 seconds by default (MCP_HANDSHAKE_TIMEOUT_MS=20000), and satellite silence allows 40 seconds (SATELLITE_SILENCE_MS). An executor that misses its handshake deadline gets one retry in a fresh pod. Investigate image pulls, scheduling and connectivity before raising these limits. Engine termination has a 150-second grace period; finish running work before upgrades.

Hosted MCP servers

Hosted plugins run as non-root pods with RuntimeDefault seccomp and all Linux capabilities dropped. Their security settings meet the restricted Pod Security Standard. Service account token mounting is disabled. The chart supplies namespace-scoped permissions and a policy allowing DNS and public destinations, while blocking private and link-local destinations. Your network plugin must enforce NetworkPolicy. Add an explicit policy exception for required internal services or NodeLocal DNSCache. Review the network plugin’s startup enforcement before using untrusted images. On EKS with the Amazon VPC CNI, set NETWORK_POLICY_ENFORCING_MODE=strict to enforce policy from pod startup. Ensure image pull secrets and namespace quotas cover these pods. Target hosted MCP exceptions with app.kubernetes.io/managed-by: 2501-mcp-hosted. Allow only the required destination and ports. For NodeLocal DNSCache, use your actual DNS address, including a link-local address when configured; the default private-address block also blocks it. Each hosted pod requests 0.25 CPU, 512 MiB memory and 64 MiB ephemeral storage; its limits are 0.5 CPU, 512 MiB and 256 MiB. Each engine runs at most 32 hosted servers. The image must work as UID 65532, or the arbitrary UID assigned by OpenShift. Reserve quota for these pods and inspect admission errors such as exceeded quota when startup fails. Set these overrides under engine.extraEnv in values.yaml when needed:

Setting	Default	Override
`MCP_HOSTED_HANDSHAKE_TIMEOUT_MS`	`60000` milliseconds	Allow more time for a hosted server that starts slowly
`MCP_HOSTED_IMAGE_PULL_SECRETS`	The executors’ pull secrets	Supply other secret names, separated by commas, in the hosted pods’ namespace

Centrals

For local Central execution, prepare a dedicated namespace with restricted pod security, image access, scoped pod/attach permissions and network policies. Set engine.extraEnv.CENTRAL_LOCAL_K8S_NAMESPACE to that namespace. The chart does not prepare this separate Central environment for you. Leave Cluster (optional) at No cluster (default) to use this local environment, or select a registered cluster. Run the Central’s dry run before assigning work; a successful check does not validate task credentials.

Prepare local Central execution

This example uses ai-2501 for the installation and central for task containers. Replace ai-2501 in the binding if your installation uses another namespace. Save the following as central.yaml:

apiVersion: v1
kind: Namespace
metadata:
  name: central
  labels:
    pod-security.kubernetes.io/enforce: restricted
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: engine-central
  namespace: central
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["create", "get", "list", "watch", "delete"]
  - apiGroups: [""]
    resources: ["pods/attach"]
    verbs: ["create", "get"]
  - apiGroups: [""]
    resources: ["pods/status", "pods/log"]
    verbs: ["get"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: engine-central
  namespace: central
subjects:
  - kind: ServiceAccount
    name: engine-executor
    namespace: ai-2501
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: engine-central
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: central-isolation
  namespace: central
spec:
  podSelector: {}
  policyTypes: [Ingress, Egress]
  egress:
    - to:
        - namespaceSelector: {}
      ports:
        - { protocol: UDP, port: 53 }
        - { protocol: TCP, port: 53 }
        - { protocol: UDP, port: 5353 }
        - { protocol: TCP, port: 5353 }
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 10.0.0.0/8
              - 172.16.0.0/12
              - 192.168.0.0/16
              - 100.64.0.0/10
              - 169.254.0.0/16
              - 127.0.0.0/8
        - ipBlock:
            cidr: ::/0
            except: ["fc00::/7", "fe80::/10", "::1/128"]

Apply isolation and permissions

Run kubectl -n central apply -f central.yaml. Confirm your network plugin enforces the policy; other policies must not grant broader access to these pods.

Prepare registry access

Create the configured executor image pull secret in central too. It must allow both the release image and your Central images.

Select the namespace

Add the values below and reapply the chart. Keep the Central manifest’s namespace unset to use this default.

Verify execution

Run the Central’s Test in Dry run and confirm command success and container removal.

engine:
  extraEnv:
    CENTRAL_LOCAL_K8S_NAMESPACE: central

The service account also needs permission to read its own pod in the installation namespace. Check this especially if executors use a separate namespace. Allow only the internal destinations your Central tools require; the example permits cluster DNS and public destinations.

​Install

​Write your values.yaml

​Images from your registry, or no internet access

​Create the secrets

​Apply

​With Helm or ArgoCD

​Your site’s values

​Executors in another namespace

​Additional installation settings

​Check

​Hosted MCP servers

​Centrals

Install

Write your values.yaml

Images from your registry, or no internet access

Create the secrets

Apply

With Helm or ArgoCD

Your site’s values

Executors in another namespace

Additional installation settings

Check

Hosted MCP servers

Centrals