设置 Ingress Controller 和网关

在 Kubernetes 上设置 Ingress Controller 和网关，然后准备创建第一条路由。API7 Dashboard 会生成 API7 的部署配置；下文的 APISIX 路径则提供可直接运行的 Helm 安装步骤，适合本地学习与测试。

设置 API7 Ingress Controller

API7 Dashboard 会为 API7 Ingress Controller 和网关生成部署命令及连接配置。请按照为网关组生成的步骤操作，然后在 Kubernetes 和 Dashboard 中验证部署。

前置条件

• 可以访问 API7 Dashboard，并有权创建 Ingress Controller 网关组、获取其部署配置和添加网关实例。本地评估可从 API7 网关快速入门开始。
• 运行 Kubernetes 1.31 或更高版本、且受 Dashboard 所选 Controller release 支持的 Kubernetes 集群。
• 安装 Helm 3.8 或更高版本和 kubectl，并将二者配置为使用目标集群。
• 具有安装 CRD、集群级 RBAC 资源、Controller 与网关工作负载的 Kubernetes 权限。

准备部署

在 Gateway Settings → Deployment 中，将 Admin API Address 配置为 Controller Pod 可访问的 API7 控制面地址；将 DP Manager Address 配置为网关 Pod 可访问的地址。本地快速入门中使用的 localhost 等地址在 Kubernetes Pod 内指向 Pod 自身，因此这里必须使用 Pod 可以访问的地址。

为部署选择命名空间，并在生成的 Controller、GatewayProxy 和网关命令中保持一致。Controller 安装命令包含 --create-namespace，因此命名空间不存在时会自动创建。请先运行该命令，再应用生成的 manifest。

后续指南中的示例使用 APISIX 本地评估环境的名称：命名空间为 aic；Gateway、GatewayClass 和 IngressClass 为 apisix；GatewayProxy 为 apisix-config；网关 Service 为 apisix-gateway；Helm release 为 apisix。如果使用 API7，请逐一替换为 Dashboard 生成的对应名称。不要修改 apisix.apache.org 等共用 Kubernetes API 标识符。

部署 Controller 和网关

核对生成的 Controller 版本

API7 Dashboard 与 API7 Ingress Controller 独立发布，因此生成的命令可能选择与本文档不同的 Controller release。运行命令前，请同时将 --version 和 deployment.image.tag 与 API7 部署版本进行比较。

1. 在 Gateway Groups 中添加一个类型为 Ingress Controller 的网关组。
2. 在 Deployment Steps 中输入 Controller 的命名空间和 release 名称，生成安装脚本，并在目标集群上运行。
3. 在同一命名空间中生成并应用 GatewayProxy 配置。若要部署生成的 GatewayClass 和 Gateway，请选择 Gateway API；若要使用 Ingress 或 APISIX CRD 并部署 IngressClass，请选择 Ingress。保留生成的连接设置和资源名称。
4. 在该网关组的 Gateway Instances 中添加网关实例，选择 Kubernetes 部署方式，然后运行生成的部署命令。

如果保留生成的命令和连接配置以便复现或排障，请安全存储，因为其中包含凭据。

验证安装

检查所选命名空间中的 Controller 和网关 Deployment：

kubectl get deployments,pods,services -n <namespace>
kubectl rollout status deployment/<ingress-controller-deployment> -n <namespace>
kubectl rollout status deployment/<gateway-deployment> -n <namespace>

两个 Deployment 都应完成滚动发布，且 Pod 均应就绪。请使用第一条命令返回的 Deployment 名称，不要假设 Helm release 名称就是 Deployment 名称。

对于 Gateway API，检查生成的连接资源和 Gateway 资源：

kubectl get gatewayproxy,gateway -n <namespace>
kubectl get gatewayclass <gatewayclass-name>

对于 Ingress 或 APISIX CRD，检查 GatewayProxy 和生成的 IngressClass：

kubectl get gatewayproxy -n <namespace>
kubectl get ingressclass <ingressclass-name>

在网关组的 Gateway Instances 中，确认网关实例显示 Healthy 状态。Pod 就绪只表明工作负载正在运行，并不能证明路由配置已完成同步。继续阅读代理请求，通过网关发送请求以验证完整流量路径；请在该教程中使用生成的命名空间以及 Gateway 或 IngressClass 名称。

如果资源存在但流量无法到达后端，请参阅排查 Manifest 转换与同步问题。

设置 APISIX Ingress Controller

以下各节将使用 Helm 在 Kubernetes 集群中安装 APISIX Ingress Controller 和 APISIX 网关，用于本地评估。

前置条件

• 安装 Docker，作为 kind 的依赖。
• 安装 kind。安装 APISIX 时，请创建本地 Kubernetes 1.31+ 集群，或使用满足该要求的现有集群。
• 安装 Helm（3.8+）。
• 安装 kubectl。

创建命名空间

创建一个名为 aic 的新命名空间（也可以使用你自定义的名称）：

kubectl create namespace aic

可选地，将该命名空间设置为当前上下文的默认命名空间：

kubectl config set-context --current --namespace=aic

安装 APISIX 和 APISIX Ingress Controller

本节将在 Kubernetes 集群中以独立模式安装 APISIX 和 APISIX Ingress Controller。

部署模式

相比基于 etcd 的传统部署，更推荐独立模式，因为它可以避免在 Kubernetes 内同时运行 APISIX 和 etcd 时可能出现的稳定性问题。

添加 APISIX Chart 仓库并更新元数据：

helm repo add apisix https://apache.github.io/apisix-helm-chart
helm repo update

确认 APISIX umbrella Chart 2.18.0 选择了兼容的 Ingress Controller Chart：

helm show chart apisix/apisix --version 2.18.0 \
  | grep -A 4 'name: apisix-ingress-controller'

依赖项应显示 version: 1.3.0 或更高的兼容版本。不要只在旧 umbrella Chart 上覆盖 Controller 镜像，否则 CRD、RBAC 和 Webhook 配置不会随之更新。

安装 APISIX 和 APISIX Ingress Controller：

helm install apisix \
  --version 2.18.0 \
  --namespace aic \
  --create-namespace \
  --set apisix.deployment.role=traditional \
  --set apisix.deployment.role_traditional.config_provider=yaml \
  --set etcd.enabled=false \
  --set ingress-controller.enabled=true \
  --set ingress-controller.config.provider.type=apisix-standalone \
  --set ingress-controller.apisix.adminService.namespace=aic \
  --set ingress-controller.gatewayProxy.createDefault=true \
  --set ingress-controller.webhook.enabled=true \
  --set ingress-controller.config.listenerPortMatchMode=off \
  apisix/apisix

❶&❷ 以 API 驱动的独立模式启动 APISIX。

❸ 禁用 etcd 部署。

❹ 安装 APISIX Ingress Controller（随 APISIX 一起安装）。

❺ 将控制器配置为独立模式，使配置直接推送到网关，而不是通过 etcd。

➏ 配置 APISIX Admin Service 所在命名空间，控制器会连接该服务并推送配置。

➐ 自动创建 GatewayProxy 资源，用于定义与 APISIX 的连接信息。

该命令还会启用准入 Webhook，使无效的 Ingress Controller 资源在协调前就被拒绝。

将 listenerPortMatchMode 设为 off 可避免 Kubernetes Service 的 80、443 等端口映射到 APISIX 容器的 9080、9443 端口时出现路由不匹配。其他匹配模式参见配置文件。

查看 GatewayProxy 资源

查询 GatewayProxy 名称：

kubectl get gatewayproxy -n aic

你应看到 GatewayProxy 名称：

NAME            AGE
apisix-config   12s

以 YAML 格式查看 GatewayProxy 配置：

kubectl get gatewayproxy apisix-config -n aic -o yaml

输出应类似如下内容：

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  annotations:
    meta.helm.sh/release-name: apisix
    meta.helm.sh/release-namespace: aic
  creationTimestamp: "2025-11-25T10:07:40Z"
  generation: 1
  labels:
    app.kubernetes.io/managed-by: Helm
  name: apisix-config
  namespace: aic
  resourceVersion: "3073"
  uid: 6b0a30db-530c-4f14-b127-024d0507b18e
spec:
  provider:
    controlPlane:
      auth:
        adminKey:
          value: edd1c9f034335f136f87ad84b625c8f1
        type: AdminKey
      service:
        name: apisix-admin
        port: 9180
    type: ControlPlane

验证安装

检查 Pod 状态，确认 APISIX Ingress Controller 已安装并运行：

kubectl get pods -n aic

APISIX 网关和 Ingress Controller Pod 都应显示 Running 状态：

NAME                                        READY   STATUS    RESTARTS   AGE
apisix-bffb459b8-rcqz7                      1/1     Running   0          2m53s
apisix-ingress-controller-ff66c9585-wlxfh   2/2     Running   0          2m53s

也可以检查 Service 状态：

kubectl get services -n aic

输出应类似如下内容：

NAME                                    TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
apisix-admin                            ClusterIP   10.96.61.223    <none>        9180/TCP       2m54s
apisix-gateway                          NodePort    10.96.108.211   <none>        80:30834/TCP   2m54s
apisix-ingress-controller               ClusterIP   10.96.249.157   <none>        8080/TCP       2m54s
apisix-ingress-controller-webhook-svc   ClusterIP   10.96.161.96    <none>        443/TCP        2m54s

如需检查已安装的 APISIX 版本，先将网关 Service 端口转发到本地：

kubectl port-forward svc/apisix-gateway -n aic 9080:80 &

然后向网关发送请求：

curl -sI "http://127.0.0.1:9080" | grep Server

响应应包含 APISIX 版本：

Server: APISIX/3.19.0

信息

如果你希望在 kind 集群中使用负载均衡器暴露服务，而不是端口转发，请参阅 kind 负载均衡器文档。

定义控制器和网关

如果计划使用 Gateway API，请查看 Gateway API 选项卡；如果计划使用 Ingress 或 APISIX CRD，请查看 Ingress 选项卡。

Gateway API

APISIX Chart 会安装 Gateway API 1.6.0 CRD。请验证 API Server 提供本文指南使用的 v1 L4 Route API：

kubectl get crd \
  tcproutes.gateway.networking.k8s.io \
  udproutes.gateway.networking.k8s.io \
  tlsroutes.gateway.networking.k8s.io \
  -o jsonpath='{range .items[*]}{.metadata.name}{": "}{range .spec.versions[?(@.served==true)]}{.name}{" "}{end}{"\n"}{end}'

每行都应包含 v1。如果平台单独管理 Gateway API CRD，请先通过相应所有者安装 Gateway API 1.6.0 standard bundle，再安装 Controller。本教程使用的 APISIX umbrella Chart 将 Gateway API 和 APISIX 两组 CRD 都置于静态 CRD 生命周期中，因此应使用 --skip-crds，并由平台管理这两组 CRD。

如果使用 Gateway API，请定义 GatewayClass 和 Gateway 资源：

gatewayclass-gateway.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: apisix
spec:
  controllerName: apisix.apache.org/apisix-ingress-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  namespace: aic
  name: apisix
spec:
  gatewayClassName: apisix
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  infrastructure:
    parametersRef:
      group: apisix.apache.org
      kind: GatewayProxy
      name: apisix-config

port 声明 Gateway API 监听器；它不会打开对应的数据面端口。本快速入门禁用了监听器端口匹配，因此当 Service 端口 80 映射到 APISIX 容器端口 9080 时，路由仍可匹配。

将配置应用到集群：

kubectl apply -f gatewayclass-gateway.yaml

Ingress

如果使用 Ingress 或 APISIX CRD，安装过程中已应用以下 IngressClass 资源。你无需额外配置即可继续。

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: apisix
spec:
  controller: apisix.apache.org/apisix-ingress-controller
  parameters:
    apiGroup: apisix.apache.org
    kind: GatewayProxy
    name: apisix-config
    namespace: aic
    scope: Namespace

如需了解这些参数以及如何按需调整，请参阅定义 Ingress Controller 和网关。

测试路由

继续阅读代理请求，创建一条指向同一集群上游服务的路由。不同产品的 Controller 版本可能会在不同时间发布，因此请留意后续指南中特定于产品的可用性说明。

清理 APISIX 本地评估环境

此清理流程仅适用于本指南安装的 APISIX 本地评估环境。不要用它移除 API7 Dashboard 生成的部署。

先删除评估环境中的路由和其他用户创建的资源。如果使用 Gateway API，请在 Controller 仍在运行时删除评估用 Gateway 和 GatewayClass apisix，并等待 GatewayClass 删除完成。最后，从 aic 命名空间卸载 apisix Helm release。Helm 会移除 Chart 管理的 Webhook Secret；只有在其他 Secret 被明确识别为评估环境专用且不与其他环境共享时，才可删除。