3scale の移行

Red Hat 3scale API Management 2.11

3scale API Management およびそのコンポーネントの移行またはアップグレード

概要

3scale をテンプレートベースから operator ベースのインストールに移行する方法を説明します。3scale およびそのコンポーネントを最新バージョンにアップグレードするための情報についても説明します。

前書き

本ガイドでは、Red Hat 3scale API Management をテンプレートベースから operator ベースのインストールに移行するための情報、3scale インストールを 2.10 から 2.11 にアップグレードするのに必要な詳細情報、および operator ベースのデプロイメントで APIcast をアップグレードする手順について説明します。

テンプレートベースから operator ベースのデプロイメントに移行するには、3scale の移行ガイド に記載の手順を参照してください。

オンプレミス型 3scale のデプロイメントを 2.10 から 2.11 にアップグレードするには、インストールのタイプに応じて以下のガイドのいずれかを参照してください。

operator ベースのデプロイメントで APIcast をアップグレードするには、operator ベースの APIcast のアップグレードガイド に記載の手順を参照してください。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施して参ります。詳細は、CTO である Chris Wright のメッセージ をご覧ください。

第1章 3scale の移行ガイド: テンプレートベースから operator ベースのデプロイメントへ

本セクションでは、Red Hat 3scale API Management を Red Hat OpenShift 3.11 を使用するテンプレートベースのデプロイメントから Red Hat OpenShift 4.x を使用する operator ベースのデプロイメントに移行する方法について説明します。

警告

必要な条件および手順を理解するために、記載の手順を適用する前に、移行ガイド全体を読んでください。移行プロセスの手順が完了するまで、サービスの提供が中断されます。このサービス中断が生じるため、メンテナンス期間を設けるようにしてください。

1.1. 移行を行うための前提条件

3scale インストールをテンプレートベースから operator ベースのデプロイメントに移行する前に、以下のガイドを参照してデプロイメントがサポートされていることを確認してください。

1.2. 3scale のテンプレートベースから operator ベースのデプロイメントへの移行

移行前の基本セットアップは、3scale が OCP3 ドメインをポイントする設定です: 3scale.example.comocp3.example.com

3scale を Red Hat OpenShift 3.11 を使用するテンプレートベースのデプロイメントから Red Hat OpenShift 4.1 を使用する operator ベースのデプロイメントに移行するには、以下の手順に従います。

上記の手順をすべて実施すると、3scale のテンプレートベースから operator ベースのデプロイメントへの移行が完了します。

第2章 テンプレートを使用した 3scale のバージョン 2.10 からバージョン 2.11 へのアップグレード

Red Hat 3scale API Management をバージョン 2.10 からバージョン 2.11 にアップグレードするには、Open Shift 3.11 でテンプレートベースのデプロイメントを使用します。

重要

必要な条件および手順を理解するために、記載の手順を適用する前に、アップグレードガイド全体を読んでください。アップグレードプロセスの手順が完了するまで、サービスの提供が中断されます。このサービス中断が生じるため、メンテナーンス期間を設けるようにしてください。

2.1. アップグレードを行うための前提条件

本セクションでは、テンプレートベースのインストール環境において、3scale を 2.10 から 2.11 にアップグレードするのに必要な設定、タスク、およびツールについて説明します。

2.1.1. 設定

  • OpenShift 3.11 上の 3scale では、テンプレートを使用した 2.10 から 2.11 へのアップグレードパスがサポートされます。

2.1.2. 主要なタスク

  • OpenShift CLI ツールが 3scale をデプロイしたプロジェクトに設定されるようにする。
  • 3scale で使用しているデータベースのバックアップを行う。バックアップの手順は、データベースのタイプや設定により異なります。

2.1.3. ツール

アップグレードを行うには、以下のツールが必要です。

  • テンプレートを使用して OpenShift 3.11 のプロジェクトにデプロイされた 3scale 2.10
  • Bash シェル: アップグレード手順で詳細を説明するコマンドを実行します。
  • base64: シークレットの情報をエンコードおよびデコードします。
  • jq: JSON 変換用です。

2.2. テンプレートベースのインストール環境における 2.10 から 2.11 へのアップグレード

テンプレートベースのインストール環境において、3scale 2.10 を 2.11 にアップグレードするには、本セクションに記載の手順に従います。

アップグレードを開始するには、3scale がデプロイされているプロジェクトに移動します。

$ oc project <3scale-project>

続いて、以下の順序で手順を実行します。

2.2.1. 3scale プロジェクトのバックアップの作成

前の手順

なし

現在の手順

3scale プロジェクトのバックアップを作成するのに必要なアクションを以下のリストに示します。

手順

  1. 3scale で使用するデータベースに応じて、${SYSTEM_DB} を以下のいずれかの値に設定します。

    • データベースが MySQL の場合: SYSTEM_DB=system-mysql
    • データベースが PostgreSQL の場合: SYSTEM_DB=system-postgresql
  2. 既存の DeploymentConfigs でバックアップファイルを作成します。

    $ THREESCALE_DC_NAMES="apicast-production apicast-staging backend-cron backend-listener backend-redis backend-worker system-app system-memcache ${SYSTEM_DB} system-redis system-sidekiq system-sphinx zync zync-database zync-que"
    
    for component in ${THREESCALE_DC_NAMES}; do oc get --export -o yaml dc ${component} > ${component}_dc.yml ; done
  3. export all コマンドでエクスポートされるプロジェクト内のすべての既存 OpenShift リソースをバックアップします。

    $ oc get -o yaml --export all > threescale-project-elements.yaml
  4. export all コマンドでエクスポートされない追加の要素でバックアップファイルを作成します。

    $ for object in rolebindings serviceaccounts secrets imagestreamtags cm rolebindingrestrictions limitranges resourcequotas pvc templates cronjobs statefulsets hpa deployments replicasets poddisruptionbudget endpoints
    do
      oc get -o yaml --export $object > $object.yaml
    done
  5. 生成されたすべてのファイルが空ではないこと、およびそれらすべての内容が予想どおりであることを確認します。

2.2.2. 3scale のバージョン番号の更新

現在の手順

この手順では、system-environment ConfigMap の 3scale のリリースバージョン番号を 2.10 から 2.11 に更新します。AMP_RELEASE は、一部の DeploymentConfig コンテナー環境で参照される ConfigMap のエントリーです。

手順

  1. AMP_RELEASE にパッチを適用するには、以下のコマンドを実行します。

    $ oc patch cm system-environment --patch '{"data": {"AMP_RELEASE": "2.11"}}'
  2. system-environment ConfigMap の AMP_RELEASE キーの値が 2.11 であることを確認します。

    $ oc get cm system-environment -o json | jq '.data["AMP_RELEASE"]'

2.2.3. 環境変数 BACKEND_ROUTE の更新

現在の手順

このステップでは、system-app および system-sidekiq Pod から BACKEND_ROUTE 環境変数を更新し、OpenShift ルートの代わりに backend-listener Kubernetes サービスを使用します。

手順

  1. system-app DeploymentConfig を編集して、system-app pre-hook pod の変数を更新します。

    $ oc edit dc system-app

    インタラクティブなエディターセッションを開きます。.spec.strategy.rollingParams.pre.execNewPod.env 配列セクションで BACKEND_ROUTE 環境変数を見つけます。

    1. 次のエントリーを

      - name: BACKEND_ROUTE
        valueFrom:
          secretKeyRef:
            key: route_endpoint
            name: backend-listener
    2. 以下のエントリーに置き換えます。

      - name: BACKEND_ROUTE
        value: http://backend-listener:3000/internal/

      変更内容を保存し、インタラクティブエディターセッションを終了します。

  2. system-app コンテナーのエントリーを更新します。

    $ oc set env dc/system-app BACKEND_ROUTE="http://backend-listener:3000/internal/"

    このコマンドがトリガーとなり system-app が再デプロイされます。再デプロイされ、対応する新しい Pod の準備が整い、以前の Pod が終了するまで待ちます。

  3. system-sidekiq コンテナーで更新します。

    $ oc set env dc/system-sidekiq BACKEND_ROUTE="http://backend-listener:3000/internal/"

    このコマンドがトリガーとなり system-sidekiq が再デプロイされます。再デプロイされ、対応する新しい Pod の準備が整い、以前の Pod が終了するまで待ちます。

2.2.4. zync Deployment Config モニターリングアノテーションの Deployment Config アノテーションから Pod Template アノテーションへの移動

現在の手順

このステップでは、prometheus.io/port and prometheus.io/scrape のアノテーションを zync DeploymentConfig アノテーションから PodTemplate アノテーションに移動します。

手順

  1. 以下を実行して prometheus.io/port and prometheus.io/scrape アノテーションの現在の値をメモします。

    $ oc get dc zync -o json | jq .metadata.annotations
  2. zync DeploymentConfig の PodTemplate アノテーションに、このアノテーションを追加します。以下のコマンドで prometheus.io/port and prometheus.io/scrape アノテーションの値が異なる場合に、直前のコマンドで示されたように zync DeploymentConfig で現在設定されている値に置き換えてください。

    $ oc patch dc zync --patch '{"spec":{"template":{"metadata":{"annotations":{"prometheus.io/port":"9393","prometheus.io/scrape":"true"}}}}}'
  3. zync Deployment Config のアノテーションからオリジナルのアノテーションを削除します。

    $ oc annotate dc zync prometheus.io/scrape-
    $ oc annotate dc zync prometheus.io/port-

    このコマンドは zync の再デプロイメントをトリガーします。再デプロイされ、対応する新しい Pod の準備が整い、以前の Pod が終了するまで待ちます。

2.2.5. backend-cronDeployment Config のリソース要件の増加

現在の手順

3scale 2.11 の時点で、backend-cron DeploymentConfig は以前のバージョンよりも多くのメモリーを消費する可能性があります。この手順で、最大メモリーの制限値を現在の設定値よりも大きくすることができます。

3scale 2.11 で必要なbackend-cronのリソースは以下の通りです。

{
  "limits": {
	"cpu": "500m",
	"memory": "500Mi"
  },
  "requests": {
	"cpu": "100m",
	"memory": "100Mi"
  }
}

現在のbackend-cronのデプロイメントにメモリーの制限がない場合や、リソースの要件がこれよりも高い場合は、以下の手順を実行する必要はありません。

手順

  1. 以下のコマンドで、backend-cronに設定されている現在のリソース要件を確認します。

    $ oc get dc backend-cron -o json | jq .spec.template.spec.containers[0].resources

    出力が空またはNULLの場合は、リソース要求が設定されていないことを意味します。

  2. 現在のbackend-cronの必要リソースを増やすには、以下のコマンドを実行します。

    $ oc patch dc backend-cron --patch '{"spec":{"template":{"spec":{"containers":[{"name":"backend-cron","resources":{"limits":{"memory":"500Mi", "cpu": "500m"}, "requests":{"memory":"100Mi", "cpu": "100m"}}}]}}}}'

    このコマンドがトリガーとなり backend-cron が再デプロイされます。再デプロイされ、対応する新しい Pod の準備が整い、以前の Pod が終了するまで待ちます。

2.2.6. 3scale イメージのアップグレード

現在の手順

この手順では、アップグレードプロセスに必要な 3scale イメージを更新します。

2.2.6.1. system イメージのパッチ

  1. 新しいイメージストリームタグを作成します。

    $ oc patch imagestream/amp-system --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "AMP system 2.11"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/system-rhel7:3scale2.11"}, "name": "2.11", "referencePolicy": {"type": "Source"}}}]'
  2. 手順を進めるには、ご自分の 3scale デプロイメントで使用しているデータベースを考慮してください。

2.2.6.1.1. システムイメージへのパッチ適用: 3scale が Oracle Database を使用する場合
  1. Oracle データベースを搭載した 3scale のシステムイメージのパッチ適用を開始するには、システムイメージの構築の手順 1、2、4、8 を実行します。
  2. system-app ImageChange トリガーにパッチを適用します。

    1. 古い 2.10-oracle トリガーを削除します。

      $ oc set triggers dc/system-app --from-image=amp-system:2.10-oracle --containers=system-master,system-developer,system-provider --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/system-app --from-image=amp-system:2.11-oracle --containers=system-master,system-developer,system-provider

      これがトリガーとなり system-app が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

  3. system-sidekiq ImageChange トリガーにパッチを適用します。

    1. 古い 2.10-oracle トリガーを削除します。

      $ oc set triggers dc/system-sidekiq --from-image=amp-system:2.10-oracle --containers=system-sidekiq,check-svc --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/system-sidekiq --from-image=amp-system:2.11-oracle --containers=system-sidekiq,check-svc

      これがトリガーとなり system-sidekiq が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

  4. system-sphinx ImageChange トリガーにパッチを適用します。

    1. 古い 2.10-oracle トリガーを削除します。

      $ oc set triggers dc/system-sphinx --from-image=amp-system:2.10-oracle --containers=system-sphinx,system-master-svc --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/system-sphinx --from-image=amp-system:2.11-oracle --containers=system-sphinx,system-master-svc

      これがトリガーとなり system-sphinx が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

  5. 3scale をスケールダウンした場合は、元に戻します。
2.2.6.1.2. システムイメージへのパッチ適用: 3scale がその他のデータベースを使用する場合
  1. system-app ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/system-app --from-image=amp-system:2.10 --containers=system-master,system-developer,system-provider --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/system-app --from-image=amp-system:2.11 --containers=system-master,system-developer,system-provider

      これがトリガーとなり system-app が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

  2. system-sidekiq ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/system-sidekiq --from-image=amp-system:2.10 --containers=system-sidekiq,check-svc --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/system-sidekiq --from-image=amp-system:2.11 --containers=system-sidekiq,check-svc

      これがトリガーとなり system-sidekiq が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

  3. system-sphinx ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/system-sphinx --from-image=amp-system:2.10 --containers=system-sphinx,system-master-svc --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/system-sphinx --from-image=amp-system:2.11 --containers=system-sphinx,system-master-svc

      これがトリガーとなり system-sphinx が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

2.2.6.2. apicast イメージのパッチ

  1. amp-apicast イメージストリームにパッチを適用します。

    $ oc patch imagestream/amp-apicast --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "AMP APIcast 2.11"}, "from": {"kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/apicast-gateway-rhel8:3scale2.11"}, "name": "2.11", "referencePolicy": {"type": "Source"}}}]'
  2. apicast-staging ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/apicast-staging --from-image=amp-apicast:2.10 --containers=apicast-staging --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/apicast-staging --from-image=amp-apicast:2.11 --containers=apicast-staging

      これがトリガーとなり apicast-staging が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

  3. apicast-production ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/apicast-production --from-image=amp-apicast:2.10 --containers=apicast-production,system-master-svc --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/apicast-production --from-image=amp-apicast:2.11 --containers=apicast-production,system-master-svc

      これがトリガーとなり apicast-production が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

2.2.6.3. backend イメージのパッチ

  1. amp-backend イメージストリームにパッチを適用します。

    $ oc patch imagestream/amp-backend --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "AMP Backend 2.11"}, "from": {"kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/backend-rhel8:3scale2.11"}, "name": "2.11", "referencePolicy": {"type": "Source"}}}]'
  2. backend-listener ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/backend-listener --from-image=amp-backend:2.10 --containers=backend-listener --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/backend-listener --from-image=amp-backend:2.11 --containers=backend-listener

      これがトリガーとなり backend-listener が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

  3. backend-worker ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/backend-worker --from-image=amp-backend:2.10 --containers=backend-worker,backend-redis-svc --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/backend-worker --from-image=amp-backend:2.11 --containers=backend-worker,backend-redis-svc

      これがトリガーとなり backend-worker が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

  4. backend-cron ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/backend-cron --from-image=amp-backend:2.10 --containers=backend-cron,backend-redis-svc --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/backend-cron --from-image=amp-backend:2.11 --containers=backend-cron,backend-redis-svc

      このコマンドがトリガーとなり backend-cron が再デプロイされます。再デプロイされ、対応する新しい Pod の準備が整い、以前の Pod が終了するまで待ちます。

2.2.6.4. zync イメージへのパッチ適用

  1. amp-zync イメージストリームにパッチを適用します。

    $ oc patch imagestream/amp-zync --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "AMP Zync 2.11"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/zync-rhel8:3scale2.11"}, "name": "2.11", "referencePolicy": {"type": "Source"}}}]'
  2. zync ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/zync --from-image=amp-zync:2.10 --containers=zync,zync-db-svc --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/zync --from-image=amp-zync:2.11 --containers=zync,zync-db-svc

      これがトリガーとなり zync が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

  3. zync-que ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/zync-que --from-image=amp-zync:2.10 --containers=que --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/zync-que --from-image=amp-zync:2.11 --containers=que

      これがトリガーとなり zync-que が再デプロイされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

2.2.6.5. system-memcached イメージのパッチ

  1. system-memcached イメージストリームにパッチを適用します。

    $ oc patch imagestream/system-memcached --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "System 2.11 Memcached"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/3scale-amp2/memcached-rhel7:3scale2.11"}, "name": "2.11", "referencePolicy": {"type": "Source"}}}]'
  2. system-memcache ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/system-memcache --from-image=system-memcached:2.10 --containers=memcache --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/system-memcache --from-image=system-memcached:2.11 --containers=memcache

      これにより、system-memcache DeploymentConfig の再デプロイメントがトリガーされます。再デプロイが完了し、対応する新規 Pod が使用できる状態になり、古い Pod が終了するまで待ちます。

2.2.6.6. zync-database-postgresql イメージのパッチ

  1. zync-database-postgresql イメージストリームにパッチを適用します。

    $ oc patch imagestream/zync-database-postgresql --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "Zync 2.11 PostgreSQL"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/postgresql-10-rhel7"}, "name": "2.11", "referencePolicy": {"type": "Source"}}}]'
    • このパッチコマンドにより zync-database-postgresql イメージストリームが更新され、2.11 タグが含まれるようになります。以下の手順により、2.11 タグが作成されていることを確認することができます。

      1. 実行コマンド

        $ oc get is zync-database-postgresql
      2. Tags 欄に 2.11 タグが表示されていることを確認します。
  2. zync-database ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/zync-database --from-image=zync-database-postgresql:2.10 --containers=postgresql --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/zync-database --from-image=zync-database-postgresql:2.11 --containers=postgresql

      イメージに新しい更新があれば、このパッチがトリガーとなり zync-database DeploymentConfig も再デプロイされます。その場合は、新規 Pod の再デプロイが完了して使用できる状態になり、古い Pod が終了するまで待ちます。

2.2.6.7. その他のイメージの変更

3scale 2.10 のインストール環境で以下の DeploymentConfig の 1 つまたは複数が利用可能な場合は、該当するリンクをクリックして詳細な操作手順を確認してください。

backend-redis DeploymentConfig

現在の 3scale インストール環境に backend-redis DeploymentConfig が存在する場合は、backend-redis 用の redis イメージにパッチを適用します。

  1. backend-redis イメージストリームにパッチを適用します。

    $ oc patch imagestream/backend-redis --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "Backend 2.11 Redis"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/redis-5-rhel7:5"}, "name": "2.11", "referencePolicy": {"type": "Source"}}}]'

    このパッチにより backend-redis イメージストリームが更新され、2.11 タグが含まれるようになります。以下のコマンドにより Tags 欄に 2.11 が表示されれば、タグが作成されていることを確認することができます。

    $ oc get is backend-redis
  2. backend-redis ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/backend-redis --from-image=backend-redis:2.10 --containers=backend-redis --remove
    2. 3scale 2.11 の redis イメージは Redis 3 から 5 にアップグレードされており、Redis への異なるバイナリーパスが含まれています。backend-redis デプロイメントコンテナーコマンドを更新して、新しいパスを使用する必要があります。注記: この変更を適用すると、次のサブステップで新しいバージョン固有のトリガーを追加する まで、 backend-redis デプロイメントがエラー状態のままになります。

      $ oc patch dc backend-redis --patch '{"spec":{"template":{"spec":{"containers":[{"name":"backend-redis","command":["/opt/rh/rh-redis5/root/usr/bin/redis-server"]}]}}}}'
    3. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/backend-redis --from-image=backend-redis:2.11 --containers=backend-redis

      イメージに新しい更新があれば、このパッチがトリガーとなり backend-redis DeploymentConfig も再デプロイされます。その場合は、新規 Pod の再デプロイが完了して使用できる状態になり、古い Pod が終了するまで待ちます。

system-redis DeploymentConfig

現在の 3scale インストール環境に system-redis DeploymentConfig が存在する場合は、system-redis 用の redis イメージにパッチを適用します。

  1. system-redis イメージストリームにパッチを適用します。

    $ oc patch imagestream/system-redis --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "System 2.11 Redis"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/redis-5-rhel7:5"}, "name": "2.11", "referencePolicy": {"type": "Source"}}}]'

    このパッチにより system-redis イメージストリームが更新され、2.11 タグが含まれるようになります。以下のコマンドにより Tags 欄に 2.11 が表示されれば、タグが作成されていることを確認することができます。

    $ oc get is system-redis
  2. system-redis ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/system-redis --from-image=system-redis:2.10 --containers=system-redis --remove
    2. 3scale 2.11 の redis イメージは Redis 3 から 5 にアップグレードされており、Redis への異なるバイナリーパスが含まれています。system-redis デプロイメントコンテナーコマンドを更新して、新しいパスを使用する必要があります。注記: この変更を適用すると、次のサブステップで新しいバージョン固有のトリガーを追加する まで、system-redis デプロイメントがエラー状態のままになります。

      $ oc patch dc system-redis --patch '{"spec":{"template":{"spec":{"containers":[{"name":"system-redis","command":["/opt/rh/rh-redis5/root/usr/bin/redis-server"]}]}}}}'
    3. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/system-redis --from-image=system-redis:2.11 --containers=system-redis

      イメージに新しい更新があれば、このパッチがトリガーとなり system-redis DeploymentConfig も再デプロイされます。その場合は、新規 Pod の再デプロイが完了して使用できる状態になり、古い Pod が終了するまで待ちます。

system-mysql DeploymentConfig

現在の 3scale インストール環境に system-mysql DeploymentConfig が存在する場合は、system-mysql 用の MySQL イメージにパッチを適用します。

  1. system-mysql イメージストリームにパッチを適用します。

    $ oc patch imagestream/system-mysql --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "System 2.11 MySQL"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/mysql-57-rhel7:5.7"}, "name": "2.11", "referencePolicy": {"type": "Source"}}}]'

    このパッチにより system-mysql イメージストリームが更新され、2.11 タグが含まれるようになります。以下のコマンドにより Tags 欄に 2.11 が表示されれば、タグが作成されていることを確認することができます。

    $ oc get is system-mysql
  2. system-mysql ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/system-mysql --from-image=system-mysql:2.10 --containers=system-mysql --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/system-mysql --from-image=system-mysql:2.11 --containers=system-mysql

      イメージに新しい更新があれば、このパッチがトリガーとなり system-mysql DeploymentConfig も再デプロイされます。その場合は、新規 Pod の再デプロイが完了して使用できる状態になり、古い Pod が終了するまで待ちます。

system-postgresql DeploymentConfig

現在の 3scale インストール環境に system-postgresql DeploymentConfig が存在する場合は、system-postgresql 用の PostgreSQL イメージにパッチを適用します。

  1. system-postgresql イメージストリームにパッチを適用します。

    $ oc patch imagestream/system-postgresql --type=json -p '[{"op": "add", "path": "/spec/tags/-", "value": {"annotations": {"openshift.io/display-name": "System 2.11 PostgreSQL"}, "from": { "kind": "DockerImage", "name": "registry.redhat.io/rhscl/postgresql-10-rhel7"}, "name": "2.11", "referencePolicy": {"type": "Source"}}}]'

    このパッチにより system-postgresql イメージストリームが更新され、2.11 タグが含まれるようになります。以下のコマンドにより Tags 欄に 2.11 が表示されれば、タグが作成されていることを確認することができます。

    $ oc get is system-postgresql
  2. system-postgresql ImageChange トリガーにパッチを適用します。

    1. 古い 2.10 トリガーを削除します。

      $ oc set triggers dc/system-postgresql --from-image=system-postgresql:2.10 --containers=system-postgresql --remove
    2. 新しいバージョン固有のトリガーを追加します。

      $ oc set triggers dc/system-postgresql --from-image=system-postgresql:2.11 --containers=system-postgresql

      イメージに新しい更新があれば、このパッチがトリガーとなり system-postgresql DeploymentConfig も再デプロイされます。その場合は、新規 Pod の再デプロイが完了して使用できる状態になり、古い Pod が終了するまで待ちます。

2.2.6.8. イメージの URL の確認

DeploymentConfig のすべてのイメージ URL に、各 URL アドレスの最後に追加されたハッシュと共に新しいイメージレジストリーの URL が含まれていることを確認します。

$ THREESCALE_DC_NAMES="apicast-production apicast-staging backend-cron backend-listener backend-redis backend-worker system-app system-memcache system-mysql system-redis system-sidekiq system-sphinx zync zync-database zync-que"
for component in ${THREESCALE_DC_NAMES}; do echo -n "${component} image: " && oc get dc $component -o json | jq .spec.template.spec.containers[0].image ; done

次のステップ

なし。上記の手順をすべて実施すると、テンプレートベースのデプロイメントにおける 3scale 2.10 から 2.11 へのアップグレードが完了します。

2.3. テンプレートベースのインストール環境での Oracle Database を使用した 3scale のアップグレード

本セクションでは、OpenShift 3.11 とテンプレートベースのインストール環境の組み合わせにおいて、Oracle Database で 3scale システムイメージを使用している場合に、Red Hat 3scale API Management をアップグレードする方法について説明します。

前提条件

Oracle Database を使用した 3scale インストール環境。Oracle Database を使用した 3scale システムイメージの設定 を参照してください。

テンプレートベースのインストール環境で Oracle Database を使用して 3scale のシステムイメージをアップグレードするには、以下の手順を実行します。

2.3.1. Oracle 19c を使用した 3scale のアップグレード

以下の手順では、Oracle Database 19c の更新、既存の 3scale 2.10 インストール環境から 3scale 2.11 への変更について説明します。

重要: データベースへの接続が失われると、3scale が破損する可能性があります。アップグレードを進める前にバックアップを作成します。詳細は、Oracle Database のドキュメント Oracle Database Backup and Recovery User's Guide を参照してください。

前提条件

  • 3scale 2.10 のインストール
  • Oracle Database 19c のインストール

手順

  1. GitHub リポジトリーから 3scale OpenShift テンプレートをダウンロードし、アーカイブを展開します。

    tar -xzf 3scale-amp-openshift-templates-3scale-2.11.1-GA.tar.gz
  2. Oracle Database の Instant Client パッケージファイルを 3scale-amp-openshift-templates-3scale-2.11.1-GA/amp/system-oracle/oracle-client-files ディレクトリーに配置します。
  3. -f オプションで build.yml OpenShift テンプレートを指定して、oc process コマンドを実行します。

    $ oc process -f build.yml | oc apply -f -
  4. -f オプションで amp.yml OpenShift テンプレートを指定し、-p オプションで WILDCARD_DOMAIN パラメーターに OpenShift クラスターのドメインを指定して、oc new-app コマンドを実行します。

    $ oc new-app -f amp.yml -p WILDCARD_DOMAIN=mydomain.com
    注記

    以下の手順は任意です。インストール後やシステムアップグレード後にORACLE_SYSTEM_PASSWORDを削除する場合に使用します。

  5. 以下の oc patch コマンドを入力します。SYSTEM_PASSWORDOracle Database の準備 で設定した Oracle Database の system パスワードに置き換えます。

    $ oc patch dc/system-app -p '[{"op": "add", "path": "/spec/strategy/rollingParams/pre/execNewPod/env/-", "value": {"name": "ORACLE_SYSTEM_PASSWORD", "value": "SYSTEM_PASSWORD"}}]' --type=json
    
    $ oc patch dc/system-app -p '{"spec": {"strategy": {"rollingParams": {"post":{"execNewPod": {"env": [{"name": "ORACLE_SYSTEM_PASSWORD", "value": "SYSTEM_PASSWORD"}]}}}}}}'
  6. 以下のコマンドを入力します。DATABASE_URLOracle Database の準備で指定した Oracle Database を参照するように置き換えます。

    $ oc patch secret/system-database -p '{"stringData": {"URL": "DATABASE_URL"}}'
  7. oc start-build コマンドを入力し、新しいシステムイメージをビルドします。

    $ oc start-build 3scale-amp-system-oracle --from-dir=.
  8. ビルドが完了するまで待ちます。ビルドの状態を確認するには、以下のコマンドを実行します。

    $ oc get build <build-name> -o jsonpath="{.status.phase}"
    1. ビルドが Complete の状態になるまで待ちます。
  9. Oracle Database で 3scale システムイメージを設定したら、system-app DeploymentConfig から ORACLE_SYSTEM_PASSWORD を削除します。新しいバージョンの 3scale にアップグレードするまで、もう一度は必要ありません。

    $ oc set env dc/system-app ORACLE_SYSTEM_PASSWORD-

関連情報

3scale と Oracle Database のサポートについては、Red Hat 3scale API Management のサポート対象設定 を参照してください。

第3章 テンプレートを使用した 3scale バージョン 2.11.0 からバージョン 2.11.1 へのアップグレード

Red Hat 3scale API Management をバージョン 2.11.0 からバージョン 2.11.1 にアップグレードするには、Open Shift 3.11 でテンプレートベースのデプロイメントを使用します。

重要

必要な条件および手順を理解するために、記載の手順を適用する前に、アップグレードガイド全体を読んでください。アップグレードプロセスの手順が完了するまで、サービスの提供が中断されます。このサービス中断が生じるため、メンテナーンス期間を設けるようにしてください。

3.1. アップグレードを行うための前提条件

本セクションでは、テンプレートベースのインストール環境において、3scale を 2.11.0 から 2.11.1 にアップグレードするのに必要な設定、タスク、およびツールについて説明します。

3.1.1. 設定

  • OpenShift 3.11 上の 3scale では、テンプレートを使用した 2.11.0 から 2.11.1 へのアップグレードパスがサポートされます。

3.1.2. 主要なタスク

  • OpenShift CLI ツールが 3scale をデプロイしたプロジェクトに設定されるようにする。
  • 3scale で使用しているデータベースのバックアップを行う。バックアップの手順は、データベースのタイプや設定により異なります。

3.1.3. ツール

アップグレードを行うには、以下のツールが必要です。

  • テンプレートを使用して OpenShift 3.11 のプロジェクトにデプロイされた 3scale 2.11.0
  • Bash シェル: アップグレード手順で詳細を説明するコマンドを実行します。
  • base64: シークレットの情報をエンコードおよびデコードします。
  • jq: JSON 変換用です。

3.2. テンプレートベースのインストール環境における 3scale 2.11.0 から 2.11.1 へのアップグレード

テンプレートベースのインストール環境において、3scale 2.11.0 を 2.11.1 にアップグレードするには、本セクションに記載の手順に従います。

アップグレードを開始するには、3scale がデプロイされているプロジェクトに移動します。

$ oc project <3scale-project>

続いて、以下の順序で手順を実行します。

3.2.1. 3scale プロジェクトのバックアップの作成

前の手順

なし

現在の手順

3scale プロジェクトのバックアップを作成するのに必要なアクションを以下のリストに示します。

手順

  1. 3scale で使用するデータベースに応じて、${SYSTEM_DB} を以下のいずれかの値に設定します。

    • データベースが MySQL の場合: SYSTEM_DB=system-mysql
    • データベースが PostgreSQL の場合: SYSTEM_DB=system-postgresql
  2. 既存の DeploymentConfigs でバックアップファイルを作成します。

    $ THREESCALE_DC_NAMES="apicast-production apicast-staging backend-cron backend-listener backend-redis backend-worker system-app system-memcache ${SYSTEM_DB} system-redis system-sidekiq system-sphinx zync zync-database zync-que"
    
    for component in ${THREESCALE_DC_NAMES}; do oc get --export -o yaml dc ${component} > ${component}_dc.yml ; done
  3. export all コマンドでエクスポートされるプロジェクト内のすべての既存 OpenShift リソースをバックアップします。

    $ oc get -o yaml --export all > threescale-project-elements.yaml
  4. export all コマンドでエクスポートされない追加の要素でバックアップファイルを作成します。

    $ for object in rolebindings serviceaccounts secrets imagestreamtags cm rolebindingrestrictions limitranges resourcequotas pvc templates cronjobs statefulsets hpa deployments replicasets poddisruptionbudget endpoints
    do
      oc get -o yaml --export $object > $object.yaml
    done
  5. 生成されたすべてのファイルが空ではないこと、およびそれらすべての内容が予想どおりであることを確認します。

3.2.2. backend-cronDeployment Config のリソース要件の増加

現在の手順

このリリースでは、backend-cronDeployment Config のリソース使用量が増える可能性があります。この手順では、必要なリソースを現在の設定値よりも増やすことができます。

3scale 2.11.1 で必要なbackend-cronのリソースは以下の通りです。

{
  "limits": {
	"cpu": "500m",
	"memory": "500Mi"
  },
  "requests": {
	"cpu": "100m",
	"memory": "100Mi"
  }
}

現在のbackend-cronのデプロイメントにメモリーの制限がない場合や、リソースの要件がこれよりも高い場合は、以下の手順を実行する必要はありません。

手順

  1. 以下のコマンドで、backend-cronに設定されている現在のリソース要件を確認します。

    $ oc get dc backend-cron -o json | jq .spec.template.spec.containers[0].resources

    出力が空またはNULLの場合は、リソース要求が設定されていないことを意味します。

  2. 現在のbackend-cronの必要リソースを増やすには、以下のコマンドを実行します。

    $ oc patch dc backend-cron --patch '{"spec":{"template":{"spec":{"containers":[{"name":"backend-cron","resources":{"limits":{"memory":"500Mi", "cpu": "500m"}, "requests":{"memory":"100Mi", "cpu": "100m"}}}]}}}}'

    このコマンドがトリガーとなり backend-cron が再デプロイされます。再デプロイされ、対応する新しい Pod の準備が整い、以前の Pod が終了するまで待ちます。

3.2.3. 3scale イメージのアップグレード

現在の手順

この手順では、アップグレードプロセスに必要な 3scale イメージを更新します。

3.2.3.1. system イメージのパッチ

  1. 手順を進めるには、ご自分の 3scale デプロイメントで使用しているデータベースを考慮してください。

3.2.3.2. システムイメージへのパッチ適用: 3scale が Oracle Database を使用する場合

  1. Oracle データベースを搭載した 3scale のシステムイメージのパッチ適用を開始するには、システムイメージの構築の手順 1、2、4、8 を実行します。
  2. 最新のamp-systemOracle データベースイメージをインポートします。

    oc import-image amp-system:2.11-oracle

3.2.3.3. システムイメージへのパッチ適用: 3scale がその他のデータベースを使用する場合

最新のsystem-appのイメージをインポートします。

oc import-image amp-system:2.11

3.2.3.4. apicast イメージのパッチ

最新のamp-apicastのイメージをインポートします。

oc import-image amp-apicast:2.11

3.2.3.5. backend イメージのパッチ

最新のamp-backendのイメージをインポートします。

oc import-image amp-backend:2.11

3.2.3.6. zync イメージへのパッチ適用

最新のamp-zyncのイメージをインポートします。

oc import-image amp-zync:2.11

3.2.3.7. system-memcached イメージのパッチ

最新のsystem-memcachedイメージをインポートします。

oc import-image system-memcached:2.11

次のステップ

なし。上記の手順をすべて実施すると、テンプレートベースのデプロイメントにおける 3scale 2.11.0 から 2.11.1 へのアップグレードが完了します。

第4章 operator ベースの 3scale のアップグレードガイド: 2.10 から 2.11 へ

オペレーターベースのインストールで Red Hat 3scale API Management をバージョン 2.10 から 2.11 にアップグレードして、Open Shift 4.x で 3scale を管理できるようにします。

3scale のマイクロリリースを自動的に取得するには、自動更新が有効であることを確認してください。これを確認するには、Setting up the 3scale operator for micro releases を参照してください。

重要

必要な条件および手順を理解するために、記載の手順を適用する前に、アップグレードガイド全体を読んでください。アップグレードプロセスの手順が完了するまで、サービスの提供が中断されます。このサービス中断が生じるため、メンテナンス期間を設けるようにしてください。

4.1. アップグレードを行うための前提条件

本セクションでは、operator ベースのインストール環境において、3scale を 2.10 から 2.11 にアップグレードするのに必要な設定について説明します。

  • OpenShift Container Platform (OCP) 4.6、4.7、4.8 クラスターおよびその管理者アクセス

    • OCP 4.9 にアップグレードする前に、3scale の 2.10 から 2.11 へのアップグレードを行う必要があります。
    • 注: 3scale をアップグレードする前に OCP を 4.9 以上にアップグレードした場合には、インストールは機能しません。
  • 3scale operator によりデプロイされている 3scale 2.10
  • threescale-2.10 チャネルの最新 CSV が使用されていることを確認します。以下を確認してください。

    • サブスクリプションの承認設定が自動の場合は、すでに最新の CSV バージョンのチャンネルになっているはずです。
    • サブスクリプションの承認設定が手動の場合、保留中のすべての Install Plans を承認し、最新の CSV バージョンがあることを確認してください。
    • 保留中のインストールプランがある場合、さらに保留中のインストールプランがある可能性があり、既存の保留中のプランがインストールされた後にのみ表示されることに注意してください。

4.2. operator ベースのインストール環境における 2.10 から 2.11 へのアップグレード

operator ベースのデプロイメントにおいて、3scale をバージョン 2.10 から 2.11 にアップグレードするには、以下の手順を実施します。

  1. 管理者権限を持つアカウントを使用して OCP コンソールにログインします。
  2. 3scale-operator がデプロイされているプロジェクトを選択します。
  3. Operators > Installed Operators の順にクリックします。
  4. Red Hat Integration - 3scale > Subscription > Channel の順に選択します。
  5. threescale-2.11 を選択してサブスクリプションのチャンネルを編集し、変更を保存します。

    これによりアップグレードプロセスが開始されます。

  6. すべての新しいバージョンが実行され、エラーなく準備ができていることを確認するまで、プロジェクトで Pod の状態を照会します。

    $ oc get pods
    注記
    • Pod ではアップグレードプロセス中、一時的にエラーが発生する場合があります。
    • Pod のアップグレードに必要な時間は、5~10 分程度です。
  7. 新しい Pod のバージョンの実行後に、3scale Admin Portal にログインして、想定どおりに動作することをチェックし、アップグレードが正常に行われたことを確認します。
  8. 以下のコマンドを実行して、APIManagerオブジェクトのステータスを確認し、YAMLコンテンツを取得します。 <myapimanager> は、APIManagerの名前を表します。

    $ oc get apimanager <myapimanager> -o yaml
    • 新しいアノテーションおよび値は以下のようになります。

      apps.3scale.net/apimanager-threescale-version: "2.11"
      apps.3scale.net/threescale-operator-version: "0.8.0"

上記の手順をすべて実施すると、operator ベースのデプロイメントにおける 3scale 2.10 から 2.11 へのアップグレードが完了します。

第5章 operator ベースの APIcast のアップグレードガイド: 2.10 から 2.11 へ

オペレータベースのインストールで APIcast を 2.10 から 2.11 にアップグレードすると、APIcast API ゲートウェイを使用して、内部および外部の API サービスを 3scale と統合できます。

重要

必要な条件および手順を理解するために、記載の手順を適用する前に、アップグレードガイド全体を読んでください。アップグレードプロセスの手順が完了するまで、サービスの提供が中断されます。このサービス中断が生じるため、メンテナンス期間を設けるようにしてください。

5.1. アップグレードを行うための前提条件

オペレーターベースのインストールで APIcast を 2.10 から 2.11 にアップグレードするには、以下の前提条件を満たしている必要があります。

  • OpenShift Container Platform (OCP) 4.6、4.7、4.8 クラスターおよびその管理者アクセス

    • OCP 4.9 にアップグレードする前に、APIcast の 2.10 から 2.11 へのアップグレードを行う必要があります。
    • 注: APIcast をアップグレードする前に OCP を 4.9 以上にアップグレードした場合には、インストールは機能しません。
  • APIcast operator によりデプロイされている APIcast 2.10
  • threescale-2.10 チャネルの最新 CSV が使用されていることを確認します。以下を確認してください。

    • サブスクリプションの承認設定が自動の場合は、すでに最新の CSV バージョンのチャンネルになっているはずです。
    • サブスクリプションの承認設定が手動の場合、保留中のすべての Install Plans を承認し、最新の CSV バージョンがあることを確認してください。
    • 保留中のインストールプランがある場合、さらに保留中のインストールプランがある可能性があり、既存の保留中のプランがインストールされた後にのみ表示されることに注意してください。

5.2. operator ベースのインストール環境における APIcast 2.10 から 2.11 へのアップグレード

オペレーターベースのインストールで、APIcast を 2.10 から 2.11 にアップグレードし、APIcast が 3scale のインストールで API ゲートウェイとして機能するようにします。

手順

  1. 管理者権限を持つアカウントを使用して OCP コンソールにログインします。
  2. APIcast operator がデプロイされているプロジェクトを選択します。
  3. Operators > Installed Operators の順にクリックします。
  4. Subscription > Channel の順に移動し、Red Hat Integration - 3scale APIcast gateway を選択します。
  5. threescale-2.11 チャンネルを選択してサブスクリプションのチャンネルを編集し、変更を保存します。

    これによりアップグレードプロセスが開始されます。

  6. すべての新しいバージョンが実行され、エラーなく準備ができていることを確認するまで、プロジェクトで Pod の状態を照会します。

    $ oc get pods
    注記
    • Pod ではアップグレードプロセス中、一時的にエラーが発生する場合があります。
    • Pod のアップグレードに必要な時間は、5~10 分程度です。
  7. APIcast オブジェクトのステータスを確認し、以下のコマンドを実行して YAML のコンテンツを取得します。

    $ oc get apicast <myapicast> -o yaml
    • 新しいアノテーションおよび値は以下のようになります。

      apicast.apps.3scale.net/operator-version: “0.5.0”

上記の手順をすべて実施すると、operator ベースのデプロイメントにおける APIcast 2.10 から 2.11 へのアップグレードが完了します。