検索

3scale の操作

download PDF
Red Hat 3scale API Management 2.6

デプロイメントの自動化、環境のスケーリング、および問題のトラブルシューティングを行う方法

概要

本書では、Red Hat 3scale API Management 2.6 のデプロイメント操作について説明します。

第1章 3scale の操作とスケーリングのガイド

1.1. はじめに

本書では、オンプレミス型 Red Hat 3scale AMP 2.6 インストール環境での操作とスケーリングタスクについて説明します。

1.1.1. 前提条件

サポート対象バージョンの OpenShift にインストールされた初期設定済みのオンプレミス型 AMP インスタンス

本書は、ノートパソコンやこれに類するエンドユーザー機器上のローカルインストールを対象としていません。

1.1.2. 関連資料

1.2. APIcast の再デプロイ

オンプレミス型 AMP をデプロイし、希望の手法で APIcast をデプロイした後、3scale 管理ポータルでシステムの変更をテストしプロモートすることができます。デフォルトでは、OpenShift 上の APIcast デプロイメントでは (組み込み型のデプロイおよび他の OpenShift クラスター上のデプロイの両方で)、AMP UI を介して変更をステージング環境用と実稼働環境用のゲートウェイにパブリッシュできるように設定されています。

APIcast を OpenShift に再デプロイします。

  1. システムに変更を加えます。
  2. UI でステージング環境にデプロイしてテストします。
  3. UI で実稼働環境にプロモートします。

デフォルトでは、APIcast はプロモートされた更新を 5 分ごとに取得し、パブリッシュします。

Docker コンテナー環境またはネイティブインストールで APIcast を使用している場合は、ステージング環境用と実稼働環境用のゲートウェイを設定し、パブリッシュした変更をゲートウェイが取得する頻度を設定する必要があります。APIcast ゲートウェイを設定したら、AMP UI で APIcast を再デプロイできます。

Docker コンテナー環境またはネイティブインストールに APIcast を再デプロイするには、以下を実行します。

  1. APIcast ゲートウェイを設定し、オンプレミス型 AMP に接続します。
  2. システムに変更を加えます。
  3. UI でステージング環境にデプロイしてテストします。
  4. UI で実稼働環境にプロモートします。

APIcast は、設定された頻度でプロモートされた更新を取得しパブリッシュします。

1.3. オンプレミス型 3scale のスケールアップ

1.3.1. ストレージのスケールアップ

APIcast デプロイメントの規模が大きくなると、利用可能なストレージの量を増やす必要が生じる可能性があります。ストレージをスケールアップする方法は、永続ストレージに使用しているファイルシステムのタイプによって異なります。

ネットワークファイルシステム (NFS) を使用している場合は、oc edit pv コマンドを使用して永続ボリュームをスケールアップできます。

oc edit pv <pv_name>

他のストレージ手段を使用している場合は、以降のセクションに挙げる方法のいずれかを使用して、永続ボリュームを手動でスケールアップする必要があります。

1.3.1.1. 方法 1: 永続ボリュームをバックアップしてスワップする
  1. 既存の永続ボリューム上のデータをバックアップします。
  2. 新しいサイズ要件に合わせて、ターゲット永続ボリュームを作成し、アタッチします。
  3. 事前バインド型の永続ボリューム要求を作成し、新しい PVC のサイズと永続ボリュームの名前を指定します。永続ボリューム名には volumeName フィールドを使用します。
  4. 新しく作成した PV に、バックアップからデータを復元します。
  5. 新しい PV の名前でデプロイメント設定を変更します。

    oc edit dc/system-app
  6. 新しい PV が設定され正常に機能していることを確認します。
  7. 以前の PVC を削除して、それが要求していたリソースを解放します。
1.3.1.2. 方法 2: 3scale をバックアップして再デプロイする
  1. 既存の永続ボリューム上のデータをバックアップします。
  2. 3scale Pod をシャットダウンします。
  3. 新しいサイズ要件に合わせて、ターゲット永続ボリュームを作成し、アタッチします。
  4. 新しく作成した PV に、バックアップからデータを復元します。
  5. 事前バインド型の永続ボリューム要求を作成します。以下の項目を指定します。

    1. 新しい PVC のサイズ
    2. 永続ボリューム名 (volumeName フィールドを使用)
  6. AMP.yml をデプロイします。
  7. 新しい PV が設定され正常に機能していることを確認します。
  8. 以前の PVC を削除して、それが要求していたリソースを解放します。

1.3.2. パフォーマンスのスケールアップ

1.3.2.1. オンプレミス型 3scale デプロイメントの設定

デフォルトでは、3scale デプロイメントは Pod ごとに 1 つのプロセスを実行します。Pod ごとに実行するプロセスを増やすことで、パフォーマンスを向上させることができます。Red Hat は、各ノードのコアごとに 1 つまたは 2 つのプロセスを実行することを推奨します。

Pod にプロセスを追加するには、以下の手順を実行します。

  1. OpenShift クラスターにログインします。

    oc login
  2. 3scale プロジェクトに切り替えます。

    oc project <project_name>
  3. 適切な環境変数に、希望する Pod ごとのプロセス数を設定します。

    1. APIcast Pod: APICAST_WORKERS (Red Hat は、APIcast が APIcast Pod で利用できる CPU の数によってワーカーの数を判断できるよう、この環境変数を未設定のままにすることを推奨します)
    2. バックエンド Pod: PUMA_WORKERS
    3. システム Pod: UNICORN_WORKERS

      oc set env dc/apicast-{production/staging} --overwrite APICAST_WORKERS=<number_of_processes>
      oc set env dc/backend-listener --overwrite PUMA_WORKERS=<number_of_processes>
      oc set env dc/system-app --overwrite UNICORN_WORKERS=<number_of_processes>
1.3.2.2. ハードウェアの垂直スケーリングと水平スケーリング

リソースを追加することで、OpenShift 上の AMP デプロイメントのパフォーマンスを高めることができます。コンピュートノードを Pod として OpenShift クラスターに追加すること (水平スケーリング) や、既存のコンピュートノードに割り当てるリソースを増やすこと (垂直スケーリング) ができます。

水平スケーリング

コンピュートノードを Pod として OpenShift に追加することができます。追加のコンピュートノードがクラスター内の既存ノードと一致する場合には、環境変数を再設定する必要はありません。

垂直スケーリング

既存のコンピュートノードに割り当てるリソースを増やすことができます。割り当てるリソースを増やす場合は、追加のプロセスを Pod に追加してパフォーマンスを高める必要があります。

注記

Red Hat は、3scale デプロイメントにおいて、仕様や設定の異なるコンピュートノードを混在させることは推奨していません。

1.3.2.3. ルーターのスケールアップ

トラフィックの増加に応じて、OCP ルーターがリクエストを適切に処理できるようにする必要があります。ルーターがリクエストのスループットを制限している場合には、ルーターノードをスケールアップする必要があります。

1.4. 操作のトラブルシューティング

本セクションでは、OpenShift で表示するために 3scale 監査ロギングを設定する方法と、OpenShift で 3scale ログおよびジョブキューにアクセスする方法を説明します。

1.4.1. OpenShift での 3scale 監査ロギングの設定

3scale がオンプレミスでデプロイされる場合、監査ロギングを stdout に設定し、すべてのアプリケーションのログを標準的な OpenShift Pod ログに転送することができます。これにより、すべてのログが 1 箇所に集約され、Elasticsearch、Fluentd、および Kibana (EFK) ロギングツールでクエリーすることができます。これらのツールにより、3scale の設定にいつ誰がどのような変更を加えたかについての可視性が向上します。たとえば、これには、請求、アプリケーションプラン、API 設定などへの変更が含まれます。

留意事項

  • 3scale がオンプレミスでデプロイされる場合、デフォルトでは stdout への監査ログの送付は無効です。この機能が完全に動作するように設定する必要があります。
  • ホスト型 3scale では、stdout への監査ログの送付を利用することはできません。
1.4.1.1. 監査ロギングの有効化

3scale は、features.xml 設定ファイルを使用して、一部のグローバル機能を有効にします。stdout への監査ログの送付を有効化するには、このファイルを ConfigMap からマウントして、デフォルトのファイルと置き換える必要があります。features.xml に依存する OpenShift Pod は、system-appsystem-sidekiq です。

前提条件

  • OpenShift でのクラスター管理者アクセス権限がある。

手順

  1. 以下のコマンドを入力して、stdout への監査ログの送付を有効にします。

    oc patch configmap system -p '{"data": {"features.yml": "features: &default\n  logging:\n    audits_to_stdout: true\n\nproduction:\n  <<: *default\n"}}'
  2. 以下の環境変数をエクスポートします。

    export PATCH_SYSTEM_VOLUMES='{"spec":{"template":{"spec":{"volumes":[{"emptyDir":{"medium":"Memory"},"name":"system-tmp"},{"configMap":{"items":[{"key":"zync.yml","path":"zync.yml"},{"key":"rolling_updates.yml","path":"rolling_updates.yml"},{"key":"service_discovery.yml","path":"service_discovery.yml"},{"key":"features.yml","path":"features.yml"}],"name":"system"},"name":"system-config"}]}}}}'
  3. 以下のコマンドを入力して、更新されたデプロイメント設定を関連する OpenShift Pod に適用します。

    oc patch dc system-app -p $PATCH_SYSTEM_VOLUMES
    oc patch dc system-sidekiq -p $PATCH_SYSTEM_VOLUMES
1.4.1.2. EFK ロギングの設定

stdout への監査ログの送付を有効にして 3scale アプリケーションログが OpenShift に転送されるようになったら、EFK ロギングツールを使用して 3scale アプリケーションを監視することができます。

OpenShift での EFK ロギングの設定方法については、以下のドキュメントを参照してください。

1.4.2. ログへのアクセス

各コンポーネントのデプロイメント設定には、アクセスと例外のログが含まれます。デプロイメントで問題が発生した場合には、これらのログで詳細を確認してください。

3scale のログにアクセスするには、以下の手順に従います。

  1. ログを必要とする Pod の ID を確認します。

    oc get pods
  2. oc logs と選択した Pod の ID を入力します。

    oc logs <pod>

    システム Pod にはコンテナーが 2 つあり、それぞれに別個のログがあります。コンテナーのログにアクセスするには、--container パラメーターで system-providersystem-developer Pod を指定します。

    oc logs <pod> --container=system-provider
    oc logs <pod> --container=system-developer

1.4.3. ジョブキューの確認

ジョブキューには、system-sidekiq Pod から送られる情報のログが含まれます。これらのログを使用して、クラスターがデータを処理しているかどうかを確認します。OpenShift CLI を使用してログを照会することができます。

oc get jobs
oc logs <job>

1.4.4. 単調増加の防止

単調増加を防止するために、3scale はデフォルトで以下のテーブルの自動パージをスケジュールします。

  • user_sessions: クリーンアップは週 1 回トリガーされ、2 週間より前のレコードを削除します。
  • audits: クリーンアップは 1 日 1 回トリガーされ、3 カ月より前のレコードを削除します。
  • log_entries: クリーンアップは 1 日 1 回トリガーされ、6 カ月より前のレコードを削除します。
  • event_store_events: クリーンアップは週 1 回トリガーされ、1 週間より前のレコードを削除します。

alerts テーブルは例外で、データベース管理者が手動でパージする必要があります。

データベースタイプSQL コマンド

MySQL

DELETE FROM alerts WHERE timestamp < NOW() - INTERVAL 14 DAY;

PostgreSQL

DELETE FROM alerts WHERE timestamp < NOW() - INTERVAL '14 day';

Oracle

DELETE FROM alerts WHERE timestamp <= TRUNC(SYSDATE) - 14;

本セクションで説明しない他のテーブルについては、データベース管理者は、システムで自動的にパージされないテーブルを手動でクリーンアップする必要があります。

第2章 3scale toolbox の使用

3scale toolbox は、コマンドラインから 3scale サービスを管理することのできる Ruby クライアントです。

2.1. toolbox のインストール

公式にサポートされている 3scale ツールボックスのインストール方法は次のとおりです。

  • yum または rpm を使用する Red Hat Enterprise Linux
  • 3scale ツールボックスコンテナーイメージ

2.1.1. RHEL へのツールボックスのインストール

yum または rpm を使用して、ツールボックスを Red Hat Enterprise Linux にインストールできます。

前提条件

次のリポジトリーへのアクセスを有効にする必要があります。

  • rhel-7-server-3scale-amp-2.6-rpms
  • rhel-server-rhscl-7-rpms

以下に例を示します。

$ sudo subscription-manager repos --enable=rhel-7-server-3scale-amp-2.6-rpms --enable rhel-server-rhscl-7-rpms

手順

  1. ツールボックスをインストールします。

    $ yum install 3scale-toolbox
  2. インストールを確認します。

    $ 3scale help

2.1.2. toolbox コンテナーイメージのインストール

前提条件

  • 3scale-amp26/toolbox イメージについては、Red Hat Container Catalog ページ を参照してください。
  • Red Hat レジストリーサービスアカウントがある。
  • Docker がインストールされていて、デーモンが実行されている必要があります。

手順

  1. Red Hat コンテナーレジストリーにログインします。

    $ docker login registry.redhat.io
    Username: ${REGISTRY-SERVICE-ACCOUNT-USERNAME}
    Password: ${REGISTRY-SERVICE-ACCOUNT-PASSWORD}
    Login Succeeded!
  2. toolbox のコンテナーイメージをプルします。

    $ docker pull registry.redhat.io/3scale-amp26/toolbox
  3. インストールを確認します。

    $ docker run --rm registry.redhat.io/3scale-amp26/toolbox:latest 3scale help

関連情報

2.1.3. サポートされないバージョンの toolbox のインストール

ただし、Fedora Linux、Ubuntu Linux、Windows、または macOS に、サポートされないバージョンを使用できます。そのためには、最新の .rpm.deb.msi、または .pkg ファイルを GitHub から ダウンロードしてインストールします。

2.2. サポートされる toolbox コマンドの使用

3scale toolbox を使用して、コマンドラインツール (CLI) から API を管理します。

注記
  • update コマンドが非推奨になり、copy コマンドに置き換えられています。

    • Red Hat は、非推奨になった機能の使用をお勧めしません。

サポートされるコマンドは以下のとおりです。

COMMANDS
    account              account super command
    activedocs           activedocs super command
    application          application super command
    application-plan     application-plan super command
    copy                 copy super command
    help                 show help
    import               import super command
    method               method super command
    metric               metric super command
    policy-registry      policy-registry super command
    proxy-config         proxy-config super command
    remote               remotes super command
    service              services super command
    update               [DEPRECTATED] update super command

OPTIONS
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.3. サービスのインポート

以下のフィールドをこの順序で指定して、CSV ファイルからサービスをインポートします (CSV ファイルにこれらのヘッダーを含める必要もあります)。

service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type

以下の情報が必要になります。

  • 3scale 管理アカウント: {3SCALE_ADMIN}
  • 3scale インスタンスが動作中のドメイン: {DOMAIN_NAME} (Hosted APICast を使用している場合は 3scale.net)
  • アカウントのアクセスキー: {ACCESS_KEY}
  • サービスの CSV ファイル (example/import_example.csv)

以下のコマンドを実行してサービスをインポートします。

$ 3scale import csv --destination=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --file=examples/import_example.csv

2.4. サービスのコピー

同じアカウントまたは別のアカウントから、既存のサービスをベースにして新しいサービスを作成します。サービスをコピーすると、関連する ActiveDocs もコピーされます。

以下の情報が必要です。

  • コピーするサービスの ID: {SERVICE_ID}
  • 3scale 管理アカウント: {3SCALE_ADMIN}
  • 3scale インスタンスが動作中のドメイン: {DOMAIN_NAME} (Hosted APICast を使用している場合は 3scale.net)
  • アカウントのアクセスキー: {ACCESS_KEY}
  • 別のアカウントにコピーする場合は、コピー先アカウントのアクセスキー: {DEST_KEY}
  • 新しいサービスの名前: {NEW_NAME}
$ 3scale copy service {SERVICE_ID} --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --target_system_name={NEW_NAME}
注記

コピーするサービスにカスタムポリシーがある場合、それぞれのカスタムポリシー定義がサービスのコピー先にすでに存在することを確認してください。カスタムポリシー定義のコピーについては、「ポリシーレジストリー (カスタムポリシー) のコピー」 を確認してください。

2.5. サービス設定のみのコピー

あるサービスから別の既存サービスに、サービス設定、プロキシー設定、メトリクス、メソッド、アプリケーションプラン、アプリケーションプランの制限、およびマッピングルールを一括コピー (更新とも呼ばれる) します。

以下の情報が必要になります。

  • コピーするサービスの ID: {SERVICE_ID}
  • コピー先のサービスの ID: {DEST_ID}
  • 3scale 管理アカウント: {3SCALE_ADMIN}
  • 3scale インスタンスが動作中のドメイン: {DOMAIN_NAME} (Hosted APICast を使用している場合は 3scale.net)
  • アカウントのアクセスキー: {ACCESS_KEY}
  • コピー先アカウントのアクセスキー: {DEST_KEY}

また、以下のオプションのフラグを使用できます。

  • -f: コピーする前に既存の対象サービスのマッピングルールを削除します。
  • -r: 対象サービスにマッピングルールのみをコピーします。
注記
  • update コマンドが非推奨になり、copy コマンドに置き換えられています。

    • Red Hat は、非推奨になった機能の使用をお勧めしません。
$ 3scale update [opts] service --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} {SERVICE_ID} {DEST_ID}

2.6. OpenAPI 定義のインポート

新しいサービスを作成する場合、または既存のサービスを更新する場合は、ローカルファイルまたはアクセスクレデンシャルからの定義を使用します。そのサービス名がすでに存在する場合は、それが更新されます。また、そのサービス名が存在しない場合は、作成されます。

インポートのデフォルトのサービス名は、OpenAPI 定義の info.title から取得されます。--target_system_name=<NEW NAME> を使用して、このサービス名を上書きできます。そのサービス名がすでに存在する場合は、それが更新されます。また、そのサービス名が存在しない場合は、作成されます。

以下のルールはすべてのインポートに適用されます。

  • 定義は OpenAPI 2.0 として検証される。
  • 3scale サービスのマッピングルールは、すべて削除される。
  • 置き換えるためには、パターンの完全一致の使用により、すべてのメソッドの名前が OpenAPI 定義 (operation.operationId) で定義されるメソッドと同一でなければならない。
  • OpenAPI 定義に含まれるメソッドのみが変更される。
  • OpenAPI 定義にしか存在していなかったすべてのメソッドが、Hits メトリクスにアタッチされる。
  • OpenAPI 定義のすべてのマッピングルールがインポートされる。

    • これらについては API > Integration で確認できます。
注記

swagger 仕様にセキュリティー要件がない場合、サービスは Open API とみなされます。ポリシーチェーンに default_credentials ポリシー (anonymous_policy とも呼ばれる) がまだない場合、toolbox はこのポリシーを追加します。default_credentials ポリシーは、オプションのパラメーター --default-credentials-userkey で提供される ユーザーキー で設定されます。

$ 3scale import openapi [opts] --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}

2.6.1. オプションのフラグ

-d --destination=<value>
3scale ターゲットインスタンス。形式: http[s]://<authentication>@3scale_domain
-t --target_system_name=<value>
ターゲットシステム名

2.7. リモートアクセスクレデンシャルの管理

リモートの 3scale インスタンスと容易に連携するため、設定ファイルでリモートの Web アドレス (URL) と共にこれらのインスタンスへのアクセスに使用する認証を定義します。3scale toolbox コマンドでは、これを短縮名で参照します。

設定ファイルのデフォルトの場所は $HOME/.3scalerc.yaml ですが、THREESCALE_CLI_CONFIG 環境変数、または --config-file <config_file> オプションを使用して、別の場所を指定することができます。

access_token または provider_key のいずれかを使用して、リモートを指定することができます。

  • http[s]://<access_token>@<3scale-instance-domain>
  • http[s]://<provider_key>@<3scale-instance-domain>

2.7.1. リモートアクセスクレデンシャルの一覧表示

3scale remote list [--config-file <config_file>]

既存のリモートのリスト (名前、URL、および認証キー) を表示します。

$ 3scale remote list
instance_a https://example_a.net 123456789
instance_b https://example_b.net 987654321

2.7.2. リモートアクセスクレデンシャルの追加

3scale remote add [--config-file <config_file>] <name> <url>

短縮名 <name> のリモートを <url> に追加します。

3scale remote add instance_a https://123456789@example_a.net

2.7.3. リモートアクセスクレデンシャルの削除

3scale remote remove [--config-file <config_file>] <name>

短縮名 <name> のリモートを削除します。

3scale remote remove instance_a

2.7.4. リモートアクセスクレデンシャルの名前変更

3scale remote rename [--config-file <config_file>] <old_name> <new_name>

リモートの短縮名を <old_name> から <new_name> に変更します。

3scale remote rename instance_a instance_b

2.8. アプリケーションプラン

3scale toolbox を使用して、デベロッパーポータルのアプリケーションプランの作成、更新、一覧表示、削除、表示、またはエクスポート/インポートを行います。

2.8.1. 新しいアプリケーションプランの作成

新しいアプリケーションプランを作成するには、以下の手順に従います。

  • アプリケーションプラン名を指定する必要があります。
  • system-name を上書きするには、オプションのパラメーターを使用します。
  • 同じ名前のアプリケーションプランがすでに存在する場合、エラーメッセージが表示されます。
  • --default フラグを使用して、アプリケーションプランを デフォルト として設定します。
  • --publish フラグを使用して、公開済み アプリケーションプランを作成します。

    • デフォルトでは、非表示 になります。
  • --disabled フラグを使用して、無効な アプリケーションプランを作成します。

    • デフォルトでは、有効 になります。
注記
  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

    • toolbox は、どちらか一方を使用します。

次の例では、新しいアプリケーションプランを作成します。

3scale application-plan create [opts] <remote> <service> <plan-name>

アプリケーションプランの作成時に、以下のオプションを使用します。

Options
       --approval-required=<value>      The application requires approval: true or false
       --cost-per-month=<value>         Cost per month
    -d --default                        This will make the default application plan
       --disabled                       This will disable all methods and metrics in
                                        the application plan
       --end-user-required=<value>      End user required: true or false
    -p --published                      This will publish the application plan
       --setup-fee=<value>              Set-up fee
    -t --system-name=<value>            This will set application plan system name
       --trial-period-days=<value>      The trial period in days

Options for application-plan
    -c --config-file=<value>            3scale toolbox configuration file
                                        (default: $HOME/.3scalerc.yaml)
    -h --help                           show help for this command
    -k --insecure                       Proceed and operate even for server
                                        connections otherwise considered insecure
    -v --version                        This will print the version of this command
       --verbose                        Verbose mode

2.8.2. アプリケーションプランの作成または更新

アプリケーションプランが存在しない場合に新しく作成する、または既存のアプリケーションプランを更新するには、以下の手順に従います。

  • --default フラグを使用して、デフォルト アプリケーションプランを更新します。
  • --publish フラグを使用して、公開済み アプリケーションプランを更新します。
  • --hide フラグを使用して、非表示の アプリケーションを更新します。
  • --disabled フラグを使用して、無効な アプリケーションプランを更新します。
  • --enabled フラグを使用して、有効な アプリケーションプランを更新します。
注記
  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

    • toolbox は、どちらか一方を使用します。
  • plan 位置引数はプランの参照で、プランの id またはプランの system_name のどちらかです。

    • toolbox は、どちらか一方を使用します。

次の例では、アプリケーションプランを更新します。

3scale application-plan apply [opts] <remote> <service> <plan>

アプリケーションプランの更新時に、以下のオプションを使用します。

Options
       --approval-required=<value>      The application requires approval: true or false
       --cost-per-month=<value>         Cost per month
       --default                        This will make the default application plan
       --disabled                       This will disable all methods and metrics in
                                        the application plan
       --enabled                        This will enable the application plan
       --end-user-required=<value>      End user required: true or false
       --hide                           This will hide the application plan
    -n --name=<value>                   This will set the plan name
    -p --publish                        This will publish the application plan
       --setup-fee=<value>              Set-up fee
       --trial-period-days=<value>      The trial period in days

Options for application-plan
    -c --config-file=<value>            3scale toolbox configuration file
                                        (default: $HOME/.3scalerc.yaml)
    -h --help                           show help for this command
    -k --insecure                       Proceed and operate even for server
                                        connections otherwise considered
                                        insecure
    -v --version                        This will print the version of this command
       --verbose                        Verbose mode

2.8.3. アプリケーションプランの一覧表示

次の例は、アプリケーションプランを一覧表示します。

3scale application-plan list [opts] <remote> <service>

アプリケーションプランの一覧表示時に、以下のオプションを使用します。

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default:$HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.8.4. アプリケーションプランの表示

次の例は、アプリケーションプランを示しています。

3scale application-plan show [opts] <remote> <service> <plan>

アプリケーションプランの表示時に、以下のオプションを使用します。

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.8.5. アプリケーションプランの削除

次の例では、アプリケーションプランを削除します。

3scale application-plan delete [opts] <remote> <service> <plan>

アプリケーションプランの削除時に、以下のオプションを使用します。

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.8.6. アプリケーションプランのエクスポート/インポート

単一のアプリケーションプランを yaml コンテンツにエクスポートすることや、コンテンツからインポートすることができます。

次の点に注意してください。アプリケーションプランで定義される制限が含まれます。アプリケーションプランで定義される課金ルールが含まれます。制限および課金ルールで参照されるメトリクス/メソッドが含まれます。アプリケーションプランで定義される機能が含まれます。サービスは id または system_name で参照できます。アプリケーションプランは id または system_name で参照できます。

2.8.6.1. ファイルへのアプリケーションプランのエクスポート

次の例では、アプリケーションプランをエクスポートします。

3scale application-plan export [opts] <remote> <service_system_name> <plan_system_name>

3scale application-plan export -f plan.yaml remote_name service_name plan_name

注記

export コマンドに固有の事項

  • リモートサービスおよびアプリケーションプランでは、読み取り専用操作になります。
  • コマンド出力は、stdout またはファイルのどちらかです。

    • -f オプションで指定しない場合、デフォルトでは、yaml コンテンツは stdout に書き出されます。

アプリケーションプランのエクスポート時に、以下のオプションを使用します。

Options
    -f --file=<value>             Write to file instead of stdout

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode
2.8.6.2. ファイルからのアプリケーションプランのインポート

次の例では、アプリケーションプランをインポートします。

3scale application-plan import [opts] <remote> <service_system_name>

3scale application-plan import -f plan.yaml remote_name service_name

2.8.6.3. URL からのアプリケーションプランのインポート
3scale application-plan import -f http[s]://domain/resource/path.yaml remote_name service_name
注記

import コマンドに固有の事項

  • コマンド入力コンテンツは、stdin、ファイル、または URL 形式のいずれかです。

    • -f オプションで指定しない場合、デフォルトでは、yaml コンテンツは stdin から読み込まれます。
  • アプリケーションプランがリモートサービスで見つからない場合は、アプリケーションプランが作成されます。
  • オプションのパラメーター -p--plan を使用すると、リモートターゲットのアプリケーションプランの id または system_name が上書きされます。

    • -p オプションで指定されていない場合、デフォルトでは、yaml コンテンツからのプラン属性 system_name によってアプリケーションプランが参照されます。
  • yaml コンテンツからのメトリクスまたはメソッドがリモートサービスで見つからない場合は、メトリクスまたはメソッドが作成されます。

アプリケーションプランのインポート時に、以下のオプションを使用します。

Options
    -f --file=<value>                  Read from file or url instead of stdin
    -p --plan=<value>                  Override application plan reference

Options for application-plan
    -c --config-file=<value>           3scale toolbox configuration file
                                       (default: $HOME/.3scalerc.yaml)
    -h --help                          show help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Prints the version of this command
       --verbose                       Verbose mode

2.9. メトリック

3scale toolbox を使用して、デベロッパーポータルのメトリクスの作成、更新、一覧表示、および削除を行います。

2.9.1. メトリクスの作成

メトリクスを作成するには、以下の手順に従います。

  • メトリクス名を指定する必要があります。
  • system-name を上書きするには、オプションのパラメーターを使用します。
  • 同じ名前のメトリクスがすでに存在する場合、エラーメッセージが表示されます。
  • --disabled フラグを使用して、無効な メトリクスを作成します。

    • デフォルトでは、有効 になります。
注記
  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

    • toolbox は、どちらか一方を使用します。

次の例では、メトリックを作成します。

3scale metric create [opts] <remote> <service> <metric-name>

メトリクスの作成時に、以下のオプションを使用します。

Options
       --description=<value>      This will set a metric description
       --disabled                 This will disable this metric in all application plans
    -t --system-name=<value>      This will set the application plan system name
       --unit=<value>             Metric unit: default hit

Option for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.9.2. メトリクスの作成または更新

メトリクスが存在しない場合に新しく作成する、または既存のメトリクスを更新するには、以下の手順に従います。

  • 同じ名前のメトリクスがすでに存在する場合、エラーメッセージが表示されます。
  • --disabled フラグを使用して、無効な メトリクスを更新します。
  • --enabled フラグを使用して、有効な メトリクスに更新します。
注記
  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

    • toolbox は、どちらか一方を使用します。
  • metric 位置引数はメトリクス参照で、メトリクスの id またはメトリクスの system_name のどちらかです。

    • toolbox は、どちらか一方を使用します。

次の例では、メトリックを更新します。

3scale metric apply [opts] <remote> <service> <metric>

メトリクスの更新時に、以下のオプションを使用します。

Options
       --description=<value>      This will set a metric description
       --disabled                 This will disable this metric in all application plans
       --enabled                  This will enable this metric in all application plans
    -n --name=<value>             This will set the metric name
       --unit=<value>             Metric unit: default hit

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.9.3. メトリクスの一覧表示

次の例は、メトリックを一覧表示します。

3scale metric list [opts] <remote> <service>

メトリクスの一覧表示時に、以下のオプションを使用します。

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.9.4. メトリクスの削除

次の例では、メトリックを削除します。

3scale metric delete [opts] <remote> <service> <metric>

メトリクスの削除時に、以下のオプションを使用します。

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.10. メソッド

3scale toolbox を使用して、デベロッパーポータルのメソッドの作成、適用、一覧表示、および削除を行います。

2.10.1. メソッドの作成

  • メソッド名を指定する必要があります。
  • system-name を上書きするには、オプションのパラメーターを使用します。
  • 同じ名前のメソッドがすでに存在する場合、エラーメッセージが表示されます。
  • --disabled フラグを使用して、無効な メソッドを作成します。

    • デフォルトでは、有効 になります。
注記
  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

    • toolbox は、どちらか一方を使用します。

次の例では、メソッドを作成します。

3scale method create [opts] <remote> <service> <method-name>

メソッドの作成時に、以下のオプションを使用します。

Option
       --description=<value>      This will set a method description
       --disabled                 This will disable this method in all
                                  application plans
    -t --system-name=<value>      This will set the method system name

Options for method
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.10.2. メソッドの作成または更新

メソッドが存在しない場合に新しく作成する、または既存のメソッドを更新するには、以下の手順に従います。

  • 同じ名前のメソッドがすでに存在する場合、コマンドは失敗します。
  • --disabled フラグを使用して、無効な メソッドに更新します。
  • --enabled フラグを使用して、有効な メソッドに更新します。
注記
  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

    • toolbox は、どちらか一方を使用します。
  • method 位置引数はメソッド参照で、メソッドの id またはメソッドの system_name のどちらかです。

    • toolbox は、どちらか一方を使用します。

次の例では、メソッドを更新します。

3scale method apply [opts] <remote> <service> <method>

メソッドの更新時に、以下のオプションを使用します。

Options
       --description=<value>      This will set a method description
       --disabled                 This will disable this method in all
                                  application plans
       --enabled                  This will enable this method in all
                                  application plans
    -n --name=<value>             This will set the method name

Options for method
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     This will show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.10.3. メソッドの一覧表示

次の例は、メソッドを一覧表示します。

3scale method list [opts] <remote> <service>

メソッドの一覧表示時に、以下のオプションを使用します。

Options for method
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.10.4. メソッドの削除

次の例では、メソッドを削除します。

3scale method delete [opts] <remote> <service> <metric>

メソッドの削除時に、以下のオプションを使用します。

Options for method
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.11. サービスの作成

3scale toolbox を使用して、デベロッパーポータルのサービスの作成、適用、一覧表示、表示、または削除を行います。

2.11.1. 新しいサービスの作成

次の例では、新しいサービスを作成します。

3scale service create [options] <remote> <service-name>

サービスの作成時に、以下のオプションを使用します。

Options
    -a --authentication-mode=<value>      Specify authentication mode of the
                                          service ('1' for API key, '2' for
                                          App Id / App Key, 'oauth' for OAuth
                                          mode, 'oidc' for OpenID Connect)
    -d --deployment-mode=<value>          Specify the deployment mode of the
                                          service
       --description=<value>              Specify the description of the
                                          service
    -s --system-name=<value>              Specify the system-name of the
                                          service
       --support-email=<value>            Specify the support email of the
                                          service

Options for service
    -c --config-file=<value>              3scale toolbox configuration file
                                          (default:
                                          $HOME/.3scalerc.yaml)
    -h --help                             show help for this command
    -k --insecure                         Proceed and operate even for server
                                          connections otherwise considered
                                          insecure
    -v --version                          Prints the version of this command
       --verbose                          Verbose mode

2.11.2. サービスの作成または更新

サービスが存在しない場合に新しく作成する、または既存のサービスを更新するには、以下の手順に従います。

注記
  • service-id_or_system-name 位置引数は、サービス参照です。

    • サービスの id、またはサービスの system_name のどちらかです。
    • toolbox は、これを自動的に判別します。
  • このコマンドは べきとう性 を持ちます。

次の例では、サービスを更新します。

3scale service apply <remote> <service-id_or_system-name>

サービスの更新時に、以下のオプションを使用します。

Options
    -a --authentication-mode=<value>      Specify authentication mode of the
                                          service ('1' for API key, '2' for
                                          App Id / App Key, 'oauth' for OAuth
                                          mode, 'oidc' for OpenID Connect)
    -d --deployment-mode=<value>          Specify the deployment mode of the
                                          service
       --description=<value>              Specify the description of the
                                          service
    -n --name=<value>                     Specify the name of the metric
       --support-email=<value>            Specify the support email of the
                                          service

Options for services
    -c --config-file=<value>              3scale toolbox configuration file
                                          (default: $HOME/.3scalerc.yaml)
    -h --help                             show help for this command
    -k --insecure                         Proceed and operate even for server
                                          connections otherwise considered
                                          insecure
    -v --version                          Prints the version of this command
       --verbose                          Verbose mode

2.11.3. サービスの一覧表示

次の例は、サービスを一覧表示します。

3scale service list <remote>

サービスの一覧表示時に、以下のオプションを使用します。

Options for services
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.11.4. サービスの表示

次の例は、サービスを示しています。

3scale service show <remote> <service-id_or_system-name>

サービスの表示時に、以下のオプションを使用します。

Options for services
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.11.5. サービスの削除

次の例では、サービスを削除します。

3scale service delete <remote> <service-id_or_system-name>

サービスの削除時に、以下のオプションを使用します。

Options for services
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.12. ActiveDocs

3scale toolbox を使用して、デベロッパーポータルの ActiveDocs の作成、更新、一覧表示、または削除を行います。

2.12.1. 新しい ActiveDocs の作成

OpenAPI/Swagger 準拠の API 定義から新しい ActiveDocs を作成するには、以下の手順を実施します。

  1. API 定義を 3scale に追加し、オプションで名前を付けます。

    3scale activedocs create <remote> <activedocs-name> <spec>

    ActiveDocs の作成時に、以下のオプションを使用します。

Options
    -d --description=<value>           Specify the description of the
                                       ActiveDocs
    -i --service-id=<value>            Specify the Service ID associated to
                                       the ActiveDocs
    -p --published                     Specify it to publish the ActiveDoc on
                                       the Developer Portal. Otherwise it
                                       will be hidden
    -s --system-name=<value>           Specify the system-name of the
                                       ActiveDocs
       --skip-swagger-validations      Specify it to skip validation of the
                                       Swagger specification

Options for ActiveDocs
    -c --config-file=<value>           3scale toolbox configuration file
                                       (default: $HOME/.3scalerc.yaml)
    -h --help                          show help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Prints the version of this command
       --verbose                       Verbose mode
  1. デベロッパーポータルに定義を 公開 します。

2.12.2. ActiveDocs の作成または更新

ActiveDoc が存在しない場合に新しく作成する、または新しい API 定義で既存の ActiveDocs を更新するには、以下を使用します。

3scale activedocs apply <remote> <activedocs_id_or_system_name>

ActiveDocs の更新時に、以下のオプションを使用します。

Options
    -d --description=<value>           Specify the description of the
                                       ActiveDocs
       --hide                          Specify it to hide the ActiveDocs on
                                       the Developer Portal
    -i --service-id=<value>            Specify the Service ID associated to
                                       the ActiveDocs
       --openapi-spec=<value>          Specify the swagger spec. Can be a
                                       file, an URL or '-' to read from
                                       stdin. This option is mandatory when
                                       applying the ActiveDoc for the first
                                       time
    -p --publish                       Specify it to publish the ActiveDocs
                                       on the Developer Portal. Otherwise it
                                       will be hidden
    -s --name=<value>                  Specify the name of the ActiveDocs
       --skip-swagger-validations      Specify it to skip validation of the
                                       Swagger specification

Options for ActiveDocs
    -c --config-file=<value>           3scale toolbox configuration file
                                       (default: $HOME/.3scalerc.yaml)
    -h --help                          show help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Prints the version of this command
       --verbose                       Verbose mode

2.12.3. ActiveDocs の一覧表示

以下の項目を含め、デベロッパーポータルのすべての ActiveDocs に関する情報を取得するには、以下のコマンドを使用します。

  • ID
  • 名前
  • システム名
  • 説明
  • 公開済み (つまり、デベロッパーポータルに表示可能) かどうか
  • 作成日
  • 最終更新日

次の例では、定義されたすべての ActiveDocs を一覧表示します。

3scale activedocs list <remote>

ActiveDocs の一覧表示時に、以下のオプションを使用します。

Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.12.4. ActiveDocs の削除

次の例では、ActiveDocs を削除します。

3scale activedocs delete <remote> <activedocs-id_or-system-name>

ActiveDocs の削除時に、以下のオプションを使用します。

Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.13. プロキシー設定

3scale toolbox を使用して、デベロッパーポータルのすべての定義済みプロキシー設定の一覧表示、表示、およびプロモートを行います。

2.13.1. プロキシー設定の一覧表示

次の例は、プロキシー設定を一覧表示します。

3scale proxy-config list <remote> <service> <environment>

プロキシー設定の一覧表示時に、以下のオプションを使用します。

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  /home/msoriano/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.13.2. プロキシー設定の表示

次の例は、プロキシー設定を示しています。

3scale proxy-config show <remote> <service> <environment>

プロキシー設定の表示時に、以下のオプションを使用します。

Options for proxy-config
    -c --config-file=<value>         3scale toolbox configuration file
                                     (default: /home/msoriano/.3scalerc.yaml)
    -h --help                        show help for this command
    -k --insecure                    Proceed and operate even for server
                                     connections otherwise considered
                                     insecure
    -v --version                     Prints the version of this command
       --verbose                     Verbose mode

2.13.3. プロキシー設定のプロモート

以下の例では、最新のステージング環境用プロキシー設定が実稼働環境にプロモートされます。

3scale proxy-config promote <remote> <service>

最新のステージング環境用プロキシー設定を実稼働環境にプロモートする際に、以下のオプションを使用します。

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  /home/msoriano/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.14. ポリシーレジストリー (カスタムポリシー) のコピー

以下に該当する場合、toolbox コマンドを使用して、3scale のソースアカウントからターゲットアカウントにポリシーレジストリーをコピーします。

  • 存在しないカスタムポリシーがターゲットアカウントに作成されている。
  • 一致するカスタムポリシーがターゲットアカウントで更新されている。
  • この copy コマンドがべきとう性を持つ。
注記
  • 存在しないカスタムポリシーとは、ソースアカウントには存在するが、アカウントのテナントには存在しないカスタムポリシーと定義されます。
  • 一致するカスタムポリシーとは、ソースアカウントとターゲットアカウントの両方に存在するカスタムポリシーと定義されます。

次の例では、ポリシーレジストリーをコピーします。

3scale policy-registry copy [opts] <source_remote> <target_remote>

Option for policy-registry
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.15. アプリケーション

3scale toolbox を使用して、デベロッパーポータルのアプリケーションの一覧表示、作成、表示、適用、または削除を行います。

2.15.1. アプリケーションの一覧表示

次の例は、アプリケーションを一覧表示します。

3scale application list [opts] <remote>

アプリケーションの一覧表示時に、以下のオプションを使用します。

OPTIONS
       --account=<value>          Filter by account
       --plan=<value>             Filter by application plan.
                                  Service option required.
       --service=<value>          Filter by service

2.15.2. アプリケーションの作成

特定の 3scale アカウントおよびアプリケーションプランにリンクされたアプリケーションを 1 つ作成するには、create コマンドを使用します。

必要な位置パラメーターは以下のとおりです。

  • <service> 参照。サービスの id またはサービスの system_name のどちらかです。
  • <account> 参照。次のいずれかです。

    • アカウント id
    • アカウントの管理ユーザーの usernameemail、または user_id
    • provider_key
  • <application plan> 参照。プランの id またはプランの system_name のどちらかです。
  • <name> アプリケーション名。

次の例では、アプリケーションを作成します。

3scale application create [opts] <remote> <account> <service> <application-plan> <name>

アプリケーションの作成時に、以下のオプションを使用します。

Options
       --application-id=<value>       App ID or Client ID (for OAuth and
                                      OpenID Connect authentication modes) of
                                      the application to be created.
       --application-key=<value>      App Key(s) or Client Secret (for OAuth
                                      and OpenID Connect authentication
                                      modes) of the application to be
                                      created.
       --description=<value>          Application description
       --redirect-url=<value>         OpenID Connect redirect url
       --user-key=<value>             User Key (API Key) of the application
                                      to be created.

2.15.3. アプリケーションの表示

次の例は、アプリケーションを示しています。

3scale application show [opts] <remote> <application>

アプリケーションパラメーターは以下のいずれかです。

  • user_key: API キー
  • App_id: app_id/app_key ペアから、または OAuth および OpenID Connect (OIDC) 認証モードの Client ID
  • アプリケーションの内部 id

2.15.4. アプリケーションの作成または更新

アプリケーションが存在しない場合に新しく作成する、または既存のアプリケーションを更新するには、以下を使用します。

3scale application apply [opts] <remote> <application>

アプリケーションパラメーターは以下のいずれかです。

  • user_key: API キー
  • App_id: app_id/app_key ペアから、または OAuth および OIDC 認証モードの Client ID
  • アプリケーションの内部 id
  • アプリケーションが見つからず作成する必要がある場合は、オプションの account 引数が必要です。次のいずれかです。

    • アカウント id
    • 3scale アカウントの管理ユーザーの usernameemail、または user_id
    • provider_key
  • 3scale ではアプリケーション名が一意ではないため、name は固有の識別子として使用できません。
  • --resume フラグで、一時停止されていたアプリケーションを再開します。
  • アプリケーションの一時停止: --suspend フラグで状態を一時停止中に変更します。

アプリケーションの更新時に、以下のオプションを使用します。

OPTIONS
       --account=<value>              Application's account. Required when
                                      creating
       --application-key=<value>      App Key(s) or Client Secret (for OAuth
                                      and OpenID Connect authentication
                                      modes) of the application to be
                                      created. Only used when application
                                      does not exist.
       --description=<value>          Application description
       --name=<value>                 Application name
       --plan=<value>                 Application's plan. Required when
                                      creating
       --redirect-url=<value>         OpenID Connect redirect url
       --resume                       Resume a suspended application
       --service=<value>              Application's service. Required when
                                      creating
       --suspend                      Suspends an application (changes the
                                      state to suspended)
       --user-key=<value>             User Key (API Key) of the application
                                      to be created.

2.15.5. アプリケーションの削除

次の例では、アプリケーションを削除します。

3scale application delete [opts] <remote> <application>

アプリケーションパラメーターは以下のいずれかです。

  • user_key: API キー
  • App_id: app_id/app_key ペアから、または OAuth および OIDC 認証モードの Client ID
  • アプリケーションの内部 id

2.16. SSL の問題のトラブルシューティング

Red Hat のドキュメントに 証明書 の詳細が記載されていますが、自己署名 SSL 証明書、SSL 証明書の問題: 自己署名証明書 などに関連する問題が発生している場合は、リモート証明書をダウンロードして使用できます。

  1. openssl を使用してリモート証明書をダウンロードします。

    $ echo | openssl s_client -showcerts -servername self-signed.badssl.com -connect self-signed.badssl.com:443 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > self-signed-cert.pem
  2. curl で使用して動作することを確認してください。

    $ SSL_CERT_FILE=self-signed-cert.pem curl -v https://self-signed.badssl.com

    証明書が正常に機能している場合、SSL エラーは発生しません。

  3. 3scale コマンドの前に SSL_CERT_FILE=self-signed-cert.pem を付けます。

    $ SSL_CERT_FILE=self-signed-cert.pem 3scale import csv

第3章 Automating API lifecycle with 3scale toolbox

本トピックでは、Red Hat 3scale API Management での API ライフサイクルの概念について説明し、3scale toolbox コマンドにより API プロバイダーが Jenkins Continuous Integration/Continuous Deployment (CI/CD) パイプラインを使用してデプロイメントステージを自動化する方法を紹介します。ここでは、サンプルの Jenkins CI/CD パイプラインのデプロイ方法、3scale 共有ライブラリーを使用してカスタムの Jenkins パイプラインを作成する方法、およびカスタムパイプラインをゼロから作成する方法について説明します。

3.1. API ライフサイクルステージの概要

API ライフサイクルは、API が作成されてから廃止されるまでに必要なすべてのアクティビティーについて説明するものです。3scale を使用すると、API プロバイダーはあらゆる API ライフサイクル管理を実施できるようになります。本セクションでは、API ライフサイクルの各ステージ、ならびにその目的および予想される結果について説明します。

以下の図は、左側に API プロバイダーベースのステージを、右側に API 利用者ベースのステージを示しています。

API lifecycle stages
注記

Red Hat は、現在 API プロバイダーサイクルの設計、実装、デプロイ、保護、および管理のフェーズ、ならびに API 利用者サイクルのすべてのフェーズをサポートしています。

3.1.1. API プロバイダーサイクル

API プロバイダーサイクルのステージは、API の詳細規定、開発、およびデプロイをベースとしています。以下に、各ステージの目的と成果を説明します。

表3.1 API プロバイダーライフサイクルのステージ
ステージ目的成果

1.ストラテジー

目的、リソース、ターゲットマーケット、タイムフレームを含む API の企業ストラテジーを決定し、計画を立てる。

目的を達成するための明確な計画と共に、企業ストラテジーが定義される。

2.設計

API 契約を早期に作成し、プロジェクト間の依存関係を解消し、フィードバックを収集して、リスクを下げ、市場に出すまでの時間を短縮する (たとえば、Apicurio Studio を使用)。

利用者向けの API 契約により、API で交換できるメッセージが定義される。API 利用者がフィードバックを提供している。

3.モック

実際の例と負荷を想定してさらに API 契約を規定し、API 利用者がこれを使用して実装を開始できるようにする。

モック API が稼働中で、実際の例を返す。例を想定した API 契約が完成する。

4.テスト

ビジネスを想定してさらに API 契約を規定し、開発した API のテストに使用できるようにする。

受け入れテストのセットが作成される。ビジネスを想定した API ドキュメントが完成する。

5.実装

Red Hat Fuse や希望の開発言語などのインテグレーションフレームワークを使用して、API を実装する。実装と API 契約を一致させる。

API が実装される。カスタム API 管理機能が必要な場合は、3scale APIcast ポリシーも開発される。

6.デプロイ

CI/CD パイプラインを 3scale toolbox で使用して、API インテグレーション、テスト、デプロイメント、および管理を自動化する。

CI/CD パイプラインにより、API が自動化された方法で実稼働環境に統合、テスト、デプロイ、および管理される。

7.保護

API が保護されるようにする (たとえば、セキュアな開発プラクティスと自動化されたセキュリティーテストを使用)。

セキュリティーガイドライン、プロセス、およびゲートが準備される。

8.管理

環境間の API プロモーション、バージョン管理、非推奨化、および廃止をまとめて管理する。

API をまとめて管理するためのプロセスとツールが準備される (たとえば、セマンティックバージョン管理により API の変更の違反を防止)。

3.1.2. API 利用者サイクル

API 利用者サイクルのステージは、API を利用するためのプロモーション、配布、および調整をベースとしています。以下に、各ステージの目的と成果を説明します。

表3.2 API 利用者ライフサイクルのステージ
ステージ目的成果

9.検出

API をサードパーティーの開発者、パートナー、および内部ユーザーにプロモーションする。

デベロッパーポータルが稼働中で、最新版のドキュメントがこのデベロッパーポータルに継続的にプッシュされる (たとえば、3scale ActiveDocs を使用)。

10.開発

サードパーティーの開発者、パートナー、および内部ユーザーが API をベースにアプリケーションを開発できるよう支援する。

デベロッパーポータルに、ベストプラクティス、ガイド、および推奨事項が含まれる。API 開発者がモックエンドポイントおよびテストエンドポイントにアクセスし、ソフトウェアを開発する。

11.利用

API 利用の増加を処理し、多数の API 利用者を管理する。

ステージングされたアプリケーションプランが利用でき、最新の価格と制限が継続的にプッシュされる。API 利用者が CI/CD パイプラインから API キーまたはクライアント ID/シークレットの生成を統合できる。

12.監視

API の健全性、品質、および開発者の関与について、実際の定量化されたフィードバックを収集する (たとえば、最初の Hello World! の時間のメトリクスなど)。

監視システムが準備される。ダッシュボードに API の KPI (たとえば、稼働時間、分ごとのリクエスト数、レイテンシーなど) が表示される。

13.収益化

新しい収益を大規模に獲得する (このステージはオプション)。

たとえば、小規模な API 利用者を多数獲得することをターゲットにする場合、収益化が有効化され、利用者が使用量に基づいて自動的に課金される。

3.2. サンプル Jenkins CI/CD パイプラインのデプロイ

3scale toolbox による API ライフサイクルの自動化は、API ライフサイクルのデプロイメントステージが対象で、CI/CD パイプラインを使用して API 管理ソリューションを自動化することができます。本トピックでは、3scale toolbox を呼び出すサンプル Jenkins パイプラインをデプロイする方法を説明します。

3.2.1. サンプル Jenkins CI/CD パイプライン

API ライフサイクルの自動化用に Jenkins パイプラインを作成してデプロイする方法の例として、以下のサンプルが Red Hat Integration リポジトリーで提供されています。

表3.3 サンプル Jenkins 共有ライブラリーパイプライン
サンプルパイプラインターゲット環境セキュリティー

SaaS - API key

ホスト型 3scale

API キー

Hybrid - open

Self-managed APIcast を使用するホスト型 3scale およびオンプレミス型 3scale

なし

Hybrid - OpenID Connect

Self-managed APIcast を使用するホスト型 3scale およびオンプレミス型 3scale

OpenID Connect (OIDC)

Multi-environment

Self-managed APIcast を使用する、開発、テスト、および実稼働環境のホスト型 3scale

API キー

Semantic versioning

Self-managed APIcast を使用する、開発、テスト、および実稼働環境のホスト型 3scale

API キー、なし、OIDC

これらのサンプルは、3scale toolbox を呼び出す 3scale Jenkins 共有ライブラリーを使用して、主要な API 管理機能を実証します。本トピックの設定手順を実施したら、各 Red Hat Integration リポジトリーのユースケース例 で提供される OpenShift テンプレートを使用してパイプラインをインストールすることができます。

重要

サンプルパイプラインおよびアプリケーションは、例としてのみ提供されています。Red Hat は、パイプラインに加えた変更を直接サポートしません。ベースとなる API、CLI、およびサンプルパイプラインが活用するその他のインターフェイスは、Red Hat により完全にサポートされています。

3.2.2. ホスト型 3scale 環境の設定

ホスト型 3scale 環境の設定は、すべてのサンプル Jenkins CI/CD パイプラインで必要です。

注記

SaaS - API key、Multi-environment、および Semantic versioning のサンプルパイプライン は、ホスト型 3scale しか使用しません。Hybrid - open および Hybrid - OIDC のパイプラインは、オンプレミス型 3scale も使用します。「オンプレミス型 3scale 環境の設定」も併せて参照してください。

前提条件

  • Linux ワークステーションがある。
  • ホスト型 3scale 環境が用意されている。
  • OpenShift 3.11 クラスターがある。現在、OpenShift 4 はサポートされていません。
  • OpenShift のドキュメント で説明されているように、必ず OpenShift ルーターでワイルドカードルートを有効にします。

手順

  1. ホスト型 3scale 管理ポータルコンソールにログインします。
  2. Account Management API への書き込みアクセス権限を設定して、新しいアクセストークンを生成します。
  3. 後で使用できるように、生成されたアクセストークンを保存します。以下に例を示します。

    export SAAS_ACCESS_TOKEN=123...456
  4. 後で使用できるように、3scale テナントの名前を保存します。これは、管理ポータル URL の -admin.3scale.net の前にある文字列です。以下に例を示します。

    export SAAS_TENANT=my_username
  5. 管理ポータルで Audience > Accounts > Listing の順に移動します。
  6. Developer をクリックします。
  7. Developer Account ID を保存します。これは、/buyers/accounts/ に続く URL の最後の部分です。以下に例を示します。

    export SAAS_DEVELOPER_ACCOUNT_ID=123...456

3.2.3. オンプレミス型 3scale 環境の設定

オンプレミス型 3scale 環境の設定は、Hybrid - open と Hybrid - OIDC のサンプル Jenkins CI/CD パイプラインでのみ必要です。

注記

これらの Hybrid サンプルパイプラインを使用する場合は、オンプレミス型 3scale 環境とホスト型 3scale 環境を設定する必要があります。「ホスト型 3scale 環境の設定」も併せて参照してください。

前提条件

  • Linux ワークステーションがある。
  • オンプレミス型 3scale 環境が必要です。テンプレートを使用して OpenShift 上にオンプレミス型 3scale をインストールする方法については、3scale のインストールに関するドキュメント を参照してください。
  • OpenShift 3.11 クラスターが必要です。現在、OpenShift 4 はサポートされていません。
  • OpenShift のドキュメント で説明されているように、必ず OpenShift ルーターでワイルドカードルートを有効にします。

手順

  1. オンプレミス型 3scale 管理ポータルコンソールにログインします。
  2. Account Management API への書き込みアクセス権限を設定して、新しいアクセストークンを生成します。
  3. 後で使用できるように、生成されたアクセストークンを保存します。以下に例を示します。

    export SAAS_ACCESS_TOKEN=123...456
  4. 後で使用できるように、3scale テナントの名前を保存します。

    export ONPREM_ADMIN_PORTAL_HOSTNAME="$(oc get route system-provider-admin -o jsonpath='{.spec.host}')"
  5. ワイルドカードルートを定義します。

    export OPENSHIFT_ROUTER_SUFFIX=app.openshift.test # Replace me!
    
    export APICAST_ONPREM_STAGING_WILDCARD_DOMAIN=onprem-staging.$OPENSHIFT_ROUTER_SUFFIX
    
    export APICAST_ONPREM_PRODUCTION_WILDCARD_DOMAIN=onprem-production.$OPENSHIFT_ROUTER_SUFFIX
    注記

    OPENSHIFT_ROUTER_SUFFIX の値を OpenShift ルーターの接尾辞に設定する必要があります (たとえば、app.openshift.test)。

  6. ワイルドカードルートを既存のオンプレミス型 3scale インスタンスに追加します。

    oc create route edge apicast-wildcard-staging --service=apicast-staging --hostname="wildcard.$APICAST_ONPREM_STAGING_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain
    
    oc create route edge apicast-wildcard-production --service=apicast-production --hostname="wildcard.$APICAST_ONPREM_PRODUCTION_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain
  7. 管理ポータルで Audience > Accounts > Listing の順に移動します。
  8. Developer をクリックします。
  9. Developer Account ID を保存します。これは、/buyers/accounts/ に続く URL の最後の部分です。

    export ONPREM_DEVELOPER_ACCOUNT_ID=5

3.2.4. OpenID Connect 向け Red Hat Single Sign-On のデプロイ

Hybrid - OpenID Connect (OIDC) または Semantic versioning のサンプルパイプラインを使用している場合、本セクションの手順を実施して 3scale で Red Hat Single Sign-On (RH-SSO) をデプロイします。これは OIDC 認証に必要であり、両方のサンプルで使用されます。

手順

  1. RH-SSO のドキュメント で説明されているように、RH-SSO 7.3 をデプロイします。

    以下のコマンド例は、簡単なサマリーを提供します。

    oc replace -n openshift --force -f https://raw.githubusercontent.com/jboss-container-images/redhat-sso-7-openshift-image/sso73-dev/templates/sso73-image-stream.json
    
    oc replace -n openshift --force -f https://raw.githubusercontent.com/jboss-container-images/redhat-sso-7-openshift-image/sso73-dev/templates/sso73-x509-postgresql-persistent.json
    
    oc -n openshift import-image redhat-sso73-openshift:1.0
    
    oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
    
    oc new-app --template=sso73-x509-postgresql-persistent --name=sso -p DB_USERNAME=sso -p SSO_ADMIN_USERNAME=admin -p DB_DATABASE=sso
  2. 後で使用できるように、RH-SSO インストールのホスト名を保存します。

    export SSO_HOSTNAME="$(oc get route sso -o jsonpath='{.spec.host}')"
  3. 3scale デベロッパーポータルのドキュメント で説明されているように 3scale 向けに RH-SSO を設定します。
  4. 後で使用できるように、レルム名、クライアント ID、およびクライアントシークレットを保存します。

    export REALM=3scale
    
    export CLIENT_ID=3scale-admin
    
    export CLIENT_SECRET=123...456

3.2.5. 3scale toolbox のインストールおよびアクセスの有効化

本セクションでは、toolbox のインストール、リモート 3scale インスタンスの作成、および管理ポータルへのアクセスに使用されるシークレットのプロビジョニングを行う方法について説明します。

手順

  1. 2章3scale toolbox の使用 で説明されているように、3scale ツールボックスをローカルにインストールします。
  2. 適切な toolbox コマンドを実行して、3scale のリモートインスタンスを作成します。

    ホスト型 3scale

    3scale remote add 3scale-saas "https://$SAAS_ACCESS_TOKEN@$SAAS_TENANT-admin.3scale.net/"

    オンプレミス型 3scale

    3scale remote add 3scale-onprem "https://$ONPREM_ACCESS_TOKEN@$ONPREM_ADMIN_PORTAL_HOSTNAME/"

  3. 以下の OpenShift コマンドを実行して、3scale 管理ポータルとアクセストークンが含まれるシークレットをプロビジョニングします。

    oc create secret generic 3scale-toolbox -n "$TOOLBOX_NAMESPACE" --from-file="$HOME/.3scalerc.yaml"

3.2.6. API バックエンドのデプロイ

本セクションでは、サンプルパイプラインで提供される API バックエンドの例をデプロイする方法について説明します。独自のパイプラインを作成してデプロイする場合、必要に応じて独自の API バックエンドを代わりに使用できます。

手順

  1. 以下のサンプルで使用するために、Beer Catalog API バックエンドの例をデプロイします。

    • SaaS - API key
    • Hybrid - open
    • Hybrid - OIDC

      oc new-app -n "$TOOLBOX_NAMESPACE" -i openshift/redhat-openjdk18-openshift:1.4 https://github.com/microcks/api-lifecycle.git --context-dir=/beer-catalog-demo/api-implementation --name=beer-catalog
      
      oc expose -n "$TOOLBOX_NAMESPACE" svc/beer-catalog
  2. 後で使用できるように、Beer Catalog API のホスト名を保存します。

    export BEER_CATALOG_HOSTNAME="$(oc get route -n "$TOOLBOX_NAMESPACE" beer-catalog -o jsonpath='{.spec.host}')"
  3. 以下のサンプルで使用するために、Red Hat Event API バックエンドの例をデプロイします。

    • Multi-environment
    • Semantic versioning

      oc new-app -n "$TOOLBOX_NAMESPACE" -i openshift/nodejs:10 'https://github.com/nmasse-itix/rhte-api.git#085b015' --name=event-api
      
      oc expose -n "$TOOLBOX_NAMESPACE" svc/event-api
  4. 後で使用できるように、Event API のホスト名を保存します。

    export EVENT_API_HOSTNAME="$(oc get route -n "$TOOLBOX_NAMESPACE" event-api -o jsonpath='{.spec.host}')"

3.2.7. Self-managed APIcast インスタンスのデプロイ

本セクションは、ホスト型 3scale 環境で Self-managed APIcast インスタンスで使用するためのものです。本セクションの説明は、SaaS - API key 以外のすべてのサンプルパイプラインに該当します。

手順

  1. ワイルドカードルートを定義します。

    export APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN=saas-staging.$OPENSHIFT_ROUTER_SUFFIX
    
    export APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN=saas-production.$OPENSHIFT_ROUTER_SUFFIX
  2. Self-managed APIcast インスタンスをプロジェクトにデプロイします。

    oc create secret generic 3scale-tenant --from-literal=password=https://$SAAS_ACCESS_TOKEN@$SAAS_TENANT-admin.3scale.net
    
    oc create -f https://raw.githubusercontent.com/3scale/apicast/v3.5.0/openshift/apicast-template.yml
    
    oc new-app --template=3scale-gateway --name=apicast-staging -p CONFIGURATION_URL_SECRET=3scale-tenant -p CONFIGURATION_CACHE=0 -p RESPONSE_CODES=true -p LOG_LEVEL=info -p CONFIGURATION_LOADER=lazy -p APICAST_NAME=apicast-staging -p DEPLOYMENT_ENVIRONMENT=sandbox -p IMAGE_NAME=registry.redhat.io/3scale-amp26/apicast-gateway
    
    oc new-app --template=3scale-gateway --name=apicast-production -p CONFIGURATION_URL_SECRET=3scale-tenant -p CONFIGURATION_CACHE=60 -p RESPONSE_CODES=true -p LOG_LEVEL=info -p CONFIGURATION_LOADER=boot -p APICAST_NAME=apicast-production -p DEPLOYMENT_ENVIRONMENT=production -p IMAGE_NAME=registry.redhat.io/3scale-amp26/apicast-gateway
    
    oc scale dc/apicast-staging --replicas=1
    
    oc scale dc/apicast-production --replicas=1
    
    oc create route edge apicast-staging --service=apicast-staging --hostname="wildcard.$APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain
    
    oc create route edge apicast-production --service=apicast-production --hostname="wildcard.$APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain

3.2.8. サンプルパイプラインのインストールとデプロイ

必要な環境を設定したら、各 Red Hat Integration リポジトリーのサンプルユースケース 用に提供される OpenShift テンプレートを使用して、サンプルパイプラインをインストールしてデプロイすることができます。このセクションでは、SaaS - API Key のサンプルについてのみ説明します。

手順

  1. 提供される OpenShift テンプレートを使用して、Jenkins パイプラインをインストールします。

    oc process -f saas-usecase-apikey/setup.yaml \
               -p DEVELOPER_ACCOUNT_ID="$SAAS_DEVELOPER_ACCOUNT_ID" \
               -p PRIVATE_BASE_URL="http://$BEER_CATALOG_HOSTNAME" \
               -p NAMESPACE="$TOOLBOX_NAMESPACE" |oc create -f -
  2. サンプルを以下のようにデプロイします。

    oc start-build saas-usecase-apikey

3.2.9. 3scale toolbox を使用した API ライフサイクル自動化の制約

本リリースでは、以下の制約が適用されます。

OpenShift のサポート
サンプルパイプラインは OpenShift 3.11 でのみサポートされます。現在、OpenShift 4 はサポートされていません。
アプリケーションの更新
  • アプリケーション用 3scale application apply toolbox コマンドを使用して、アプリケーションの作成と更新の両方を行うことができます。作成コマンドは、アカウント、プラン、サービス、およびアプリケーションキーをサポートします。
  • 更新コマンドは、アカウント、プラン、またはサービスに対する変更をサポートしません。変更が渡されると、パイプラインがトリガーされエラーは表示されませんが、これらのフィールドは更新されません。
サービスのコピー
3scale copy service toolbox コマンドを使用してカスタムポリシーが設定されたサービスをコピーする場合、先に個別にカスタムポリシーをコピーする必要があります。

3.3. 3scale Jenkins 共有ライブラリーを使用したパイプラインの作成

本セクションでは、3scale toolbox を使用するカスタム Jenkins パイプラインを作成するためのベストプラクティスについて説明します。ここでは、アプリケーションの例をベースに、3scale Jenkins 共有ライブラリーを使用して toolbox を呼び出す Jenkins パイプラインを Groovy で記述する方法を説明します。詳細は、Jenkins 共有ライブラリー についてのドキュメントを参照してください。

重要

Red Hat では、Red Hat Integration リポジトリーで提供される サンプル Jenkins パイプライン をサポートしています。

このパイプラインに対して行った変更については、Red Hat による直接のサポートはありません。独自の環境用に作成したカスタムのパイプラインはサポート対象外です。

前提条件

手順

  1. Jenkins パイプラインの先頭に以下の設定を追加して、パイプラインから 3scale 共有ライブラリーを参照します。

    #!groovy
    
    library identifier: '3scale-toolbox-jenkins@master',
       retriever: modernSCM([$class: 'GitSCMSource',
         remote: 'https://github.com/rh-integration/3scale-toolbox-jenkins.git'])
  2. ThreescaleService オブジェクトを保持するグローバル変数を宣言し、パイプラインの別ステージからそれを使用できるようにします。

    def service = null
  3. 関連情報がすべて含まれる ThreescaleService を作成します。

    stage("Prepare") {
      service = toolbox.prepareThreescaleService(
         openapi: [ filename: "swagger.json" ],
         environment: [ baseSystemName: "my_service" ],
         toolbox: [ openshiftProject: "toolbox",
                       destination: "3scale-tenant",
                       secretName: "3scale-toolbox" ],
         service: [:],
         applications: [
            [ name: "my-test-app", description: "This is used for tests", plan: "test", account: "<CHANGE_ME>" ]
            ],
         applicationPlans: [
           [ systemName: "test", name: "Test", defaultPlan: true, published: true ],
           [ systemName: "silver", name: "Silver" ],
           [ artefactFile: "https://raw.githubusercontent.com/my_username/API-Lifecycle-Mockup/master/testcase-01/plan.yaml"],
         ]
        )
    
      echo "toolbox version = " + service.toolbox.getToolboxVersion()
     }
    • openapi.filename は、OpenAPI 仕様が含まれるファイルへのパスです。
    • environment.baseSystemName は、environment.environmentName と OpenAPI 仕様 info.version からの API メジャーバージョンをベースにした、最終的な system_name の算出に使用されます。
    • toolbox.openshiftProject は、そこで Kubernetes ジョブが作成される OpenShift プロジェクトです。
    • toolbox.secretName は、「3scale toolbox のインストールおよびアクセスの有効化」 に示すように、3scale toolbox 設定ファイルが含まれる Kubernetes シークレットの名前です。
    • toolbox.destination は、3scale toolbox リモートインスタンスの名前です。
    • applicationPlans は、.yaml ファイルを使用して、またはアプリケーションプランのプロパティー詳細を提示することで作成するアプリケーションプランのリストです。
  4. 3scale でサービスをプロビジョニングするパイプラインステージを追加します。

    stage("Import OpenAPI") {
      service.importOpenAPI()
      echo "Service with system_name ${service.environment.targetSystemName} created !"
    }
  5. アプリケーションプランを作成するステージを追加します。

    stage("Create an Application Plan") {
      service.applyApplicationPlans()
    }
  6. テストアプリケーションを作成するグローバル変数とステージを追加します。

    stage("Create an Application") {
      service.applyApplication()
    }
  7. インテグレーションテストを実行するステージを追加します。Hosted APIcast インスタンスを使用する場合、ステージング環境用の公開 URL を抽出するためにプロキシー定義を取得する必要があります。

    stage("Run integration tests") {
      def proxy = service.readProxy("sandbox")
      sh """set -e +x
      curl -f -w "ListBeers: %{http_code}\n" -o /dev/null -s ${proxy.sandbox_endpoint}/api/beer -H 'api-key: ${service.applications[0].userkey}'
      curl -f -w "GetBeer: %{http_code}\n" -o /dev/null -s ${proxy.sandbox_endpoint}/api/beer/Weissbier -H 'api-key: ${service.applications[0].userkey}'
      curl -f -w "FindBeersByStatus: %{http_code}\n" -o /dev/null -s ${proxy.sandbox_endpoint}/api/beer/findByStatus/   available -H 'api-key: ${service.applications[0].userkey}'
      """
    }
  8. API を実稼働環境にプロモートするステージを追加します。

    stage("Promote to production") {
      service.promoteToProduction()
    }

3.4. Jenkinsfile を使用したパイプラインの作成

本セクションでは、3scale toolbox を使用するカスタム Jenkinsfile を新規に Groovy で記述するためのベストプラクティスについて説明します。

重要

Red Hat では、Red Hat Integration リポジトリーで提供される サンプル Jenkins パイプライン をサポートしています。

このパイプラインに対して行った変更については、Red Hat による直接のサポートはありません。独自の環境用に作成したカスタムのパイプラインはサポート対象外です。本セクションは参照用途としてのみ提供されています。

前提条件

手順

  1. 3scale toolbox を呼び出すためのユーティリティー関数を記述します。以下の例は、3scale toolbox を実行する Kubernetes ジョブを作成します。

    #!groovy
    
    def runToolbox(args) {
      def kubernetesJob = [
        "apiVersion": "batch/v1",
        "kind": "Job",
        "metadata": [
          "name": "toolbox"
        ],
        "spec": [
          "backoffLimit": 0,
          "activeDeadlineSeconds": 300,
          "template": [
            "spec": [
              "restartPolicy": "Never",
              "containers": [
                [
                 "name": "job",
                 "image": "registry.access.redhat.com/3scale-amp26/toolbox:latest",
                 "imagePullPolicy": "Always",
                 "args": [ "3scale", "version" ],
                 "env": [
                   [ "name": "HOME", "value": "/config" ]
                 ],
                 "volumeMounts": [
                   [ "mountPath": "/config", "name": "toolbox-config" ],
                   [ "mountPath": "/artifacts", "name": "artifacts" ]
                  ]
                ]
              ],
              "volumes": [
                [ "name": "toolbox-config", "secret": [ "secretName": "3scale-toolbox" ] ],
                [ "name": "artifacts", "configMap": [ "name": "openapi" ] ]
              ]
            ]
          ]
        ]
      ]
    
      kubernetesJob.spec.template.spec.containers[0].args = args
    
      sh "rm -f -- job.yaml"
      writeYaml file: "job.yaml", data: kubernetesJob
    
      sh """set -e
      oc delete job toolbox --ignore-not-found
      sleep 2
      oc create -f job.yaml
      sleep 20 # Adjust the sleep duration to your server velocity
      """
    
      def logs = sh(script: "set -e; oc logs -f job/toolbox", returnStdout: true)
      echo logs
      return logs
    }

    Kubernetes オブジェクトテンプレート

    提示しているこの関数は、Kubernetes オブジェクトテンプレートを使用して 3scale toolbox を実行するもので、必要に応じて調整できます。

    • この関数は 3scale ツールボックスコマンドラインインターフェイス (CLI) 引数を設定し、結果の Kubernetes ジョブ定義を YAML ファイルに書き込みます。
    • また、この関数は 3scale ツールボックスの以前の実行をクリーンアップします。
    • この関数は Kubernetes ジョブを作成し、待機します。待機時間は、Pod が Created から Running 状態に移行するのに要する時間に一致するように、サーバー速度に合わせて調整することができます。ポーリングループを使用して、この手順を改善することもできます。
    • OpenAPI 仕様ファイルは、openapi という名前の ConfigMap から取得されます。表示されているソースコードの例を参照してください。
    • 3scale 管理ポータルのホスト名とアクセストークンは、「3scale toolbox のインストールおよびアクセスの有効化」 のように 3scale-toolbox という名前のシークレットから取得されます。
    • openapi ConfigMap は、ステップ 3 のパイプラインによって作成されます。ただし、シークレットはパイプラインの外部で事前にプロビジョニングされています。このシークレットは、セキュリティーを強化するためにロールベースのアクセス制御 (RBAC) の対象となります。
  2. Jenkins パイプラインステージで 3scale toolbox で使用するグローバル環境変数を定義します。以下に例を示します。

    ホスト型 3scale

    def targetSystemName = "saas-apikey-usecase"
    def targetInstance = "3scale-saas"
    def privateBaseURL = "http://echo-api.3scale.net"
    def testUserKey = "abcdef1234567890"
    def developerAccountId = "john"

    オンプレミス型 3scale

    Self-managed APIcast またはオンプレミス型 3scale のインストールを使用する場合、さらに 2 つの変数を宣言する必要があります。

    def publicStagingBaseURL = "http://my-staging-api.example.test"
    def publicProductionBaseURL = "http://my-production-api.example.test"

    変数の説明は、以下のとおりです。

    • targetSystemName: 作成されるサービスの名前
    • targetInstance: この変数は、「3scale toolbox のインストールおよびアクセスの有効化」 で作成された 3scale リモートインスタンスの名前と一致します。
    • privateBaseURL: API バックエンドのエンドポイントホスト
    • testUserKey: インテグレーションテストの実行に使用されるユーザー API キー。ここで示されているようにハードコーディングするか、ハッシュベースのメッセージ認証コード (HMAC) 関数からこれを生成できます。
    • developerAccountId: テストアプリケーションが含まれるターゲットアカウントの識別子。
    • publicStagingBaseURL: サービスのパブリックステージングベース URL。
    • publicProductionBaseURL: サービスのパブリックプロダクションベース URL。
  3. 以下のように、OpenAPI 仕様ファイルを取得して OpenShift で ConfigMap としてプロビジョニングするパイプラインステージを追加します。

    node() {
     stage("Fetch OpenAPI") {
       sh """set -e
       curl -sfk -o swagger.json https://raw.githubusercontent.com/microcks/api-lifecycle/master/beer-catalog-demo/api-contracts/beer-catalog-api-swagger.json
       oc delete configmap openapi --ignore-not-found
       oc create configmap openapi --from-file="swagger.json"
       """
     }
  4. 3scale toolbox を使用して API を 3scale にインポートするパイプラインステージを追加します。

    ホスト型 3scale

    stage("Import OpenAPI") {
      runToolbox([ "3scale", "import", "openapi", "-d", targetInstance, "/artifacts/swagger.json", "--override-private-base-url=${privateBaseURL}", "-t", targetSystemName ])
    }

    オンプレミス型 3scale

    Self-managed APIcast またはオンプレミス型 3scale のインストールを使用する場合、ステージング環境と実稼働環境の公開ベース URL のオプションも指定する必要あります。

    stage("Import OpenAPI") {
      runToolbox([ "3scale", "import", "openapi", "-d", targetInstance, "/artifacts/swagger.json", "--override-private-base-url=${privateBaseURL}", "-t", targetSystemName, "--production-public-base-url=${publicProductionBaseURL}", "--staging-public-base-url=${publicStagingBaseURL}" ])
    }
  5. toolbox を使用して 3scale のアプリケーションプランとアプリケーションを作成するパイプラインステージを追加します。

    stage("Create an Application Plan") {
      runToolbox([ "3scale", "application-plan", "apply", targetInstance, targetSystemName, "test", "-n", "Test Plan", "--default" ])
    }
    
    stage("Create an Application") {
      runToolbox([ "3scale", "application", "apply", targetInstance, testUserKey, "--account=${developerAccountId}", "--name=Test Application", "--description=Created by Jenkins", "--plan=test", "--service=${targetSystemName}" ])
    }
  6. ツールボックスを使用して継続的インテグレーションテストを実行するステージを追加します。Hosted 3scale インスタンスを使用する場合、ステージング環境用の公開 URL を抽出するためにプロキシー定義を取得する必要があります。それ以外の場合は、すでに定義されている publicStagingBaseURL 変数を再利用できます。

    stage("Run integration tests") {
      def proxyDefinition = runToolbox([ "3scale", "proxy", "show", targetInstance, targetSystemName, "sandbox" ])
      def proxy = readJSON text: proxyDefinition
      proxy = proxy.content.proxy
    
      sh """set -e
      echo "Public Staging Base URL is ${proxy.sandbox_endpoint}"
      echo "userkey is ${testUserKey}"
      curl -vfk ${proxy.sandbox_endpoint}/beer -H 'api-key: ${testUserKey}'
      curl -vfk ${proxy.sandbox_endpoint}/beer/Weissbier -H 'api-key: ${testUserKey}'
      curl -vfk ${proxy.sandbox_endpoint}/beer/findByStatus/available -H 'api-key: ${testUserKey}'
      """
    }
  7. toolbox を使用して API を実稼働環境にプロモートするステージを追加します。

    stage("Promote to production") {
      runToolbox([ "3scale", "proxy", "promote", targetInstance,  targetSystemName ])
    }

第4章 3scale での API 環境のマッピング

API プロバイダー は、3scale 管理ポータルを通じて所有する API へのアクセスを提供します。多くの環境で API バックエンドをデプロイできます。これらのバックエンド環境には、次のものを含めることができます。

  • 開発、品質保証、ステージング、および実稼働環境に使用されるさまざまな環境。
  • API バックエンドの独自のセットを管理するチームまたは部門に使用されるさまざまな環境。

Red Hat 3scale API Management サービス は、単一の API または API のサブセットを表すことができますが、さまざまな API バックエンド環境のマッピングおよび管理にも使用できます。

本章では、以下のトピックについて説明します。

  • 環境の設定
  • 使用するゲートウェイ数の設定
  • 3 つ以上の環境を使用した THREESCALE_PORTAL_ENDPOINT と公開ベース URL の設定。

    • たとえば、開発、品質保証、本番環境などです。
  • ある環境から別の環境にコピー/昇格する方法に関する操作。

    • たとえば、生産への品質保証の推進などです。

4.1. 環境ごとのサービス

この方法では、API バックエンド環境ごとに個別の 3scale サービスを使用します。それぞれのサービスで、実稼働環境のゲートウェイとステージングゲートウェイを設定します。これにより、ゲートウェイ設定の変更を安全にテストし、API バックエンドと同様に実稼働設定にプロモートできます。

Production Service => Production Service APIcast gateway => Production Service API upstream.
Staging Service => Staging Service APIcast gateway => Staging Service API backend.

次の例に示すように、本番ゲートウェイとステージングゲートウェイの両方の プライベートベース URL は、この 3scale サービスが設定されているマッピング対象の環境の API バックエンドに設定されます。

4.2. オンプレミス型 3scale インスタンス

オンプレミス型 3scale インスタンスの場合、API バックエンド環境を管理するために 3scale を設定する方法は複数あります。

  • API バックエンド環境ごとに個別の 3scale インスタンス
  • マルチテナンシー 機能を使用する単一の 3scale インスタンス

4.2.1. 環境ごとの 3scale インスタンスの分離

このアプローチでは、API バックエンド環境ごとに個別の 3scale インスタンスがデプロイされます。このアーキテクチャーの利点は、各環境が互いに分離されるため、共有するデータベースやその他のリソースがないことです。たとえば、ある環境で行われる負荷テストは、他の環境のリソースには影響しません。

注記

このインストールの分離は上記のような利点がありますが、より多くの運用リソースとメンテナーンスが必要になります。これらの追加リソースは、OpenShift 管理レイヤーで必要になりますが、3scale レイヤーで必要になるとは限りません。

4.2.2. 環境ごとの 3scale テナントの分離

この方法では、単一の 3scale インスタンスが使用されますが、マルチテナンシー機能は複数の API バックエンドをサポートするために使用されます。

以下の 2 つのオプションがあります。

  • 単一のテナント内で、環境と 3scale サービス間の 1 対 1 のマッピングを作成します。
  • 必要に応じて、テナントごとに 1 つ 以上のサービスを使用して、環境とテナントの間に 1 対 1 のマッピングを作成します。

    • API バックエンド環境に対応するテナントが 3 つあります (dev-tenant、qa-tenant、prod-tenant)。このアプローチの利点は、環境を論理的に分離可能にしますが、共有物理リソースを使用できることです。
注記

AP I 環境を複数のテナントを持つ単一のインストールにマッピングするための最適なストラテジーを分析する場合、共有物理リソースを最終的に考慮する必要があります。

4.3. 混合アプローチ

「オンプレミス型 3scale インスタンス」 で説明されているアプローチを組み合わせることができます。以下に例を示します。

  • 実稼働用の別の 3scale インスタンス
  • dev および qa の非実稼働環境用の独立したテナントを使用する別の 3scale インスタンス

4.4. APIcast ゲートウェイ

3scale オンプレミスインストールでは、APIcast ゲートウェイに複数の選択肢があります。

  • 3scale インストールごとに、ステージングおよび実稼働用の 2 つの組み込み APIcast ゲートウェイがあります。
  • 追加の APIcast ゲートウェイは、3scale インスタンスが実行されている OpenShift クラスターの外部にデプロイできます。

4.4.1. APIcast の組み込みデフォルトゲートウェイ

APIcast 組み込みゲートウェイを使用する場合には、「APIcast ゲートウェイ」 のアプローチを使用して設定された API バックエンドは、自動的に処理されます。3scale マスター管理によりテナントが追加されると、実稼働環境およびステージングの組み込み APIcast ゲートウェイでテナントのルートが作成されます。マルチテナント対応サブドメインについて を参照してください。

  • <API_NAME>-<TENANT_NAME>-apicast.staging.<WILDCARD_DOMAIN>
  • <API_NAME>-<TENANT_NAME>-apicast.production.<WIDLCARD_DOMAIN>

したがって、異なるテナントにマッピングされた各 API バックエンド環境は、独自のルートを取得します。以下に例を示します。

  • Dev <API_NAME>-dev-apicast.staging.<WILDCARD_DOMAIN>
  • QA <API_NAME>-qa-apicast.staging.<WILDCARD_DOMAIN>
  • Prod <API_NAME>-prod-apicast.staging.<WILDCARD_DOMAIN>

4.4.2. 追加の APIcast ゲートウェイ

追加の APIcast ゲートウェイは、3scale インスタンスが実行されているものとは 異なる OpenShift クラスター にデプロイされたものです。追加の APIcast ゲートウェイを設定して使用する方法は複数あります。APIcast の輝度言う時に使用される環境変数 THREESCALE_PORTAL_ENDPOINT の値は、追加の APIcast ゲートウェイの設定方法により異なります。

API バックエンド環境ごとに個別の APIcast ゲートウェイを使用することができます。以下に例を示します。

DEV_APICAST -> DEV_TENANT ; DEV_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for DEV_TENANT
QA_APICAST -> QA_TENANT ; QA_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for QA_APICAST
PROD_APICAST -> PROD_TENANT ; PROD_APICAST started with THREESCALE_PORTAL_ENDPOINT = admin portal for PROD_APICAST

THREESCALE_PORTAL_ENDPOINT は、設定をダウンロードするために APIcast によって使用されます。API バックエンド環境にマップされるテナントごとに個別の APIcast ゲートウェイが使用される場合に、THREESCALE_PORTAL_ENDPOINT は、その API バックエンド環境に固有のすべてのサービス設定を含むテナントの管理ポータルに設定されます。

単一の APIcast ゲートウェイは、複数の API バックエンド環境と共に使用することができます。この場合、THREESCALE_PORTAL_ENDPOINTマスター管理ポータル に設定されます。

第5章 機能: operator を使用した 3scale のサービスおよび設定のプロビジョニング

本章では、3scale operator の機能について説明します。これは、OpenShift Container Platform ユーザーインターフェイスを介して 3scale operator を使用して 3scale サービスおよび設定をプロビジョニングするものです。

重要

3scale operator の機能は、テクノロジープレビューの機能としてのみ提供されます。テクノロジープレビューの機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではないことがあります。Red Hat は実稼働環境でこれらを使用することを推奨していません。テクノロジープレビューの機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行いフィードバックを提供していただくことを目的としています。Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲 を参照してください。

5.1. 前提条件

警告

3scale operator を使用して 3scale で API 設定を更新する場合は、カスタムリソース定義 (CRD) が信頼できるソースです。管理ユーザーインターフェイスに変更が加えられると、それらは永続化されず、最終的に CRD の定義で上書きされます。

5.3. オプションテナントカスタムリソースのデプロイ

オプションで、Tenant カスタムリソースオブジェクトをデプロイするその他のテナントを作成できます。

手順

  1. Catalog > Installed Operators の順にクリックします。

    1. Installed Operators のリストで、3scale Operator をクリックします。
  2. Tenant タブをクリックします。
  3. Create Tenant をクリックします。
  4. サンプルのコンテンツを消去し、以下の YAML 定義をエディターに追加してから、Create をクリックします。

    apiVersion: capabilities.3scale.net/v1alpha1
    kind: Tenant
    metadata:
      name: ecorp-tenant
    spec:
      username: admin
      systemMasterUrl: https://master.<wildcardDomain>
      email: admin@ecorp.com
      organizationName: ECorp
      masterCredentialsRef:
        name: system-seed
      passwordCredentialsRef:
        name: ecorp-admin-secret
      tenantSecretRef:
        name: ecorp-tenant-secret
        namespace: operator-test

    テナントの provider_keyadmin domain URL はシークレットに格納されます。tenantSecretRef テナント仕様キーを使用して、シークレットの場所を指定できます。

    注記

    Tenant Custom Resource フィールドと設定可能な値については、テナント CRD のリファレンス を参照してください。

5.4. 作成したカスタムリソースの削除

以下の手順で、カスタムリソースを削除する方法を説明します。

手順

  1. Catalog > Installed Operators の順にクリックします。

    1. Installed Operators のリストで、3scale Operator をクリックします。
  2. 削除するリソースのタブをクリックします。

    1. すでにリソースが作成されていれば、リソースのリストが表示されます。
  3. 名前をクリックして概要を表示します。
  4. Action > Delete の順にクリックします。
  5. Delete をクリックして削除を確認するか、Cancel をクリックして前の画面に戻ります。

あるいは、3scale operator、その関連付けられたロール、およびサービスアカウントを削除するには、以下の手順を実施します。

手順

  1. Catalog > Installed Operators の順にクリックします。

    1. Installed Operators のリストで、3scale Operator をクリックします。
  2. Action > Delete Cluster Service Version の順にクリックします。
  3. Delete をクリックして削除を確認するか、Cancel をクリックして前の画面に戻ります。

第6章 3scale のバックアップと復元

本セクションでは、Red Hat 3scale API Management インストール環境の管理者が以下の操作を行うのに必要な情報を提供します。

  • 永続データのバックアップ手順を設定する
  • 永続データのバックアップから復元を行う

MySQL データベースの 1 つまたは複数に障害が発生した場合に、3scale を以前の稼働状態に正しく復元することができます。

6.1. 前提条件

注記

3scale インストールの namespace にローカルでバインドされた edit クラスターロールを持つユーザーは、バックアップと復元の手順を実行できます。

6.2. 永続ボリューム

OpenShift 上の 3scale のデプロイメントでは、すべての永続データは、クラスター内のストレージサービス (現在使用されていない) か、ベースとなるインフラストラクチャーによってクラスターに提供される永続ボリューム (PV) か、または同じデータセンターか別のデータセンターにあるクラスター外のストレージサービスのいずれかに保存されます。

6.3. 留意事項

永続データのバックアップおよび復元手順は、使用するストレージタイプによって異なります。バックアップと復元とでデータの一貫性を維持するためには、データベースのベースとなる PV をバックアップするだけでは不十分です。部分書き込みや部分トランザクションだけを取得するべきではないからです。PV をバックアップするのではなく、データベースのバックアップメカニズムを使用してください。

また、データの一部は、異なるコンポーネント間で同期されます。あるコピーは、データセットの 信頼できるソース とみなされ、他は、ローカルでは変更されないが 信頼できるソース から同期されるコピーです。このような場合は、復元にあたり、信頼できるソース を復元し、その後その他のコンポーネントのコピーをそこから同期する必要があります。

6.4. データセットの使用

本セクションでは、さまざまな永続ストアのさまざまなデータセット、その目的、使用されるストレージタイプ、およびそれが 信頼できるソース であるかどうかについて、さらに詳しく説明します。

3scale デプロイメントの状態は、すべて以下の DeploymentConfig オブジェクトとその PV のいずれかに保存されます。

名前説明

system-mysql

MySQL データベース (mysql-storage)

system-storage

ファイル用のボリューム

zync-database

  • zync コンポーネント用の Postgres データベース
  • これには、ストレージとして HostPath が使用されます。
  • Pod が別のノードに移動すると、データが失われます。
  • データは同期ジョブの一部で、完全に永続的な訳ではありません。

backend-redis

Redis データベース (backend-redis-storage)

system-redis

Redis データベース (system-redis-storage)

6.4.1. system-mysql の定義

system-mysql はリレーショナルデータベースで、3scale 管理コンソールのユーザー、アカウント、API、プランなどについての情報を保存します。

サービスに関連するこの情報のサブセットは、Backend コンポーネントと同期され、backend-redis に保存されます。system-mysql は、この情報の 信頼できるソース です。

6.4.2. system-storage の定義

system-storage は、システム コンポーネントにより読み取り/書き込みされるファイルを保存します。

これは 2 つのカテゴリーに分類されます。

  • 実行時に システム コンポーネントが読み込む設定ファイル
  • デベロッパーポータルを作成する目的で、CMS 機能によってシステムにアップロードされる静的ファイル (たとえば、HTML、CSS、JS など)
注記

システム は、上記の静的ファイルをアップロードおよび読み込む複数の Pod により水平スケーリングすることができます。したがって、ReadWriteMany (RWX) PersistentVolume が必要です。

6.4.3. zync-database の定義

zync-database はリレーショナルデータベースで、3scale とアイデンティティープロバイダー (IdP) 間におけるアイデンティティーの同期に関連する情報を保存します。この情報は他のコンポーネントには複製されず、唯一の 信頼できるソース です。

6.4.4. backend-redis の定義

backend-redis には、バックエンド コンポーネントにより使用される複数のデータセットが含まれます。

  • Usages: これは バックエンド により集約された API 使用量についての情報です。これは、バックエンド による流量制限の決定と、システム による解析情報の表示 (UI または API 経由) に使用されます。
  • Config: これはサービス、流量制御などに関する設定情報で、内部 API 経由で システム から同期されます。これは、この情報の 信頼できるソース ではありませんが、システムsystem-mysql は信頼できるソースです。
  • AuthKeys: バックエンド に直接作成された OAuth キーのストレージ。これは、この情報の信頼できるソースです。
  • Queues: これは、ワーカープロセスで実行されるバックグラウンドジョブのキューです。これらは一時的なものであり、処理後に削除されます。

6.4.5. system-redis の定義

system-redis には、バックグラウンドで処理されるジョブのキューが含まれます。これらは一時的なものであり、処理後に削除されます。

6.5. バックアップの手順

システムデータベースをバックアップしアーカイブするには、以下のコマンドを使用します。

6.5.1. system-mysql のバックアップ

MySQL バックアップコマンドを実行します。

oc rsh $(oc get pods -l 'deploymentConfig=system-mysql' -o json | jq -r '.items[0].metadata.name') bash -c 'export MYSQL_PWD=${MYSQL_ROOT_PASSWORD}; mysqldump --single-transaction -hsystem-mysql -uroot system' | gzip > system-mysql-backup.gz

6.5.2. system-storage のバックアップ

system-storage ファイルを別のストレージにアーカイブします。

oc rsync $(oc get pods -l 'deploymentConfig=system-app' -o json | jq '.items[0].metadata.name' -r):/opt/system/public/system ./local/dir

6.5.3. zync-database のバックアップ

Postgres バックアップコマンドを実行します。

 oc rsh $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq '.items[0].metadata.name' -r) bash -c 'pg_dumpall -c --if-exists' | gzip > zync-database-backup.gz

6.5.4. backend-redis のバックアップ

redis からの dump.rb ファイルをバックアップします。

oc cp $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r):/var/lib/redis/data/dump.rdb ./backend-redis-dump.rdb

6.5.5. system-redis のバックアップ

redis からの dump.rb ファイルをバックアップします。

oc cp $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r):/var/lib/redis/data/dump.rdb ./system-redis-dump.rdb

6.6. データベースの復元手順

以下のコマンドを使用して、システム障害が発生した後にシステムデータベースを復元できます。

6.6.1. system-mysql の復元

  1. MySQL ダンプを system-mysql Pod にコピーします。

    oc cp ./system-mysql-backup.gz $(oc get pods -l 'deploymentConfig=system-mysql' -o json | jq '.items[0].metadata.name' -r):/var/lib/mysql
  2. バックアップファイルを展開します。

    oc rsh $(oc get pods -l 'deploymentConfig=system-mysql' -o json | jq -r '.items[0].metadata.name') bash -c 'gzip -d ${HOME}/system-mysql-backup.gz'
  3. MySQL DB バックアップファイルを復元します。

    oc rsh $(oc get pods -l 'deploymentConfig=system-mysql' -o json | jq -r '.items[0].metadata.name') bash -c 'export MYSQL_PWD=${MYSQL_ROOT_PASSWORD}; mysql -hsystem-mysql -uroot system < ${HOME}/system-mysql-backup'

6.6.2. system-storage の復元

バックアップファイルを system-storage に復元します。

oc rsync ./local/dir $(oc get pods -l 'deploymentConfig=system-app' -o json | jq '.items[0].metadata.name' -r):/opt/system/public/system

6.6.3. zync-database の復元

  1. Zync データベースダンプを zync-database Pod にコピーします。

    oc cp ./zync-database-backup.gz $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq '.items[0].metadata.name' -r):/var/lib/pgsql/
  2. バックアップファイルを展開します。

    oc rsh $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq -r '.items[0].metadata.name') bash -c 'gzip -d ${HOME}/zync-database-backup.gz'
  3. PostgreSQL DB バックアップファイルを復元します。

    oc rsh $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq -r '.items[0].metadata.name') bash -c 'psql -f ${HOME}/zync-database-backup'

6.6.4. バックエンドシステム 間の情報の一貫性確保

backend-redis の復元後、System からの設定情報と同期させ、Backend の情報と信頼できるソース である System の情報の一貫性を確保する必要があります。

6.6.4.1. backend-redis のデプロイメント設定の管理

以下の手順は、動作中の backend-redis インスタンス用です。

  1. redis-config configmap を編集します。

    oc edit configmap redis-config
  2. redis-config configmap の SAVE コマンドをコメント化します。

     #save 900 1
     #save 300 10
     #save 60 10000
  3. redis-config configmap の appendonlyno に設定します。

    appendonly no
  4. backend-redis を再デプロイして、新しい設定を読み込みます。

    oc rollout latest dc/backend-redis
  5. dump.rb ファイルの名前を変更します。

    oc rsh $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'mv ${HOME}/data/dump.rdb ${HOME}/data/dump.rdb-old'
  6. appendonly.aof ファイルの名前を変更します。

    oc rsh $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'mv ${HOME}/data/appendonly.aof ${HOME}/data/appendonly.aof-old'
  7. バックアップファイルを POD に移動します。

    oc cp ./backend-redis-dump.rdb $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r):/var/lib/redis/data/dump.rdb
  8. backend-redis を再デプロイして、バックアップを読み込みます。

    oc rollout latest dc/backend-redis
  9. appendonly ファイルを作成します。

    oc rsh $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'redis-cli BGREWRITEAOF'
  10. しばらくしてから、AOF の書き換えが完了していることを確認します。

    oc rsh $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'redis-cli info' | grep aof_rewrite_in_progress
    • aof_rewrite_in_progress = 1 の間は、実行は進行中です。
    • aof_rewrite_in_progress = 0 となるまで、定期的に確認します。ゼロは実行が完了したことを示します。
  11. redis-config configmap を編集します。

    oc edit configmap redis-config
  12. redis-config configmap の SAVE コマンドをコメント解除します。

     save 900 1
     save 300 10
     save 60 10000
  13. redis-config configmap の appendonlyyes に設定します。

    appendonly yes
  14. backend-redis を再デプロイして、デフォルト設定を再読み込みします。

    oc rollout latest dc/backend-redis
6.6.4.2. system-redis のデプロイメント設定の管理

以下の手順は、動作中の system-redis インスタンス用です。

  1. redis-config configmap を編集します。

    oc edit configmap redis-config
  2. redis-config configmap の SAVE コマンドをコメント化します。

     #save 900 1
     #save 300 10
     #save 60 10000
  3. redis-config configmap の appendonlyno に設定します。

    appendonly no
  4. system-redis を再デプロイして、新しい設定を読み込みます。

    oc rollout latest dc/system-redis
  5. dump.rb ファイルの名前を変更します。

    oc rsh $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'mv ${HOME}/data/dump.rdb ${HOME}/data/dump.rdb-old'
  6. appendonly.aof ファイルの名前を変更します。

    oc rsh $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'mv ${HOME}/data/appendonly.aof ${HOME}/data/appendonly.aof-old'
  7. バックアップ ファイルを POD に移動します。

    oc cp ./system-redis-dump.rdb $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r):/var/lib/redis/data/dump.rdb
  8. system-redis を再デプロイして、バックアップを読み込みます。

    oc rollout latest dc/system-redis
  9. appendonly ファイルを作成します。

    oc rsh $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'redis-cli BGREWRITEAOF'
  10. しばらくしてから、AOF の書き換えが完了していることを確認します。

    oc rsh $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'redis-cli info' | grep aof_rewrite_in_progress
    • aof_rewrite_in_progress = 1 の間は、実行は進行中です。
    • aof_rewrite_in_progress = 0 となるまで、定期的に確認します。ゼロは実行が完了したことを示します。
  11. redis-config configmap を編集します。

    oc edit configmap redis-config
  12. redis-config configmap の SAVE コマンドをコメント解除します。

     save 900 1
     save 300 10
     save 60 10000
  13. redis-config configmap の appendonlyyes に設定します。

    appendonly yes
  14. system-redis を再デプロイして、デフォルト設定を再読み込みします。

    oc rollout latest dc/system-redis

第7章 トラブルシューティング

本章の目的は、ユーザーが API インフラストラクチャーに関連する問題の原因を特定して修正できるように支援することです。

API インフラストラクチャーは、長く複雑なトピックです。ただし、少なくとも、インフラストラクチャーには 3 つの可動部分があります。

  1. API ゲートウェイ
  2. 3scale
  3. API
3scale Gateway Flowchart

これらの 3 つの要素のいずれかでエラーが起こると、顧客は API にアクセスできなくなります。ただし、障害の原因となったコンポーネントを特定することは困難です。本章では、インフラストラクチャーのトラブルシューティングを行って問題を特定するためのヒントを紹介します。

7.1. 典型的な問題

3scale とのインテグレーションに関する非常に典型的な問題を示す症状がいくつかあります。これらは、API プロジェクトの最初の段階であるのか、インフラストラクチャーをセットアップしているのか、またはすでに実稼働環境に移行しているのかによって異なります。

7.1.1. インテグレーションの問題

以降のセクションで、3scale とのインテグレーションにおける初期段階 (Hosted APIcast 使用の初期段階および実稼働環境への移行前、ならびに Self-managed APIcast の稼働中) で、APIcast エラーログでよく見られる問題のいくつかについて概要を説明します。

7.1.1.1. Hosted APIcast

Service Integration 画面で API と Hosted APIcast を初めて統合する場合、以下のエラーのいずれかがページに表示されたり、インテグレーションの成功を確認するためのテストコールでエラーが返されたりする可能性があります。

  • Test request failed: execution expired

    API が一般のインターネットからアクセス可能であることを確認します。Hosted APIcast は、プライベート API を扱うことができません。Hosted APIcast と統合する際に API を一般に公開したくない場合は、Hosted APIcast と API との間にプライベートシークレットを設定し、API ゲートウェイ以外からの呼び出しを拒否することができます。

  • The accepted format is protocol://address(:port)

    API のプライベートベース URL の最後にあるパスを削除します。これらのパスは、マッピングルールのパターン、または API テスト GET リクエストの最初に追加できます。

  • Test request failed with HTTP code XXX

    • 405: エンドポイントが GET リクエストを受け入れることを確認します。APIcast は、インテグレーションをテストするための GET リクエストのみをサポートしています。
    • 403: Authentication parameters missing: API にすでに何らかの認証が設定されている場合は、APIcast はテストリクエストを送信することができません。
    • 403: Authentication failed: 3scale でこれ以前にサービスを作成したことがある場合は、テストリクエストを行うためのクレデンシャルが設定されたサービスでアプリケーションを作成していることを確認します。これが統合する最初のサービスである場合は、サインアップ時に作成したテストアカウントまたはアプリケーションを削除していないことを確認します。
7.1.1.2. Self-managed APIcast

Self-managed APIcast とのインテグレーションのテストが正常に終了したら、API ゲートウェイを独自にホストすることが望ましい場合があります。以下は、自己管理型ゲートウェイを初めてインストールし、これを介して API を呼び出す際に生じる可能性のあるエラーです。

  • upstream timed out (110: Connection timed out) while connecting to upstream

    API ゲートウェイと一般のインターネットの間に、Self-managed APIcast ゲートウェイが 3scale に到達するのを妨げるファイアウォールまたはプロキシーがないことを確認します。

  • failed to get list of services: invalid status: 403 (Forbidden)

      2018/06/04 08:04:49 [emerg] 14#14: [lua] configuration_loader.lua:134: init(): failed to load configuration,   exiting (code 1)
      2018/06/04 08:04:49 [warn] 22#22: *2 [lua] remote_v2.lua:163: call(): failed to get list of services:   invalid status: 403 (Forbidden) url: https://example-admin.3scale.net/admin/api/services.json , context:   ngx.timer
      ERROR: /opt/app-root/src/src/apicast/configuration_loader.lua:57: missing configuration

    THREESCALE_PORTAL_ENDPOINT の値に使用するアクセストークンが正しいこと、またスコープに Account Management API が含まれていることを確認します。そのためには、curl コマンドを使用して確認します (curl -v "https://example-admin.3scale.net/admin/api/services.json?access_token=<YOUR_ACCESS_TOKEN>")。

    JSON ボディーでレスポンス 200 が返されるはずです。エラーステータスコードを返す場合は、レスポンスのボディーで詳細を確認します。

  • service not found for host apicast.example.com

      2018/06/04 11:06:15 [warn] 23#23: *495 [lua] find_service.lua:24: find_service(): service not found for host apicast.example.com, client: 172.17.0.1, server: _, request: "GET / HTTP/1.1", host: "apicast.example.com"

    このエラーは、公開ベース URL が正しく設定されていないことを示しています。設定された公開ベース URL は、Self-managed APIcast へのリクエストに使用するものと同じにする必要があります。正しい公開ベース URL を設定した後、以下を実行します。

    • APIcast が実稼働用に設定されていることを確認します (THREESCALE_DEPLOYMENT_ENV 変数で上書きされていない場合のスタンドアロン APIcast のデフォルト設定)。必ず設定を実稼働環境にプロモートしてください。
    • 環境変数 APICAST_CONFIGURATION_CACHEAPICAST_CONFIGURATION_LOADER を使用して自動的に設定を再読み込みするように設定していなかった場合は、APIcast を再起動します。

以下は、Self-managed APIcast の誤ったインテグレーションを示すその他の症状の例です。

  • マッピングルールの不一致/API コールの二重カウント: メソッドと API の実際の URL エンドポイント間のマッピングをどのように定義したかによって、場合により、メソッドが一致しない、またはリクエストごとに複数回カウントが増加することがあります。この問題のトラブルシューティングを行うには、3scale デバッグヘッダー を使用して API にテストコールを行います。これにより、API コールで一致したすべてのメソッドのリストが返されます。
  • 認証パラメーターが見つからない: パラメーターを Service Integration 画面で指定した正しい場所に送信していることを確認します。クレデンシャルをヘッダーとして送信しない場合、GET リクエストについてはクエリーパラメーターとして、その他の HTTP メソッドについてはボディーパラメーターとして送信する必要があります。3scale デバッグヘッダーを使用して、API ゲートウェイによりリクエストから読み取られるクレデンシャルを再確認します。

7.1.2. 実稼働環境の問題

セットアップを完全にテストし、しばらくの間実際に API を運用した後に、API ゲートウェイに関連して問題が発生することはほとんどありません。ただし、実際の実稼働環境で発生しうる問題の一部をここに挙げます。

7.1.2.1. 可用性の問題

可用性の問題は、通常、nginx error.log に upstream timed out エラーが表示されることが特徴です。以下に例を示します。

upstream timed out (110: Connection timed out) while connecting to upstream, client: X.X.X.X, server: api.example.com, request: "GET /RESOURCE?CREDENTIALS HTTP/1.1", upstream: "http://Y.Y.Y.Y:80/RESOURCE?CREDENTIALS", host: "api.example.com"

断続的に 3scale の可用性の問題が発生する場合、以下が原因の可能性があります。

  • 使用されていない古い 3scale IP に解決しようとしている。

    最新バージョンの API ゲートウェイ設定ファイルは、毎回強制的に IP を解決するために、変数として 3scale を定義します。応急処置として、NGINX インスタンスを再読み込みします。長期的な修正としては、アップストリームブロックで 3scale バックエンドを定義するのではなく、たとえば以下のように、各サーバーブロック内の変数として定義します。

    server {
      # Enabling the Lua code cache is strongly encouraged for production use. Here it is enabled
      .
      .
      .
      set $threescale_backend "https://su1.3scale.net:443";

    これを参照する場合は、以下のとおりです。

    location = /threescale_authrep {
      internal;
      set $provider_key "YOUR_PROVIDER_KEY";
    
      proxy_pass $threescale_backend/transactions/authrep.xml?provider_key=$provider_key&service_id=$service_id&$usage&$credentials&log%5Bcode%5D=$arg_code&log%5Brequest%5D=$arg_req&log%5Bresponse%5D=$arg_resp;
    }
  • すべての 3scale IP がホワイトリスト上に記載されていない。3scale が解決する IP の現在のリストを以下に示します。

    • 75.101.142.93
    • 174.129.235.69
    • 184.73.197.122
    • 50.16.225.117
    • 54.83.62.94
    • 54.83.62.186
    • 54.83.63.187
    • 54.235.143.255

      上記の問題は、3scale の可用性の問題と考えられます。ただし、API が AWS ELB の背後に置かれている場合、API ゲートウェイからの API 可用性に同様の問題が発生する可能性があります。これは、デフォルトでは NGINX が起動時に DNS 解決を行ってから IP アドレスをキャッシュするためです。ただし、ELB は静的 IP アドレスを確保せず、頻繁に変わる可能性があります。ELB が別の IP に変わると、NGINX はその IP に到達できません。

      この問題の解決方法は、強制的にランタイム DNS 解決を行う上述の修正と類似しています。

      1. http セクションの最上部に resolver 8.8.8.8 8.8.4.4; という行を追加して、Google DNS などの特定の DNS リゾルバーを設定します。
      2. server セクションの最上部近くの任意の場所に、API のベース URL を変数として設定しますset $api_base "http://api.example.com:80";
      3. location / セクション内で proxy_pass の行を探し、それを proxy_pass $api_base; に置き換えます。

7.1.3. デプロイ後の問題

新しいエンドポイントを追加するなど、API に変更を加える場合、API ゲートウェイの新しい設定ファイルのセットをダウンロードする前に、必ず新しいメソッドおよび URL マッピングを追加する必要があります。

3scale からダウンロードした設定を変更した場合の最も典型的な問題は、Lua のコードエラーです。これにより、以下のような 500 - Internal server error が発生します。

curl -v -X GET "http://localhost/"
* About to connect() to localhost port 80 (#0)
*   Trying 127.0.0.1... connected
> GET / HTTP/1.1
> User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3
> Host: localhost
> Accept: */*
>
< HTTP/1.1 500 Internal Server Error
< Server: openresty/1.5.12.1
< Date: Thu, 04 Feb 2016 10:22:25 GMT
< Content-Type: text/html
< Content-Length: 199
< Connection: close
<

<head><title>500 Internal Server Error</title></head>

<center><h1>500 Internal Server Error</h1></center>
<hr><center>openresty/1.5.12.1</center>


* Closing connection #0

nginx error.log を見て、原因を確認することができます。以下に例を示します。

2016/02/04 11:22:25 [error] 8980#0: *1 lua entry thread aborted: runtime error: /home/pili/NGINX/troubleshooting/nginx.lua:66: bad argument #3 to '_newindex' (number expected, got nil)
stack traceback:
coroutine 0:
  [C]: in function '_newindex'
  /home/pili/NGINX/troubleshooting/nginx.lua:66: in function 'error_authorization_failed'
  /home/pili/NGINX/troubleshooting/nginx.lua:330: in function 'authrep'
  /home/pili/NGINX/troubleshooting/nginx.lua:283: in function 'authorize'
  /home/pili/NGINX/troubleshooting/nginx.lua:392: in function  while sending to client, client: 127.0.0.1, server: api-2445581381726.staging.apicast.io, request: "GET / HTTP/1.1", host: "localhost"

access.log では、以下のようになります。

127.0.0.1 - - [04/Feb/2016:11:22:25 +0100] "GET / HTTP/1.1" 500 199 "-" "curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3"

上記のセクションでは、3scale 運用のいずれかのステージで発生する可能性のある最も典型的でよく知られた問題の概要を示します。

これらをすべて確認してもなお問題の原因と解決策が見つからない場合は、より詳細な操作上のトラブルシューティングに進む必要があります (以下のトラブルシューティングのチェックリストセクションを参照)。問題のある箇所の特定を試みるため、API から始めてクライアントまで遡って作業します。

7.2. トラブルシューティングの基本

サーバーへの接続時にエラーが発生する場合、それが API ゲートウェイでも、3scale でも、またはご自分の API でも、まずは以下のトラブルシューティング手順から作業を始めてください。

7.2.1. 1. 接続の可否を確かめる

telnet を使用して、基本的な TCP/IP 接続 (telnet api.example.com 443) を確認します。

  • 正常に接続できる場合
telnet echo-api.3scale.net 80
Trying 52.21.167.109...
Connected to tf-lb-i2t5pgt2cfdnbdfh2c6qqoartm-829217110.us-east-1.elb.amazonaws.com.
Escape character is '^]'.
Connection closed by foreign host.
  • 失敗
telnet su1.3scale.net 443
Trying 174.129.235.69...
telnet: Unable to connect to remote host: Connection timed out

7.2.2. 2.問題の発生場所を特定する

さまざまなネットワークの場所、デバイス、および宛先から、同じサーバーへの接続を試みます。たとえば、クライアントが API に到達できない場合は、API ゲートウェイなど、アクセスできるはずのマシンから API への接続を試みます。

接続試行のいずれかが成功した場合、実際のサーバーに関する問題を除外して、両者間のネットワークのトラブルシューティングに集中できます。問題がここにある可能性が最も高いからです。

7.2.3. 3. DNS に問題がないか調べる

ホスト名の代わりに IP アドレスを使ってサーバーへの接続を試みます。たとえば、telnet apis.io 80 の代わりに telnet 94.125.104.17 80 を使用します。

これにより、DNS に関する問題はすべて排除されます。

3scale の例では、dig su1.3scale.net または dig any su1.3scale.net (ホストが解決する IP が複数あると思われる場合) のように、dig を使用してサーバーの IP アドレスを取得することができます。

注記: 一部のホストは dig any をブロックします

7.2.4. 4. SSL に問題がないか調べる

OpenSSL を使用して、以下の項目をテストすることができます。

  • ホストまたは IP へのセキュアな接続 (たとえば、シェルプロンプトから openssl s_client -connect su1.3scale.net:443 を実行)

    出力:

    CONNECTED(00000003)
    depth=1 C = US, O = GeoTrust Inc., CN = GeoTrust SSL CA - G3
    verify error:num=20:unable to get local issuer certificate
    ---
    Certificate chain
     0 s:/C=ES/ST=Barcelona/L=Barcelona/O=3scale Networks, S.L./OU=IT/CN=*.3scale.net
       i:/C=US/O=GeoTrust Inc./CN=GeoTrust SSL CA - G3
     1 s:/C=US/O=GeoTrust Inc./CN=GeoTrust SSL CA - G3
       i:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA
    ---
    Server certificate
    -----BEGIN CERTIFICATE-----
    MIIE8zCCA9ugAwIBAgIQcz2Y9JNxH7f2zpOT0DajUjANBgkqhkiG9w0BAQsFADBE
    ...
    TRUNCATED
    ...
    3FZigX+OpWLVRjYsr0kZzX+HCerYMwc=
    -----END CERTIFICATE-----
    subject=/C=ES/ST=Barcelona/L=Barcelona/O=3scale Networks, S.L./OU=IT/CN=*.3scale.net
    issuer=/C=US/O=GeoTrust Inc./CN=GeoTrust SSL CA - G3
    ---
    Acceptable client certificate CA names
    /C=ES/ST=Barcelona/L=Barcelona/O=3scale Networks, S.L./OU=IT/CN=*.3scale.net
    /C=US/O=GeoTrust Inc./CN=GeoTrust SSL CA - G3
    Client Certificate Types: RSA sign, DSA sign, ECDSA sign
    Requested Signature Algorithms: RSA+SHA512:DSA+SHA512:ECDSA+SHA512:RSA+SHA384:DSA+SHA384:ECDSA+SHA384:RSA+SHA256:DSA+SHA256:ECDSA+SHA256:RSA+SHA224:DSA+SHA224:ECDSA+SHA224:RSA+SHA1:DSA+SHA1:ECDSA+SHA1:RSA+MD5
    Shared Requested Signature Algorithms: RSA+SHA512:DSA+SHA512:ECDSA+SHA512:RSA+SHA384:DSA+SHA384:ECDSA+SHA384:RSA+SHA256:DSA+SHA256:ECDSA+SHA256:RSA+SHA224:DSA+SHA224:ECDSA+SHA224:RSA+SHA1:DSA+SHA1:ECDSA+SHA1
    Peer signing digest: SHA512
    Server Temp Key: ECDH, P-256, 256 bits
    ---
    SSL handshake has read 3281 bytes and written 499 bytes
    ---
    New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES256-GCM-SHA384
    Server public key is 2048 bit
    Secure Renegotiation IS supported
    Compression: NONE
    Expansion: NONE
    No ALPN negotiated
    SSL-Session:
        Protocol  : TLSv1.2
        Cipher    : ECDHE-RSA-AES256-GCM-SHA384
        Session-ID: A85EFD61D3BFD6C27A979E95E66DA3EC8F2E7B3007C0166A9BCBDA5DCA5477B8
        Session-ID-ctx:
        Master-Key: F7E898F1D996B91D13090AE9D5624FF19DFE645D5DEEE2D595D1B6F79B1875CF935B3A4F6ECCA7A6D5EF852AE3D4108B
        Key-Arg   : None
        PSK identity: None
        PSK identity hint: None
        SRP username: None
        TLS session ticket lifetime hint: 300 (seconds)
        TLS session ticket:
        0000 - a8 8b 6c ac 9c 3c 60 78-2c 5c 8a de 22 88 06 15   ..l..<`x,\.."...
        0010 - eb be 26 6c e6 7b 43 cc-ae 9b c0 27 6c b7 d9 13   ..&l.{C....'l...
        0020 - 84 e4 0d d5 f1 ff 4c 08-7a 09 10 17 f3 00 45 2c   ......L.z.....E,
        0030 - 1b e7 47 0c de dc 32 eb-ca d7 e9 26 33 26 8b 8e   ..G...2....&3&..
        0040 - 0a 86 ee f0 a9 f7 ad 8a-f7 b8 7b bc 8c c2 77 7b   ..........{...w{
        0050 - ae b7 57 a8 40 1b 75 c8-25 4f eb df b0 2b f6 b7   ..W.@.u.%O...+..
        0060 - 8b 8e fc 93 e4 be d6 60-0f 0f 20 f1 0a f2 cf 46   .......`.. ....F
        0070 - b0 e6 a1 e5 31 73 c2 f5-d4 2f 57 d1 b0 8e 51 cc   ....1s.../W...Q.
        0080 - ff dd 6e 4f 35 e4 2c 12-6c a2 34 26 84 b3 0c 19   ..nO5.,.l.4&....
        0090 - 8a eb 80 e0 4d 45 f8 4a-75 8e a2 06 70 84 de 10   ....ME.Ju...p...
    
        Start Time: 1454932598
        Timeout   : 300 (sec)
        Verify return code: 20 (unable to get local issuer certificate)
    ---
  • SSLv3 のサポート (3scale ではサポートされません)

    openssl s_client -ssl3 -connect su.3scale.net:443

    出力

CONNECTED(00000003)
140735196860496:error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure:s3_pkt.c:1456:SSL alert number 40
140735196860496:error:1409E0E5:SSL routines:ssl3_write_bytes:ssl handshake failure:s3_pkt.c:644:
---
no peer certificate available
---
No client certificate CA names sent
---
SSL handshake has read 7 bytes and written 0 bytes
---
New, (NONE), Cipher is (NONE)
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
    Protocol  : SSLv3
    Cipher    : 0000
    Session-ID:
    Session-ID-ctx:
    Master-Key:
    Key-Arg   : None
    PSK identity: None
    PSK identity hint: None
    SRP username: None
    Start Time: 1454932872
    Timeout   : 7200 (sec)
    Verify return code: 0 (ok)
---

詳細は、OpenSSL の man ページ を参照してください。

7.3. トラブルシューティングのチェックリスト

API に対するリクエストのどこに問題があるのかを特定するには、以下のリストに従って確認を行います。

7.3.1. API

API が動作状態にあり、リクエストに応答していることを確認するため、同じリクエストを API に対し直接、API ゲートウェイを経由せずに実行します。API ゲートウェイを経由する場合のリクエストと同じパラメーターおよびヘッダーを送信していることを確認する必要があります。失敗したリクエストが正確にわからない場合は、API ゲートウェイと API 間のトラフィックを取得します。

呼び出しに成功する場合、API に関する問題を除外できますが、失敗した場合には、さらに API のトラブルシューティングを行う必要があります。

7.3.2. API ゲートウェイ > API

API ゲートウェイと API 間のネットワークの問題を除外するには、前と同じ呼び出しを、API に直接、ゲートウェイサーバーから実行します。

呼び出しに成功する場合、API ゲートウェイ自体のトラブルシューティングに進むことができます。

7.3.3. API ゲートウェイ

API ゲートウェイが正常に機能していることを確認するためには、多くのステップを順に実施します。

7.3.3.1. 1. API ゲートウェイが起動して稼働しているか調べる

ゲートウェイが稼働しているマシンにログインします。これに失敗する場合、ゲートウェイサーバーがダウンしている可能性があります。

ログインしたら、NGINX プロセスが実行中であることを確認します。そのためには、ps ax | grep nginx または htop を実行します。

リストに nginx master processnginx worker process が表示されている場合、NGINX は稼働中です。

7.3.3.2. 2. ゲートウェイログでエラーの有無を確認する

以下は、error.log のゲートウェイログで表示される可能性のある典型的なエラーの例です。

  • API ゲートウェイが API に接続できない

    upstream timed out (110: Connection timed out) while connecting to upstream, client: X.X.X.X, server: api.example.com, request: "GET /RESOURCE?CREDENTIALS HTTP/1.1", upstream: "http://Y.Y.Y.Y:80/RESOURCE?CREDENTIALS", host: "api.example.com"
  • API ゲートウェイが 3scale に接続できない

    2015/11/20 11:33:51 [error] 3578#0: *1 upstream timed out (110: Connection timed out) while connecting to upstream, client: 127.0.0.1, server: , request: "GET /api/activities.json?user_key=USER_KEY HTTP/1.1", subrequest: "/threescale_authrep", upstream: "https://54.83.62.186:443/transactions/authrep.xml?provider_key=YOUR_PROVIDER_KEY&service_id=SERVICE_ID&usage[hits]=1&user_key=USER_KEY&log%5Bcode%5D=", host: "localhost"

7.3.4. API ゲートウェイ > 3scale

API ゲートウェイが正常に動作していることを確認したら、次のステップは API ゲートウェイと 3scale 間の接続についてのトラブルシューティングです。

7.3.4.1. 1. API ゲートウェイが 3scale にアクセスできるか調べる

API ゲートウェイに NGINX を使用している場合、ゲートウェイが 3scale と通信できないときは、以下のメッセージが NGINX エラーログに表示されます。

2015/11/20 11:33:51 [error] 3578#0: *1 upstream timed out (110: Connection timed out) while connecting to upstream, client: 127.0.0.1, server: , request: "GET /api/activities.json?user_key=USER_KEY HTTP/1.1", subrequest: "/threescale_authrep", upstream: "https://54.83.62.186:443/transactions/authrep.xml?provider_key=YOUR_PROVIDER_KEY&service_id=SERVICE_ID&usage[hits]=1&user_key=USER_KEY&log%5Bcode%5D=", host: "localhost"

ここでは、upstream の値に注意してください。この IP は、3scale サービスが解決する IP の 1 つに対応します。これは、3scale へのアクセスに問題があることを意味します。逆引き DNS ルックアップを実行して、nslookup を呼び出すことで、IP のドメインを確認することができます。

たとえば、API ゲートウェイが 3scale にアクセスできないからといって、3scale がダウンしているとは限りません。この問題の最も典型的な理由の 1 つは、API ゲートウェイが 3scale に接続することを妨げるファイアウォールルールです。

ゲートウェイと 3scale の間に、接続のタイムアウトを引き起こすネットワークの問題が存在する可能性があります。この場合、一般的な接続の問題のトラブルシューティング に関する手順を実施して、問題がどこにあるのかを特定する必要があります。

ネットワークの問題を除外するため、traceroute または MTR を使用して、ルーティングおよびパケット送信を確認します。3scale と API ゲートウェイに接続できるマシンから同じコマンドを実行し、出力を比較することもできます。

さらに、API ゲートウェイと 3scale の間で送信されているトラフィックを確認するには、一時的に 3scale サービスの HTTP エンドポイント (su1.3scale.net) を使用するように切り替えている限りは、tcpdump を使用できます。

7.3.4.2. 2.API ゲートウェイが 3scale のアドレスを正しく解決しているか調べる

nginx.conf にリゾルバーディレクティブが追加されていることを確認します。

nginx.conf の設定例を以下に示します。

http {
  lua_shared_dict api_keys 10m;
  server_names_hash_bucket_size 128;
  lua_package_path ";;$prefix/?.lua;";
  init_by_lua 'math.randomseed(ngx.time()) ; cjson = require("cjson")';

  resolver 8.8.8.8 8.8.4.4;

Google DNS (8.8.8.8 および 1377 8.8.4.4) は希望する DNS と置き換え可能です。

API ゲートウェイから DNS 解決を確認するには、以下のように指定したリゾルバー IP で nslookup を呼び出します。

nslookup su1.3scale.net 8.8.8.8
;; connection timed out; no servers could be reached

上記の例は、Google DNS に到達できない場合に返されるレスポンスを示しています。この場合、リゾルバー IP を更新する必要があります。nginx の error.log に、以下のアラートが表示される場合もあります。

2016/05/09 14:15:15 [alert] 9391#0: send() failed (1: Operation not permitted) while resolving, resolver: 8.8.8.8:53

最後に、dig any su1.3scale.net を実行して、現在 3scale Service Management API について動作中の IP アドレスを確認します。これは、3scale によって使用される可能性のある IP アドレスの範囲全体ではないことに注意してください。容量の理由から、一部の IP アドレスがスワップインまたはスワップアウトされる場合があります。さらに、3scale サービスのドメイン名を今後追加することもできます。このため、該当する場合は、インテグレーション中に指定された特定のアドレスに対して必ずテストを行う必要があります。

7.3.4.3. 3. API ゲートウェイが 3scale を正しく呼び出していることの確認

API ゲートウェイが 3scale に送信しているリクエストを確認する場合は、トラブルシューティング用途に限り、nginx.conf の 3scale authrep の場所 (API キーおよび App_id 認証モードの場合は /threescale_authrep) に、以下のスニペットを追加することができます。

body_filter_by_lua_block{
  if ngx.req.get_headers()["X-3scale-debug"] == ngx.var.provider_key then
    local resp = ""
    ngx.ctx.buffered = (ngx.ctx.buffered or "") .. string.sub(ngx.arg[1], 1, 1000)
    if ngx.arg[2] then
      resp = ngx.ctx.buffered
    end

    ngx.log(0, ngx.req.raw_header())
    ngx.log(0, resp)
  end
}

X-3scale-debug header が送信されると (例: curl -v -H 'X-3scale-debug: YOUR_PROVIDER_KEY' -X GET "https://726e3b99.ngrok.com/api/contacts.json?access_token=7c6f24f5")、このスニペットにより以下の追加ロギングが nginx error.log に追加されます。

これにより、以下のログエントリーが生成されます。

2016/05/05 14:24:33 [] 7238#0: *57 [lua] body_filter_by_lua:7: GET /api/contacts.json?access_token=7c6f24f5 HTTP/1.1
Host: 726e3b99.ngrok.io
User-Agent: curl/7.43.0
Accept: */*
X-Forwarded-Proto: https
X-Forwarded-For: 2.139.235.79

 while sending to client, client: 127.0.0.1, server: pili-virtualbox, request: "GET /api/contacts.json?access_token=7c6f24f5 HTTP/1.1", subrequest: "/threescale_authrep", upstream: "https://54.83.62.94:443/transactions/oauth_authrep.xml?provider_key=REDACTED&service_id=REDACTED&usage[hits]=1&access_token=7c6f24f5", host: "726e3b99.ngrok.io"
2016/05/05 14:24:33 [] 7238#0: *57 [lua] body_filter_by_lua:8: <?xml version="1.0" encoding="UTF-8"?><error code="access_token_invalid">access_token "7c6f24f5" is invalid: expired or never defined</error> while sending to client, client: 127.0.0.1, server: pili-virtualbox, request: "GET /api/contacts.json?access_token=7c6f24f5 HTTP/1.1", subrequest: "/threescale_authrep", upstream: "https://54.83.62.94:443/transactions/oauth_authrep.xml?provider_key=REDACTED&service_id=REDACTED&usage[hits]=1&access_token=7c6f24f5", host: "726e3b99.ngrok.io"

最初のエントリー (2016/05/05 14:24:33 [] 7238#0: *57 [lua] body_filter_by_lua:7:) は、3scale に送信されたリクエストヘッダーを出力します。この例では、Host、User-Agent、Accept、X-Forwarded-Proto、および X-Forwarded-For です。

2 番目のエントリー (2016/05/05 14:24:33 [] 7238#0: *57 [lua] body_filter_by_lua:8:) は、3scale からのレスポンスを出力します。この例では、<error code="access_token_invalid">access_token "7c6f24f5" is invalid: expired or never defined</error> となります。

どちらの要求も、元の要求 (GET /api/contacts.json?access_token=7c6f24f5) とサブ要求の場所 (/threescale_authrep) およびアップストリーム要求 (upstream: "hits=1&access_token=7c6f24f5") を出力します。 この最後の値で、どの 3scale IP が解決されているかと、3scale に行った実際のリクエストも確認できます。

7.3.5. 3scale

7.3.5.1. 1. 3scale が利用可能か確かめる

3scale のステータスページ または Twitter で @3scalestatus を確認してください。

7.3.5.2. 2. 3scale がエラーを返しているか調べる

3scale は利用可能だが、呼び出しが API に通ることを妨げるエラーを API ゲートウェイに返している可能性もあります。承認呼び出しを 3scale で直接実行して、レスポンスを確認します。エラーが発生した場合は、3scale のエラーコードセクションで何が問題かを確認します。

7.3.5.3. 3. 3scale デバッグヘッダーを使用する

たとえば、以下のように X-3scale-debug ヘッダーを設定して API を呼び出すことで、3scale デバッグヘッダーを有効にすることもできます。

curl -v -X GET "https://api.example.com/endpoint?user_key" X-3scale-debug: YOUR_PROVIDER_KEY

これにより、API レスポンスで以下のヘッダーが返されます。

X-3scale-matched-rules: /, /api/contacts.json
< X-3scale-credentials: access_token=TOKEN_VALUE
< X-3scale-usage: usage[hits]=2
< X-3scale-hostname: HOSTNAME_VALUE
7.3.5.4. 4.インテグレーションエラーを確認する

管理ポータルでインテグレーションエラーを確認し、3scale へのトラフィックに関する問題がないか確認することもできます。https://YOUR_DOMAIN-admin.3scale.net/apiconfig/errors を参照してください。

インテグレーションエラーの理由の 1 つは、サーバーブロックでは無効な underscores_in_headers ディレクティブによりヘッダーでクレデンシャルを送信していることです。

7.3.6. クライアント API ゲートウェイ

7.3.6.1. 1. 一般のインターネットから API ゲートウェイにアクセスできるか調べる

ブラウザーをゲートウェイサーバーの IP アドレス (またはドメイン名) に転送するよう試みます。これに失敗する場合、該当するポートのファイアウォールが開いていることを確認してください。

7.3.6.2. 2. クライアントから API ゲートウェイにアクセスできるか調べる

可能な場合は、前述の方法 (telnet、curl など) のいずれかを使用して、クライアントから API ゲートウェイへの接続を試みます。 接続に失敗する場合、クライアントと API ゲートウェイ間のネットワークに問題が発生しています。

そうでない場合は、API への呼び出しを行うクライアントのトラブルシューティングに進む必要があります。

7.3.7. クライアント

7.3.7.1. 1. 別のクライアントを使用して同じ呼び出しをテストする

リクエストが想定される結果を返さない場合は、別の HTTP クライアントでテストします。たとえば、Java HTTP クライアントで API を呼び出している時に何らかの問題が生じる場合、cURL を使用して結果を照合します。

クライアントとゲートウェイ間のプロキシー経由で API を呼び出し、クライアントが送信している正確なパラメーターとヘッダーを取得することもできます。

7.3.7.2. 2. クライアントから送信されたトラフィックを確認する

Wireshark などのツールを使用して、クライアントが送信しているリクエストを調べます。これにより、クライアントが API を呼び出しているかどうか、およびリクエストの詳細を確認することができます。

7.4. その他の問題

7.4.1. ActiveDocs の問題

コマンドラインから API を呼び出す場合には機能するが、ActiveDocs を経由する場合には失敗することがあります。

ActiveDocs 呼び出しを機能させるために、これらの呼び出しを 3scale 側のプロキシー経由で送信します。このプロキシーが追加する特定のヘッダーが API にとって想定外だった場合に、問題を引き起こす可能性があります。これを確認するには、以下の手順を試みます。

7.4.1.1. 1. petstore.swagger.io を使用する

Swagger では、petstore.swagger.io にホスト型の swagger-ui が用意されています。これを使用して、最新バージョンの swagger-ui により Swagger 仕様と API をテストすることができます。swagger-ui と ActiveDocs の両方が同じように失敗する場合、ActiveDocs や ActiveDocs プロキシーの問題は除外して、ご自分の仕様のトラブルシューティングに集中できます。あるいは、swagger-ui GitHub リポジトリーで、現在の swagger-ui のバージョンに関する既知の問題を確認できます。

7.4.1.2. 2. ファイアウォールが ActiveDocs プロキシーからの接続を許可していることを確認する

API を使用するクライアントの IP アドレスをホワイトリスト化しないよう推奨しています。ActiveDocs プロキシーは、高可用性を実現するためにフローティング IP アドレスを使用していますが、現在これらの IP の変更を通知する仕組みはありません。

7.4.1.3. 3. 無効なクレデンシャルを使用して API を呼び出す

ActiveDocs プロキシーが正しく機能しているかどうかを確認する方法の 1 つは、無効なクレデンシャルを使用して API を呼び出すことです。これにより、ActiveDocs プロキシーと API ゲートウェイの両方について、問題の有無を確認することができます。

API 呼び出しから 403 コード (または不正なクレデンシャルに対してゲートウェイで設定しているコード) が返される場合、呼び出しはゲートウェイに到達しているので、問題は API にあります。

7.4.1.4. 4. 呼び出しを比較する

ActiveDocs から行った呼び出しと ActiveDocs 外からの呼び出し間でヘッダーおよびパラメーターの相違点を特定するには、API に送信する前に HTTP 呼び出しを検証および比較できる特定のサービス (オンプレミスの APItools、Runscope など) を介して呼び出しを実行することが有益な場合もあります。これにより、API プロバイダー側で問題を引き起こす可能性のあるリクエスト内のヘッダーやパラメーターを特定することができます。

7.5. 付録

7.5.1. NGINX でのロギング

これについての包括的なガイドは、NGINX のロギングとモニターリング に関するドキュメントを参照してください。

7.5.1.1. デバッグログの有効化

デバッグログの有効化の詳細については、NGINX のデバッグログに関するドキュメント を参照してください。

7.5.2. 3scale のエラーコード

3scale Service Management API エンドポイントによって返されるエラーコードを確認するには、以下の手順に従って 3scale API Documentation のページを参照します。

  1. 管理ポータルの右上隅にある疑問符 (?) アイコンをクリックします。
  2. 3scale API Docs を選択します。

以下は、3scale によって返される HTTP レスポンスコードと、そのコードが返される条件の一覧です。

  • 400: 不正なリクエスト。原因は以下のとおりです。

    • エンコーディングが無効である。
    • 負荷が大きすぎる。
    • コンテンツタイプが無効 (POST 呼び出しの場合) である。Content-Type ヘッダーの有効な値は、application/x-www-form-urlencodedmultipart/form-data、または空のヘッダーです。
  • 403:

    • クレデンシャルが有効ではない。
    • 3scale に GET リクエスト用のボディーデータを送信している
  • 404: アプリケーションやメトリクスなど、存在しないエンティティーが参照されている
  • 409:

    • 使用制限の超過。
    • アプリケーションがアクティブではない。
    • アプリケーションキーが無効、または提供されない (app_id/app_key 認証メソッドの場合)。
    • 参照元が許可されていない、または提供されない (参照元フィルターが有効で必要な場合)
  • 422: 必要なパラメーターが提供されない

これらのエラーレスポンスのほとんどには、マシンリーダブルなエラーカテゴリーと人が判読できる説明が含まれる XML ボディーも含まれています。

標準の API ゲートウェイ設定を使用する場合、3scale から 200 以外のコードが返されると、クライアントには以下のどちらかのコードと共にレスポンスが返されます。

  • 403
  • 404
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

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

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.