安装 Apigee APIM Operator for Kubernetes

本页面适用于 Apigee，但不适用于 Apigee Hybrid。

查看 Apigee Edge 文档。

本页面介绍了安装和配置 Apigee APIM Operator for Kubernetes 所需的步骤。如需详细了解使用 APIM Operator 的优势，请参阅 Apigee APIM Operator for Kubernetes 概览。

准备工作

在开始安装 APIM Operator 之前，请确保您拥有完成相应步骤所需的角色和权限，并且已完成 APIM Operator：准备工作中所述的前提任务。

所需的角色

如需获得安装 APIM Operator 所需的权限，请让您的管理员为您授予组织的以下 IAM 角色：

创建和管理 GKE 集群：Container Admin (roles/container.admin)
创建和管理服务账号：Service Account Admin (roles/iam.serviceAccountAdmin)
创建和管理服务扩展：Service Extensions Admin (roles/networkservices.serviceExtensionsAdmin)
创建和管理网络端点组 (NEG)：Compute Instance Admin (roles/compute.instanceAdmin)
创建和管理后端服务：Compute Load Balancer Admin (roles/compute.loadBalancerAdmin)
创建和管理 Apigee 资源：Apigee Admin (roles/apigee.admin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

安装和配置 APIM Operator

以下部分介绍了安装和配置 APIM Operator 所需的步骤：

设置环境变量。
启用所需的 API。
检索和配置凭证。
安装 APIM Operator。
创建工作负载身份。
创建 Apigee 环境。
验证 GKE 网关设置。

设置环境变量

在包含 Apigee 实例的 Google Cloud 项目中，使用以下命令设置环境变量：

export PROJECT_ID=PROJECT_ID
export CLUSTER_NAME=CLUSTER_NAME
export REGION=REGION
export APIGEE_ORG=APIGEE_ORG

其中：

PROJECT_ID 是包含 Apigee 实例的项目的 ID。
CLUSTER_NAME 是 GKE 集群的名称。
REGION 是 GKE 集群所在的区域。
APIGEE_ORG 设置为与 PROJECT_ID 相同的值。

如需确认环境变量设置正确，请运行以下命令：

echo $PROJECT_ID $CLUSTER_NAME $REGION $APIGEE_ORG

启用必需的 API

APIM Operator 需要以下 API 的访问权限：

名称	标题
`apigee.googleapis.com`	Apigee API
`compute.googleapis.com`	Compute Engine API
`networkservices.googleapis.com`	Network Services API
`container.googleapis.com`	Google Kubernetes Engine API

使用以下命令确认是否已启用所需的 API：

gcloud services list --project=$PROJECT_ID

如果您在命令输出中未看到所需的 API，请予以启用：

gcloud services enable apigee.googleapis.com --project=$PROJECT_ID
gcloud services enable compute.googleapis.com --project=$PROJECT_ID
gcloud services enable networkservices.googleapis.com --project=$PROJECT_ID
gcloud services enable container.googleapis.com --project=$PROJECT_ID

检索和配置凭证

检索集群凭据并创建服务账号以连接到 Google Cloud 服务：

使用以下命令获取集群凭据：
```
gcloud container clusters get-credentials $CLUSTER_NAME --location=$REGION --project=$PROJECT_ID
```
这些凭据用于与在前提步骤中创建的 GKE 集群进行通信。
设置服务账号凭证以连接到 Google Cloud 服务：
```
gcloud iam service-accounts create apigee-apim-gsa
```

使用以下命令向您创建的服务账号授予所需的角色和权限：

Apigee 管理员角色：必须具有此角色才能创建和管理 Apigee 资源。

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
    --role "roles/apigee.admin"

服务扩展程序管理员角色：必须具有此角色才能创建和管理服务扩展程序。

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
    --role "roles/networkservices.serviceExtensionsAdmin"

网络管理员角色：必须具有此角色才能使用服务扩展程序来管理对 Apigee 的访问权限。

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
    --role "roles/compute.networkAdmin"

负载均衡器管理员角色：必须具有此角色才能管理网络端点组 (NEG) 与后端服务之间的访问权限。

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
    --role "roles/compute.loadBalancerAdmin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
    --role "roles/iam.workloadIdentityUser"

创建工作负载身份

在下一步中通过 helm 安装 APIM Operator 时，系统会在 apim 命名空间中创建一个所需的名为 apim-ksa 的 Kubernetes 服务账号 (KSA)。创建的 KSA 会包含所需的注解，以便与 APIM Operator 用来访问必要的 Apigee 和 Service Networking 资源的工作负载身份进行关联。

如需创建工作负载身份，请使用以下命令：

gcloud iam service-accounts add-iam-policy-binding apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com --role roles/iam.workloadIdentityUser --member "serviceAccount:$PROJECT_ID.svc.id.goog[apim/apim-ksa]"

此命令会将 KSA 与您在检索和配置凭证部分创建的 Google 服务账号绑定，并分配 workloadIdentityUser 角色。

工作负载身份更改可能需要几分钟（可能长达 7 分钟或更长时间）才能在整个系统中传播。

如需确认工作负载身份已创建，请使用以下命令：

gcloud config set project $PROJECT_ID

kubectl run --rm -it --image google/cloud-sdk:slim \
  --namespace apim workload-identity-test \
  --overrides='{ "spec": { "serviceAccountName": "apim-ksa" } }'  \
  -- gcloud auth list

输出应类似如下所示：

Credentialed Accounts
  ACTIVE  ACCOUNT
  *       GSA@$PROJECT_ID.iam.gserviceaccount.com

安装自定义资源定义 (CRD) 和 APIM Operator

安装 Kubernetes 自定义资源定义 (CRD) 和 APIM Operator：

为 APIM Operator 创建命名空间：
```
kubectl create ns apim
```

安装 APIM Operator 自定义资源定义 (CRD)：

helm install apigee-apim-crds -n apim \
  oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-crds \
  --version 1.0.0 \
  --atomic

安装 APIM Operator：

helm install apigee-apim-operator -n apim \
  oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-helm \
  --version 1.0.0 \
  --set projectId=$PROJECT_ID \
  --set serviceAccount=apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com \
  --set apigeeOrg=$PROJECT_ID \
  --set generateEnv=TRUE \
  --atomic

确认安装已成功完成：

helm list -n apim

输出应类似如下所示：

NAME                	NAMESPACE	REVISION	UPDATED                                	STATUS  	CHART                          	APP VERSION
apigee-apim-crds    	apim     	1       	2025-02-01 00:17:03.399810627 +0000 UTC	deployed	apigee-apim-operator-crds-1.0.0	1.0.0
apigee-apim-operator	apim     	1       	2025-02-01 00:15:00.362829981 +0000 UTC	deployed	apigee-apim-operator-helm-1.0.0	1.0.0

确认 KSA 已创建且包含所需的注解：

kubectl describe serviceaccounts apim-ksa -n apim

输出应类似如下所示：

Name:                apim-ksa
Namespace:           apim
...
Annotations:         iam.gke.io/gcp-service-account: apigee-apim-gsa@my-project-id.iam.gserviceaccount.com

确认 APIM Operator 已在集群的 Pod 中启动并正在运行：
```
kubectl get pods -n apim
```
输出应类似如下所示：
```
NAME                                    READY   STATUS    RESTARTS     AGE
apigee-apim-operator-8559d4994b-h55fl   1/1     Running   0            8m34s
```
如果 STATUS 不是 Running，或者 READY 未显示 1/1，请参阅 APIM Operator 问题排查，以排查安装问题。

创建 Apigee 环境

如果您在上一步中安装 APIM Operator 时使用了 generateEnv=TRUE，则当系统创建并应用 APIM 扩展程序政策时，该 Operator 会创建一个新的 Apigee 环境。新环境的名称具有前缀 apim-enabled-dep-env。

如果您在安装 APIM Operator 时使用了 generateEnv=FALSE，则必须创建新的 Apigee 环境：

设置 curl 命令所需的 TOKEN：

export TOKEN=$(gcloud auth print-access-token)

使用以下命令之一创建环境：

对于 2021 年订阅组织：

curl -X POST "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments" -H \
  "Authorization: Bearer $TOKEN" -H "content-type:application/json" \
    -d '{
      "name": "ENV_NAME",
      "displayName": "ENV_NAME",
      "state": "ACTIVE",
      "deploymentType": "PROXY",
      "apiProxyType": "PROGRAMMABLE",
      "properties": {
        "property": [
          {
            "name": "apigee-service-extension-enabled",
            "value": "true"
          }
        ]
      }
  }'

其中，ENV_NAME 是要创建的环境的名称。

对于 2024 年订阅组织和随用随付组织：

curl -i -X POST -H "Authorization: Bearer $TOKEN"  "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments" -H "Content-Type:application/json" -d '{
  "name": "ENV_NAME",
  "displayName": "ENV_NAME",
  "state": "ACTIVE",
  "deploymentType": "PROXY",
  "apiProxyType": "PROGRAMMABLE",
  "type" : "COMPREHENSIVE",
  "properties": {
    "property": [
      {
        "name": "apigee-service-extension-enabled",
        "value": "true"
      }
    ]
  }
}'

其中：

ENV_NAME 是要创建的环境的名称。
ENV_TYPE 是要创建的环境的类型。例如 INTERMEDIATE 或 COMPREHENSIVE。

如需检查环境是否已成功创建，请运行以下命令：

curl -i -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments"

将环境关联到您的 Apigee 实例：

curl -i -X POST -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/instances/INSTANCE_NAME/attachments" \
  -H "Content-Type:application/json" -d '{"environment": "ENV_NAME"}'

其中：

INSTANCE_NAME 是您的 Apigee 实例的名称。
ENV_NAME 是在之前步骤中创建的环境的名称。

如需检查环境关联操作的状态，请运行以下命令：

curl -X GET -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/operations/OPERATION_ID"

其中，OPERATION_ID 是环境关联操作的 ID。

问题排查

如果您在安装 APIM Operator 时遇到问题，请参阅 APIM Operator 问题排查，了解常见错误的解决方案。

安装 Apigee APIM Operator for Kubernetes 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

安装和配置 APIM Operator

设置环境变量

启用必需的 API

检索和配置凭证

创建工作负载身份

安装自定义资源定义 (CRD) 和 APIM Operator

创建 Apigee 环境

问题排查

后续步骤

安装 Apigee APIM Operator for Kubernetes