為 Apigee Hybrid 安裝 Kubernetes 適用的 Apigee Operator

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本頁說明安裝及設定 Apigee Operator for Kubernetes 的必要步驟，以便搭配 Apigee Hybrid 使用。如要進一步瞭解使用 Apigee Operator for Kubernetes 的優點，請參閱 Apigee Operator for Kubernetes 總覽。

如果您未使用 Apigee Hybrid，請參閱「安裝 Kubernetes 適用的 Apigee Operator」，為 Apigee 安裝 Kubernetes 適用的 Apigee Operator。

事前準備

開始之前，請確認您具備以下項目：

必要的角色

如要取得設定資源的權限，以便安裝及使用 Kubernetes 適用的 Apigee Operator，請要求管理員授予您機構的下列 IAM 角色：

  • 建立及管理服務帳戶：服務帳戶管理員 (roles/iam.serviceAccountAdmin)
  • 建立及管理 Apigee 資源：Apigee 管理員 (roles/apigee.admin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

必要設定工作

安裝 Kubernetes 適用的 Apigee Operator 前，請務必完成下列工作，設定使用這項功能所需的資源：

  1. 使用 1.15.0 以上版本安裝 Apigee Hybrid。如需安裝 Apigee Hybrid 的操作說明，請參閱「大方向」。
  2. 在支援 Istio Gateway 的雲端服務供應商 (例如 Google Cloud、Azure 或 Amazon) 中建立 Kubernetes 叢集。
  3. 在 K8s 叢集中安裝 Istio Gateway：
    • 如果是 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 Gateway 部署至 Kubernetes 叢集。
    1. 建立名為 gateway.yaml 的檔案，並在其中加入下列內容，以部署 Istio Gateway： 
      #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 Gateway 設定 (選用)

在本指南中，我們建議您在預設命名空間中部署範例 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 資源部署至叢集，將流量從 Gateway 對應至後端服務。

      在本指南中，我們建議您按照「建立 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 Operator

    以下程序說明如何安裝及設定 Kubernetes 適用的 Apigee Operator。

    安裝及設定 Kubernetes 適用的 Apigee 運算子

    下列各節說明安裝及設定 Kubernetes 適用的 Apigee Operator 的必要步驟：

    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 Operator

    安裝 Kubernetes 自訂資源定義 (CRD) 和 Kubernetes 適用的 Apigee 運算子：

    1. 為 Kubernetes 適用的 Apigee Operator 建立命名空間
      kubectl create namespace apim
    2. 安裝 Kubernetes 自訂資源定義 (CRD) 的 Apigee 運算子： 
      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 運算子： 
      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，請參閱「Troubleshoot the Apigee Operator for Kubernetes」(排解 Kubernetes 適用的 Apigee 運算子問題)，排解安裝問題。

    建立 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 (必要) 環境名稱可包含小寫字母、破折號和數字，且開頭必須是小寫字母。這個名稱會做為 ID，建立後即無法變更。
      • DOMAIN (必要)：這是部署至這個群組環境的所有 Proxy 都會使用的主機名稱。這必須是您管理的網域。地址可以是網域本身 (例如 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 叢集中安裝新環境的程序，與在叢集中安裝其他環境的程序類似。這是將新環境和環境群組詳細資料新增至 Kubernetes 叢集 (已安裝 Apigee Hybrid) 的必要步驟。

    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. 使用下列指令，以 Base64 編碼 TLS 公開憑證： 
      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. 在 envs 下方更新 overrides.yaml 檔案，加入下列項目： 
      - 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. 在 virtualhosts 下的 overrides.yaml 檔案中新增下列項目 
      - name: 
  selector:
    app: apigee-ingressgateway
    ingress_name: INGRESS_NAME
  sslCertPath: certs/keystore_$ENV_GROUP.pem
  sslKeyPath: certs/keystore_$ENV_GROUP.key

      其中 INGRESS_NAME (必要) 是部署作業的 Apigee Ingress 閘道名稱，詳情請參閱這裡。

    5. 安裝環境和環境群組

      1. 安裝環境。

        一次只能安裝一個環境。使用 --set env=ENV_NAME 指定環境。如果您已在殼層中設定 $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 說明文件中的「Three big concepts」(三大概念)。

        安裝圖表：

        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. 一次只能安裝一個環境群組 (虛擬主機)。使用 --set envgroup=ENV_GROUP 指定環境群組。如果您已在殼層中設定 $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」中的程序，建立擴充功能政策。