Apigee ハイブリッドのバージョン 1.3.6 へのアップグレード

バージョン 1.3.6 へのアップグレードの概要

以降のセクションでは、Apigee Hybrid のアップグレード手順を次の順番で説明します。

  1. 準備
    1. サービス アカウントを作成して更新する。
    2. 環境グループを計画する。
    3. オーバーライド ファイルをコピーして更新する。
  2. Istio と cert-manager をアップグレードする。
  3. ハイブリッド ランタイム バージョン 1.3 をインストールする。
  4. クリーンアップする。

前提条件

準備

  1. （推奨）バージョン 1.2 の $APIGEECTL_HOME/ ディレクトリのバックアップを作成します。次に例を示します。 
    tar -czvf $APIGEECTL_HOME/../apigeectl-v1.2-backup.tar.gz $APIGEECTL_HOME
  2. （推奨）Cassandra のバックアップと復元の手順に従って Cassandra データベースをバックアップします。
  3. Kubernetes プラットフォームをアップグレードする方法は次のとおりです。ヘルプが必要な場合は、プラットフォームのドキュメントをご覧ください。
    プラットフォーム アップグレード後のバージョン
    GKE 1.15.x
    Anthos 1.5
    AKS Anthos アタッチ クラスタを使用する 1.16.x
  4. ハイブリッド インストールで Apigee Connect を使用していない場合は、Apigee Connect を有効にします。
    1. Apigee Connect API が有効になっていることを確認します。
      gcloud services list | grep apigeeconnect

apigeeconnect.googleapis.com         Apigee Connect API
    2. 有効になっていない場合は、この API を有効にします。
      gcloud services enable apigeeconnect.googleapis.com --project $PROJECT_ID

      ここで、$PROJECT_ID は Google Cloud プロジェクト ID です。

    3. 次の例のように、コマンドラインで gcloud 認証情報を取得します。

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

      トークンにデータが入力されていることを確認するには、次の例のように echo を使用します。

      echo $TOKEN

      エンコードされた文字列としてトークンが表示されるはずです。

      詳細については、gcloud コマンドライン ツールの概要をご覧ください。

    4. 組織で Apigee Connect が有効になっていることを確認します。
      curl -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"

      ここで、$ORG_NAME は組織の ID です。

      出力を確認します。

            "name" : "features.mart.connect.enabled",
      "value" : "true"

      Apigee Connect が有効になっています。

    5. Apigee Connect が有効になっていない場合は、Apigee Connect エージェントのロールを MART サービス アカウントに割り当てます。
      gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:apigee-mart@$PROJECT_ID.iam.gserviceaccount.com \
  --role roles/apigeeconnect.Agent
    6. 次のコマンドで Apigee Connect を有効にします。
      curl -H "Authorization: Bearer $TOKEN" -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "name" : "'"$ORG_NAME"'",
    "properties" : {
      "property" : [ {
        "name" : "features.hybrid.enabled",
        "value" : "true"
      }, {
        "name" : "features.mart.connect.enabled",
        "value" : "true"
      } ]
    }
  }' \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"

      出力に次の 2 つのプロパティが含まれいれば、Apigee Connect は有効になっています。

            {
        "name": "features.mart.connect.enabled",
        "value": "true"
      },
      {
        "name": "features.hybrid.enabled",
        "value": "true"
      }
  5. apigee-watcher サービス アカウントを作成します。Apigee Watcher は、v1.3 で導入された新しいサービス アカウントです。Synchronizer は組織レベルの変更を考慮して、それらの変更を適用して Istio Ingress を構成します。

    メインのハイブリッド ディレクトリから: 

    ./tools/create-service-account apigee-watcher ./service-accounts
  6. Apigee ランタイム エージェントのロールを Watcher サービス アカウントに割り当てます。
    gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:apigee-watcher@$PROJECT_ID.iam.gserviceaccount.com \
  --role roles/apigee.runtimeAgent

    ここで、PROJECT_ID は Google Cloud プロジェクト ID です。サービス アカウントのメールアドレスがこのパターンと異なる場合は、適宜置き換えます。

    出力には、すべてのサービス アカウントとそれらのロールのリストが含まれているはずです。

      ...
- members:
  - serviceAccount:apigee-watcher@hybrid13rc5.iam.gserviceaccount.com
  role: roles/apigee.runtimeAgent
  ...
  7. 環境グループのルーティングを計画します。Apigee ハイブリッド 1.3 では、routingRules ではなく、環境グループでベースパス ルーティングを管理します。ハイブリッド構成で routingRules を使用している場合は、ルーティングを複製するように環境を設計します。

    環境グループを 1 つ以上作成する必要があります。

    環境グループについてをご覧ください。

  8. オーバーライド ファイルを更新します。
    1. オーバーライド ファイルのコピーを作成します。
    2. gcp と k8sCluster スタンザを更新します。

      ハイブリッド バージョン 1.3 では、次の構成プロパティが置き換えられました。

      • gcpRegion が gcp:region に代わりました。
      • gcpProjectID が gcp:projectID に代わりました。
      • gcpProjectIDRuntime が gcp:gcpProjectIDRuntime に代わりました。
      • k8sClusterName が k8s:clusterName に代わりました。
      • k8sClusterRegion が k8s:clusterRegion に代わりました。

      たとえば、次の構造で

      gcpRegion: gcp region
gcpProjectID: gcp project ID
gcpProjectIDRuntime: gcp project ID

k8sClusterName: name
k8sClusterRegion: region

      次のように置き換えます。

      gcp:
 projectID: gcp project ID
 region: gcp region
 gcpProjectIDRuntime: gcp project ID # optional. This is only required if you
                                       # want logger/metrics data to be sent in
                                       # different gcp project.

k8sCluster:
 name: gcp project ID
 region: gcp region
    3. オーバーライド ファイルに一意のインスタンス ID がない場合は、追加します。
      # unique identifier for this installation. 63 chars length limit
instanceID: ID

      ID は、このハイブリッド インストールの一意の識別子です（「my-hybrid-131-installation」や「acmecorp-hybrid-131」など）。

    4. オーバーライド ファイルに Watcher（apigee-watcher）サービス アカウントを追加します。
      # Note: the SA should have the "Apigee Runtime Agent" role
watcher:
 serviceAccountPath: "service account file"
    5. オーバーライド ファイルに Metrics（apigee-metrics）サービス アカウントを追加します。
      metrics:
 serviceAccountPath: "service account file"
    6. virtualhosts: スタンザを更新して、routingRules を実際の環境グループに置き換えます。
      1. -name: 名前を実際の環境グループの名前に置き換えます。環境グループごとに 1 つずつ複数の名前エントリを作成できます。
      2. hostAliases:[] この行を削除します。
      3. sslCertPath: エントリと sslKeyPath: エントリを保持または追加します。
      4. すべての routingRules エントリを削除します。

      次に例を示します。

      virtualhosts:
  - name: default
    hostAliases:
      - "*.acme.com"
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
    routingRules:
      - paths:
        - /foo
        - /bar
      - env: my-environment

      展開後:

      virtualhosts:
  - name: example-env-group
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
    7. mart スタンザと connectAgent: スタンザを更新します。
      1. mart: で、hostAlias:、sslCertPath:、sslKeyPath: のエントリを削除します。
      2. connectAgent: スタンザを追加します。
      3. connectAgent: の下に serviceAccountPath: エントリを追加し、Apigee Connect エージェントのロールが割り当てられているサービス アカウント（通常は MART サービス アカウント）のパスを指定します。

      次に例を示します。

      mart:
  hostAlias: "mart.apigee-hybrid-docs.net"
  serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json
  sslCertPath: ./certs/fullchain.pem
  sslKeyPath: ./certs/privkey.key

      以下のようになります。

      mart:
  serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json

connectAgent:
  serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json

Istio と cert-manager をアップグレードする

Apigee ハイブリッド バージョン 1.3 では、証明書と Anthos Service Mesh（ASM）バージョン 1.5.7 以降で提供される Istio ディストリビューションの管理と検証を行い、ランタイム Ingress ゲートウェイの作成と管理を行うために、cert-manager v0.14.2 が必要です。

Istio 1.4.6 を ASM 1.5.7 以降にアップグレードする

  1. ダウンタイムを最小限に抑えるために、Istio のデプロイと HPA に 2 つ以上のレプリカが必要です。次のコマンドを実行して、レプリカの数を確認します。
    kubectl -n istio-system get deployments # list of deployments
kubectl -n istio-system get hpa # list of hpa
  2. レプリカが 1 つしかないデプロイを編集し、replicas: を 2 以上に変更します。
    kubectl -n istio-system edit deployment name

    次に例を示します。

    spec:
  progressDeadlineSeconds: 600
  replicas: 2
  3. レプリカが 1 つしかない HPA を編集し、minReplicas: を 2 以上に変更します。
    kubectl -n istio-system edit hpa name

    次に例を示します。 

    spec:
  maxReplicas: 5
  minReplicas: 2
  4. ASM をダウンロードしてインストールするの手順に従って、ASM をダウンロードしてインストールします。
  5. インストールが完了したら、version コマンドを実行して、1.5.x が正しくインストールされていることを確認します。
    ./bin/istioctl version

client version: 1.5.8-asm.0
apigee-mart-ingressgateway version:
citadel version: 1.4.6
galley version: 1.4.6
ingressgateway version: 1.5.8-asm.0
pilot version: 1.4.6
policy version: 1.4.6
sidecar-injector version: 1.4.6
telemetry version: 1.4.6
pilot version: 1.5.8-asm.0
data plane version: 1.4.6 (1 proxies), 1.5.8-asm.0 (2 proxies)

cert-manager をアップグレードする

  1. 現在の cert-manager のデプロイを削除します。
    kubectl delete -n cert-manager deployment cert-manager cert-manager-cainjector cert-manager-webhook
  2. Kubernetes のバージョンを確認します。
    kubectl version
  3. 次のコマンドを実行して、Jetstack から cert-manager をインストールします。
    kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.2/cert-manager.yaml

ハイブリッド ランタイムをインストールする

  1. 最新のバージョン番号を変数に保存します。
    export VERSION=$(curl -s \
    https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt?ignoreCache=1)
  2. 変数にバージョン番号が挿入されていることを確認します。別のバージョンを使用する場合は、そのバージョンを環境変数に保存します。次に例を示します。
    echo $VERSION
  1.3.6

  3. ご使用のオペレーティング システムに対応したリリース パッケージをダウンロードします。

    Mac 64 ビット:

    curl -LO \
    https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_mac_64.tar.gz

    Linux 64 ビット:

    curl -LO \
    https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_64.tar.gz

    Mac 32 ビット:

    curl -LO \
    https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_mac_32.tar.gz

    Linux 32 ビット:

    curl -LO \
    https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_32.tar.gz
  4. 現在の apigeectl/ ディレクトリをバックアップ ディレクトリ名に変更します。次に例を示します。
    mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/

  5. ダウンロードした gzip ファイルの内容をハイブリッドのベース ディレクトリに展開します。次に例を示します。

    tar xvzf filename.tar.gz -C hybrid-base-directory
  6. cd でベース ディレクトリに移動します。

  7. デフォルトでは、tar の内容が展開されるディレクトリの名前には、バージョンとプラットフォームが含まれています。例: ./apigeectl_1.0.0-f7b96a8_linux_64。このディレクトリの名前を apigeectl に変更します。

    mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl
  8. apigee-system から apigee-resources-install ジョブを削除します。
    kubectl -n apigee-system delete job apigee-resources-install
  9. 古い CRD を削除します。
    kubectl delete crd apigeetelemetries.apigee.cloud.google.com
  10. externalSeedHost プロパティを使用して、オーバーライド ファイルの cassandra: スタンザを更新します。このプロパティにより、新しいハイブリッド バージョン 1.3.6 のインストールで、バージョン 1.2 のインストールと同じ Kubernetes クラスタが使用されるようになります。これは、ハイブリッド バージョン 1.2 からバージョン 1.3.6（または 1.3.6 以降）にアップグレードする場合にのみ必要になる 1 回限りのステップです。
    1. 1.2.0 のインストールをアップグレードするのと同じ Kubernetes クラスタで、既存の Cassandra の IP アドレスを探します。
      kubectl -n namespace get pods -o wide

      ここで、namespace は Apigee ハイブリッドの名前空間です。

      Cassandra ノードの IP アドレスをメモしておきます。次に例を示します。

      kubectl -n apigee get pods -o wide
NAME                  READY   STATUS    RESTARTS   AGE   IP          NODE
apigee-cassandra-0    1/1     Running   0          33d   10.68.8.24   gke-example-cluster-rc5-apigee-data-c8bf1234-09kc
apigee-cassandra-1    1/1     Running   0          16d   10.68.8.33   gke-example-cluster-rc5-apigee-data-c9221ee7-10kc
apigee-cassandra-2    1/1     Running   0          23h   10.68.9.11   gke-example-cluster-rc5-apigee-data-d123e456-11kc
    2. externalSeedHost プロパティの値を追加します。
      cassandra:
 externalSeedHost: Cassandra_node_IP

      ここで、Cassandra_node_IP は Cassandra ノードの IP です（上記の例では 10.68.8.24）。

  11. 新しい apigeectl/ ディレクトリで、apigeectl init、apigeectl apply、apigeectl check-ready を実行します。
    1. ハイブリッド 1.3.6 を初期化します。
      apigeectl init -f overrides_1.3.yaml

      ここで、overrides_1.3.yaml は編集した overrides.yaml ファイルです。

    2. ハイブリッド バージョン 1.3 では、--dry-run フラグの構文は、実行している kubectl のバージョンによって異なります。kubectl のバージョンを確認します。
      gcloud version
    3. ドライランでエラーを確認します。

      kubectl バージョン 1.17 以前:

      apigeectl apply -f overrides_1.3.yaml --dry-run=true

      kubectl バージョン 1.18 以降: 

      apigeectl apply -f overrides_1.3.yaml --dry-run=client
    4. オーバーライドを適用します。インストールの環境に応じて、本番環境またはデモ / 試験運用版環境の手順を選択して実行します。

      本番

      本番環境では各ハイブリッド コンポーネントを個別にアップグレードし、次のコンポーネントに進む前に、アップグレードされたコンポーネントのステータスを確認します。

      1. オーバーライドを適用して Cassandra をアップグレードします。 
        apigeectl apply -f overrides_1.3.yaml --datastore
      2. 完了を確認します。 
        kubectl -n namespace get pods

        ここで、namespace は Apigee ハイブリッドの名前空間です。

        Pod の準備ができた場合にのみ、次の手順に進みます。

      3. オーバーライドを適用してテレメトリー コンポーネントをアップグレードし、完了を確認します。 
        apigeectl apply -f overrides_1.3.yaml --telemetry
         
        kubectl -n namespace get pods
      4. オーバーライドを適用して、組織レベルのコンポーネント（MART、Watcher、Apigee Connect）をアップグレードし、完了を確認します。
        apigeectl apply -f overrides_1.3.yaml --org
         
        kubectl -n namespace get pods
      5. オーバーライドを適用して環境をアップグレードします。これには、次の 2 つの選択肢があります。
        • 一度に 1 つの環境にオーバーライドを適用して、完了を確認します。環境ごとにこの手順を繰り返します。
          apigeectl apply -f overrides_1.3.yaml --env env_name
           
          kubectl -n namespace get pods

          ここで、env_name はアップグレードする環境の名前です。

        • すべての環境にオーバーライドを一度に適用して、完了を確認します。 
          apigeectl apply -f overrides_1.3.yaml --all-envs
           
          kubectl -n namespace get pods

      デモ / 試験運用版

      ほとんどのデモまたは試験運用環境では、すべてのコンポーネントにオーバーライドを一度に適用できます。デモ / 試験運用版が大規模で複雑な環境、または本番環境が似ている場合や本番環境に酷似している場合は、本番環境のアップグレード手順を使用します。

      1. apigeectl apply -f overrides_1.3.yaml
      2. ステータスを確認します。 
        apigeectl check-ready -f overrides_1.3.yaml

      詳細については、GKE ハイブリッドの設定 - ステップ 5: GKE にハイブリッドをインストールするをご覧ください。

    5. ハイブリッド 1.3 を設定して実行したら、すべての Cassandra ノード（古いノードと新しいノード）が同じ Cassandra クラスタに含まれていることを確認します。いずれかの Cassandra ノードで次のコマンドを実行します。
      kubectl -n namespace get pods
kubectl -n namespace exec old Cassandra pod -- nodetool status

      次の出力例では、10.68.8.24 はバージョン 1.2.0 から出力され、externalSeedHost として使用したノード IP です。10.68.7.11 はバージョン 1.3.6 から出力されます。

      Datacenter: dc-1
================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
--  Address     Load        Tokens       Owns (effective)  Host ID                               Rack
UN  10.68.8.24  379.41 KiB  256          50.8%             11bbd43b-af64-464b-a96d-0d6dd0521de1  ra-1
UN  10.68.7.11  1.35 MiB    256          49.2%             0b4d9e08-f353-413a-b4a9-7d18a8d07e58  ra-1

      これらが同じクラスタ内にない場合は、externalSeedHost の値を確認してください。

    6. すべての Pod が稼働状態になったら、オーバーライド ファイルから externalSeedHost を削除し、--datastore オプションを指定して apigeectl apply を再度実行します。
      apigeectl apply --datastore -f overrides_1.3.6.yaml

    クリーンアップ

    すべての Pod が正常に稼働していて、ASM エンドポイントが新しいインストールに対して有効であることを確認したら、クリーンアップできます。

    • ハイブリッド 1.2 のリソース。
    • 古い Cassandra インスタンス。
    • Istio 1.4.6 のリソース。

    ハイブリッド 1.2.0 リソースを削除する

    1. 1.2.0 仮想ホストのルーティングの詳細を削除します。
      $APIGEECTL_HOME-v1.2/apigeectl delete -s virtualhost -f 1.2.0_overrides.yaml

      ここで、$APIGEECTL_HOME-v1.2 は apigeectl バージョン 1.2 ディレクトリをバックアップしたディレクトリです。

    2. エンドポイントが期待どおりに動作しており、すべての 1.3.0 コンポーネントが動作していることを確認したら、次のコマンドを実行してハイブリッド 1.2.0 リソースを削除します。
      $APIGEECTL_HOME-v1.2/apigeectl delete -c "mart,connect-agent,synchronizer,runtime,udca,metrics,logger" \
  -f 1.2.0_overrides.yaml

    古い Cassandra インスタンスを無効にする

    1. 新しくインストールされた apigeectl ディレクトリに cd を実行します。
    2. tools/cas_cleanup.sh スクリプトを実行します。

      このスクリプトは、Cassandra リングから古い Cassandra Pod を無効にして、古い STS を削除し、PVC を削除します。

      bash cas_cleanup.sh Apigee namespace

    Istio バージョン 1.4.6 リソースを削除する

    1. 最新の Istio v.1.4.6 リソースを削除するには、次のコマンドを実行します。
      kubectl delete all -n istio-system --selector \
  'app in (apigee-mart-istio-ingressgateway, galley, security, istio-nodeagent, istio-mixer, sidecarInjectorWebhook, istio-mixer)'
    2. Istio 1.4.6 インストールから古いジョブを削除するには、次のコマンドを実行します。
      kubectl -n istio-system delete job istio-init-crd-10-1.4.6
kubectl -n istio-system delete job istio-init-crd-11-1.4.6
kubectl -n istio-system delete job istio-init-crd-14-1.4.6

    これで完了です。Apigee ハイブリッド バージョン 1.3.6 に正常にアップグレードされました。