跳到主要内容

设置 Ingress Controller 和网关

本教程侧重于在 Kubernetes 集群中搭建 APISIX Ingress Controller 和 APISIX 网关，适用于本地学习和测试。

API7 企业版用户

如果你使用 API7 企业版，API7 控制台会引导你完成 API7 Ingress Controller 和网关的设置，并生成所需部署脚本。请确保完成以下操作：

  • 创建一个类型为 Ingress Controller 的新网关组。控制台会根据你指定的 namespace 和 name 生成以下部署步骤：
    • 安装 Ingress Controller。
    • 部署 GatewayProxy 配置。如果计划使用 Gateway API，请选择 Gateway API 选项卡；如果计划使用 Ingress 或 APISIX CRD，请选择 Ingress 选项卡。
  • 在 Kubernetes 上部署网关实例。

完成后，可以直接进入下一篇教程，学习如何创建路由，将请求代理到同一集群中的上游服务。

前提条件​

  • 安装 Docker，作为 kind 的依赖。
  • 安装 kind 并创建本地集群，或使用任意现有 Kubernetes 集群（1.26+）。
  • 安装 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 和 APISIX Ingress Controller：

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

helm install apisix \
  --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 \
  apisix/apisix

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

❸ 禁用 etcd 部署。

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

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

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

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

查看 GatewayProxy 资源

查询 GatewayProxy 名称：

kubectl get gatewayproxy

你应看到如下 GatewayProxy 名称：

NAME            AGE
apisix-config   12s

以 YAML 格式查看 GatewayProxy 资源配置：

kubectl get gatewayproxy apisix-config -o yaml

你应看到类似如下的 GatewayProxy 资源配置：

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

如果一切正常，所有 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

如果一切正常，你应看到类似如下输出：

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 9080:80 &

然后向网关发送请求：

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

如果一切正常，你应看到 APISIX 版本：

Server: APISIX/3.17.0
信息

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

定义控制器和网关​

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

如果使用 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

注意，Gateway 监听器中的 port 可用于基于 listener_port_match_mode（auto、explicit 或 off）进行路由匹配。控制器无法在数据面上动态打开新端口，因此请确保 APISIX 或 API7 网关已配置为监听该端口。

将配置应用到集群：

kubectl apply -f gatewayclass-gateway.yaml

如需了解这些参数以及如何按需调整，请参阅配置示例。

下一步​

在下一篇教程中，你将学习如何创建路由，将请求代理到同一集群中的上游服务。