Skip to main content
API7.ai Logo
Version: 1.6.0

Deploy AISIX OSS on OpenShift or OKD

AISIX OSS runs on OpenShift and OKD without a control plane. The gateway loads models, provider credentials, caller API keys, and policies from a declarative resources.yaml file, while the platform assigns its runtime UID through the default restricted-v2 Security Context Constraint (SCC).

This procedure installs one gateway replica, exposes it with an edge Route, and verifies both the AISIX configuration and the OpenShift security context. Configure shared Redis before increasing the replica count when limits or cache entries must remain consistent across replicas.

Prerequisites​

  • An existing OpenShift or OKD 4.11 or later cluster.
  • An oc session that can create resources in the target project.
  • Helm 3 and Docker.
  • An upstream provider key and a caller API key. The examples use OpenAI and the model alias gpt-4o-mini.

Prepare the Project and Credentials​

Select an existing project, or request a new one if the cluster permits project creation:

oc project aisix-dp

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

Export the credentials used by the example, then store them as Secrets:

export OPENAI_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

oc -n aisix-dp create secret generic openai-credentials \
  --from-literal=api-key="$OPENAI_API_KEY"
oc -n aisix-dp create secret generic aisix-caller-keys \
  --from-literal=my-caller="$CALLER_API_KEY"

Prepare and Validate AISIX Resources​

Save the following chart values as values.yaml. The chart stores the inline resource document in a Secret, while the credentials remain in the Secrets created above:

values.yaml
replicaCount: 1

image:
  repository: ghcr.io/api7/aisix
  tag: "1.6.0"

controlPlane:
  enabled: false

standalone:
  resources:
    _format_version: "1"
    provider_keys:
      - display_name: openai-main
        provider: openai
        adapter: openai
        api_key: ${OPENAI_API_KEY}
        api_base: https://api.openai.com/v1
    models:
      - display_name: gpt-4o-mini
        provider: openai
        model_name: gpt-4o-mini
        provider_key: openai-main
    api_keys:
      - display_name: my-caller
        key_env: CALLER_API_KEY
        allowed_models:
          - gpt-4o-mini

extraEnvVars:
  - name: OPENAI_API_KEY
    valueFrom:
      secretKeyRef:
        name: openai-credentials
        key: api-key
  - name: CALLER_API_KEY
    valueFrom:
      secretKeyRef:
        name: aisix-caller-keys
        key: my-caller

If another system manages resources.yaml, use the existing Secret or ConfigMap workflow in Deploy AISIX OSS on Kubernetes instead. Keep using the aisix-dp project and oc for the commands in that workflow.

Render the chart-managed Secret and extract the exact resource document assembled from values.yaml:

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

helm template aisix-dp api7/aisix --namespace aisix-dp --version 1.6.0 \
  -f values.yaml --show-only templates/secret.yaml |
  awk '
    /^  resources\.yaml: \|$/ { in_resources = 1; next }
    in_resources && /^---$/ { exit }
    in_resources { sub(/^    /, ""); print }
  ' > rendered-resources.yaml

Validate the rendered document with the same credentials that the gateway will receive:

docker run --rm -i \
  -e OPENAI_API_KEY -e CALLER_API_KEY \
  --entrypoint /bin/sh ghcr.io/api7/aisix:1.6.0 \
  -c 'umask 077; cat > /tmp/resources.yaml && exec /usr/local/bin/aisix validate --resources /tmp/resources.yaml' \
  < rendered-resources.yaml

Streaming the document avoids weakening its host permissions or changing its SELinux label.

Deploy the Gateway​

Install the chart in the selected project:

helm install aisix-dp api7/aisix \
  --namespace aisix-dp \
  --version 1.6.0 \
  --values values.yaml

The gateway chart does not pin runAsUser, runAsGroup, or fsGroup. It enables runAsNonRoot and the RuntimeDefault seccomp profile, allowing restricted-v2 to assign IDs from the project range. The container uses a read-only root filesystem, disables privilege escalation, and drops every capability except NET_BIND_SERVICE; runtime-writable paths use emptyDir volumes.

Do not grant the gateway service account anyuid. If the cluster administrator allocates fixed IDs for an organization policy or custom volume, set podSecurityContext.runAsUser, podSecurityContext.runAsGroup, and podSecurityContext.fsGroup to those allocated values. Do not reuse image UID 10001 unless it belongs to the project's allowed range.

If an organization policy applies an SCC stricter than restricted-v2, ask the cluster administrator to review the rendered manifests and allocate any required IDs or capabilities explicitly.

Expose the Gateway​

Create an edge Route to the default plain-HTTP proxy Service port. The OpenShift router terminates TLS and forwards HTTP to the gateway:

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

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

This command uses the default release name and proxy Service port. If the release uses a name override or custom listeners, run oc get service -n aisix-dp and substitute the actual Service name and named port.

If you use organization-managed DNS, set GATEWAY_ROUTE_HOST to that hostname and ensure it resolves to the router. Provide a matching Route certificate and key, or configure the Ingress Controller's default certificate to cover the hostname.

For a gateway listener that terminates TLS in the pod, use a passthrough Route. Use re-encrypt termination when the router must establish a new verified TLS connection to the Service.

Verify the Deployment​

The default applications domain normally uses a wildcard certificate signed by the cluster's internal ingress CA. When that CA is not already trusted on the workstation, export it for the curl checks:

oc get configmap default-ingress-cert -n openshift-config-managed \
  -o jsonpath='{.data.ca-bundle\.crt}' > ingress-ca.crt
export CURL_CA_BUNDLE="$PWD/ingress-ca.crt"

Skip this export when the Route or default Ingress Controller uses a certificate that the workstation already trusts.

Wait for the gateway Deployment and confirm its assigned SCC and UID:

oc rollout status deployment/aisix-dp -n aisix-dp --timeout=5m

export GATEWAY_POD="$(oc get pod -n aisix-dp \
  -l 'app.kubernetes.io/instance=aisix-dp,app.kubernetes.io/component=gateway' \
  -o jsonpath='{.items[0].metadata.name}')"

oc get pod -n aisix-dp "$GATEWAY_POD" \
  -o jsonpath='{.metadata.annotations.openshift\.io/scc}{"\n"}'
oc exec -n aisix-dp "$GATEWAY_POD" -- id -u

The first line should report restricted-v2, and the second should show the UID used by the running process. Confirm that the UID is in the project's allocated range.

Send requests through the Route to verify readiness, caller authentication, and the upstream provider connection:

export AISIX_PROXY="https://$GATEWAY_ROUTE_HOST"

curl -sS "$AISIX_PROXY/readyz"
curl -sS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer $CALLER_API_KEY"
curl -sS "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Reply with: AISIX is ready"
      }
    ]
  }'

The readiness request should return ok, the model list should contain gpt-4o-mini, and the completion should contain the requested assistant message.

Next Steps​