Deploy the Open-Source Gateway on Kubernetes

The api7/aisix Helm chart installs the AISIX gateway in either of two modes. By default it connects to an AISIX Cloud control plane, which is covered in Deploy AISIX Gateways on Kubernetes. This page covers the other mode: controlPlane.enabled: false, which runs the open-source AISIX gateway with no control plane at all.

In standalone mode every resource — provider keys, models, caller API keys, guardrails, MCP servers, rate-limit policies — comes from one declarative resources.yaml file that you supply through the chart. Nothing under controlPlane is read, and no gateway certificate bundle is needed.

Prerequisites

• A Kubernetes cluster with kubectl configured to access it, and Helm 3.
• A resources.yaml file declaring at least one provider key, one model, and one caller API key. Write it with the Open-Source AISIX Gateway Quickstart and the Resources File Reference.

Validate the file before you install it. The validate subcommand parses it without binding a listener:

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

Choose a Resource Source

The chart takes resources.yaml from exactly one of three places. Setting none of them, or more than one, fails the render with a message naming the three keys — it is not resolved by precedence.

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.

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.

Install with Inline Resources

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

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

kubectl create namespace aisix
helm install aisix api7/aisix --namespace aisix -f values.yaml

Install from an Existing Secret

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

helm install aisix api7/aisix --namespace aisix \
  --set controlPlane.enabled=false \
  --set standalone.existingSecret=aisix-resources

Use standalone.existingConfigMap the same way when the file holds no literal credentials.

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

extraEnvVars:
  - name: AISIX_OBSERVABILITY__LOG_LEVEL
    value: debug
  - name: AISIX_CACHE__BACKEND
    value: redis

The chart also sets enableServiceLinks: false on the gateway pods. Kubernetes would otherwise inject a Docker-style link variable into the container for every Service in the namespace, and a Service named aisix or aisix-something produces variables with the AISIX_ prefix 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, and /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 a standalone gateway starts serving immediately rather than waiting on a configuration fetch. See Health Checks.

Expose, Scale, and Operate

Standalone mode changes where resources come from, not how the gateway runs. Service exposure, autoscaling with a HorizontalPodAutoscaler or KEDA, shared rate-limit counters in Redis, pod disruption budgets, and the termination and draining behavior are identical to the control-plane-connected mode and are documented in Deploy AISIX Gateways on Kubernetes.

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, so a standalone gateway can serve an HTTPS port and a plain-HTTP port side by side; see Serve HTTPS and Plain HTTP Together.

To see every value the chart accepts:

helm show values api7/aisix

The chart source is published in the api7/api7-helm-chart repository.

What Is Not Available

Standalone mode has no control plane, so none of the AISIX Cloud surfaces exist: no dashboard, no organizations or environments, no centralized usage and cost reporting, no budgets, and no per-environment configuration delivery. Export logs and metrics to systems you operate instead — see Exporters.

The admin API is left unbound as well. Against a file source it is read-only, and binding it needs admin keys the chart does not manage. Turn it on through extraEnvVars if you want it:

extraEnvVars:
  - name: AISIX_ADMIN__ENABLED
    value: "true"
  - name: AISIX_ADMIN__ADDR
    value: "0.0.0.0:9180"
  - name: AISIX_ADMIN__ADMIN_KEYS
    value: <admin-key>

To move to a managed deployment later, install the chart with controlPlane.enabled at its default and issue a gateway certificate from the control plane. Resources are not carried over — recreate them there, as described in Plan a Migration.