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

Get 2501-<build>.tgz and values.example.yaml from installation releases. Verify the files.

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 administrator and organization	Optional `identity` settings
First LLM	Set `llm.provider`, `llm.baseUrl` and `llm.model` together, with its key secret

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.

Create the secrets

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.

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.19.0-r1. Helm and ArgoCD skip pre-release builds in ordinary version ranges such as 0.19.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.

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

Issue a certificate covering ai-2501-engine, ai-2501-engine.<namespace>.svc and ai-2501-engine.<namespace>.svc.cluster.local. Adapt the prefix if you change stackName.

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

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

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.

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/<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 cannot yet be checked
`/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. Readiness stays successful after the first successful check; it is not an ongoing database health test. 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.

Hosted MCP servers

Hosted plugins run as non-root pods without a service account token. 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. Ensure image pull secrets and namespace quotas cover these pods.

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 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

​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

Create the secrets

Apply

With Helm or ArgoCD

Your site’s values

Executors in another namespace

Additional installation settings

Check

Hosted MCP servers

Centrals