Run AISIX on OKD

AISIX uses its standard Kubernetes installation and upgrade procedures on OKD, with platform-specific handling for Security Context Constraints (SCCs), Routes, and the bundled PostgreSQL security context. This page covers AISIX gateways across all three products, plus the AISIX Enterprise control plane.

Start with an existing OKD cluster and an oc session that can create resources in the target project. AISIX Helm charts support the default restricted-v2 SCC used by OKD 4.11 or later. Confirm that the AISIX service accounts can use this SCC before installing or upgrading AISIX. Creating or upgrading the OKD cluster itself is separate from installing AISIX.

For a new installation, choose the base Kubernetes procedure for your deployment, then apply the corresponding OKD guidance on this page.

Deployment	Kubernetes procedure	Platform-specific requirement
AISIX OSS	Deploy AISIX OSS on Kubernetes	No additional SCC values.
Gateway connected to AISIX Enterprise or AISIX Cloud	Deploy Gateways for AISIX Enterprise or AISIX Cloud	No additional SCC values.
AISIX Enterprise	Install AISIX Enterprise	Disable the bundled PostgreSQL security contexts, or use an external database.

Understand the Security Context

The AISIX application charts do not pin runAsUser, runAsGroup, or fsGroup. Their pod security context enables runAsNonRoot and the RuntimeDefault seccomp profile. The platform can therefore assign IDs from the project's allowed range.

The application containers use read-only root filesystems and disable privilege escalation. The gateway drops all capabilities except NET_BIND_SERVICE; the control-plane containers drop all capabilities. Runtime-writable paths use emptyDir volumes.

Do not grant AISIX service accounts the anyuid SCC. If existing values pin user or group IDs, remove those values unless the cluster administrator allocated them to the project.

Select an OKD Project

Use an existing project, or request a new one if your cluster permits project creation:

# Select an existing project.
oc project aisix

# Or request a new project.
oc new-project aisix

The examples on this page use aisix. When following a linked Kubernetes procedure, skip any kubectl create namespace command and omit --create-namespace from Helm commands. Use the selected OKD project wherever the procedure specifies a namespace.

Choose Route Host Names

Choose the host names for the Routes that your deployment creates. Choose the control-plane and data-plane manager host names before installing AISIX Enterprise. The public control-plane URL is used for browser links, and the data-plane manager issues its TLS certificate for the configured endpoint.

The following example creates names under the cluster's wildcard applications domain:

export ROUTE_DOMAIN="$(oc get ingresses.config.openshift.io cluster \
  -o jsonpath='{.spec.domain}')"

export GATEWAY_ROUTE_HOST="aisix-gateway.$ROUTE_DOMAIN"
export CP_ROUTE_HOST="aisix.$ROUTE_DOMAIN"
export DPM_ROUTE_HOST="aisix-dpm.$ROUTE_DOMAIN"

If you use organization-managed DNS instead, set the variables to those host names and ensure they resolve to the OKD router. For edge Routes, also provide a matching Route certificate and key, or configure the Ingress Controller's default certificate to cover those host names. The data-plane manager passthrough Route uses the certificate issued from api.dpmgrBaseURL.

Install a Gateway

Follow the applicable Kubernetes gateway procedure in the preceding table, using oc in place of kubectl and the project selected above in place of its namespace. No custom SCC or service-account changes are required.

After installation, confirm that the pods use restricted-v2 and a project-assigned UID:

export GATEWAY_NAMESPACE="aisix"
export GATEWAY_RELEASE="aisix-dp"

oc get pods -n "$GATEWAY_NAMESPACE" \
  -l "app.kubernetes.io/instance=$GATEWAY_RELEASE,app.kubernetes.io/component=gateway"

oc get pod -n "$GATEWAY_NAMESPACE" <gateway-pod> \
  -o jsonpath='{.metadata.annotations.openshift\.io/scc}{"\n"}{.spec.containers[0].securityContext.runAsUser}{"\n"}'

The annotation should report restricted-v2. The platform may place the assigned UID on the pod rather than the container, so an empty second line does not by itself indicate a problem. Use oc exec -n "$GATEWAY_NAMESPACE" <gateway-pod> -- id when you need to confirm the runtime UID.

Install AISIX Enterprise

Review the requirements in Install AISIX Enterprise, but do not run that page's helm install command. The command in this section replaces it with the OKD-specific PostgreSQL values and Route URLs.

The cp-api and dp-manager workloads require no additional SCC values. Use the Route host names selected in the preceding section during installation so the data-plane manager certificate matches its passthrough Route.

The bundled PostgreSQL dependency pins its own user and group IDs. Disable its pod and container security contexts so restricted-v2 can assign them:

values.yaml

postgresql:
  primary:
    podSecurityContext:
      enabled: false
    containerSecurityContext:
      enabled: false

Pass the file with the public endpoints and required secrets during installation:

helm repo add api7 https://charts.api7.ai
helm repo update

helm install aisix-cp api7/aisix-cp \
  --namespace aisix \
  --version 1.6.0 \
  --values values.yaml \
  --set-string api.publicBaseURL="https://$CP_ROUTE_HOST" \
  --set-string api.dpmgrBaseURL="https://$DPM_ROUTE_HOST" \
  --set secrets.masterKey="$(openssl rand -base64 32)" \
  --set postgresql.auth.password="$(openssl rand -hex 24)" \
  --set postgresql.auth.postgresPassword="$(openssl rand -hex 24)"

Do not disable postgresql.shmVolume. Without it, PostgreSQL falls back to the 64 MB /dev/shm provided by the container runtime, and parallel queries can fail with could not resize shared memory segment.

For production, use an external highly available PostgreSQL database instead of the bundled database.

Expose AISIX with Routes

Create only the Routes required by your deployment model. The following gateway example uses the chart's default plain-HTTP proxy listener. The edge Route terminates TLS at the router and forwards HTTP to the gateway Service:

oc create route edge aisix \
  --service=aisix-dp \
  --port=proxy \
  --hostname="$GATEWAY_ROUTE_HOST" \
  --namespace aisix

For AISIX Enterprise, expose the control-plane API and dashboard with an edge Route to the cp-api Service:

oc create route edge aisix-cp \
  --service=aisix-cp-api \
  --port=http \
  --hostname="$CP_ROUTE_HOST" \
  --namespace aisix

The data-plane manager uses mutual TLS between connected gateways and the control plane. Expose it with TLS passthrough so the router does not terminate that connection:

oc create route passthrough aisix-cp-dpm \
  --service=aisix-cp-dpm \
  --port=tls \
  --hostname="$DPM_ROUTE_HOST" \
  --namespace aisix

These examples use the default release names and Service ports. Use the actual Service name and named port from oc get service -n aisix when the release uses name overrides or the gateway uses custom listeners. For a gateway listener that terminates TLS in the pod, use a passthrough Route, or use re-encrypt termination when the router must establish a new verified TLS connection to the Service. The data-plane manager certificate must include the passthrough Route hostname in its subject alternative names.

Upgrade AISIX

Choose the canonical upgrade procedure for the deployment model:

• For an open-source AISIX gateway or a gateway connected to AISIX Cloud, follow Upgrade an AISIX Gateway on Kubernetes. The connected gateway path skips the AISIX OSS resource validation.
• For AISIX Enterprise, follow Upgrade AISIX Enterprise. Upgrade the control plane before its connected gateways.

Set the namespaces used by the upgrade and verification commands:

export GATEWAY_NAMESPACE="aisix"
export CP_NAMESPACE="aisix" # AISIX Enterprise only

Capture the current Routes before changing a release so you can compare their Service targets after each rollout:

oc get routes -n "$GATEWAY_NAMESPACE"

# AISIX Enterprise only
oc get routes -n "$CP_NAMESPACE"

Before running the selected procedure, preserve the PostgreSQL overrides in the saved control-plane values when the deployment uses the bundled database. Remove fixed runAsUser, runAsGroup, and fsGroup values that are not allocated to the project.

Use oc in place of kubectl. Before changing a release, run the procedure's Helm server-side dry run. A successful --dry-run=server checks rendering, cluster lookups, and OpenAPI validation, but it does not submit the objects to SCC, quota, or other admission checks. The assigned SCC is confirmed only when the platform creates a pod.

After each rollout, check the pods and Routes:

oc get pods -n "$GATEWAY_NAMESPACE"
oc get routes -n "$GATEWAY_NAMESPACE"

# AISIX Enterprise only
oc get pods -n "$CP_NAMESPACE"
oc get routes -n "$CP_NAMESPACE"

For AISIX Enterprise, verify that existing gateways remain healthy after the control-plane upgrade. Confirm that the control-plane API edge Route and data-plane manager passthrough Route still target the same Services they did before the upgrade. The data-plane manager Route hostname must also match the address stored in the gateway configuration.

Troubleshoot a Web Console Upgrade

A control-plane release originally installed with the Helm CLI can fail to upgrade in the OKD web console. If the console reports the following error, continue with the Helm CLI upgrade procedure:

found in Chart.yaml, but missing in charts/ directory: postgresql

The published control-plane chart already includes its PostgreSQL dependency, so do not download the dependency separately or rebuild the chart.

Troubleshoot SCC Admission

Find the FailedCreate event, then describe the controller named by the event. A gateway or control-plane API pod is owned by a ReplicaSet; bundled PostgreSQL is owned by a StatefulSet.

export FAILED_NAMESPACE="<project-containing-rejected-workload>"

oc get events -n "$FAILED_NAMESPACE" --sort-by=.lastTimestamp
oc describe -n "$FAILED_NAMESPACE" <controller-kind>/<controller-name>

For an AISIX application pod, remove fixed runAsUser, runAsGroup, and fsGroup values. For bundled PostgreSQL, disable both dependency-chart security contexts as shown in Install AISIX Enterprise.

Do not work around a denied pod by granting anyuid. If an organization policy applies an SCC stricter than restricted-v2, have the cluster administrator review the rendered manifests and allocate any required IDs or capabilities explicitly.

Troubleshoot a Container Start Failure

Describe the pod first. Read its current logs if the container started:

oc describe pod -n <namespace> <pod>
oc logs -n <namespace> <pod> --all-containers --tail=300

If a container restarted, identify its name in the pod description and read its previous logs:

oc logs -n <namespace> <pod> -c <restarted-container> --previous --tail=300

If CRI-O reports exec: Operation not permitted for a customized gateway container, confirm that the container security context permits NET_BIND_SERVICE. The gateway binary carries that file capability, so CRI-O must keep it in the container's capability bounding set even when the configured listener port is not privileged. Keep all other capabilities dropped.