第29章 サービスディスカバリー

3scale の提供するサービスディスカバリー機能を使用すると、OpenShift から API サービスをインポートすることができます。

29.1. サービスディスカバリーについて

サービスディスカバリーが設定されると、3scale は同じ OpenShift クラスター内で実行されている検出可能な API サービスの有無をスキャンし、関連する API 定義を 3scale に自動的にインポートします。さらに、3scale は OpenAPI Specification (OAS) に基づいて API インテグレーションおよびその仕様を更新し、それらをクラスターと再同期できます。

サービスディスカバリーにより、以下の機能を利用することができます。

  • クラスター API を使用して、正しく検出のアノテーションが付けられたサービスのクエリーを行う。
  • クラスター内の内部エンドポイントを使用してサービスにアクセスするように 3scale を設定する。
  • API サービス仕様を 3scale ActiveDocs としてインポートする。
  • OpenShift と Red Hat Single Sign-On (RH-SSO) の承認フローをサポートする。
  • Fuse バージョン 7.2 以降の Red Hat Fuse と協調する。

検出可能なサービスをインポートする場合、その namespace はサービスが属するプロジェクト内に維持されます。インポートされたサービスは、新しい顧客がアクセスする API (プロダクト) およびそれに対応する内部 API (バックエンド) になります。

  • オンプレミス型 3scale では、3scale API プロバイダーは固有の namespace およびサービスを持つ場合があります。検出されたサービスは、3scale の既存ネイティブサービスと共存することができます。
  • Fuse の検出可能サービスは、Fuse のプロダクション namespace にデプロイされます。

29.2. 検出可能サービスの条件

3scale が OpenShift (OCP) クラスターの API サービスを検出できるためには、その OCP は以下に示す各要素の条件を満たしている必要があります。

Content-Type ヘッダー

API 仕様の Content-Type ヘッダーの値は、以下のいずれかでなければなりません。

  • application/swagger+json
  • application/vnd.oai.openapi+json
  • application/json

OpenShift Service Object YAML 定義

  • OpenShift Service Object YAML 定義には、以下のメタデータが含まれている必要があります。

    • discovery.3scale.net ラベル: (必須)「true」に設定します。検出が必要なすべてのサービスを探すために 3scale がセレクター定義を実行する際に、このラベルが使用されます。
    • 以下のアノテーションを使用できます。

      discovery.3scale.net/discovery-version: (任意) 3scale 検出プロセスのバージョン

      discovery.3scale.net/scheme: (必須) サービスをホストする URL のスキーム部分。設定可能な値は「http」および「https」です。

      discovery.3scale.net/port: (必須) クラスター内のサービスのポート番号

      discovery.3scale.net/path: (オプション) サービスをホストする URL の相対ベースパス。パスがルート (「/」) の場合には、このアノテーションを省略することができます。

      discovery.3scale.net/description-path: サービスの OpenAPI サービス記述ドキュメントへのパス。

      例を以下に示します。

          metadata:
            annotations:
              discovery.3scale.net/scheme: "https"
              discovery.3scale.net/port: '8081'
              discovery.3scale.net/path: "/api"
              discovery.3scale.net/description-path: "/api/openapi/json"
           labels:
              discovery.3scale.net: "true"
           name: i-task-api
           namespace: fuse
    • 管理者権限を持つ OpenShift ユーザーであれば、OpenShift のコンソールで API サービスの YAML ファイルを表示することができます。

      1. Applications > Services の順に選択します。
      2. サービスを選択し (例: i-task-api)、その Details のページを表示します。
      3. Actions > Edit YAML の順に選択し、YAML ファイルを開きます。
      4. ファイルの表示を終えたら、Cancel を選択します。

ovs-networkpolicy プラグインを持つクラスター

  • OpenShift と 3scale プロジェクト間のトラフィックを許可する場合、ovs-networkpolicy プラグインを持つクラスターには、アプリケーションプロジェクト内で作成された NetworkPolicy オブジェクトが必要です。
  • NetworkPolicy オブジェクトの設定についての詳細は、『Networking』の「About network policy」を参照してください。

29.3. サービスディスカバリーを有効にするための OpenShift 設定に関する考慮事項

3scale の管理者は、Open Authorization (OAuth) サーバーの使用/不使用とは独立に、2 とおりの方法でサービスディスカバリーを設定することができます。

OAuth サーバーと共に 3scale サービスディスカバリーを設定する場合、ユーザーが 3scale にサインインした際のフローは以下のとおりです。

  • ユーザーが OAuth サーバーにリダイレクトされる。
  • ユーザーがまだ OAuth サーバーにログインしていなければ、ログインを求められる。
  • ユーザーが 3scale のサービスディスカバリーと SSO の組み合わせを初めて実装する場合には、OAuth サーバーは必要なアクションを実行するために承認を要求する。
  • ユーザーが再度 3scale にリダイレクトされる。

OAuth サーバー と組み合わせてサービスディスカバリーを設定する場合には、以下のオプションがあります。

OAuth サーバーと組み合わせずにサービスディスカバリーを設定する 場合、ユーザーが 3scale にサインインしてもリダイレクトされません。その代わりに、サービスディスカバリーのために、3scale Single Service Account がクラスターに対してシームレスに認証を行います。3scale を通じて API サービスを検出する間、すべての 3scale テナント管理ユーザーはクラスターに対して同じアクセスレベルを持ちます。

29.4. OpenShift OAuth サーバーと組み合わせてサービスディスカバリーを設定する

3scale のシステム管理者は、ユーザーが OpenShift の組み込み OAuth サーバーを使用して、個別に認証、3scale を承認して API を検出するのを許可します。

前提条件

  • OpenShift クラスター (バージョン 3.11 以降) に 3scale 2.10 をデプロイしている必要があります。
  • 3scale を OpenShift にデプロイするには、3scale-amp-openshift-templates を使用する必要があります。
  • 3scale でサービスディスカバリーを使用する 3scale ユーザーは、OpenShift クラスターにアクセスできる必要があります。

手順

  1. 3scale 用の OpenShift OAuth クライアントを作成します。詳細は、OpenShift の認証に関するドキュメント を参照してください。以下の例で、<provide-a-client-secret> を生成するシークレットに、<3scale-master-domain-route> を 3scale マスター管理ポータルにアクセスするための URL に、それぞれ置き換えます。

        $ oc project default
        $ cat <<-EOF | oc create -f -
        kind: OAuthClient
        apiVersion: v1
        metadata:
         name: 3scale
        secret: "<provide-a-client-secret>"
        redirectURIs:
         - "<3scale-master-domain-route>"
        grantMethod: prompt
        EOF
  2. 3scale サービスディスカバリーの設定ファイルを開きます。

        $ oc project <3scale-project>
        $ oc edit configmap system
  3. 以下のように設定します。

        service_discovery.yml:
          production:
            enabled: true
            authentication_method: oauth
            oauth_server_type: builtin
            client_id: '3scale'
            client_secret: '<choose-a-client-secret>'
  4. ユーザーが適切なアクセス権限を持ち、検出可能なサービスが含まれるクラスタープロジェクトを表示できるようにしてください。

    <user> で表される管理ユーザーに、検出されるサービスが含まれる <namespace> プロジェクトを表示する権限を付与するには、以下のコマンドを使用します。

    oc adm policy add-role-to-user view <user> -n <namespace>
  5. configmap を変更したら、system-app および system-sidekiq Pod を再デプロイし、変更を適用する必要があります。

    oc rollout latest dc/system-app
    oc rollout latest dc/system-sidekiq
  6. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。

    oc rollout status dc/system-app
    oc rollout status dc/system-sidekiq

その他のリソース

29.5. RH-SSO サーバー (Keycloak) と組み合わせてサービスディスカバリーの設定する

システム管理者は、ユーザーが OpenShift 向け Red Hat Single Sign-On を使用して、個別に認証、3scale を承認してサービスを検出するのを許可します。

OpenShift の承認ゲートウェイとして RH-SSO デプロイメントを使用する OpenShift の設定例については、この ワークフロー を参照してください。

前提条件

  • OpenShift クラスター (バージョン 3.11 以降) に 3scale 2.10 をデプロイしている必要があります。
  • 3scale を OpenShift にデプロイするには、3scale-amp-openshift-templates を使用する必要があります。
  • 3scale でサービスディスカバリーを使用する 3scale ユーザーは、OpenShift クラスターにアクセスできる必要があります。

手順

  1. Red Hat OAuth サーバー (Keycloak) に、3scale 用の OAuth クライアントを作成します。

    注記

    クライアント設定で、OpenShift がアカウントをリンクすることができるように、usernamepreferred_username にマッピングされていることを確認します。

  2. 3scale サービスディスカバリーの設定を編集します。

        $ oc project <3scale-project>
        $ oc edit configmap system
  3. 以下のように設定されていることを確認します。ここで、<the-client-secret-from-Keycloak> は OAuth クライアントの作成時に Keycloak が自動生成した値です。

        service_discovery.yml:
          production:
            enabled: true
            authentication_method: oauth
            oauth_server_type: rh_sso
            client_id: '3scale'
            client_secret: '<the-client-secret-from-Keycloak>'
  4. ユーザーが適切なアクセス権限を持ち、検出可能なサービスが含まれるクラスタープロジェクトを表示できるようにしてください。

    たとえば、<user><namespace> プロジェクトを表示する権限を付与するには、以下のコマンドを使用します。

    oc adm policy add-role-to-user view <user> -n <namespace>
  5. configmap を変更したら、system-app および system-sidekiq Pod を再デプロイし、変更を適用する必要があります。

その他のリソース

  • トークンの有効期限:『Keycloak Server Administration Guide』の「Session and Token Timeouts」に記載されるように、デフォルトではセッショントークンの有効期限は 1 分です。ただし、タイムアウトを妥当な値 (たとえば 1 日) に設定することを推奨します。

29.6. OAuth サーバーと組み合わせないサービスディスカバリーの設定

OAuth サーバーを使用しない状況で 3scale のサービスディスカバリーを設定する場合には、3scale Single Service Account を使用して OpenShift API サービスに対する認証を行うことができます。

前提条件

  • OpenShift クラスター (バージョン 3.11 以降) に 3scale 2.10 をデプロイしている必要があります。
  • 3scale を OpenShift にデプロイするには、3scale-amp-openshift-templates を使用する必要があります。
  • 3scale でサービスディスカバリーを使用する 3scale ユーザーは、OpenShift クラスターにアクセスできる必要があります。

手順

  1. 3scale プロジェクトをアクティブなプロジェクトにします。

       $ oc project <3scale-project>
  2. エディターで 3scale サービスディスカバリーの設定を開きます。

       $ oc edit configmap system
  3. 以下のように設定されていることを確認します。

    service_discovery.yml:
       production:
          enabled: <%= cluster_token_file_exists = File.exists?(cluster_token_file_path = '/var/run/secrets/kubernetes.io/serviceaccount/token') %>
          bearer_token: "<%= File.read(cluster_token_file_path) if cluster_token_file_exists %>"
          authentication_method: service_account
  4. 以下のいずれかのオプションに従って、3scale デプロイメントの amp サービスアカウントに、検出可能なサービスが含まれるプロジェクトを表示するための適切な権限を付与します。

    • 3scale デプロイメントの amp サービスアカウントに、クラスターレベルの view 権限を付与する。

      oc adm policy add-cluster-role-to-user view system:serviceaccount:<3scale-project>:amp
    • 『Developer Guide』の「Service Accounts」で説明するように、より厳しいポリシーを適用する。

29.7. 検出されたサービスのインポート

OpenShift クラスターから、OpenAPI Specification に準拠する新しい API サービスをインポートします。この API を 3scale で管理します。

前提条件

  • OpenShift の管理者が、OpenShift クラスターにサービスディスカバリーを設定している。たとえば、OpenShift の管理者は、Fuse Online カスタムリソースを編集して 3scale ユーザーインターフェースの URL を指定し、3scale の検出機能を有効にしている必要があります。
  • 「サービスディスカバリーについて」で説明するように、3scale の管理者が 3scale デプロイメントでサービスディスカバリーを設定している。
  • 3scale の管理者が、3scale ユーザーまたはサービスアカウント (設定されている認証モードによる) に、API サービスおよびその namespace を表示するのに必要な権限を付与している。詳細は、「OpenShift プロジェクトへの 3scale アクセスの承認」を参照してください。
  • 「検出可能サービスの条件」で説明するように、サービスディスカバリーを有効にする正しいアノテーションが API に付けられている。
  • API サービスが、3scale をインストールしたクラスターと同じ OpenShift クラスターにデプロイされている。
  • API のサービス名およびその namespace (OpenShift プロジェクト) を把握している。

手順

  1. 3scale 管理ポータルにログインします。
  2. 管理ポータルの Dashboard で、NEW API をクリックします。
  3. Import from OpenShift を選択します。

  4. Namespace フィールドで、API が含まれる OpenShift プロジェクトを指定または選択します (例: fuse)。
  5. Name フィールドで、上記 namespace 内の OpenShift サービスの名前を入力または選択します (例: i-task-api)。
  6. Create Service をクリックします。
  7. 新しい API サービスが 3scale に非同期的にインポートされるのを待ちます。管理ポータル右上のセクションに、The service will be imported shortly. You will receive a notification when it is done. というメッセージが表示されます。

その他のリソース

29.8. OpenShift プロジェクトへの 3scale アクセスの承認

OAuth トークンが有効ではない場合、OpenShift プロジェクトの管理者は 3scale ユーザーが namespace にアクセスするのを承認することができます。

前提条件

  • OpenShift プロジェクトの管理者としてのクレデンシャルが設定されている。
  • OpenShift の管理者が、OpenShift クラスターにサービスディスカバリーを設定している。たとえば、Fuse Online API の場合、OpenShift の管理者は Fuse Online サービスの CONTROLLERS_EXPOSE_VIA3SCALE 環境変数を true に設定する必要があります。
  • 「検出可能サービスの条件」で説明するように、3scale の管理者が 3scale デプロイメントでサービスディスカバリーを設定している。
  • API サービスの名前およびその OpenShift プロジェクトの namespace を把握している。
  • API サービスが、3scale をインストールしたクラスターと同じ OpenShift クラスターにデプロイされている。
  • 「検出可能サービスの条件」で説明するように、サービスディスカバリーを有効にする正しいアノテーションが API に付けられている。

手順

  1. Authenticate to enable this option のリンクをクリックします。
  2. namespace 管理者のクレデンシャルを使用して OpenShift にログインします。
  3. Allow selected permissions をクリックし、3scale ユーザーのアクセスを承認します。

その他のリソース

29.9. サービスの更新

3scale の既存 API サービスを、クラスターの最新サービス定義で更新 (リフレッシュ) することができます。

前提条件

手順

  1. 3scale 管理ポータルにログインします。
  2. API プロダクトの Overview ページに移動します。
  3. Source: OpenSource の横にある Refresh のリンクをクリックします。
  4. 新しい API サービスが 3scale に非同期的にインポートされるのを待ちます。