为 Apigee Hybrid 启用 Workload Identity

您当前正在查看 Apigee Hybrid 文档的 1.5 版。 此版本已终止服务。 您应该升级到更高的版本。如需了解详情，请参阅支持的版本。

Version 1.5 (unsupported)

   Supported versions:

• v1.12 (latest)                        
• v1.11                         
• v1.10                                        
• List of supported versions

   Unsupported versions:

• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

本主题介绍如何启用 Apigee Hybrid。

概览

Workload Identity 是 GKE (Google Kubernetes Engine) 内运行的应用访问 Google Cloud 服务的一种方法。如需查看 Workload Identity 的概览，请参阅：

• 引入 Workload Identity：为 GKE 应用提供更好的身份验证方法
• 使用 Workload Identity

Google Cloud IAM 服务账号是一个身份，应用可使用该身份向 Google API 发出请求。在本文档中，这些服务账号称为 GSA（Google 服务账号）。如需详细了解 GSA，请参阅服务账号。

Kubernetes 也有自己的服务账号概念。服务账号为 pod 中运行的进程提供身份。Kubernetes 服务账号属于 Kubernetes 资源，而 Google 服务账号专用于 Google Cloud。如需了解 Kubernetes 服务账号，请参阅 Kubernetes 文档中的为 Pod 配置服务账号。

在 Apigee Hybrid 1.4 及更高版本中，Apigee 会为每种类型的组件创建和使用一个 Kubernetes 服务账号。启用 Workload Identity 后，Hybrid 组件可与 Kubernetes 服务账号交互。

前提条件

在为 Apigee Hybrid 启用 Workload Identity 之前，必须为运行 Apigee 的 GKE 集群启用 Workload Identity。

如果您已按照 Anthos Service Mesh (ASM) 的说明操作，则集群已启用 Workload Identity。

您可以通过运行以下命令来确认是否已启用 Workload Identity：

gcloud container clusters describe $CLUSTER_NAME

输出内容应如下所示：

…
…
status: RUNNING
subnetwork: default
workloadIdentityConfig:
  workloadPool: PROJECT_ID.svc.id.goog

在 GKE 上运行 Apigee Hybrid 时，标准做法是为每个服务账号创建和下载私钥（.json 文件）。使用 Workload Identity 时，您无需下载服务账号私钥并将其添加到 GKE 集群。

启用 Workload Identity

说明分为三个部分：

• 准备启用 Workload Identity。在启用 Workload Identity 之前，按照这些说明更新节点池并初始化变量。
• 为全新安装启用 Workload Identity。遵循新 Apigee Hybrid 安装的说明，或者如果您未在 Hybrid 安装时安装 ASM。
• 升级安装以使用 Workload Identity。按照这些说明在现有 Apigee Hybrid 安装上启用 Workload Identity。

准备启用 Workload Identity

以下说明介绍如何为 Apigee Hybrid 运行时启用 Workload Identity。

更新节点池

使用以下命令确保为每个节点池启用 Workload Identity：

gcloud container node-pools update $NODE_POOL_NAME \
  --cluster=$CLUSTER_NAME \
  --workload-metadata=GKE_METADATA

初始化变量

初始化以下变量：

export PROJECT_ID=my-project-id
export ORG_NAME=$PROJECT_ID
export ENV_NAME=my-environment-name
export NAMESPACE=apigee #the namespace where apigee is installed

gcloud config set project $PROJECT_ID

为全新安装启用 Workload Identity

1. 将以下突出显示的行添加到的 overrides.yaml 文件中的 gcp 节下：

   gcp:
     projectID: "my-project"
     name: "my-project"
     region: "us-west1"
     workloadIdentityEnabled: true

2. 创建 Google 服务账号。您可以使用两种方法：
   • 使用 create-service-account 工具，通过以下命令为每个组件创建一个 Google 服务账号：

     $APIGEECTL_HOME/tools/create-service-account --env prod --dir $APIGEECTL_HOME/../service-accounts

     此命令将创建以下服务账号：

     • apigee-logger
     • apigee-metrics
     • apigee-cassandra
     • apigee-udca
     • apigee-synchronizer
     • apigee-mart
     • apigee-watcher
     • apigee-distributed-trace

     以下说明假设您使用 create-service-account 工具生成服务账号。

   • 为每个环境定义自定义命名规则和服务账号（高级用户）
3. 创建 Kubernetes 服务账号。

   对于组织级组件：

   • Cassandra

     kubectl create sa -n $NAMESPACE apigee-cassandra-schema-setup-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-cassandra,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-cassandra-schema-setup-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

     kubectl create sa -n $NAMESPACE apigee-cassandra-user-setup-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-cassandra,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-cassandra-user-setup-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • MART

     kubectl create sa -n $NAMESPACE apigee-mart-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-mart,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-mart-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • Apigee Connect

     kubectl create sa -n $NAMESPACE apigee-connect-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-connect,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-connect-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com
     

   • Apigee Watcher

     kubectl create sa -n $NAMESPACE apigee-watcher-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-watcher,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-watcher-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   对于每个环境：

   注意：请确保 GSA_NAME 与组件匹配。在以下说明中，GSA_NAME 不是环境变量。
   • 运行时

     kubectl create sa -n $NAMESPACE apigee-runtime-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-runtime,org=$ORG_NAME,env=$ENV_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-runtime-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • UDCA

     kubectl create sa -n $NAMESPACE apigee-udca-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-udca,org=$ORG_NAME,emv=$ENV_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-udca-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • 同步器

     kubectl create sa -n $NAMESPACE apigee-synchronizer-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-synchronizer,org=$ORG_NAME,env=$ENV_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-syncrhonizer-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

4. 继续按照正常步骤安装 Apigee Hybrid。

升级安装以使用 Workload Identity

以下示例展示了为 Apigee 创建的 Google 服务账号 (GSA)：

gcloud iam service-accounts list | grep apigee

apigee-connect   apigee-connect@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-runtime   apigee-runtime@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-metrics   apigee-metrics@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-mart      apigee-mart@$PROJECT_ID.iam.gserviceaccount.com       False
apigee-watcher   apigee-watcher@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-sync      apigee-sync@$PROJECT_ID.iam.gserviceaccount.com       False
apigee-udca      apigee-udca@$PROJECT_ID.iam.gserviceaccount.com       False

以下是为 Apigee 创建的 Kubernetes 服务账号 (KSA) 示例（假设安装了 Apigee Hybrid 1.4 或更高版本）：

kubectl get sa -n $NAMESPACE

apigee-cassandra-schema-setup-ORG_NAME-cb84b88-sa                1         xxd
apigee-cassandra-user-setup-ORG_NAME-cb84b88-sa                  1         xxd
apigee-connect-agent-ORG_NAME-cb84b88-sa                         1         xxd
apigee-init                                                        1         xxd
apigee-mart-ORG_NAME-cb84b88-sa                                  1         xxd
apigee-metrics-apigee-telemetry                                    1         xxd
apigee-runtime-ORG_NAME-ENV_NAME-1d0dc5e-sa                    1         xxd
apigee-synchronizer-ORG_NAME-ENV_NAME-1d0dc5e-sa               1         xxd
apigee-udca-ORG_NAME-ENV_NAME-1d0dc5e-sa                       1         xxd
apigee-watcher-ORG_NAME-cb84b88                                  1         xxd

其中：ORG_NAME 和 ENV_NAME 可以是组织和环境名称的缩短版本。

1. 将 Workload Identity 角色添加到每个服务账号：

   gcloud iam service-accounts add-iam-policy-binding \
     --role roles/iam.workloadIdentityUser \
     --member "serviceAccount:$PROJECT_ID.svc.id.goog[$NAMESPACE/$KSA_NAME]" \
     GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com
   

   例如，如果为 Apigee Synchronizer 设置权限，请运行以下命令：

   export KSA_NAME=$(kubectl get sa -n apigee -l app=apigee-synchronizer,env=$ENV_NAME,org=$ORG_NAME --output=jsonpath={.items..metadata.name})
   

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

2. 使用 GSA 详细信息为每个 KSA 添加注释：

   kubectl annotate serviceaccount \
     --namespace $NAMESPACE \
     $KSA_NAME \
    iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com
   

   例如，如果为 Apigee Synchronizer 设置权限，请运行以下命令：

   export KSA_NAME=$(kubectl get sa -n apigee -l app=apigee-synchronizer,env=$ENV_NAME,org=$ORG_NAME --output=jsonpath={.items..metadata.name})
   

   kubectl annotate serviceaccount --namespace $NAMESPACE $KSA_NAME iam.gke.io/gcp-service-account=apigee-sync@$PROJECT_ID.iam.gserviceaccount.com
   

3. 验证相关步骤是否奏效：

   gcloud config set project $PROJECT_ID
   

   kubectl run --rm -it --image google/cloud-sdk:slim --serviceaccount $KSA_NAME --namespace $NAMESPACE workload-identity-test -- gcloud auth list
   

   如果没有看到命令提示符，请尝试按 Enter 键。

   如果步骤正确运行，您应该会看到如下所示的响应：

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

4. 如果要从先前的安装升级，请清理包含服务账号私钥的 Secret：

   kubectl delete secrets -n $NAMESPACE $(k get secrets -n $NAMESPACE | grep svc-account | awk '{print $1}')
   

5. 检查日志：

   kubectl logs -n $NAMESPACE -l app=apigee=synchronizer,env=$ENV_NAME,org=$ORG_NAME apigee-synchronizer