为 Apigee Hybrid 安装 Apigee Operator for Kubernetes

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

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

如果您尚未使用 Apigee Hybrid，请参阅安装 Apigee Operator for Kubernetes，以为 Apigee 安装 Apigee Operator for Kubernetes。

准备工作

在开始之前，请确保您具备以下各项：

所需的角色

如需获得设置安装和使用 Apigee Operator for Kubernetes 所需资源所需的权限，请让您的管理员为您授予组织的以下 IAM 角色：

  • 创建和管理服务账号：Service Account Admin (roles/iam.serviceAccountAdmin)
  • 创建和管理 Apigee 资源：Apigee Admin (roles/apigee.admin)

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

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

所需的设置任务

在安装 Apigee Operator for Kubernetes 之前，务必先完成以下任务，以设置使用该功能所需的资源：

  1. 安装 1.15.0 版或更高版本的 Apigee Hybrid。如需获取安装 Apigee Hybrid 的说明，请参阅概览。
  2. 在支持 Istio 网关的云服务提供商（例如 Google Cloud、Azure 或 Amazon）上创建 Kubernetes 集群。
  3. 将 Istio 网关安装到您的 K8s 集群中：
    • 对于 GKE 上的集群： 
      kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml
curl -L https://istio.io/downloadIstio | sh -
cd 1.6.11-asm.1
export PATH=$PWD/bin:$PATH
istioctl install --set profile=minimal --set values.global.platform=gke -y
    • 对于其他提供商上的集群： 
      kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml
curl -L https://istio.io/downloadIstio | sh -
cd 1.6.11-asm.1
export PATH=$PWD/bin:$PATH
istioctl install --set profile=minimal -y
  4. 将 Istio 网关部署到您的 Kubernetes 集群中。
    1. 创建名为 gateway.yaml 的文件，其中包含以下内容，以部署包含相应设置的 Istio 网关： 
      #gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: istio-gateway
  namespace: default
  annotations:
    service.beta.kubernetes.io/port_80_health-probe_protocol: tcp
spec:
  gatewayClassName: istio
  listeners:
  - name: default
    hostname: "*.httpbin.com"
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: All
    2. 使用以下命令将该文件应用于您的集群：
      kubectl apply -f gateway.yaml

验证 Istio 网关设置（可选）

在本指南中，我们建议您在默认命名空间中部署一个 httpbin 应用示例，以测试您部署的网关。

  1. 将后端应用部署到 Kubernetes 集群，以测试网关。
    1. 创建名为 target.yaml 的新文件，并将以下内容添加到该新文件中
      kubectl apply -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: httpbin
---
apiVersion: v1
kind: Service
metadata:
  name: httpbin
  labels:
    app: httpbin
    service: httpbin
spec:
  ports:
  - name: http
    port: 8000
    targetPort: 8080
  selector:
    app: httpbin
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: httpbin
spec:
  replicas: 1
  selector:
    matchLabels:
      app: httpbin
      version: v1
  template:
    metadata:
      labels:
        app: httpbin
        version: v1
    spec:
      serviceAccountName: httpbin
      containers:
      - image: docker.io/mccutchen/go-httpbin:v2.15.0
        imagePullPolicy: IfNotPresent
        name: httpbin
        ports:
        - containerPort: 8080
EOF
    2. 将 HTTPRoute 资源部署到集群，以将来自网关的流量映射到您的后端服务。

      在本指南中，我们建议您按照创建 HTTPRoute 中的步骤部署外部网关和 HTTPRoute。

      如需详细了解 HTTPRoute 资源，请参阅部署 HTTPRoute（适用于内部网关）或创建 HTTPRoute（适用于外部网关）。

      1. 按照创建 HTTPRoute 中的说明，使用以下 yaml 配置创建 HTTPRoute：
        apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-bin-route
  namespace: default
spec:
  parentRefs:
  - name: istio-gateway
    namespace: default
  hostnames: ["example.httpbin.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /get
    backendRefs:
    - name: httpbin
      port: 8000
      2. 将该文件应用于集群： 
        kubectl apply -f httproute.yaml
    3. 验证 GKE 网关设置，以确认其运行状况是否符合预期。
      1. 使用以下命令获取网关详情
        kubectl get gateway global-ext-lb1

        您应该会看到类似如下所示的输出：

        NAME            CLASS   ADDRESS        PROGRAMMED   AGE
istio-gateway   istio   34.54.193.72   True         11d

        确认已为网关分配 IP 地址，并且 PROGRAMMED 的值为 True。

      2. 描述网关以确认路由已关联：
        kubectl describe gateway istio-gateway

        输出应类似如下所示：

        ...
  Listeners:
    Attached Routes: 1
    Conditions:
      Last Transition Time:  2024-10-03T03:10:17Z
...

        确认“关联的路由”的值为 1，表示路由已关联。

      3. 向网关发送请求
        curl http://GATEWAY_IP_ADDRESS/get \
  -H "Host: example.httpbin.com"

        其中：GATEWAY_IP_ADDRESS 是网关的 IP 地址。您可以使用以下命令检索网关 IP 地址，其中 GATEWAY_NAME 是网关的名称：

        kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME -o=jsonpath="{.status.addresses.value}"

        例如：

        curl http://34.54.193.72/get -H "Host: example.httpbin.com"

        响应应该类似以下内容：

        {
    "args": {},
    "headers": {
      "Accept": "*/*",
      "Host": "http://example.httpbin.com",
      "User-Agent": "curl/8.7.1",
      "X-Cloud-Trace-Context": "2bb8a80e29e80662ff9cb89971c447d9/13083106619927322701"
    },
    "origin": "67.164.1.10,34.54.193.72",
    "url": "http://example.httpbin.com/get"
}

    安装 Apigee Operator for Kubernetes

    此过程介绍了安装和配置 Apigee Operator for Kubernetes 所需的步骤。

    安装和配置 Apigee Operator for Kubernetes

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

    1. 设置环境变量。
    2. 创建和配置 APIM 服务账号。
    3. 安装 Apigee Operator for Kubernetes。
    4. 创建 Apigee Hybrid 环境。
    5. 使用 Helm 安装 Apigee Hybrid 环境。

    设置环境变量

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

    export PROJECT_ID=PROJECT_ID
export APIGEE_ORG=APIGEE_ORG

    其中：

    • PROJECT_ID 是您的 Apigee Hybrid 实例所在项目的 ID。
    • APIGEE_ORG 是您的 Apigee Hybrid 实例的组织名称。

    使用以下命令确认环境变量是否设置正确：

    echo $PROJECT_ID $APIGEE_ORG

    创建和配置 APIM 服务账号

    创建服务账号以连接到 Apigee Hybrid 配置平面。

    1. 创建 apigee-apim-gsa 服务账号以连接到 Google Cloud 服务
      2. gcloud iam service-accounts create apigee-apim-gsa
    2. 使用以下命令向您创建的服务账号授予 Apigee Admin 角色。必须拥有此角色才能创建和管理 Apigee 资源 
      gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
  --role "roles/apigee.admin"
    3. 下载服务账号的相应 JSON 密钥文件。
      1. 使用以下命令创建并下载 $PROJECT_ID-apigee-apim-gsa.json 密钥文件： 
        gcloud iam service-accounts keys create $PROJECT_ID-apigee-apim-gsa.json \
  --iam-account=apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com
  --project=$PROJECT_ID
      2. 验证文件是否已正确下载： 
        ls $PROJECT_ID-apigee-apim-gsa.json

    安装 Apigee Operator for Kubernetes

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

    1. 为 Apigee Operator for Kubernetes 创建命名空间 
      kubectl create namespace apim
    2. 安装 Apigee Operator for Kubernetes 自定义资源定义 (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.1.0 \
  --atomic
    3. 安装 Apigee Operator for Kubernetes：
      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.1.0 \
  --set serviceAccount=apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com \
  --set apigeeOrg=$APIGEE_ORG \
  --set apigeeEnv=ENV_NAME \
  --set-file serviceAccountKeyFileContent=$PROJECT_ID-apigee-apim-gsa-key.json \
  --atomic

      其中，ENV_NAME 是您要在其中安装 Apigee Operator for Kubernetes 的 Apigee Hybrid 环境的名称。

    4. 确认安装已成功完成： 
      helm list -n apim

      输出应类似如下所示：

      NAME  NAMESPACE  REVISION  UPDATED  STATUS  CHART  APP VERSION
apigee-apim-crds  apim  1  2025-09-01 00:17:03.399810627 +0000 UTC  deployed  apigee-apim-operator-crds-1.1.0  1.1.0
apigee-apim-operator  apim  1  2025-09-01 00:15:00.362829981 +0000 UTC  deployed  apigee-apim-operator-helm-1.1.0  1.1.0
    5. 确认 Kubernetes 服务账号 (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
    6. 确认 Apigee Operator for Kubernetes 已在集群的 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”，请参阅“排查 Apigee Operator for Kubernetes 问题”，以排查安装问题。

    创建 Apigee Hybrid 环境

    如要在 Apigee Hybrid 中使用 Apigee Operator for Kubernetes，您必须创建一个带有特殊标志的环境，以实现服务扩展程序。

    1. 获取令牌以向 Apigee API 进行身份验证。

      在命令行中，获取 gcloud 身份验证凭据，如以下示例所示：

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

      如需检查是否已填充令牌，请使用 echo，如以下示例所示：

      echo $TOKEN

      这应该会以编码字符串的形式显示令牌。

      如需了解详情，请参阅 gcloud 命令行工具概览。

    2. 使用以下命令之一创建环境：
      • 对于 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_DISPLAY_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" : "ENV_TYPE",
  "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 Hybrid 安装说明中的创建环境部分。

    3. 使用以下命令创建环境组： 
      curl -i -X POST -H "Authorization: Bearer $TOKEN"  "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/envgroups" -H "Content-Type:application/json" -d '{
     "name": "'"$ENV_GROUP"'",
     "hostnames":["'"$DOMAIN"'"]
   }'

      其中：

      • ENV_GROUP（必需）环境名称可以包含小写字母、短划线和数字，并且必须以小写字母开头。此名称将用作标识符，创建后便无法更改。
      • DOMAIN（必需）这是部署到该环境组中环境的所有代理都将使用的主机名。这应该是您管理的网域。地址可以是网域本身（例如 example.com），也可以包含子网域（例如 my-proxies.example.com）。如果您没有托管网域，则可以暂时输入占位符。您稍后可以更改网域地址。

      如需了解详情，请参阅 Apigee Hybrid 安装说明中的创建环境组部分。

    4. 使用以下命令将环境附加到您刚创建的环境组： 
      curl -i -X POST -H "Authorization: Bearer $TOKEN"  "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/envgroups/$ENV_GROUP/attachments" -H "Content-Type:application/json" -d '{
     "environment": "'"$ENV_NAME"'",
   }'

    使用 Helm 安装 Apigee Hybrid 环境

    在 Apigee Hybrid 集群中安装新环境的过程与在集群中安装其他环境的过程类似。这是将新环境和环境组详细信息添加到已安装 Apigee Hybrid 的 Kubernetes 集群所必需的。

    1. 使用以下命令为环境组网域生成 TLS 证书： 
      openssl req -nodes -new -x509 -keyout $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/certs/keystore_$ENV_GROUP.key -out $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/certs/keystore_$ENV_GROUP.pem -subj "/CN=$DOMAIN" -addext "subjectAltName = DNS:$DOMAIN" -days 3650

      其中：

      • APIGEE_HELM_CHARTS_HOME （必需）在 Apigee Hybrid 安装期间下载 Apigee Helm 图表的目录。
    2. 使用以下命令对 TLS 公共证书进行 Base64 编码： 
      cat $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/certs/keystore_$ENV_GROUP.pem | base64 -w0 > $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/certs/keystore_$ENV_GROUP.pem.base64
    3. 使用以下条目更新 overrides.yaml 文件中的 envs 部分 
      - name: ENV_NAME
  serviceAccountPaths:
    # Provide the path relative to the apigee-env chart directory.
    synchronizer: SYNCHRONIZER_SERVICE_ACCOUNT_FILEPATH
    # For example: "PROJECT_ID-apigee-synchronizer.json"
    runtime: RUNTIME_SERVICE_ACCOUNT_FILEPATH
    # For example: "PROJECT_ID-apigee-runtime.json"
    udca: UDCA_SERVICE_ACCOUNT_FILEPATH
    # For example: "PROJECT_ID-apigee-udca.json"

      其中，*_SERVICE_ACCOUNT_FILEPATH （必需）是您在 Apigee Hybrid 安装期间使用的服务账号的 JSON 密钥文件；如需了解详情，请参阅 Apigee Hybrid 安装说明中的创建替换文件部分。

    4. 在 overrides.yaml 文件中的 virtualhosts 下添加以下条目 
      - name: 
  selector:
    app: apigee-ingressgateway
    ingress_name: INGRESS_NAME
  sslCertPath: certs/keystore_$ENV_GROUP.pem
  sslKeyPath: certs/keystore_$ENV_GROUP.key

      其中，INGRESS_NAME （必需）是部署的 Apigee 入站网关的名称；如需了解详情，请点击此处。

    5. 安装环境和环境组

      1. 安装环境。

        一次只能安装一个环境。使用 --set env=ENV_NAME 指定环境。如果您已在 shell 中设置 $ENV_NAME 环境变量，则可以在以下命令中使用该变量：

        试运行：

        helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set env=$ENV_NAME \
  -f overrides.yaml \
  --dry-run=server

          ENV_RELEASE_NAME 是用于跟踪 apigee-env 图表的安装和升级情况的名称。此名称必须与安装中的其他 Helm 版本名称不同。 通常，这与 ENV_NAME 相同。但是，如果环境与环境组具有相同的名称，则您必须为环境和环境组使用不同的版本名称，例如 dev-env-release 和 dev-envgroup-release。如需详细了解 Helm 中的版本，请参阅 Helm 文档中的三大概念。

        安装图表：

        helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set env=$ENV_NAME \
  -f overrides.yaml

        通过检查相应环境的状态来验证它已启动并正在运行：

        kubectl -n APIGEE_NAMESPACE get apigeeenv

        NAME                    STATE       AGE   GATEWAYTYPE
apigee-org1-dev-1       running     2d
      2. 安装环境组 (virtualhosts)。
        1. 一次只能安装一个环境组 (virtualhost)。使用 --set envgroup=ENV_GROUP 指定环境组。如果您已在 shell 中设置 $ENV_GROUP 环境变量，则可以在以下命令中使用该变量。对 overrides.yaml 文件中提到的每个环境组重复运行以下命令：

          试运行：

          helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set envgroup=$ENV_GROUP \
  -f overrides.yaml \
  --dry-run=server

            ENV_GROUP_RELEASE_NAME 是用于跟踪 apigee-virtualhosts 图表的安装和升级情况的名称。此名称必须与安装中的其他 Helm 版本名称不同。通常，这与 ENV_GROUP 相同。但是，如果环境组与安装中的环境具有相同的名称，则必须为环境组和环境使用不同的版本名称，例如 dev-envgroup-release 和 dev-env-release。如需详细了解 Helm 中的版本，请参阅 Helm 文档中的三大概念。

          安装图表：

          helm upgrade $ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set envgroup=$ENV_GROUP \
  -f overrides.yaml

      您的 Apigee Hybrid 组织现在已准备就绪，并包含用于测试服务扩展程序的新环境。

      继续执行创建 APIMExtensionPolicy 中的步骤以创建扩展程序政策。