在 OpenShift 上安装 API7 Ingress Controller

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

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

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

安全上下文约束（SCC）： OpenShift 默认限制 Pod 安全策略。必须为 Ingress Controller 配置适当的 SCC（通常为 nonroot-v2），才能使其正常运行。
非 root 运行要求： OpenShift 要求容器使用分配的 UID，以非 root 用户身份运行。因此，必须在 Helm 安装命令中显式配置 securityContext。
自定义资源定义（CRD）管理： OpenShift 会保护 Gateway API CRD 等系统 CRD。使用 Helm 安装时，请添加 --skip-crds 标志以避免权限冲突，随后再单独安装 APISIX 相关 CRD。

前置条件

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

安装 API7 Ingress Controller

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

生成并运行部署脚本

进入 API7 控制台：

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

添加新的网关组

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

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

然后点击生成脚本。

在命令末尾手动附加高亮显示的标志。确保前一行以反斜杠（\）结尾。命令应类似于以下内容：

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.24 \
  --set "deployment.image.repository=api7/api7-ingress-controller" \
  --set "deployment.image.tag=2.1.0" \
  --set "config.controllerName=api7.ai/api7-ingress-controller" \
  --set "config.leaderElection.id=api7-ingress-controller-leader" \
  --set "adc.securityContext.runAsUser=65532" \
  --skip-crds

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

❷ --skip-crds：跳过通过 Helm 安装 CRD，因为 OpenShift 限制了 CRD 管理。Gateway API CRD 已经存在，而 APISIX CRD 必须在之后手动安装。

信息

如果你打算使用 Gateway API 创建资源，请使用 0.1.23 或更高版本的 Helm Chart。较早的 Chart 版本无法在 OpenShift 环境中正确安装 Gateway API 资源。

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

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

安装 APISIX CRD

在 OpenShift 中，Gateway API CRD 是预安装的，并且受到平台保护。Helm 安装必须使用 --skip-crds，以避免在尝试安装这些受保护的 CRD 时出现权限错误。因此，APISIX CRD 也被跳过，需要手动安装。

kubectl apply -f https://raw.githubusercontent.com/api7/api7-helm-chart/refs/heads/main/charts/ingress-controller/crds/apisix-crds.yaml

你应该会得到以下响应。

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/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​

安装 APISIX CRD​

部署 GatewayProxy 配置​

创建网关实例​

验证​