# 在 Kubernetes 上部署 AISIX OSS

`api7/aisix` Helm Chart 用于在 Kubernetes 上部署开源 AISIX 网关。将 `controlPlane.enabled` 设为 `false`，无需控制面或网关证书包即可运行网关，并从声明式 [`resources.yaml` 文件](https://docs.apiseven.com/ai-gateway/reference/resources-file.md)加载资源。

服务提供方密钥、模型、调用方 API Key、安全护栏、MCP 服务器和限流策略均来自该文件；Kubernetes 则管理网关 Pod、Service、健康检查和滚动更新。要部署连接 AISIX Enterprise 或 AISIX Cloud 的网关，请按照[连接控制面的安装流程](https://docs.apiseven.com/ai-gateway/cloud/kubernetes.md)操作。在 OpenShift 或 OKD 上部署时，请改用[在 OpenShift 或 OKD 上部署 AISIX OSS](https://docs.apiseven.com/ai-gateway/deployment/aisix-oss-on-openshift-okd.md)。

## 前置条件[​](#prerequisites "前置条件的直接链接")

* 一个已配置 `kubectl` 访问权限的 Kubernetes 集群。
* Helm 3 和 Docker。
* 一个上游服务提供方密钥和一个调用方 API Key。示例使用 OpenAI 和模型别名 `gpt-4o-mini`。

## 准备集群和凭据[​](#prepare-the-cluster-and-credentials "准备集群和凭据的直接链接")

导出示例使用的服务提供方凭据和调用方凭据：

```
# 替换为你的 OpenAI API Key。

export OPENAI_API_KEY="YOUR_PROVIDER_API_KEY"



# 选择一个调用 AISIX 时使用的 API Key。

export CALLER_API_KEY="YOUR_CALLER_API_KEY"
```

添加 Chart 仓库、创建命名空间，并将两个凭据存储为 Kubernetes Secret：

```
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 "选择资源来源的直接链接")

`controlPlane.enabled` 默认为 `true`。下方每个完整的 `values.yaml` 都将其设为 `false`，并从三种来源中的一种提供 `resources.yaml`。省略来源或同时设置多个来源都会导致 Helm 渲染失败。

| 配置值                         | 文件位置                                                            | 适用场景                                         |
| ------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------ |
| `standalone.resources`         | 作为 YAML Map 内联在 values 中。Chart 将其渲染到自己管理的 Secret。 | 文件与 Release 一同管理。                        |
| `standalone.existingSecret`    | 位于你创建的 Secret 中，键名为 `resources.yaml`。                   | 文件包含明文凭据，或由其他系统管理其生命周期。   |
| `standalone.existingConfigMap` | 位于你创建的 ConfigMap 中，键名为 `resources.yaml`。                | 文件中的每个凭据都是 `${VAR}` 引用，而非明文值。 |

每个安装示例都只启动一个网关副本，因为限流计数器默认使用每个副本自己的内存。增加副本数前，请先配置共享 Redis。

Chart 会将 `standalone.resources` 渲染到 Secret 而非 ConfigMap，因为服务提供方密钥属于凭据。凭据仍无需直接写入 values 文件：文件加载时会从容器环境解析 `${VAR}` 引用，因此可通过 `extraEnvVars` 提供取值。参见[环境变量插值](https://docs.apiseven.com/ai-gateway/reference/resources-file.md#environment-interpolation)。

选择下方一种方式。Secret 和 ConfigMap 方式都从相同的文件准备步骤开始。每种方式都会提供完整的 `values.yaml`，随后继续执行[安装网关](#deploy-the-gateway)。

### 使用内联资源[​](#use-inline-resources "使用内联资源的直接链接")

将以下 Chart 配置保存为 `values.yaml`。Chart 会把内联资源文档存储到 Secret，而两个凭据值仍保存在前面创建的独立 Secret 中：

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

内联资源并不存在可单独验证的文件。安装前，渲染由 Chart 管理的 Secret，并提取从 `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
```

使用文档引用的凭据验证渲染结果：

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

流式传入文档可避免修改其宿主机权限或 SELinux 标签。

### 准备资源文件[​](#prepare-a-resources-file "准备资源文件的直接链接")

Secret 和 ConfigMap 方式都从本地文件开始。按照[开源 AISIX 网关快速入门](https://docs.apiseven.com/ai-gateway/getting-started/gateway-quickstart.md)创建可用的 `resources.yaml`；完整 schema 请参阅[资源文件参考](https://docs.apiseven.com/ai-gateway/reference/resources-file.md)。保留快速入门中的 `${OPENAI_API_KEY}` 和 `key_env: CALLER_API_KEY` 引用。

使用与网关将接收的环境变量相同的环境变量验证文件。`validate` 子命令会解析文件，但不会绑定监听器：

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

流式传入文件可避免修改其宿主机权限或 SELinux 标签。

### 使用现有 Secret[​](#use-an-existing-secret "使用现有 Secret的直接链接")

将经过验证的文件存入 Secret：

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

  --from-file=resources.yaml=./resources.yaml
```

将以下 Chart 配置保存为 `values.yaml`。`extraEnvVars` 会让 `resources.yaml` 引用的凭据变量在网关容器中可用：

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

### 使用现有 ConfigMap[​](#use-an-existing-configmap "使用现有 ConfigMap的直接链接")

只有经过验证的 `resources.yaml` 文件中的每个凭据都是环境变量引用时，才使用 ConfigMap。创建 ConfigMap：

```
kubectl -n aisix-dp create configmap aisix-resources-file \

  --from-file=resources.yaml=./resources.yaml
```

将以下 Chart 配置保存为 `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 "部署网关的直接链接")

从 `values.yaml` 安装网关：

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

## 验证部署[​](#verify-the-deployment "验证部署的直接链接")

等待网关 Deployment 可用：

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

在另一个终端中，将代理 Service 端口转发到工作站：

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

回到原来的终端，检查就绪状态，并列出该调用方密钥可用的模型：

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

就绪请求应返回 `ok`，模型列表应包含 `gpt-4o-mini`。通过网关发送请求，验证服务提供方凭据和上游连接：

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

      }

    ]

  }'
```

成功响应应包含助手消息 `AISIX is ready`。这表示网关已加载资源和凭据、验证调用方身份，并能够访问上游服务提供方。

## Chart 配置内容[​](#what-the-chart-configures "Chart 配置内容的直接链接")

Chart 会将资源文件以只读方式挂载到 `/etc/aisix/resources/resources.yaml`。它会根据 `config` value 把网关的[启动配置](https://docs.apiseven.com/ai-gateway/reference/configuration-files.md)渲染到 ConfigMap 中，以只读方式挂载到 `/etc/aisix/chart/config.yaml`，并为独立模式填入由它负责的键：

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

admin:

  enabled: false
```

设置 `admin.enabled: true` 后，Chart 会改为渲染 `admin.enabled: true`，以及绑定 `containerPorts.admin` 的 `admin.addr`。参见[启用 Admin API](#enable-the-admin-api)。

Chart 还会根据自身的 value 设置代理和指标监听器地址以及限流后端。其他启动配置字段请写在 `config` 下，节名和键名与配置文件相同。例如，以下配置会启用调试日志：

```
config:

  observability:

    log_level: debug
```

修改 `config` 后，`helm upgrade` 会滚动更新 Pod。包含凭据的设置（例如 Redis 密码）请改为通过 `configSecrets` 从 Secret 读取。Chart 在 `config` 下拒绝的键以及 `configSecrets` 的用法，请参阅[设置其他网关配置](https://docs.apiseven.com/ai-gateway/cloud/kubernetes.md#set-any-other-gateway-configuration)。

`extraEnvVars` 用于系统级环境变量以及资源文件引用的变量。覆盖 Chart 自身设置的变量只是为现有部署保留的兼容途径，参见[设置其他网关配置](https://docs.apiseven.com/ai-gateway/cloud/kubernetes.md#set-any-other-gateway-configuration)。

Chart 还会在网关 Pod 上设置 `enableServiceLinks: false`。否则 Kubernetes 会为命名空间中的每个 Service 注入 Docker 风格的链接变量。名为 `aisix` 或 `aisix-something` 的 Service 会生成带 `AISIX_` 前缀的变量，而网关会读取这些变量。参见 [Kubernetes Service Link](https://docs.apiseven.com/ai-gateway/reference/environment-variables.md#kubernetes-service-links)。

### 应用资源文件变更[​](#apply-a-change-to-the-resources-file "应用资源文件变更的直接链接")

网关只会在收到 `SIGHUP` 时重新读取 `resources.yaml`，而 Chart 不会发送该信号。必须滚动更新 Pod 才会应用变更。

* **内联资源。** 编辑 `standalone.resources` 并运行 `helm upgrade`。Pod 模板带有渲染文件的校验和，因此变更会自动滚动更新 Pod。

* **现有 Secret 或 ConfigMap。** 在 Helm 之外编辑对象不会触发滚动更新：Kubernetes 会就地更新挂载文件，但不会通知网关。请显式应用：

  ```
  kubectl rollout restart deployment/aisix-dp -n aisix-dp
  ```

对于本指南使用的 Release 和 Namespace，Deployment 名称为 `aisix-dp`。使用其他 Release 名、Namespace 或名称覆盖时，请使用 Chart 安装后说明中输出的 Deployment。Chart 并不总会在 Release 名后追加 `-aisix`。

## 健康检查[​](#health-checks "健康检查的直接链接")

两个探针都指向代理端口。代理监听器绑定后，`/livez` 即可响应。当实例能够提供服务时，`/readyz` 返回 `200`；实例排空期间返回 `503`。使用文件来源时，只要文件解析成功就会绑定监听器，网关无需等待配置拉取。参见[健康检查](https://docs.apiseven.com/ai-gateway/deployment/health-checks.md)。

## 暴露、扩缩容和运维[​](#expose-scale-and-operate "暴露、扩缩容和运维的直接链接")

Service 暴露、自动扩缩容、Redis 限流计数器、Pod 中断预算、终止和排空不依赖网关获取资源的方式。[在 Kubernetes 上部署 AISIX 网关](https://docs.apiseven.com/ai-gateway/cloud/kubernetes.md)介绍了这些通用的 Kubernetes 运维操作。

运行多个副本前，请配置共享 Redis 后端。限流计数器默认按副本保存，因此 N 个副本会把每项配置的限制放大为 N 倍。

`listeners` 配置值的用法也相同。开源网关可以同时提供 HTTPS 和纯 HTTP；参见[同时提供 HTTPS 和纯 HTTP](https://docs.apiseven.com/ai-gateway/cloud/kubernetes.md#serve-https-and-plain-http-together)。

查看 Chart 支持的所有配置值：

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

Chart 源码和发布包见 [`aisix-1.10.0` Helm Chart 发布版本](https://github.com/api7/api7-helm-chart/releases/tag/aisix-1.10.0)。

## 启用 Admin API[​](#enable-the-admin-api "启用 Admin API的直接链接")

Chart 默认关闭网关的 Admin API。设置 `admin.enabled: true` 后，Chart 会在 `containerPorts.admin`（默认 `3001`）上绑定 Admin API，并通过单独的 ClusterIP Service `<fullname>-admin` 发布它；release 名为 `aisix-dp` 时，该 Service 名为 `aisix-dp-admin`。代理 Service 永远不会承载它。

针对资源文件，`/admin/v1/*` 是只读的：它列出和获取网关已加载的内容，包括模型状态。对这些路径的每个请求都需要携带一个 Admin Key，形式为 `Authorization: Bearer <key>` 或 `x-api-key: <key>`。

同一个监听器还提供 Playground，即 `POST /playground/chat/completions`。它与代理一样使用调用方 API Key 认证，并会向你的上游提供商发送真实请求。只读仅适用于 `/admin/v1/*`，因此请把 Admin Service 的访问权限视同代理的访问权限。

将 Admin Key 存入你自己管理的 Secret，避免写进 values 文件：

```
# 选择一个 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"
```

在 `values.yaml` 中添加以下内容：

values.yaml（Admin API）

```
admin:

  enabled: true

  existingSecret: aisix-admin-keys
```

| Value                       | 默认值       | 说明                                                                |
| --------------------------- | ------------ | ------------------------------------------------------------------- |
| `admin.enabled`             | `false`      | 绑定 Admin API 并创建 Admin Service。                               |
| `admin.keys`                | `[]`         | Admin Key，渲染到由 Chart 管理的 Secret 中。                        |
| `admin.existingSecret`      | `""`         | 改为从现有 Secret 读取 Admin Key。                                  |
| `admin.existingSecretKey`   | `admin-keys` | `admin.existingSecret` 中保存 Admin Key 的键。多个 Key 用逗号分隔。 |
| `containerPorts.admin`      | `3001`       | Admin API 在容器内绑定的端口。                                      |
| `admin.service.port`        | `3001`       | Admin Service 的端口。                                              |
| `admin.service.annotations` | `{}`         | Admin Service 的额外注解。                                          |

无论采用哪种方式，Admin Key 都会以 `AISIX_ADMIN__ADMIN_KEYS` 环境变量的形式从 Secret 传给网关，永远不会写入配置 ConfigMap。网关按逗号分隔读取该变量，因此 Admin Key 中不能包含逗号。

如果 `admin.enabled` 为 `true`，但 `admin.keys` 和 `admin.existingSecret` 都没有提供 Key，渲染会失败。如果同时设置了 `controlPlane.enabled: true`，渲染也会失败：Admin API 只适用于独立模式，因为连接到控制面的网关没有 Admin API。

应用 values，然后在需要时转发 Admin Service：

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

在另一个终端中列出网关已加载的模型：

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

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

已经通过 `extraEnvVars` 中的 `AISIX_ADMIN__*` 变量绑定 Admin API 的 release 仍可继续工作，因为环境变量会覆盖配置文件。把这些设置迁移到 `admin` 后，API 还会获得自己的 Service。

[]()

## 迁移到 AISIX Enterprise 或 AISIX Cloud[​](#migrate-to-aisix-enterprise-or-aisix-cloud "迁移到 AISIX Enterprise 或 AISIX Cloud的直接链接")

AISIX OSS 不包含控制面控制台、组织和环境、集中式用量与成本报告、预算或按环境交付配置的功能。请改为将日志和指标导出到自己运维的系统；参见[导出器](https://docs.apiseven.com/ai-gateway/observability/exporters.md)。

通过 AISIX Enterprise 或 AISIX Cloud 部署网关，并由控制面签发网关证书。资源不会自动迁移；请按照[规划迁移](https://docs.apiseven.com/ai-gateway/getting-started/products-and-deployment-options.md#plan-a-migration)在所选产品中重新创建。
