为 Apigee Hybrid 安装适用于 Kubernetes 的 Apigee Operator

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

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

如果您未使用 Apigee Hybrid，请参阅安装适用于 Kubernetes 的 Apigee Operator，以安装适用于 Apigee 的 Apigee Operator for Kubernetes。

准备工作

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

所需的角色

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

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

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

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

所需的设置任务

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

  1. 使用 1.15.0 版或更高版本安装 Apigee Hybrid。如需了解安装 Apigee Hybrid 的说明，请参阅概览。
  2. 在支持 Istio 网关的云提供商（例如 Google Cloud、Azure 或 Amazon）中创建 Kubernetes 集群。
  3. 将 Istio Gateway 安装到您的 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 Gateway 设置，以确认其运行状况是否符合预期。
      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"
}

    安装适用于 Kubernetes 的 Apigee 操作器

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

    安装和配置适用于 Kubernetes 的 Apigee Operator

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

    1. 设置环境变量。
    2. 创建并配置 APIM 服务账号。
    3. 安装适用于 Kubernetes 的 Apigee Operator。
    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 管理员角色。必须具有此角色才能创建和管理 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

    安装适用于 Kubernetes 的 Apigee 操作器

    安装 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. 安装适用于 Kubernetes 的 Apigee 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.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. 确认适用于 Kubernetes 的 Apigee 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，请参阅“排查 Apigee Operator for Kubernetes 问题”，以排查安装问题。

    创建 Apigee Hybrid 环境

    如需在 Apigee Hybrid 中使用适用于 Kubernetes 的 Apigee Operator，您必须创建一个带有特殊标志的环境，以用于服务扩展。

    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 以创建扩展政策。