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

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

以降のセクションで、Apigee ハイブリッドのアップグレード手順について説明します。

準備

サービスアカウントを作成して更新する。
環境グループを計画する。
オーバーライドファイルをコピーして更新する。

Istio と cert-manager をアップグレードする。
ハイブリッドランタイムバージョン 1.3 をインストールする。
クリーンアップする。

前提条件

Apigee ハイブリッドバージョン 1.2。以前のバージョンから更新する場合は、Apigee ハイブリッドバージョン 1.2 へのアップグレードをご覧ください。

準備

（推奨）バージョン 1.2 の $APIGEECTL_HOME/ ディレクトリのバックアップコピーを作成します。次に例を示します。
```
tar -czvf $APIGEECTL_HOME/../apigeectl-v1.2-backup.tar.gz $APIGEECTL_HOME
```
（推奨）Cassandra のバックアップと復元の手順に従って Cassandra データベースをバックアップします。

Kubernetes プラットフォームをアップグレードする方法は次のとおりです。ヘルプが必要な場合は、プラットフォームのドキュメントをご覧ください。

プラットフォーム	アップグレード後のバージョン
GKE	1.15.x
Anthos	1.5
AKS	1.16.x（Anthos アタッチクラスタを使用）

ハイブリッドインストールで 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
```
  ヒント: MART サービスアカウントのメールアドレスを取得する必要がある場合は、次のコマンドを実行します。
```
gcloud iam service-accounts list | grep mart
```
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"
      }
```
apigee-watcher サービスアカウントを作成します。Apigee Watcher は、v1.3 で導入された新しいサービスアカウントです。組織レベルの変更がないか Synchronizer を監視し、変更を適用して Istio Ingress を構成します。
メインのハイブリッドディレクトリから作成します。
```
./tools/create-service-account apigee-watcher ./service-accounts
```
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 です。サービスアカウントのメールアドレスがこのパターンと異なる場合は、適宜置き換えます。
ヒント: Watcher サービスアカウントのメールアドレスを取得する必要がある場合は、次のコマンドを実行します。
```
gcloud iam service-accounts list | grep watcher
```
出力には、次のようにすべてのサービスアカウントとそれらのロールのリストが含まれます。
```
  ...
- members:
  - serviceAccount:apigee-watcher@hybrid13rc5.iam.gserviceaccount.com
  role: roles/apigee.runtimeAgent
  ...
```
環境グループのルーティングを計画します。Apigee ハイブリッド 1.3 では、routingRules ではなく、環境グループでベースパスルーティングを管理します。ハイブリッド構成で routingRules を使用している場合は、ルーティングを複製するように環境を設計します。
環境グループを 1 つ以上作成する必要があります。

環境グループについてをご覧ください。
クリックすると、routingRules を置き換える環境グループの例が表示されます

この例では、overrides.yaml ファイル内の以下の routingRules で foo および bar API プロキシへのリクエストを prod-env-1 環境にルーティングし、foo-test プロキシへのリクエストを test-env 環境にルーティングします。
```
virtualhosts:
  - name: default
    hostAliases:
      - "*.acme.com"
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
    routingRules:
      - paths:
        - /foo
        - /bar
      - env: prod-env-1
      - paths:
        - foo-test
      -env: test-env
```
ハイブリッドバージョン 1.3.6 でこれを複製するには、次の手順に従います。
1. foo プロキシと bar プロキシを prod-env-1 環境にデプロイします。
2. foo-test プロキシと bar プロキシを test-env 環境にデプロイします。
3. プロキシのホストエイリアスを使用して、api.acme.com のような環境グループを作成します。
  ヒント: バージョン 1.2 で使用した仮想ホストの名前と同じ名前で環境グループを作成します。
4. overrides.yaml の virtualhosts スタンザを変更します。
  - virtualhosts:name は、環境グループの名前に置き換えます。
  - virtualhosts:routingRules を削除します。
  次に例を示します。
```
virtualhosts:
  - name: default # environment group name
    sslCertPath: ./certs/keystore.pem
    sslKeyPath: ./certs/keystore.key
```
オーバーライドファイルを更新します。

オーバーライドファイルのコピーを作成します。
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
```
オーバーライドファイルに一意のインスタンス ID がない場合は、追加します。
```
# unique identifier for this installation. 63 chars length limit
instanceID: ID
```
ID は、このハイブリッドインストールの固有識別子です（「my-hybrid-131-installation」や「acmecorp-hybrid-131」など）。
オーバーライドファイルに Watcher（apigee-watcher）サービスアカウントを追加します。
```
# Note: the SA should have the "Apigee Runtime Agent" role
watcher:
 serviceAccountPath: "service account file"
```
オーバーライドファイルに Metrics（apigee-metrics）サービスアカウントを追加します。
```
metrics:
 serviceAccountPath: "service account file"
```
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
```
mart スタンザと connectAgent: スタンザを更新します。
注: ハイブリッド 1.3 のインストールで Apigee Connect を使用する予定がない場合は、この手順をスキップして、アップグレード後に Apigee Connect でステップ 5 のヒントに従ってください。
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 以降にアップグレードする

ダウンタイムを最小限に抑えるために、Istio のデプロイと HPA に 2 つ以上のレプリカが必要です。次のコマンドを実行して、レプリカの数を確認します。
```
kubectl -n istio-system get deployments # list of deployments
kubectl -n istio-system get hpa # list of hpa
```
レプリカが 1 つしかないデプロイを編集し、replicas: を 2 以上に変更します。
```
kubectl -n istio-system edit deployment name
```
次に例を示します。
```
spec:
  progressDeadlineSeconds: 600
  replicas: 2
```
レプリカが 1 つしかない HPA を編集し、minReplicas: を 2 以上に変更します。
```
kubectl -n istio-system edit hpa name
```
次に例を示します。
```
spec:
  maxReplicas: 5
  minReplicas: 2
```
ASM をダウンロードしてインストールするの手順に沿って、ASM をダウンロードしてインストールします。

インストールが完了したら、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 をアップグレードする

現在の cert-manager のデプロイを削除します。

kubectl delete -n cert-manager deployment cert-manager cert-manager-cainjector cert-manager-webhook

Kubernetes のバージョンを確認します。
```
kubectl version
```

次のコマンドを実行して、Jetstack から cert-manager をインストールします。

kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.2/cert-manager.yaml

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

最新のバージョン番号を変数に格納します。

export VERSION=$(curl -s \
    https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt?ignoreCache=1)

変数にバージョン番号が挿入されていることを確認します。別のバージョンを使用する場合は、そのバージョンを環境変数に保存します。次に例を示します。
```
echo $VERSION
  1.3.6
```

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

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

現在の apigeectl/ ディレクトリをバックアップディレクトリ名に変更します。次に例を示します。
```
mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/ 
```
ダウンロードした gzip ファイルの内容をハイブリッドのベースディレクトリに展開します。次に例を示します。
```
tar xvzf filename.tar.gz -C hybrid-base-directory
```
cd でベースディレクトリに移動します。
デフォルトでは、tar の内容が展開されるディレクトリの名前には、バージョンとプラットフォームが含まれています。たとえば、./apigeectl_1.0.0-f7b96a8_linux_64 のようになります。このディレクトリの名前を apigeectl に変更します。
```
mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl
```
apigee-system から apigee-resources-install ジョブを削除します。
```
kubectl -n apigee-system delete job apigee-resources-install
```

古い CRD を削除します。

kubectl delete crd apigeetelemetries.apigee.cloud.google.com

externalSeedHost プロパティを使用して、オーバーライドファイルの cassandra: スタンザを更新します。このプロパティにより、新しいハイブリッドバージョン 1.3.6 のインストールでバージョン 1.2 のインストールと同じ Kubernetes クラスタが使用されるようになります。これは、ハイブリッドバージョン 1.2 からバージョン 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）。
  注: 新しい Cassandra が実行されて確認された後、以降の手順で externalSeedHost プロパティを削除します。
新しい 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 つずつコンポーネントをアップグレードすることをおすすめします。
  本番環境
  
  本番環境では、ハイブリッドコンポーネントを個別にアップグレードし、アップグレードされたコンポーネントのステータスを確認してから次のコンポーネントに進んでください。
  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 リソースを削除する
注: この手順では、バックアップされたディレクトリに apigeectl バージョン 1.2 のコマンドが必要です。apigeectl バージョン 1.2 の別のコピーをダウンロードする必要がある場合は、次のコマンドを使用します。
```
curl -LO \
    https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/1.2.0/apigeectl_your_system.tar.gz
```
your_system は、linux_32、linux_64、mac_32 または mac_64 のいずれかです。
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 リソースを削除する

注: Istio バージョン 1.4.6 リソースを削除すると、MART Ingress も削除されます。Apigee ハイブリッドバージョン 1.3 では、MART Ingress が Apigee Connect に置き換えられました。
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 に正常にアップグレードされました。

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

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

前提条件

準備

クリックすると、routingRules を置き換える環境グループの例が表示されます

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

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

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

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

本番環境

デモ / 試験運用

クリーンアップ

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

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

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

クリックすると、`routingRules` を置き換える環境グループの例が表示されます

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