Deploy the Open-Source AISIX Gateway on Kubernetes

The api7/aisix Helm chart deploys the open-source AISIX gateway on Kubernetes. Set controlPlane.enabled: false to run the gateway without a control plane or gateway certificate bundle and load its resources from a declarative resources.yaml file.

Provider keys, models, caller API keys, guardrails, MCP servers, and rate-limit policies all come from that file, while Kubernetes manages the gateway pods, Services, health checks, and rollouts. To deploy gateways for AISIX Cloud instead, follow Deploy AISIX Gateways on Kubernetes.

Prerequisites

A Kubernetes cluster with kubectl configured to access it.
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 Cluster and Credentials

Export the provider and caller credentials used by the examples:

# Replace with your OpenAI API key.
export OPENAI_API_KEY="YOUR_PROVIDER_API_KEY"

# Choose a caller API key for requests to AISIX.
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

Add the chart repository, create a namespace, and store both credentials as Kubernetes Secrets:

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

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

Choose a Resource Source

controlPlane.enabled defaults to true. Each complete values.yaml below sets it to false and supplies resources.yaml from exactly one of three sources. Omitting the source, or setting more than one, causes Helm rendering to fail.

Value	Where the file lives	Use it when
`standalone.resources`	Inline in your values, as a YAML map. The chart renders it into a Secret it manages.	The file is managed together with the release.
`standalone.existingSecret`	A Secret you create, under the key `resources.yaml`.	The file carries literal credentials, or something else owns its lifecycle.
`standalone.existingConfigMap`	A ConfigMap you create, under the key `resources.yaml`.	Every credential in the file is a `${VAR}` reference rather than a literal.

Each installation example starts one gateway replica because rate-limit counters use per-replica memory by default. Configure shared Redis before increasing the replica count.

The chart renders standalone.resources into a Secret rather than a ConfigMap because provider keys are credentials. Credentials still do not have to sit in your values file: a ${VAR} reference is resolved from the container's environment when the file loads, so supply the value through extraEnvVars instead. See Environment Interpolation.

Choose one option below. The Secret and ConfigMap options begin with the same file-preparation step. Each option provides a complete values.yaml, then continues at Install the Gateway.

Use Inline Resources

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

values.yaml

replicaCount: 1

image:
  repository: ghcr.io/api7/aisix
  tag: dev

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

Inline resources do not exist as a separate file to validate. Before installing, render the chart-managed Secret and extract the exact resource document assembled from values.yaml:

helm template aisix api7/aisix --namespace aisix \
  -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 that rendered document with the credentials it references:

docker run --rm -v "$(pwd):/work:ro" \
  -e OPENAI_API_KEY -e CALLER_API_KEY \
  --entrypoint /usr/local/bin/aisix ghcr.io/api7/aisix:1.5.0 \
  validate --resources /work/rendered-resources.yaml

Prepare a Resources File

The Secret and ConfigMap options both start with a local file. Create resources.yaml with the Open-Source AISIX Gateway Quickstart and Resources File Reference. Keep the ${OPENAI_API_KEY} and key_env: CALLER_API_KEY references from the quickstart.

Validate the file with the same environment variables that the gateway will receive. The validate subcommand parses the file without binding a listener:

docker run --rm -v "$(pwd):/work:ro" \
  -e OPENAI_API_KEY -e CALLER_API_KEY \
  --entrypoint /usr/local/bin/aisix ghcr.io/api7/aisix:1.5.0 \
  validate --resources /work/resources.yaml

Use an Existing Secret

Store the validated file in a Secret:

kubectl -n aisix create secret generic aisix-resources \
  --from-file=resources.yaml=./resources.yaml

Save the following chart values as values.yaml. extraEnvVars makes the credential variables referenced by resources.yaml available to the gateway container:

values.yaml

replicaCount: 1

image:
  repository: ghcr.io/api7/aisix
  tag: dev

controlPlane:
  enabled: false

standalone:
  existingSecret: aisix-resources

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

Use an Existing ConfigMap

Use a ConfigMap only when every credential in the validated resources.yaml file is an environment-variable reference. Create the ConfigMap:

kubectl -n aisix create configmap aisix-resources \
  --from-file=resources.yaml=./resources.yaml

Save the following chart values as values.yaml:

values.yaml

replicaCount: 1

image:
  repository: ghcr.io/api7/aisix
  tag: dev

controlPlane:
  enabled: false

standalone:
  existingConfigMap: aisix-resources

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

Install the Gateway

Install the gateway from values.yaml:

helm install aisix api7/aisix --namespace aisix --version 1.5.0 -f values.yaml

Verify the Deployment

Wait for the gateway Deployment to become available:

kubectl rollout status deployment/aisix --namespace aisix --timeout=5m

In a separate terminal, forward the proxy Service to your workstation:

kubectl -n aisix port-forward service/aisix 3000:80

Back in the original terminal, check readiness and list the models available to the caller key:

export AISIX_PROXY="http://127.0.0.1:3000"

curl -sS "$AISIX_PROXY/readyz"
curl -sS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer $CALLER_API_KEY"

The readiness request should return ok, and the model list should contain gpt-4o-mini. Send a request through the gateway to verify the provider credential and upstream connection:

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"
      }
    ]
  }'

A successful response should contain the assistant message AISIX is ready. This confirms that the gateway loaded the resources and credentials, authenticated the caller, and reached the upstream provider.

What the Chart Configures

The chart mounts the resources file read-only at /etc/aisix/resources/resources.yaml and renders a startup configuration at /etc/aisix/standalone/config.yaml containing only two settings:

resources_file: /etc/aisix/resources/resources.yaml
admin:
  enabled: false

Everything else reaches the gateway as an environment variable, which takes precedence over that file. The chart sets the proxy and metrics listener addresses itself. Supply any other startup configuration field through extraEnvVars as AISIX_<SECTION>__<KEY>. For example, this enables debug logging:

extraEnvVars:
  - name: AISIX_OBSERVABILITY__LOG_LEVEL
    value: debug

The chart also sets enableServiceLinks: false on the gateway pods. Kubernetes would otherwise inject a Docker-style link variable for every Service in the namespace. A Service named aisix or aisix-something produces variables with the AISIX_ prefix that the gateway reads. See Kubernetes Service Links.

Apply a Change to the Resources File

The gateway re-reads resources.yaml on SIGHUP only, and the chart never sends one. A pod rollout is what applies a change.

Inline resources. Edit standalone.resources and run helm upgrade. The pod template carries a checksum of the rendered file, so the change rolls the pods on its own.
An existing Secret or ConfigMap. Editing the object out of band does not roll anything — Kubernetes updates the mounted file in place and nothing tells the gateway. Apply it explicitly:
```
kubectl rollout restart deploy/<release>-aisix -n <namespace>
```

The chart prints the right command for your installation in its post-install notes.

Health Checks

Both probes target the proxy port. /livez answers once the proxy listener is bound. /readyz answers 200 when the instance can serve and 503 while it is draining. Against a file source, the listener binds as soon as the file parses, so the gateway does not wait on a configuration fetch. See Health Checks.

Expose, Scale, and Operate

Service exposure, autoscaling, Redis rate-limit counters, pod disruption budgets, termination, and draining do not depend on how the gateway receives resources. Deploy AISIX Gateways on Kubernetes covers these shared Kubernetes operations.

Configure a shared Redis backend before running more than one replica. Rate-limit counters are per-replica by default, so N replicas enforce N times every configured limit.

The listeners values work the same way here. An open-source gateway can serve HTTPS and plain HTTP side by side; see Serve HTTPS and Plain HTTP Together.

To see every value the chart accepts:

helm show values api7/aisix --version 1.5.0

The chart source and package are published in the aisix-1.5.0 Helm chart release.

Enable the Read-Only Admin API

The chart leaves the admin API unbound and does not publish an admin Service. Against a file source, the API is read-only. If you need temporary operational access, keep the listener on pod loopback and store its key in a Secret:

# Choose an admin API key.
export AISIX_ADMIN_KEY="YOUR_ADMIN_API_KEY"

kubectl -n aisix create secret generic aisix-admin-keys \
  --from-literal=admin-key="$AISIX_ADMIN_KEY"

Add the following entries to the existing extraEnvVars list in values.yaml. Do not create a second top-level extraEnvVars key:

values.yaml (admin API settings)

extraEnvVars:
  - name: AISIX_ADMIN__ENABLED
    value: "true"
  - name: AISIX_ADMIN__ADDR
    value: "127.0.0.1:9180"
  - name: AISIX_ADMIN__ADMIN_KEYS
    valueFrom:
      secretKeyRef:
        name: aisix-admin-keys
        key: admin-key

Apply the values, then forward the listener when you need it:

helm upgrade aisix api7/aisix --namespace aisix -f values.yaml
kubectl rollout status deployment/aisix --namespace aisix --timeout=5m
kubectl -n aisix port-forward deployment/aisix 9180:9180

Migrate to AISIX Cloud

The open-source gateway does not include the AISIX Cloud dashboard, organizations and environments, centralized usage and cost reporting, budgets, or per-environment configuration delivery. Export logs and metrics to systems you operate instead; see Exporters.

Deploy a gateway through AISIX Cloud and issue its gateway certificate from the control plane. Resources are not carried over; recreate them in AISIX Cloud as described in Plan a Migration.