# 在 OpenShift 上安装 API7 Ingress Controller

与标准 Kubernetes 环境相比，OpenShift 实施了更严格的安全控制和平台级约束。因此，部署时需要额外考虑若干事项。

本指南介绍如何在 OpenShift 集群上部署与 API7 企业版配合使用的 API7 Ingress Controller。

如果由 Red Hat OpenShift GitOps 管理安装，请按照[使用 Argo CD 管理](https://docs.apiseven.com/ingress-controller/installation/gitops/argo-cd.md)完成协调，并应用本文所述的 OpenShift 专用 SCC、非 root 运行和 CRD 要求。

本文不涵盖在 OpenShift 上安装 APISIX Ingress Controller。两个控制器具有以下相同的 OpenShift 运行时要求，但其 Chart 的 CRD 所有权控制方式不同：

* **安全上下文约束（SCC）：** OpenShift 默认限制 Pod 安全策略。必须为 Ingress Controller 配置适当的 SCC（通常为 `nonroot-v2`），才能使其正常运行。
* **非 root 运行要求：** OpenShift 要求容器使用分配的 UID，以非 root 用户身份运行。因此，必须在 Helm 安装命令中显式配置 `securityContext`。
* **自定义资源定义（CRD）管理：** Gateway API 所有权取决于 OpenShift 版本。OpenShift 4.18 及更早版本默认不安装这些 CRD；从 4.19 开始由 Ingress Operator 管理。下文的 API7 工作流使用 `--skip-crds`，并由平台管理 Gateway API 和 APISIX CRD。独立的 APISIX Chart 1.4.1 则使用 `crds.gatewayAPI.enabled` 控制其渲染的 Gateway API 资源；请遵循该 Chart 的 [GitOps 所有权指南](https://docs.apiseven.com/ingress-controller/installation/gitops.md#choose-crd-ownership)。

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

完成[在 OpenShift 上部署 API7 企业版](https://docs.apiseven.com/api7-gateway/install/deploy-on-openshift.md)中的前置条件和安装步骤，但跳过[生成部署脚本](https://docs.apiseven.com/api7-gateway/install/deploy-on-openshift.md#generate-deployment-script)步骤。使用 Ingress Controller 时，必须在 Ingress Controller 类型的网关组中部署网关实例。

## 安装 API7 Ingress Controller[​](#安装-api7-ingress-controller "安装 API7 Ingress Controller的直接链接")

如果你想使用不同的命名空间或自定义其他配置名称，请相应地调整安装命令和配置值。

### 生成并运行部署脚本[​](#生成并运行部署脚本 "生成并运行部署脚本的直接链接")

进入 API7 控制台：

1. 从侧边导航栏选择**网关组**，然后点击**添加网关组**。

2. 选择类型为**Ingress Controller**。

3. 在**名称**字段中输入 `api7-ingress`。

4. 点击**添加**。

![添加新的网关组](https://static.api7.ai/uploads/2026/01/30/szv2XsKn_3-2-add-gateway-group.webp)

网关组创建后，部署步骤面板会提示你安装 Ingress Controller 并部署 GatewayProxy 配置。

输入 Ingress Controller 的命名空间和名称。

![安装 API7 Ingress Controller](https://static.api7.ai/uploads/2026/01/30/4ANfaYGB_3-3.webp)

然后点击**生成脚本**。

![安装 API7 Ingress Controller](https://static.api7.ai/uploads/2026/03/02/TYCrKtcv_ic-deployment.webp)

标注 ❶ 和 ❷ 表示发布版本固定值。请在命令末尾手动附加标为 ❸ 和 ❹ 的 OpenShift 专用参数，并确保前一行以反斜杠（`\`）结尾。命令应类似于以下内容：

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

helm repo update

helm upgrade --install -n api7-enterprise-project --create-namespace api7-ingress api7/api7-ingress-controller \

  --version 0.1.28 \

  --set "deployment.image.repository=api7/api7-ingress-controller" \

  --set "deployment.image.tag=2.2.1" \

  --set "config.controllerName=api7.ai/api7-ingress-controller" \

  --set "config.leaderElection.id=api7-ingress-controller-leader" \

  --set "adc.securityContext.runAsUser=65532" \

  --skip-crds
```

❶ `--version 0.1.28`：固定兼容的 API7 Ingress Controller Chart。

❷ `deployment.image.tag=2.2.1`：运行与 Chart 匹配的 Controller 镜像。

请始终使用同一 Controller 发布版本的 Chart、镜像和 CRD。不要把固定到其他 Controller 版本的 Dashboard 生成脚本，与本文档中的 CRD 混用。

❸ `--set "adc.securityContext.runAsUser=65532"`：将 ADC 边车（sidecar）容器配置为以非 root 用户 ID 65532 运行。此值不会设置 Ingress Controller 容器的安全上下文。

❹ `--skip-crds`：跳过通过 Helm 安装 CRD，使集群平台团队可以根据已安装的 OpenShift 版本管理 Gateway API 所有权。之后必须单独安装 APISIX CRD。

在终端中运行它。如果部署成功，你应该会看到类似于以下的响应：

```
NAME: api7-ingress

LAST DEPLOYED: Mon Feb 2 15:12:59 2026

NAMESPACE: api7-enterprise-project

STATUS: deployed

REVISION: 1

TEST SUITE: None
```

### 为 API7 Ingress Controller 配置 SCC[​](#为-api7-ingress-controller-配置-scc "为 API7 Ingress Controller 配置 SCC的直接链接")

Chart 会使用 release 名称创建 Controller ServiceAccount，本例中为 `api7-ingress`。请为这个现有账号授予 SCC 权限，不要另建第二个账号。使用其他 release 名称时，请检查运行中 Deployment 的 `serviceAccountName`。

```
oc get serviceaccount api7-ingress -n api7-enterprise-project
```

创建一个带有 `nonroot-v2` SCC 的角色：

```
oc create role api7-ingress \

  --verb=use \

  --resource=scc \

  --resource-name=nonroot-v2 \

  -n api7-enterprise-project
```

将角色绑定到服务账户：

```
oc create rolebinding api7-ingress \

  --role=api7-ingress \

  --serviceaccount=api7-enterprise-project:api7-ingress \

  -n api7-enterprise-project
```

### 安装所需 CRD[​](#安装所需-crd "安装所需 CRD的直接链接")

`--skip-crds` 标志会同时跳过 Chart 自带的 APISIX 与 Gateway API CRD。请根据 OpenShift 版本安装所需 CRD。

#### OpenShift 4.18 及更早版本[​](#openshift-418-及更早版本 "OpenShift 4.18 及更早版本的直接链接")

默认不安装 Gateway API CRD。如果计划使用 Gateway API 资源，请从相同的固定 Chart 版本安装 Gateway API CRD。请使用服务端应用，因为捆绑的 CRD 会超过客户端注解大小限制。如果应用报告所有权冲突，请确定现有 CRD 管理方，并通过该所有者更新 CRD，不要强制覆盖：

```
kubectl apply --server-side \

  -f https://raw.githubusercontent.com/api7/api7-helm-chart/refs/tags/api7-ingress-controller-0.1.28/charts/ingress-controller/crds/gwapi-crds.yaml
```

安装 APISIX CRD：

```
kubectl apply --server-side \

  -f https://raw.githubusercontent.com/api7/api7-helm-chart/refs/tags/api7-ingress-controller-0.1.28/charts/ingress-controller/crds/apisix-crds.yaml
```

#### OpenShift 4.19 及更高版本[​](#openshift-419-及更高版本 "OpenShift 4.19 及更高版本的直接链接")

OpenShift Ingress Operator 会安装并管理 Gateway API CRD。不要应用 Chart 中的 `gwapi-crds.yaml` 文件。只从相同的固定 Chart 版本安装 APISIX CRD：

```
kubectl apply --server-side \

  -f https://raw.githubusercontent.com/api7/api7-helm-chart/refs/tags/api7-ingress-controller-0.1.28/charts/ingress-controller/crds/apisix-crds.yaml
```

OpenShift 4.19 使用其支持的 Gateway API 版本，而不是 Chart 自带的版本。请确认计划使用的 Gateway API 资源在集群中可用。

安装 APISIX CRD 后，应得到类似以下输出：

```
customresourcedefinition.apiextensions.k8s.io/apisixconsumers.apisix.apache.org created

customresourcedefinition.apiextensions.k8s.io/apisixglobalrules.apisix.apache.org created

customresourcedefinition.apiextensions.k8s.io/apisixpluginconfigs.apisix.apache.org created

customresourcedefinition.apiextensions.k8s.io/apisixroutes.apisix.apache.org created

customresourcedefinition.apiextensions.k8s.io/apisixtlses.apisix.apache.org created

customresourcedefinition.apiextensions.k8s.io/apisixupstreams.apisix.apache.org created

customresourcedefinition.apiextensions.k8s.io/backendtrafficpolicies.apisix.apache.org created

customresourcedefinition.apiextensions.k8s.io/consumers.apisix.apache.org created

customresourcedefinition.apiextensions.k8s.io/gatewayproxies.apisix.apache.org created

customresourcedefinition.apiextensions.k8s.io/httproutepolicies.apisix.apache.org created

customresourcedefinition.apiextensions.k8s.io/l4routepolicies.apisix.apache.org created

customresourcedefinition.apiextensions.k8s.io/pluginconfigs.apisix.apache.org created
```

### 部署 GatewayProxy 配置[​](#部署-gatewayproxy-配置 "部署 GatewayProxy 配置的直接链接")

1. 在**命名空间**字段中输入 `api7-enterprise-project`。
2. 在**名称**字段中输入 `api7-ingress`。
3. 点击**生成脚本**。

![](https://static.api7.ai/uploads/2026/03/02/yrVUQCqo_20260302-150006.webp)

如果你尚未配置 Admin API 地址，系统将提示你先添加它。

![添加 Admin API 地址](https://static.api7.ai/uploads/2026/02/03/5oauslQU_configure-admin-api-address.webp)

4. 选择 **Ingress** 或 **Gateway API** 标签页。

![安装 API7 Ingress Controller](https://static.api7.ai/uploads/2026/02/03/eREXO4eB_deploy-gatewayproxy.webp)

5. 复制生成的脚本并在终端中运行。

输出的资源取决于所选页签。使用 **Gateway API** 页签时，输出应类似于：

```
namespace/api7-enterprise-project configured

secret/api7-ingress-admin-secret configured

gatewayclass.gateway.networking.k8s.io/api7-ingress created

gatewayproxy.apisix.apache.org/api7-ingress created

gateway.gateway.networking.k8s.io/api7-ingress created
```

使用 **Ingress** 页签时，会创建 IngressClass，而不是 GatewayClass 和 Gateway：

```
namespace/api7-enterprise-project configured

secret/api7-ingress-admin-secret configured

gatewayproxy.apisix.apache.org/api7-ingress created

ingressclass.networking.k8s.io/api7-ingress created
```

## 创建网关实例[​](#创建网关实例 "创建网关实例的直接链接")

前往**网关实例**页面并添加一个网关实例。

![激活网关实例](https://static.api7.ai/uploads/2026/01/30/cMRCUY5o_3-5-add-gateway-instance.webp)

切换到 **Kubernetes** 标签页并填写参数。完成后，点击**生成**以查看部署脚本。

![激活网关实例](https://static.api7.ai/uploads/2026/01/30/LoqEVp3W_3-6-add-gateway-instance.webp)

生成的脚本结尾没有反斜杠（`\`）。确保 `apisix.image.tag` 行以 `\` 结尾，并且额外的 `securityContext` 设置被附加到 Helm 命令的末尾，如下所示：

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

helm repo update

cat > /tmp/tls.crt <<EOF

-----BEGIN CERTIFICATE-----

MIIBhjCCATigAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI

EwpDYWxpZm9ybmlhMQ0wCwYDVQQKEwRBUEk3MREwDwYDVQQDEwhBUEk3IEluYzAe

Fw0yNTEyMzEwNzQ3MzZaFw0zNjAxMjgwNzQ3MzZaMC4xDTALBgNVBAoTBEFQSTcx

HTAbBgNVBAMTFEdBVEVXQVktQ0EtVkVSU0lPTi0xMCowBQYDK2VwAyEA0WOxi3H/

gxsh/kNEg8L9cLrfZmRqE5lB4fW0DVObre2jZDBiMA4GA1UdDwEB/wQEAwIHgDAT

BgNVHSUEDDAKBggrBgEFBQcDAjAtBgNVHQ4EJgQkYWZjNmQ0ODctMmVmZC00MjZh

LWJiNDktMTA2ZWQ2NDIyOWFkMAwGA1UdIwQFMAOAATEwBQYDK2VwA0EAJJh+f8Sv

4OWo41Um3NOpvB30tjWQEsUXpDKyh9Kh8b7ymcDVQ0Hn1J9jFyI5Y/yFT8ZSz7ek

1GGpngVMsWTiDg==

-----END CERTIFICATE-----

EOF

cat > /tmp/tls.key <<EOF

-----BEGIN PRIVATE KEY-----

MC4CAQAwBQYDK2VwBCIEIFXsXU+dBdP8lkheZH/6SMy7ZnMionHN/xRDHBjOMAvP

-----END PRIVATE KEY-----

EOF

cat > /tmp/ca.crt <<EOF

-----BEGIN CERTIFICATE-----

MIIBeDCCASqgAwIBAgIRAP4AwnUs3br0nZ7V03gyt84wBQYDK2VwMEQxCzAJBgNV

BAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMQ0wCwYDVQQKEwRBUEk3MREwDwYD

VQQDEwhBUEk3IEluYzAgFw0yNTEyMzEwNjU1NDlaGA8yMDg2MDExNTA2NTU0OVow

RDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAoTBEFQ

STcxETAPBgNVBAMTCEFQSTcgSW5jMCowBQYDK2VwAyEAHTkeAU7NKliDJFd5UN9b

xYIMgAz4RG3QUwEBXl2NwdCjLzAtMA4GA1UdDwEB/wQEAwIChDAPBgNVHRMBAf8E

BTADAQH/MAoGA1UdDgQDBAExMAUGAytlcANBABrSW1mdva+TFJNiOpyblbz5vSJY

Jk9HSb3vHYfa3dncCz2A5m5sOs1VNFq3QQqPVaI41dx0FvIrp89gVsFVMAk=

-----END CERTIFICATE-----

EOF

kubectl create namespace api7-enterprise-project --dry-run=client -o yaml | kubectl apply -f -

kubectl create secret generic -n api7-enterprise-project api7-ee-3-gateway-tls --from-file=tls.crt=/tmp/tls.crt --from-file=tls.key=/tmp/tls.key --from-file=ca.crt=/tmp/ca.crt

helm upgrade --install -n api7-enterprise-project --create-namespace api7-ee-3-gateway api7/gateway \

  --set "etcd.auth.tls.enabled=true" \

  --set "etcd.auth.tls.existingSecret=api7-ee-3-gateway-tls" \

  --set "etcd.auth.tls.certFilename=tls.crt" \

  --set "etcd.auth.tls.certKeyFilename=tls.key" \

  --set "etcd.auth.tls.verify=true" \

  --set "gateway.tls.existingCASecret=api7-ee-3-gateway-tls" \

  --set "gateway.tls.certCAFilename=ca.crt" \

  --set "apisix.extraEnvVars[0].name=API7_GATEWAY_GROUP_SHORT_ID" \

  --set "apisix.extraEnvVars[0].value=eybqbncmefrqq" \

  --set "etcd.host[0]=https://api7ee3-dp-manager.api7-enterprise-project.svc.cluster.local:7943" \

  --set "apisix.replicaCount=1" \

  --set "apisix.image.repository=api7/api7-ee-3-gateway" \

  --set "apisix.image.tag=3.9.3" \

  --set "apisix.securityContext.runAsNonRoot=true" \

  --set "apisix.securityContext.runAsUser=636"
```

❶ `--set "apisix.securityContext.runAsNonRoot=true"`：确保 APISIX Pod 以非 root 用户身份运行，以符合 OpenShift 安全要求。

❷ `--set "apisix.securityContext.runAsUser=636"`：为 APISIX Pod 进程指定 UID（636），以满足 OpenShift SCC 要求。

返回网关实例页面，你应该会看到一个健康的网关实例。

![运行中的 API7 网关实例](https://static.api7.ai/uploads/2026/01/30/lj8dFhRQ_3-7-add-gateway-instance.webp)

## 验证[​](#验证 "验证的直接链接")

检查所有 Pod 状态：

```
kubectl get pods -n api7-enterprise-project
```

确保 Ingress Controller 和 Gateway Pod 处于 Running 状态：

```
NAME                                                    READY   STATUS    RESTARTS         AGE

api7-ee-3-gateway-78f8fd49f9-6fkhv                      1/1     Running   0                4m44s

api7-ingress-api7-ingress-controller-568867b656-v8ftd   2/2     Running   0                65m

api7-postgresql-0                                       1/1     Running   0                91m

api7-prometheus-server-5c9b5c98ff-mf2gl                 1/1     Running   0                91m

api7ee3-dashboard-df48f5f59-x5zkt                       1/1     Running   0                91m

api7ee3-developer-portal-7fbd8fdc54-jvnvc               1/1     Running   0                91m

api7ee3-dp-manager-7b449767dc-dxfrr                     1/1     Running   0                91m
```

列出所有 Service：

```
kubectl get svc -n api7-enterprise-project
```

你应该会看到一个可用的网关服务：

```
NAME                                               TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                      AGE

api7-ee-3-gateway-gateway                          NodePort    172.30.128.146   <none>        80:31474/TCP,443:30130/TCP   32m

api7-ingress-api7-ingress-controller-webhook-svc   ClusterIP   172.30.63.42     <none>        443/TCP                      67m

api7-ingress-metrics-service                       ClusterIP   172.30.133.232   <none>        8443/TCP                     67m

api7-postgresql                                    ClusterIP   172.30.123.46    <none>        5432/TCP                     92m

api7-postgresql-hl                                 ClusterIP   None             <none>        5432/TCP                     92m

api7-prometheus-server                             ClusterIP   172.30.10.79     <none>        9090/TCP                     92m

api7ee3-dashboard                                  ClusterIP   172.30.84.136    <none>        7080/TCP,7443/TCP            92m

api7ee3-developer-portal                           ClusterIP   172.30.42.148    <none>        4321/TCP                     92m

api7ee3-dp-manager                                 ClusterIP   172.30.153.144   <none>        7900/TCP,7943/TCP            92m
```
