在 OKD 上运行 AISIX

AISIX 在 OKD 上使用标准 Kubernetes 安装与升级流程，同时针对 Security Context Constraints（SCC）、Route 和内置 PostgreSQL 安全上下文进行平台专用处理。本页涵盖三种产品的 AISIX 网关，以及 AISIX Enterprise 控制面。

请先准备现有 OKD 集群，以及可在目标项目中创建资源的 oc 会话。AISIX Helm Chart 支持 OKD 4.11 或更高版本默认使用的 restricted-v2 SCC。安装或升级 AISIX 前，请确认 AISIX 服务账户可以使用该 SCC。创建或升级 OKD 集群本身与安装 AISIX 是不同的操作。

新安装时，请先选择适合部署方式的基础 Kubernetes 流程，再应用本页相应的 OKD 指导。

部署方式	Kubernetes 流程	平台专用要求
AISIX OSS	在 Kubernetes 上部署 AISIX OSS	无需额外 SCC values。
连接 AISIX Enterprise 或 AISIX Cloud 的网关	为 AISIX Enterprise 或 AISIX Cloud 部署网关	无需额外 SCC values。
AISIX Enterprise	安装 AISIX Enterprise	禁用内置 PostgreSQL 安全上下文，或使用外部数据库。

了解安全上下文

AISIX 应用 Chart 不固定 runAsUser、runAsGroup 或 fsGroup。其 Pod 安全上下文启用 runAsNonRoot 和 RuntimeDefault seccomp 配置，因此平台可以从项目允许范围内分配 ID。

应用容器使用只读根文件系统，并禁止权限提升。网关移除除 NET_BIND_SERVICE 之外的所有能力；控制面容器移除所有能力。运行时可写路径使用 emptyDir 卷。

不要为 AISIX 服务账户授予 anyuid SCC。如果现有 values 固定了用户或组 ID，请移除这些值，除非集群管理员已将其分配给项目。

选择 OKD 项目

使用现有项目，或在集群允许创建项目时申请新项目：

# 选择现有项目。
oc project aisix

# 或申请新项目。
oc new-project aisix

本页示例使用 aisix。按照链接中的 Kubernetes 流程操作时，请跳过任何 kubectl create namespace 命令，并从 Helm 命令中省略 --create-namespace。流程中指定命名空间的地方均应使用选定的 OKD 项目。

选择 Route 主机名

为部署创建的 Route 选择主机名。安装 AISIX Enterprise 前，请先选择控制面和数据面管理器的主机名。公共控制面 URL 用于浏览器链接；数据面管理器会为配置的端点签发 TLS 证书。

以下示例在集群的通配应用域名下创建名称：

export ROUTE_DOMAIN="$(oc get ingresses.config.openshift.io cluster \
  -o jsonpath='{.spec.domain}')"

export GATEWAY_ROUTE_HOST="aisix-gateway.$ROUTE_DOMAIN"
export CP_ROUTE_HOST="aisix.$ROUTE_DOMAIN"
export DPM_ROUTE_HOST="aisix-dpm.$ROUTE_DOMAIN"

若改用组织管理的 DNS，请将变量设为相应主机名，并确保它们解析到 OKD 路由器。对于 edge Route，还需提供匹配的 Route 证书和密钥，或配置 Ingress Controller 默认的证书以覆盖这些主机名。数据面管理器的 passthrough Route 使用根据 api.dpmgrBaseURL 签发的证书。

安装网关

按照前表中适用的 Kubernetes 网关流程操作，用 oc 替代 kubectl，并用前面选定的项目替代流程中的命名空间。无需自定义 SCC 或修改服务账户。

安装后，确认 Pod 使用 restricted-v2 和项目分配的 UID：

export GATEWAY_NAMESPACE="aisix"
export GATEWAY_RELEASE="aisix-dp"

oc get pods -n "$GATEWAY_NAMESPACE" \
  -l "app.kubernetes.io/instance=$GATEWAY_RELEASE,app.kubernetes.io/component=gateway"

oc get pod -n "$GATEWAY_NAMESPACE" <gateway-pod> \
  -o jsonpath='{.metadata.annotations.openshift\.io/scc}{"\n"}{.spec.containers[0].securityContext.runAsUser}{"\n"}'

注解应显示 restricted-v2。平台可能将分配的 UID 放在 Pod 而非容器上，因此第二行为空本身不表示存在问题。如需确认运行时 UID，请使用 oc exec -n "$GATEWAY_NAMESPACE" <gateway-pod> -- id。

安装 AISIX Enterprise

请查看安装 AISIX Enterprise中的要求，但不要执行该页的 helm install 命令。本节命令会使用 OKD 专用的 PostgreSQL values 和 Route URL 替代该安装命令。

cp-api 和 dp-manager 工作负载无需额外 SCC values。请在安装时使用前节选定的 Route 主机名，使数据面管理器证书与其 passthrough Route 匹配。

内置 PostgreSQL 依赖固定了自己的用户和组 ID。请禁用其 Pod 和容器安全上下文，让 restricted-v2 分配 ID：

values.yaml

postgresql:
  primary:
    podSecurityContext:
      enabled: false
    containerSecurityContext:
      enabled: false

安装时，将该文件与公共端点和所需密钥一起传入：

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

helm install aisix-cp api7/aisix-cp \
  --namespace aisix \
  --version 1.6.0 \
  --values values.yaml \
  --set-string api.publicBaseURL="https://$CP_ROUTE_HOST" \
  --set-string api.dpmgrBaseURL="https://$DPM_ROUTE_HOST" \
  --set secrets.masterKey="$(openssl rand -base64 32)" \
  --set postgresql.auth.password="$(openssl rand -hex 24)" \
  --set postgresql.auth.postgresPassword="$(openssl rand -hex 24)"

不要禁用 postgresql.shmVolume。否则 PostgreSQL 会退回使用容器运行时提供的 64 MB /dev/shm，并行查询可能以 could not resize shared memory segment 失败。

生产环境中，请使用外部高可用 PostgreSQL 数据库，而非内置数据库。

通过 Route 暴露 AISIX

只创建部署方式所需的 Route。以下网关示例使用 Chart 默认的明文 HTTP proxy 监听器。edge Route 在路由器上终止 TLS，再将 HTTP 转发到网关 Service：

oc create route edge aisix \
  --service=aisix-dp \
  --port=proxy \
  --hostname="$GATEWAY_ROUTE_HOST" \
  --namespace aisix

对于 AISIX Enterprise，请使用指向 cp-api Service 的 edge Route 暴露控制面 API 和控制台：

oc create route edge aisix-cp \
  --service=aisix-cp-api \
  --port=http \
  --hostname="$CP_ROUTE_HOST" \
  --namespace aisix

数据面管理器使用双向 TLS 连接受管网关与控制面。请使用 TLS passthrough 暴露它，避免路由器终止该连接：

oc create route passthrough aisix-cp-dpm \
  --service=aisix-cp-dpm \
  --port=tls \
  --hostname="$DPM_ROUTE_HOST" \
  --namespace aisix

以下示例使用默认 Release 名称和 Service 端口。若 Release 使用名称覆盖项，或网关使用自定义监听器，请使用 oc get service -n aisix 显示的实际 Service 名称和命名端口。对于在 Pod 内终止 TLS 的网关监听器，请使用 passthrough Route；若路由器必须向 Service 建立新的、经验证的 TLS 连接，也可使用 re-encrypt 终止方式。数据面管理器证书的使用者可选名称必须包含 passthrough Route 主机名。

升级 AISIX

根据部署方式选择规范的升级流程：

• 对于开源 AISIX 网关，或连接 AISIX Enterprise 或 AISIX Cloud 的网关，请按照升级 Kubernetes 上的 AISIX 网关操作。已连接控制面的网关路径会跳过 AISIX OSS 资源校验。
• 对于 AISIX Enterprise，请按照升级 AISIX Enterprise操作。先升级控制面，再升级其连接的网关。

设置升级和验证命令使用的命名空间：

export GATEWAY_NAMESPACE="aisix"
export CP_NAMESPACE="aisix" # 仅适用于 AISIX Enterprise

更改 Release 前，请记录当前 Route，便于在每次滚动更新后比较其 Service 目标：

oc get routes -n "$GATEWAY_NAMESPACE"

# 仅适用于 AISIX Enterprise
oc get routes -n "$CP_NAMESPACE"

执行选定流程前，如果部署使用内置数据库，请在保存的控制面 values 中保留 PostgreSQL 覆盖项。移除未分配给项目的固定 runAsUser、runAsGroup 和 fsGroup 值。

用 oc 替代 kubectl。更改 Release 前，运行流程中的 Helm 服务端演练。--dry-run=server 成功仅表示渲染、集群查询和 OpenAPI 校验通过，并未将对象提交给 SCC、配额或其他准入检查。只有平台创建 Pod 后，才能确认分配的 SCC。

每次滚动更新后，检查 Pod 和 Route：

oc get pods -n "$GATEWAY_NAMESPACE"
oc get routes -n "$GATEWAY_NAMESPACE"

# 仅适用于 AISIX Enterprise
oc get pods -n "$CP_NAMESPACE"
oc get routes -n "$CP_NAMESPACE"

对于 AISIX Enterprise，请在升级控制面后验证现有网关仍然健康。确认控制面 API 的 edge Route 和数据面管理器的 passthrough Route 仍指向升级前相同的 Service。数据面管理器 Route 的主机名还必须与网关配置中保存的地址一致。

排查 Web 控制台升级

最初通过 Helm CLI 安装的控制面 Release，可能无法在 OKD Web 控制台中升级。如果控制台报告以下错误，请继续使用 Helm CLI 升级流程：

found in Chart.yaml, but missing in charts/ directory: postgresql

已发布的控制面 Chart 已经包含 PostgreSQL 依赖，因此不要单独下载该依赖，也不要重新构建 Chart。

排查 SCC 准入

找到 FailedCreate 事件，再描述事件所指明的控制器。网关或控制面 API Pod 由 ReplicaSet 管理，内置 PostgreSQL 由 StatefulSet 管理。

export FAILED_NAMESPACE="<project-containing-rejected-workload>"

oc get events -n "$FAILED_NAMESPACE" --sort-by=.lastTimestamp
oc describe -n "$FAILED_NAMESPACE" <controller-kind>/<controller-name>

对于 AISIX 应用 Pod，请移除固定的 runAsUser、runAsGroup 和 fsGroup 值。对于内置 PostgreSQL，请按照安装 AISIX Enterprise禁用依赖 Chart 的两个安全上下文。

不要通过授予 anyuid 来绕过 Pod 准入拒绝。如果组织策略使用比 restricted-v2 更严格的 SCC，请让集群管理员审查渲染后的清单，并明确分配所需 ID 或能力。

排查容器启动失败

请先描述 Pod。如果容器已启动，再读取其当前日志：

oc describe pod -n <namespace> <pod>
oc logs -n <namespace> <pod> --all-containers --tail=300

如果容器发生过重启，请在 Pod 描述中确定容器名称，并读取其上一次运行的日志：

oc logs -n <namespace> <pod> -c <restarted-container> --previous --tail=300

如果 CRI-O 为自定义网关容器报告 exec: Operation not permitted，请确认容器安全上下文允许 NET_BIND_SERVICE。网关二进制具有该文件能力，因此即使配置的监听端口不是特权端口，CRI-O 也必须在容器的能力边界集中保留它。其他能力应继续全部移除。