在 OpenShift 上安装 API7 Ingress Controller

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

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

如果由 Red Hat OpenShift GitOps 管理安装，请按照使用 Argo CD 管理完成协调，并应用本文所述的 OpenShift 专用 SCC、非 root 运行和 CRD 要求。

本文不涵盖在 OpenShift 上安装 APISIX Ingress Controller，但两个控制器具有相同的 OpenShift 特定要求，因此安装流程大体相似：

安全上下文约束（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 管理。此工作流使用 --skip-crds，并由集群平台团队单独管理所需 Gateway API 和 APISIX CRD。

前置条件

完成在 OpenShift 上部署 API7 企业版中的前置条件和安装步骤，但跳过生成部署脚本步骤。使用 Ingress Controller 时，必须在 Ingress Controller 类型的网关组中部署网关实例。

安装 API7 Ingress Controller

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

生成并运行部署脚本

进入 API7 控制台：

从侧边导航栏选择网关组，然后点击添加网关组。
选择类型为Ingress Controller。
在名称字段中输入 api7-ingress。
点击添加。

添加新的网关组

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

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

然后点击生成脚本。

标注 ❶ 和 ❷ 表示发布版本固定值。请在命令末尾手动附加标为 ❸ 和 ❹ 的 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.26 \
  --set "deployment.image.repository=api7/api7-ingress-controller" \
  --set "deployment.image.tag=2.2.0" \
  --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.26：固定兼容的 API7 Ingress Controller Chart。

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

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

❸ --set "adc.securityContext.runAsUser=65532"：以非 root 用户（UID 65532）身份运行 API7 Ingress Controller，以符合 OpenShift 的安全策略。

❹ --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 的服务账户，该账户将在 Helm Chart 发布名称中被引用。角色必须分配给 Ingress Controller 部署所使用的服务账户。

oc create 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

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

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.26/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.26/charts/ingress-controller/crds/apisix-crds.yaml

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.26/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 配置

在命名空间字段中输入 api7-enterprise-project。
在名称字段中输入 api7-ingress。
点击生成脚本。

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

添加 Admin API 地址

选择 Ingress 或 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
ingressclass.networking.k8s.io/api7-ingress created

创建网关实例

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

激活网关实例

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

激活网关实例

生成的脚本结尾没有反斜杠（\）。确保 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 网关实例

验证

检查所有 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

前置条件​

安装 API7 Ingress Controller​

生成并运行部署脚本​

为 API7 Ingress Controller 配置 SCC​

安装所需 CRD​

OpenShift 4.18 及更早版本​

OpenShift 4.19 及更高版本​

部署 GatewayProxy 配置​

创建网关实例​

验证​