# Deploy AISIX OSS on Kubernetes

The `api7/aisix` Helm chart deploys AISIX OSS 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](https://docs.api7.ai/ai-gateway/reference/resources-file.md).

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 connected to AISIX Enterprise or AISIX Cloud, follow the [control-plane-connected installation path](https://docs.api7.ai/ai-gateway/cloud/kubernetes.md). For an OpenShift or OKD deployment, follow [Deploy AISIX OSS on OpenShift or OKD](https://docs.api7.ai/ai-gateway/deployment/aisix-oss-on-openshift-okd.md) instead.

## Prerequisites[​](#prerequisites "Direct link to 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[​](#prepare-the-cluster-and-credentials "Direct link to 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-dp

kubectl -n aisix-dp create secret generic openai-credentials \

  --from-literal=api-key="$OPENAI_API_KEY"

kubectl -n aisix-dp create secret generic aisix-caller-keys \

  --from-literal=my-caller="$CALLER_API_KEY"
```

## Choose a Resource Source[​](#choose-a-resource-source "Direct link to 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](https://docs.api7.ai/ai-gateway/reference/resources-file.md#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 [Deploy the Gateway](#deploy-the-gateway).

### Use Inline Resources[​](#use-inline-resources "Direct link to 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: "1.10.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
```

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-dp api7/aisix --namespace aisix-dp --version 1.10.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 that rendered document with the credentials it references:

```
docker run --rm -i \

  -e OPENAI_API_KEY -e CALLER_API_KEY \

  --entrypoint /bin/sh ghcr.io/api7/aisix:1.10.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 changing its host permissions or SELinux label.

### Prepare a Resources File[​](#prepare-a-resources-file "Direct link to Prepare a Resources File")

The Secret and ConfigMap options both start with a local file. Follow [Get Started with AISIX OSS](https://docs.api7.ai/ai-gateway/getting-started/gateway-quickstart.md) to create a working `resources.yaml`, and consult the [Resources File Reference](https://docs.api7.ai/ai-gateway/reference/resources-file.md) for its full schema. Keep the `${OPENAI_API_KEY}` and `key_env: CALLER_API_KEY` references from the getting-started guide.

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

  -e OPENAI_API_KEY -e CALLER_API_KEY \

  --entrypoint /bin/sh ghcr.io/api7/aisix:1.10.0 \

  -c 'umask 077; cat > /tmp/resources.yaml && exec /usr/local/bin/aisix validate --resources /tmp/resources.yaml' \

  < resources.yaml
```

Streaming the file avoids changing its host permissions or SELinux label.

### Use an Existing Secret[​](#use-an-existing-secret "Direct link to Use an Existing Secret")

Store the validated file in a Secret:

```
kubectl -n aisix-dp create secret generic aisix-resources-file \

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



controlPlane:

  enabled: false



standalone:

  existingSecret: aisix-resources-file



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-an-existing-configmap "Direct link to 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-dp create configmap aisix-resources-file \

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



controlPlane:

  enabled: false



standalone:

  existingConfigMap: aisix-resources-file



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

## Deploy the Gateway[​](#deploy-the-gateway "Direct link to Deploy the Gateway")

Install the gateway from `values.yaml`:

```
helm install aisix-dp api7/aisix --namespace aisix-dp --version 1.10.0 -f values.yaml
```

## Verify the Deployment[​](#verify-the-deployment "Direct link to Verify the Deployment")

Wait for the gateway Deployment to become available:

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

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

```
kubectl -n aisix-dp port-forward service/aisix-dp 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[​](#what-the-chart-configures "Direct link to What the Chart Configures")

The chart mounts the resources file read-only at `/etc/aisix/resources/resources.yaml`. It renders the gateway's [startup configuration](https://docs.api7.ai/ai-gateway/reference/configuration-files.md) from the `config` value into a ConfigMap, mounted read-only at `/etc/aisix/chart/config.yaml`, and fills in the keys it owns for standalone mode:

```
resources_file: /etc/aisix/resources/resources.yaml

admin:

  enabled: false
```

With `admin.enabled: true`, the chart renders `admin.enabled: true` and an `admin.addr` that binds `containerPorts.admin` instead. See [Enable the Admin API](#enable-the-admin-api).

The chart also sets the proxy and metrics listener addresses and the rate-limit backend from its own values. Set any other startup configuration field under `config`, with the same section and key names as the configuration file. For example, this enables debug logging:

```
config:

  observability:

    log_level: debug
```

A change to `config` rolls the pods on `helm upgrade`. Settings that hold a credential, such as a Redis password, are read from a Secret through `configSecrets` instead. See [Set Any Other Gateway Configuration](https://docs.api7.ai/ai-gateway/cloud/kubernetes.md#set-any-other-gateway-configuration) for the keys the chart refuses under `config` and for `configSecrets`.

`extraEnvVars` is for system-level environment variables and for the variables the resources file references. Overriding a variable the chart sets itself is only a compatibility path for existing deployments; see [Set Any Other Gateway Configuration](https://docs.api7.ai/ai-gateway/cloud/kubernetes.md#set-any-other-gateway-configuration).

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](https://docs.api7.ai/ai-gateway/reference/environment-variables.md#kubernetes-service-links).

### Apply a Change to the Resources File[​](#apply-a-change-to-the-resources-file "Direct link to 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 deployment/aisix-dp -n aisix-dp
  ```

For the release and namespace used in this guide, the Deployment is `aisix-dp`. With another release name, namespace, or name override, use the Deployment printed in the chart's post-install notes. The chart does not always append `-aisix` to the release name.

## Health Checks[​](#health-checks "Direct link to 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](https://docs.api7.ai/ai-gateway/deployment/health-checks.md).

## Expose, Scale, and Operate[​](#expose-scale-and-operate "Direct link to 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. The [Kubernetes deployment and operations guide](https://docs.api7.ai/ai-gateway/cloud/kubernetes.md) covers these shared tasks.

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. The gateway can serve HTTPS and plain HTTP side by side; see [Serve HTTPS and Plain HTTP Together](https://docs.api7.ai/ai-gateway/cloud/kubernetes.md#serve-https-and-plain-http-together).

To see every value the chart accepts:

```
helm show values api7/aisix --version 1.10.0
```

The chart source and package are published in the [`aisix-1.10.0` Helm chart release](https://github.com/api7/api7-helm-chart/releases/tag/aisix-1.10.0).

## Enable the Admin API[​](#enable-the-admin-api "Direct link to Enable the Admin API")

The chart leaves the gateway's Admin API off by default. Set `admin.enabled: true` to bind it on `containerPorts.admin` (default `3001`) and publish it on its own ClusterIP Service, `<fullname>-admin`, which is `aisix-dp-admin` for a release named `aisix-dp`. The proxy Service never carries it.

Against the resources file, `/admin/v1/*` is read-only: it lists and gets what the gateway loaded, including model status. Every request there needs one of the admin keys, sent as `Authorization: Bearer <key>` or `x-api-key: <key>`.

The same listener also serves the Playground, `POST /playground/chat/completions`. It authenticates with a caller API key, exactly like the proxy, and sends real requests to your upstream providers. Read-only applies to `/admin/v1/*` only, so treat access to the admin Service as access to the proxy.

Store the admin keys in a Secret you manage, so they stay out of your values file:

```
# Choose an admin API key.

export AISIX_ADMIN_KEY="YOUR_ADMIN_API_KEY"



kubectl -n aisix-dp create secret generic aisix-admin-keys \

  --from-literal=admin-keys="$AISIX_ADMIN_KEY"
```

Add the following to `values.yaml`:

values.yaml (Admin API)

```
admin:

  enabled: true

  existingSecret: aisix-admin-keys
```

| Value                       | Default      | Description                                                                                    |
| --------------------------- | ------------ | ---------------------------------------------------------------------------------------------- |
| `admin.enabled`             | `false`      | Bind the Admin API and create the admin Service.                                               |
| `admin.keys`                | `[]`         | Admin keys, rendered into a chart-managed Secret.                                              |
| `admin.existingSecret`      | `""`         | Read the admin keys from an existing Secret instead.                                           |
| `admin.existingSecretKey`   | `admin-keys` | Key in `admin.existingSecret` that holds the admin keys. Several keys are separated by commas. |
| `containerPorts.admin`      | `3001`       | Port the Admin API binds inside the container.                                                 |
| `admin.service.port`        | `3001`       | Port of the admin Service.                                                                     |
| `admin.service.annotations` | `{}`         | Extra annotations for the admin Service.                                                       |

Either way, the keys reach the gateway as the `AISIX_ADMIN__ADMIN_KEYS` environment variable from the Secret and are never written to the configuration ConfigMap. The gateway reads that variable as a comma-separated list, so an admin key cannot contain a comma.

The render fails if `admin.enabled` is `true` without keys from `admin.keys` or `admin.existingSecret`. It also fails if `controlPlane.enabled` is `true`: the Admin API is available in standalone mode only, because a gateway connected to a control plane has no Admin API.

Apply the values, then forward the admin Service when you need it:

```
helm upgrade aisix-dp api7/aisix --namespace aisix-dp --version 1.10.0 -f values.yaml

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

kubectl -n aisix-dp port-forward svc/aisix-dp-admin 3001:3001
```

In another terminal, list the models the gateway loaded:

```
curl "http://127.0.0.1:3001/admin/v1/models" \

  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"
```

A release that already binds the Admin API through `AISIX_ADMIN__*` variables in `extraEnvVars` keeps working, because the environment overrides the configuration file. Moving those settings to `admin` also gives the API its Service.

## Migrate to AISIX Enterprise or AISIX Cloud[​](#migrate-to-aisix-enterprise-or-aisix-cloud "Direct link to Migrate to AISIX Enterprise or AISIX Cloud")

AISIX OSS does not include a control-plane 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](https://docs.api7.ai/ai-gateway/observability/exporters.md).

Deploy a gateway through AISIX Enterprise or AISIX Cloud and issue its gateway certificate from the control plane. Recreate your provider keys, models, caller API keys, and policies in the selected product.
