Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

Red Hat 3scale API Management の操作

Red Hat 3scale API Management 2.14

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

Red Hat Customer Content Services

概要

このガイドでは、Red Hat 3scale API Management 2.14 のデプロイメント操作を説明します。

Red Hat ドキュメントへのフィードバック (英語のみ)
リンクのコピー

Red Hat ドキュメントに関するご意見やご感想をお寄せください。

改善を提案するには、Jira 課題を作成し、変更案を説明してください。ご要望に迅速に対応できるよう、できるだけ詳細にご記入ください。

前提条件

  • Red Hat カスタマーポータルのアカウントがある。このアカウントを使用すると、Red Hat Jira Software インスタンスにログインできます。アカウントをお持ちでない場合は、アカウントを作成するように求められます。

手順

  1. Create issue にアクセスします。
  2. Summary テキストボックスに、問題の簡単な説明を入力します。

  3. Description テキストボックスに、次の情報を入力します。

    • 問題が見つかったページの URL
    • 問題の詳細情報
      他のフィールドの情報はデフォルト値のままにすることができます。
  4. Create をクリックして、Jira 課題をドキュメントチームに送信します。

フィードバックをご提供いただきありがとうございました。

第1章 3scale API Management の一般的な設定オプション
リンクのコピー

Red Hat 3scale API Management 管理者は、インストールまたはアカウントで一般的な設定オプションを使用して設定を調整できます。

1.1. 有効なログインセッションの長さの設定
リンクのコピー

Red Hat 3scale API Management 管理者は、管理ポータルとデベロッパーポータルで有効なログインセッションの長さを設定して、最大タイムアウトおよびアクティブではない状態に対して、制限を指定できます。

有効なログインセッションの長さを実装するには、USER_SESSION_TTL を秒単位で設定する必要があります。たとえば、1,800 秒は 30 分です。値が null (設定されていないか、空の文字列に設定されている) の場合には、セッションのデフォルトの長さは 2 週間になります。

前提条件

  • 管理者権限が設定された 3scale アカウント

手順

  1. system-app シークレットの USER_SESSION_TTL の値を更新します (秒単位)。 

    $ oc patch secret system-app -p '{"stringData": {"USER_SESSION_TTL": "'1800'"}}'
    Copy to Clipboard Toggle word wrap

  2. system-app をロールアウトします。 

    $ oc rollout latest dc/system-app
    Copy to Clipboard Toggle word wrap

第2章 3scale API Management の操作とスケーリング
リンクのコピー

注記

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

この章では、Red Hat 3scale API Management 2.14 インストール環境での操作とスケーリングタスクを説明します。

前提条件

3scale の操作およびスケーリングタスクを行うには、以下のセクションで説明している手順を実行します。

2.1. APIcast の再デプロイ
リンクのコピー

3scale 管理ポータルで、システムの変更をテストしプロモートすることができます。

前提条件

  • デプロイされたオンプレミス型 3scale のインスタンス。
  • APIcast のデプロイメント方法を選択している。

デフォルトでは、OpenShift 上の APIcast デプロイメントでは (Embedded 型のデプロイおよび他の OpenShift クラスター上のデプロイの両方で)、3scale 管理ポータルを介して変更をステージング環境用と実稼働環境用のゲートウェイにパブリッシュできるように設定されています。

APIcast を OpenShift に再デプロイするには、以下の手順を実施します。

手順

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

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

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

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

手順

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

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

2.2. 3scale API Management のオンプレミスでのスケールアップ
リンクのコピー

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

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

$ oc edit pv <pv_name>
Copy to Clipboard Toggle word wrap

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

2.2.1. 方法 1: 永続ボリュームをバックアップしてスワップする
リンクのコピー

手順

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

  5. 新しい PV の名前でデプロイメント設定を変更します。 

    $ oc edit dc/system-app
    Copy to Clipboard Toggle word wrap
  6. 新しい PV が設定され正常に機能していることを確認します。
  7. 以前の PVC を削除して、それが要求していたリソースを解放します。

2.2.2. 方法 2: 3scale API Management をバックアップして再デプロイする
リンクのコピー

手順

  1. 既存の永続ボリューム上のデータをバックアップします。
  2. 3scale Pod をシャットダウンします。
  3. 新しいサイズ要件に合わせて、ターゲット永続ボリュームを作成し、アタッチします。
  4. 新しく作成した PV に、バックアップからデータを復元します。

  5. 事前バインド型の永続ボリューム要求を作成します。以下の項目を指定します。

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

2.2.3. オンプレミス型 3scale API Management デプロイメントの設定
リンクのコピー

3scale でスケーリングされる主要なデプロイメント設定項目は以下のとおりです。

  • 実稼働環境用 APIcast
  • バックエンドリスナー
  • バックエンドワーカー
2.2.3.1. OCP によるスケーリング
リンクのコピー

APIManager CR を使用する OpenShift Container Platform (OCP) を介して、デプロイメント設定をスケールアップまたはスケールダウンできます。

特定のデプロイメント設定をスケーリングするには、以下を使用します。

  • 次の APIManager CR を使用して APIcast 実稼働デプロイメント設定をスケールアップします。 

    apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  apicast:
    productionSpec:
      replicas: X
    Copy to Clipboard Toggle word wrap

  • 次の APIManager CR を使用して、デプロイメント設定のバックエンドリスナー、バックエンドワーカー、およびバックエンド cron コンポーネントをスケールアップします。 

    apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: example-apimanager
spec:
  backend:
    listenerSpec:
      replicas: X
    workerSpec:
      replicas: Y
    cronSpec:
      replicas: Z
    Copy to Clipboard Toggle word wrap

  • 適切な環境変数に、希望する Pod ごとのプロセス数を設定します。

    • backend-listener Pod の PUMA_WORKERS: 

      $ oc set env dc/backend-listener --overwrite PUMA_WORKERS=<number_of_processes>
      Copy to Clipboard Toggle word wrap

    • system-app Pod の UNICORN_WORKERS: 

      $ oc set env dc/system-app --overwrite UNICORN_WORKERS=<number_of_processes>
      Copy to Clipboard Toggle word wrap
2.2.3.2. ハードウェアの垂直スケーリングと水平スケーリング
リンクのコピー

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

水平スケーリング

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

垂直スケーリング

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

注記

3scale デプロイメントにおいて、仕様や設定の異なるコンピュートノードを使用しないでください。

2.2.3.3. ルーターのスケールアップ
リンクのコピー

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

2.3. 操作のトラブルシューティング
リンクのコピー

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

2.3.1. OpenShift での 3scale API Management 監査ロギングの設定
リンクのコピー

この設定により、すべてのログが 1 箇所に集約され、Elasticsearch、Fluentd、および Kibana (EFK) ロギングツールでクエリーすることができます。これらのツールにより、3scale の設定にいつ誰がどのような変更を加えたかの可視性が向上します。たとえば、これには、課金、アプリケーションプラン、アプリケーションプログラミングインターフェイス (API) 設定などの変更が含まれます。

前提条件

  • 3scale 2.14 デプロイメント

手順

すべてのアプリケーションログを標準の OpenShift Pod ログに転送するように、監査ロギングを stdout に設定します。

留意事項

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

2.3.2. 監査ロギングの有効化
リンクのコピー

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

前提条件

  • 3scale プロジェクトの管理者アクセス権。

手順

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

    $ oc patch configmap system -p '{"data": {"features.yml": "features: &default\n  logging:\n    audits_to_stdout: true\n\nproduction:\n  <<: *default\n"}}'
    Copy to Clipboard Toggle word wrap

  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"}]}}}}'
    Copy to Clipboard Toggle word wrap

  3. 以下のコマンドを入力して、更新されたデプロイメント設定を関連する OpenShift Pod に適用します。 

    $ oc patch dc system-app -p $PATCH_SYSTEM_VOLUMES

$ oc patch dc system-sidekiq -p $PATCH_SYSTEM_VOLUMES
    Copy to Clipboard Toggle word wrap

2.3.3. Red Hat OpenShift のロギングの設定
リンクのコピー

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

Red Hat OpenShift でのログ記録の設定の詳細は、以下を参照してください。

2.3.4. ログへのアクセス
リンクのコピー

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

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

手順

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

    $ oc get pods
    Copy to Clipboard Toggle word wrap

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

    $ oc logs <pod>
    Copy to Clipboard Toggle word wrap

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

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

$ oc logs <pod> --container=system-developer
    Copy to Clipboard Toggle word wrap

2.3.5. ジョブキューの確認
リンクのコピー

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

$ oc get jobs
Copy to Clipboard Toggle word wrap 
$ oc logs <job>
Copy to Clipboard Toggle word wrap

2.3.6. 単調増加の防止
リンクのコピー

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

  • user_sessions

    クリーンアップは週に 1 回トリガーされ、2 週間より前のレコードが削除されます。

  • audits

    クリーンアップは 1 日 1 回トリガーされ、3 カ月より前のレコードが削除されます。

  • log_entries

    クリーンアップは 1 日に 1 回トリガーされ、6 カ月より前のレコードが削除されます。

  • event_store_events

    クリーンアップは週に 1 回トリガーされ、1 週間より前のレコードが削除されます。

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

  • alerts
Expand
表2.1 SQL パージコマンド
データベースタイプSQL コマンド

MySQL 

DELETE FROM alerts WHERE timestamp < NOW() - INTERVAL 14 DAY;
Copy to Clipboard Toggle word wrap

PostgreSQL 

DELETE FROM alerts WHERE timestamp < NOW() - INTERVAL '14 day';
Copy to Clipboard Toggle word wrap

Oracle 

DELETE FROM alerts WHERE timestamp <= TRUNC(SYSDATE) - 14;
Copy to Clipboard Toggle word wrap

関連情報

第3章 3scale API Management のモニタリング
リンクのコピー

Prometheus は、履歴データを保存し、大型でスケーラブルなシステムを監視するために構築されたコンテナーネイティブなソフトウェアです。現在実行中のセッションだけでなく、長時間にわたってデータを収集します。Prometheus のアラートルールは、Alertmanager によって管理されます。

Prometheus および Alertmanager を使用して、Red Hat 3scale API Management データを監視および保存します。これにより、Grafana などのグラフィカルツールを使用して、データを視覚化し、クエリーを実行することができます。

重要
  • Prometheus はオープンソースのシステム監視ツールキットで、Grafana はオープンソースのダッシュボードツールキットです。Prometheus および Grafana に対する Red Hat のサポートは、Red Hat の製品ドキュメントに記載されている推奨設定に限定されます。
  • 3scale Operator は監視リソースを作成しますが、これらのリソースの変更は妨げません。
  • 3scale Operator と Prometheus Operator を同じ namespace にインストールするか、クラスター全体の Operator を使用する必要があります。

3scale Operator では、既存の Prometheus および Grafana Operator のインストールを使用して、3scale の使用状況およびリソースを監視することができます。

前提条件

  • 3scale operator がインストールされている。

  • Prometheus Operator がクラスターにインストールされている。Prometheus Operator は、Prometheus インスタンスを作成および管理します。3scale の監視に必要な Prometheus カスタムリソース定義 (CRD) を提供します。

    以下の Prometheus Operator およびイメージバージョンは、3scale でテストされています。

    • Prometheus Operator v0.37.0
    • Prometheus イメージ: quay.io/prometheus/prometheus:v2.16.0

  • Grafana Operator がクラスターにインストールされている。Grafana Operator は、Grafana インスタンスを作成および管理します。3scale モニタリングに必要な GrafanaDashboard CRD を提供します。

    以下の Grafana Operator およびイメージバージョンは、3scale でテストされています。

    • Grafana Operator v3.9.0
    • Grafana イメージ: registry.hub.docker.com/grafana/grafana:7.1.1
重要

クラスターがインターネット上で公開される場合は、必ず Prometheus サービスおよび Grafana サービスを保護するようにしてください。

このセクションでは、Grafana ダッシュボードを表示できるように、3scale インスタンスのモニタリングを有効にする方法を説明します。

3.1. 3scale API Management のモニタリングの有効化
リンクのコピー

3scale を監視するには、APIManager カスタムリソース (CR) を設定して監視を有効にする必要があります。

手順

  1. 3scale を設定し、3scale デプロイメント YAML の spec.monitoring.enabled パラメーターを true に設定して監視を有効にします。以下に例を示します。

    1. モニタリングを有効にするには、3scale-monitoring.yml という名前の APIManager CR を作成します。 

      apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: apimanager1
spec:
  wildcardDomain: example.com
  monitoring:
    enabled: true
    enablePrometheusRules: false
      1
      Copy to Clipboard Toggle word wrap
      1
      オプションで PrometheusRules を無効にできます。それ以外の場合は、デフォルトで有効になります。

    2. OpenShift クラスターにログインします。3scale の OpenShift プロジェクトのクラスター 編集 ロールを持つユーザーとしてログインする必要があります (例: cluster-admin)。 

      $ oc login
      Copy to Clipboard Toggle word wrap

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

      $ oc project <project_name>
      Copy to Clipboard Toggle word wrap

    4. カスタムリソースをデプロイします。 

      $ oc apply -f 3scale-monitoring.yml
      Copy to Clipboard Toggle word wrap

関連情報

3.2. 3scale API Management を監視するための Prometheus の設定
リンクのコピー

3scale のモニタリングを有効にするには、Prometheus カスタムリソース (CR) を使用して Prometheus をデプロイおよび設定する必要があります。

注記

Prometheus のドキュメント の説明に従ってパーミッションが正しく設定されていることを確認してください。

手順

  1. クラスター内のすべてのリソースを監視するか、3scale リソースのみを監視するかに応じて、以下のように Prometheus CR をデプロイします。

    • クラスターのすべてのリソースを監視するには、spec.podMonitorSelector 属性を {} に、spec.ruleSelector 属性を {} に、spec.serviceMonitorSelector 属性を {} に設定します。たとえば、次の CR を適用します。 

      apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
  name: prometheus
spec:
  podMonitorSelector: {}
  ruleSelector: {}
  serviceMonitorSelector: {}
      Copy to Clipboard Toggle word wrap

    • 3scale と Prometheus Operator を同じ OpenShift プロジェクトにデプロイし、APP_LABEL の値がデフォルトの 3scale-api-management に設定されている場合は、以下の手順に従って 3scale リソースを監視します。

      1. spec.podMonitorSelector 属性を以下のように設定します。 

         podMonitorSelector:
  matchExpressions:
  - key: app
      operator: In
      values:
      - 3scale-api-management
        Copy to Clipboard Toggle word wrap

      2. spec.ruleSelector 属性を以下のように設定します。 

           matchExpressions:
   - key: app
     operator: In
     values:
     - 3scale-api-management
        Copy to Clipboard Toggle word wrap

        たとえば、次の CR を適用します。 

        apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
  name: example
spec:
 podMonitorSelector:
  matchExpressions:
  - key: app
      operator: In
      values:
      - 3scale-api-management
 ruleSelector:
   matchExpressions:
   - key: app
     operator: In
     values:
     - 3scale-api-management
        Copy to Clipboard Toggle word wrap

    • 3scale と Prometheus Operator を別の OpenShift プロジェクトにデプロイした場合には、以下の手順に従って 3scale リソースを監視します。

      1. 3scale がデプロイされている OpenShift プロジェクトに MYLABELKEY=MYLABELVALUE のラベルを付けます。

      2. podMonitorNamespaceSelector フィルターを使用して 3scale Pod を選択します。たとえば、次の CR を適用します。 

        apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
  name: example
spec:
 podMonitorSelector: {}
 ruleSelector: {}
 podMonitorNamespaceSelector:
   matchExpressions:
   - key: MYLABELKEY
     operator: In
     values:
     - MYLABELVALUE
        Copy to Clipboard Toggle word wrap

  2. ダッシュボードおよびアラートが予想通りに機能させるには、以下のいずれかを実行して Kubernetes メトリック (kube-state-metrics) を取り込む必要があります。

    • Prometheus インスタンスをクラスターのデフォルト Prometheus インスタンスでフェデレーションする。
    • 独自の収集ジョブを設定し、kubelet、etcd、その他からメトリックを取得する。

関連情報

3.3. 3scale API Management を監視するための Grafana の設定
リンクのコピー

3scale の監視を有効にするには、Grafana を設定する必要があります。

手順

  1. app=3scale-api-management ラベルを上書きして、GrafanaDashboards リソースを監視するように Grafana サービスが設定されていることを確認してください。たとえば、次のカスタムリソース (CR) を適用します。 

    apiVersion: integreatly.org/v1alpha1
kind: Grafana
metadata:
  name: grafana
spec:
  dashboardLabelSelector:
  - matchExpressions:
    - key: app
      operator: In
      values:
      - 3scale-api-management
    Copy to Clipboard Toggle word wrap

    3scale Operator によって作成された Grafana ダッシュボードには、以下のようにラベルが付けられます。 

    app: 3scale-api-management
monitoring-key: middleware
    Copy to Clipboard Toggle word wrap
  2. Grafana Operator が 3scale 以外の namespace にインストールされている場合は、--namespaces または --scan-all Operator フラグを使用して、namespace 外部のリソースを監視するように設定します。Operator フラグの詳細は、Grafana のドキュメント を参照してください。

  3. Grafana での Prometheus データの使用を可能にするために、prometheus タイプの GrafanaDataSource CR を作成します。以下に例を示します。 

    apiVersion: integreatly.org/v1alpha1
kind: GrafanaDataSource
metadata:
  name: prometheus
spec:
  name: middleware
  datasources:
    - name: Prometheus
      type: prometheus
      access: proxy
      url: http://prometheus-operated:9090
      isDefault: true
      version: 1
      editable: true
      jsonData:
        timeInterval: "5s"
    Copy to Clipboard Toggle word wrap

    http://prometheus-operated:9090 は Prometheus のルートです。

  4. Operator フラグ Grafana ドキュメントの説明に従って、パーミッションが正しく設定されていることを確認します。

関連情報

3.4. 3scale API Management のメトリクスの表示
リンクのコピー

3scale、Prometheus、および Grafana の設定後に、このセクションで説明するメトリックを表示できます。

手順

  1. Grafana コンソールにログインします。

  2. 以下のメトリックを表示できることを確認します。

    • 3scale がインストールされている Pod および namespace レベルでの Kubernetes リソース
    • ステージング環境用 APIcast
    • 実稼働環境用 APIcast
    • バックエンドワーカー
    • バックエンドリスナー
    • System
    • Zync

3.5. Prometheus に公開される 3scale API Management システムメトリクス
リンクのコピー

以下のポートを、Prometheus エンドポイントと共に 3scale システム Pod を使用してメトリックを公開するように設定できます。

Expand
表3.1 3scale システムポート
system-appポート

system-developer

9394

system-master

9395

system-provider

9396

Expand
system-sidekiqポート

system-sidekiq

9394

エンドポイントは、以下を使用して内部でのみアクセスできます。 

http://${service}:${port}/metrics
Copy to Clipboard Toggle word wrap

以下に例を示します。 

http://system-developer:9394/metrics
Copy to Clipboard Toggle word wrap

関連情報

第4章 Webhook を使用した 3scale API Management の自動化
リンクのコピー

Webhook は自動化を容易にする機能であり、3scale で発生したイベントに基づいて他のシステムを統合するのにも使用されます。3scale システムで指定のイベントが発生すると、Webhook メッセージを使用してアプリケーションに通知が送信されます。たとえば、Webhook を設定して、新規アカウントのサインアップからのデータでデベロッパーポータルに反映することができます。

4.1. Webhook の概要
リンクのコピー

Webhook は、Webhook 設定ウィンドウで利用可能なイベントから選択されたイベントによってトリガーされるカスタム HTTP コールバックです。これらのイベントのいずれかが発生すると、3scale システムは、Webhook セクションで指定した URL アドレスに対して HTTP または HTTPS リクエストを行います。Webhook では、リスナーを設定してイベント追跡などの目的の動作を呼び出すことができます。

Webhook のフォーマットは常に同じです。以下の構造の XML ドキュメントでエンドポイントにポストします。 

<?xml version="1.0" encoding="UTF-8"?>
<event>
  <type>application</type>
  <action>updated</action>
  <object>
    THE APPLICATION OBJECT AS WOULD BE RETURNED BY A GET ON THE ACCOUNT MANAGEMENT
    API
  </object>
</event>
Copy to Clipboard Toggle word wrap

各要素では、以下の情報を提供します。

  • <type>

    application、account など、イベントの主体を表します。

  • <action>

    updated、created、deleted などの値を使用してアクションを指定します。

  • <object>

    Account Management API によって返される、同じフォーマットの XML オブジェクト自体です。インタラクティブな ActiveDocs を使用して確認できます。

Webhook が 3scale によって実行されたことを保証する必要がある場合は、HTTPS Webhook URL を公開し、3scale の Webhook 宣言にカスタムパラメーターを追加します。たとえば、https://your-webhook-endpoint?someSecretParameterName=someSecretParameterValue です。パラメーター名と値を指定します。続いて、Webhook エンドポイント内で、このパラメーター値があることを確認します。

4.2. Webhook の設定
リンクのコピー

手順

  1. Dashboard メニューから Account Settings を選択し、Integrate > Webhooks に移動します。

  2. Webhook の動作を指定します。以下の 2 つのオプションがあります。

    • Webhooks enabled: Webhook を有効または無効にするには、このチェックボックスを選択します。

    • Actions in the admin portal also trigger webhooks: イベント発生時に Webhook をトリガーするには、このチェックボックスを選択します。

      以下の点を考慮してください。

      • トリガーとなるイベントが設定された内部 3scale API への呼び出しを行う場合は、プロバイダーキーではなくアクセストークンを使用します。
      • このチェックボックスを選択しないままにすると、デベロッパーポータルのアクションだけが Webhook のトリガーになります。
  3. 選択したイベントがトリガーとなった際にイベントを通知するための URL アドレスを指定します。
  4. 指定した URL アドレスへのコールバックのトリガーとなるイベントを選択します。

設定が完了したら、Update webhooks settings をクリックして変更を保存します。

4.3. Webhook のトラブルシューティング
リンクのコピー

リッスンしているエンドポイントに障害が発生した場合、失敗した配信を回復できます。エンドポイントがコード 200 を返す場合に、3scale は Webhook が配信されたとみなします。そうでない場合は、60 秒間隔で 5 回リトライします。障害からの復旧後に、または定期的にチェックを実行し、必要に応じキューをクリーンアップする必要があります。ActiveDocs では、以下のメソッドの詳細情報を確認できます。

  • Webhook は失敗した配信をリストします。
  • Webhook は失敗した配信を削除します。

関連情報

第5章 3scale API Management toolbox
リンクのコピー

注記

ツールボックス CLI コンポーネントは、現在の機能拡張における主要項目ではなくなりました。引き続き利用できますが、今後の改善が限られる点を把握しておくことをおすすめします。現在、プロビジョニングと自動化のニーズは、3scale Application Capabilities Operator に重点が置かれています。

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

3scale のドキュメントには、3scale toolbox のインストール、サポートされる toolbox コマンド、サービス、プラン、SSL および TLS に関する問題のトラブルシューティングなどの情報が掲載されています。詳細は、以下のいずれかのセクションを参照してください。

5.1. toolbox のインストール
リンクのコピー

公式にサポートされている 3scale toolbox のインストール方法は、3scale toolbox のコンテナーイメージを使用するものです。

5.1.1. toolbox コンテナーイメージのインストール
リンクのコピー

このセクションでは、toolbox コンテナーイメージをインストールする方法を説明します。

前提条件

手順

  1. Red Hat Ecosystem Catalog にログインします。 

    $ podman login registry.redhat.io
Username: ${REGISTRY-SERVICE-ACCOUNT-USERNAME}
Password: ${REGISTRY-SERVICE-ACCOUNT-PASSWORD}
Login Succeeded!
    Copy to Clipboard Toggle word wrap

  2. toolbox のコンテナーイメージをプルします。 

    $ podman pull registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14
    Copy to Clipboard Toggle word wrap

  3. インストールを確認します。 

    $ podman run registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14 3scale help
    Copy to Clipboard Toggle word wrap

関連情報

5.2. サポートされる toolbox コマンド
リンクのコピー

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

注記

update コマンドは削除され、copy コマンドに置き換えられました。

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

COMMANDS
    account              account super command
    activedocs           activedocs super command
    application          application super command
    application-plan     application-plan super command
    backend              backend super command
    copy                 copy super command
    help                 print help
    import               import super command
    method               method super command
    metric               metric super command
    policy-registry      policy-registry super command
    product              product super command
    proxy-config         proxy-config super command
    remote               remotes super command
    service              services 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
Copy to Clipboard Toggle word wrap

5.3. サービスのインポート
リンクのコピー

以下のフィールドをこの順序で指定して、CSV ファイルからサービスをインポートします。以下のヘッダーを CSV ファイルに追加します。 

service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type
Copy to Clipboard Toggle word wrap

以下の情報が必要です。

  • 3scale 管理アカウント: {3SCALE_ADMIN}

  • 3scale インスタンスが実行されているドメイン: {DOMAIN_NAME}

    • Hosted APICast を使用している場合、ドメインは 3scale.net です。
  • アカウントのアクセスキー: {ACCESS_KEY}
  • サービスの CSV ファイル (例: example/import_example.csv)

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

例

$ podman run -v $PWD/examples/import_example.csv:/tmp/import_example.csv registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14 3scale import csv --destination=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --file=/tmp/import_example.csv
Copy to Clipboard Toggle word wrap

この例では、Podman ボリュームを使用して、リソースファイルをコンテナーにマウントします。これは、このファイルが現在の $PWD フォルダーにあることを前提としています。

5.4. サービスのコピー
リンクのコピー

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

以下の情報が必要です。

  • コピーするサービスの ID: {SERVICE_ID}
  • 3scale 管理アカウント: {3SCALE_ADMIN}

  • 3scale インスタンスが実行されているドメイン: {DOMAIN_NAME}

    • Hosted APICast を使用している場合、ドメインは 3scale.net です。
  • アカウントのアクセスキー: {ACCESS_KEY}
  • 別のアカウントにコピーする場合は、コピー先アカウントのアクセスキー: {DEST_KEY}
  • 新しいサービスの名前: {NEW_NAME}

例

$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14 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}
Copy to Clipboard Toggle word wrap

注記

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

5.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 コマンドに置き換えられました。

以下のコマンド例により、あるサービスから別の既存サービスに一括コピーが行われます。 

$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14 3scale copy [opts] service --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} {SERVICE_ID} {DEST_ID}
Copy to Clipboard Toggle word wrap

5.6. OpenAPI 認証
リンクのコピー

3scale ツールボックスを使用して OpenAPI 認証を実装すると、承認されたユーザーのみが API にアクセスできるようにして、機密データを保護し、API の使用を効率的に管理できます。このアプローチにより、API インフラストラクチャーが強化され、開発者とコンシューマー間の信頼関係が構築されます。

注記

最上位のセキュリティー要件は 1 つだけサポートされています。操作レベルのセキュリティー要件はサポートされていません。

サポートされているセキュリティースキーム: 任意のフロータイプの apiKey および oauth2。

apiKey セキュリティースキームタイプの場合は、以下のようになります。

  • 認証情報の場所は、セキュリティースキームオブジェクトのフィールドで OpenAPI から読み取られます。
  • 認証ユーザーキーは、セキュリティースキームオブジェクトの OpenAPI 名フィールドから読み取られます。

apiKey セキュリティー要件を備えた OpenAPI 3.0.2 の部分的な例:

openapi: "3.0.2"
security:
  - petstore_api_key: []
components:
  securitySchemes:
    petstore_api_key:
      type: apiKey
      name: api_key
      in: header
      ...
Copy to Clipboard Toggle word wrap

oauth2 セキュリティースキームタイプの場合は、以下のようになります。

  • 認証情報の場所は headers にハードコーディングされています。
  • OpenID Connect Issuer Type のデフォルトは rest です。--oidc-issuer-type=<value> コマンドオプションを使用してこれをオーバーライドできます。
  • OpenID Connect Issuer は OpenAPI から読み取られません。3scale では発行者の URL にクライアントシークレットが含まれている必要があるため、この --oidc-issuer-endpoint=<value> コマンドオプションを使用して発行を設定する必要があります。
  • OIDC AUTHORIZATION FLOW は、セキュリティースキームオブジェクトの flows フィールドから読み取られます。

oauth2 セキュリティー要件を備えた OpenAPI 3.0.2 の部分的な例:

openapi: "3.0.2"
security:
    - petstore_oauth:
      - write:pets
      - read:pets
  components:
    securitySchemes:
      petstore_oauth:
        type: oauth2
        flows:
          clientCredentials:
            tokenUrl: http://example.org/api/oauth/dialog
            scopes:
              write:pets: modify pets in your account
              read:pets: read your pets
              ...
Copy to Clipboard Toggle word wrap

OpenAPI がセキュリティー要件を指定していない場合:

  • この製品は Open API とみなされます。
  • default_credentials 3scale ポリシーが追加されました。注記: これは anonymous_policy とも呼ばれます。
  • --default-credentials-userkey コマンドが必要です。注記: 指定されていない場合、コマンドは失敗します。

関連情報

5.7. OpenAPI 定義のインポート
リンクのコピー

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

import openapi コマンドのフォーマットは以下のとおりです。 

$ 3scale import openapi [opts] -d <destination> <specification>
Copy to Clipboard Toggle word wrap

OpenAPI <specification> は、以下のいずれかです。

  • /path/to/your/definition/file.[json|yaml|yml]
  • http[s]://domain/resource/path.[json|yaml|yml]

例

$ podman run -v $PWD/my-test-api.json:/tmp/my-test-api.json registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14 3scale import openapi [opts] -d=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} /tmp/my-test-api.json
Copy to Clipboard Toggle word wrap

コマンドオプション

import openapi コマンドのオプションは以下のとおりです。

-d --destination=<value>
3scale のターゲットインスタンス (http[s]://<authentication>@3scale_domain 形式)
-t --target_system_name=<value>
3scale のターゲットシステム名
--backend-api-secret-token=<value>
API ゲートウェイによってバックエンド API に送信されるカスタムシークレットトークン
--backend-api-host-header=<value>
API ゲートウェイによってバックエンド API に送信されるカスタムホストヘッダー

その他のオプションは、3scale import openapi --help コマンドを参照してください。

OpenAPI のインポートルール

サポートされるセキュリティースキームは、apiKey および oauth2 (任意の OAuth フロータイプに対応) です。

OpenAPI 仕様は、以下の値のいずれかでなければなりません。

  • 利用可能なパスのファイル名
  • toolbox がコンテンツをダウンロードすることのできる URL。サポートされるスキームは http および https です。
  • stdin 標準入力ストリームから読み込む。これは、値に - を設定することで制御されます。

OpenAPI 定義をインポートする場合、以下の追加ルールが適用されます。

  • 定義は OpenAPI 2.0 または OpenAPI 3.0 として検証される。
  • OpenAPI 定義のすべてのマッピングルールがインポートされる。これらについては API > Integration で確認できます。
  • 3scale プロダクトのすべてのマッピングルールは置き換えられる。
  • OpenAPI 定義に含まれるメソッドのみが変更される。
  • OpenAPI 定義にしか存在していなかったすべてのメソッドが、Hits メトリクスにアタッチされる。
  • メソッドを置き換えるには、パターンの完全一致の使用により、メソッドの名前が OpenAPI 定義 operation.operationId で定義されるメソッドと同一でなければならない。
注記

ポリシーチェーンに default_credentials ポリシー (anonymous_policy とも呼ばれる) がまだない場合、toolbox はこのポリシーを追加します。default_credentials ポリシーは、オプションのパラメーター --default-credentials-userkey で提供される ユーザーキー で設定されます。

OpenAPI 3.0 は、セキュリティースキームとセキュリティー要件機能を使用して、API のセキュリティーを指定する方法を提供します。詳細は、Swagger Authentication and Authorization の公式ドキュメントを参照してください。

OpenAPI 3.0 の制約

OpenAPI 3.0 定義をインポートする場合、以下の制約が適用されます。

  • servers リストの最初の server.url 要素だけがプライベート URL として処理される。server.url 要素の path コンポーネントが、OpenAPI の basePath プロパティーとして使用されます。
  • toolbox は、パス項目および操作オブジェクトのサーバーを処理しない。
  • セキュリティースキームオブジェクトでは、複数のフローはサポートされない。

5.8. OpenAPI 定義からの 3scale API Management バックエンドのインポート
リンクのコピー

toolbox import コマンドを使用して OpenAPI 定義をインポートし、3scale バックエンド API を作成できます。コマンドラインオプション --backend は、この機能を有効にします。3scale は OpenAPI 定義を使用して、バックエンドとそのプライベートベース URL と、そのマッピングルールおよびメソッドを作成し、保存します。

前提条件

  • オンプレミス型 3scale 2.14 インスタンスの管理者権限を持つユーザーアカウント
  • API を定義する OAS ドキュメント

手順

  • 以下の形式を使用し、import コマンドを実行してバックエンドを作成します。 

    $ 3scale import openapi -d <remote> --backend <OAS>
    Copy to Clipboard Toggle word wrap
  • <remote> は、バックエンドを作成する 3scale インスタンスの URL に置き換えます。http[s]://<authentication>@3scale_domain の形式を使用します。

  • <OAS> は /path/to/your/oasdoc.yaml に置き換えます。

    Expand
    表5.1 追加の OpenAPI 定義オプション
    オプション説明

    -o --output=<value>

    出力フォーマット。JSON または YAML のいずれかを使用できます。

    --override-private-base-url=<value>

    3scale は OpenAPI 定義の servers[0].url フィールドからバックエンドのプライベートエンドポイントを読み取ります。このフィールドの設定をオーバーライドするには、このオプションを指定し、<value> は選択したプライベートベース URL に置き換えます。OpenAPI 定義が servers[0].url フィールドに値を指定しておらず、import コマンドでこのオプションを指定しないと、実行に失敗します。

    --prefix-matching

    OpenAPI 操作から派生するマッピングルールに厳密なマッチングではなく、接頭辞のマッチングを使用します。

    --skip-openapi-validation

    OpenAPI スキーマ検証を省略します。

    -t --target_system_name=<value>

    ターゲットシステム名はテナントの一意のキーです。システム名は OpenAPI 定義から推測できますが、このパラメーターを使用して独自の名前に上書きできます。

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

リモートの 3scale インスタンスと容易に連携するため、3scale toolbox を使用して、設定ファイルでリモート URL アドレスおよびこれらのリモートインスタンスにアクセスするための認証情報を定義することができます。その後、toolbox コマンドでは短縮名を使用してこれらのリモートを参照することができます。

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

リモートアクセスクレデンシャルを追加する場合、access_token または provider_key を指定することができます。

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

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

以下のコマンド例により、短縮名 <name> のリモート 3scale インスタンスが <url> に追加されます。 

$ 3scale remote add [--config-file <config_file>] <name> <url>
Copy to Clipboard Toggle word wrap

例

$ podman run --name toolbox-container registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14 3scale remote add instance_a https://123456789@example_a.net

$ podman commit toolbox-container toolbox
Copy to Clipboard Toggle word wrap

上記の例では、リモートインスタンスを作成し、コンテナーをコミットして新しいイメージを作成します。次に、含まれるリモート情報を使用して新しいイメージを実行することができます。たとえば、以下のコマンドでは、新しいイメージを使用して新たに追加されたリモートを表示します。 

$ podman run toolbox 3scale remote list
instance_a https://example_a.net 123456789
Copy to Clipboard Toggle word wrap

続いて、他の toolbox コマンドは、新たに作成されたイメージを使用して、追加されたリモートにアクセスすることができます。以下の例では、registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14 ではなく toolbox という名前のイメージが使用されています。

警告

toolbox のシークレットをコンテナーに保存することは、シークレットと共にコンテナーを他のユーザーに提供する場合や、自動化のためにコンテナーを使用する場合など、セキュリティー上のリスクとなる可能性があります。Podman のセキュアなボリューム、または OpenShift のシークレットを使用してください。

関連情報

Podman の使用の詳細は、以下のドキュメントを参照してください。

5.9.2. リモートアクセスクレデンシャルのリスト表示
リンクのコピー

以下のコマンド例は、リモートアクセスクレデンシャルを一覧表示する方法を示しています。 

$ 3scale remote list [--config-file <config_file>]
Copy to Clipboard Toggle word wrap

このコマンドにより、追加されたリモート 3scale インスタンスのリストが <name> <URL> <authentication-key> のフォーマットで表示されます。

例

$ podman run <toolbox_image_with_remotes_added> 3scale remote list
instance_a https://example_a.net 123456789
instance_b https://example_b.net 987654321
Copy to Clipboard Toggle word wrap

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

以下のコマンド例は、リモートアクセスクレデンシャルを削除する方法を示しています。 

$ 3scale remote remove [--config-file <config_file>] <name>
Copy to Clipboard Toggle word wrap

このコマンドにより、短縮名 <name> のリモート 3scale インスタンスが削除されます。

例

$ podman run <toolbox_image_with_remote_added> 3scale remote remove instance_a
Copy to Clipboard Toggle word wrap

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

以下のコマンド例は、リモートアクセスクレデンシャルの名前を変更する方法を示しています。 

$ 3scale remote rename [--config-file <config_file>] <old_name> <new_name>
Copy to Clipboard Toggle word wrap

このコマンドにより、短縮名 <old_name> のリモート 3scale インスタンスの名前が <new_name> に変更されます。

例

$ podman run <toolbox_image_with_remote_added> 3scale remote rename instance_a instance_b
Copy to Clipboard Toggle word wrap

5.10. アプリケーションプランの作成
リンクのコピー

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

5.10.1. 新しいアプリケーションプランの作成
リンクのコピー

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

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

  • --publish フラグを使用して、公開済み アプリケーションプランを作成します。

    • デフォルトでは、非表示 になります。

  • --disabled フラグを使用して、無効な アプリケーションプランを作成します。

    • デフォルトでは、有効 になります。
注記

  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

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

以下のコマンドにより、新しいアプリケーションプランが作成されます。 

$ 3scale application-plan create [opts] <remote> <service> <plan-name>
Copy to Clipboard Toggle word wrap

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

Options
       --approval-required=<value>    The application requires approval:
                                      true or false
       --cost-per-month=<value>       Cost per month
       --default                      Make the default application plan
       --disabled                     Disable all methods and metrics in
                                      the application plan
    -o --output=<value>               Output format on stdout:
                                      one of json|yaml
    -p --published                    Publish the application plan
       --setup-fee=<value>            Set-up fee
    -t --system-name=<value>          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:
                                      defaults to $HOME/.3scalerc.yaml
    -h --help                         Print help for this command
    -k --insecure                     Proceed and operate even for server
                                      connections otherwise considered
                                      insecure
    -v --version                      Print the version of this command
       --verbose                      Verbose mode
Copy to Clipboard Toggle word wrap

5.10.2. アプリケーションプランの作成または更新
リンクのコピー

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

  • --default フラグを使用して、default アプリケーションプランを更新します。
  • --publish フラグを使用して、published アプリケーションプランを更新します。
  • --hide フラグを使用して、hidden アプリケーションを更新します。
  • --disabled フラグを使用して、disabled アプリケーションプランを更新します。
  • --enabled フラグを使用して、enabled アプリケーションプランを更新します。
注記

  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

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

  • plan 位置引数はプランの参照で、プランの id またはプランの system_name のどちらかです。

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

以下のコマンドにより、アプリケーションプランが更新されます。 

$ 3scale application-plan create [opts] <remote> <service> <plan>
Copy to Clipboard Toggle word wrap

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

Options
       --approval-required=<value>    The application requires approval:
                                      true or false
       --cost-per-month=<value>       Cost per month
       --default                      Make the default application plan
       --disabled                     Disable all methods and metrics in
                                      the application plan
       --enabled                      Enable the application plan
       --hide                         Hide the application plan
    -n --name=<value>                 Set the plan name
    -o --output=<value>               Output format on stdout:
                                      one of json|yaml
    -p --publish                      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:
                                      defaults to $HOME/.3scalerc.yaml
    -h --help                         Print help for this command
    -k --insecure                     Proceed and operate even for server
                                      connections otherwise considered
                                      insecure
    -v --version                      Print the version of this command
       --verbose                      Verbose mode
Copy to Clipboard Toggle word wrap

5.10.3. アプリケーションプランのリスト表示
リンクのコピー

以下のコマンドにより、アプリケーションプランがリスト表示されます。 

$ 3scale application-plan list [opts] <remote> <service>
Copy to Clipboard Toggle word wrap

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

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.10.4. アプリケーションプランの表示
リンクのコピー

以下のコマンドにより、アプリケーションプランが表示されます。 

$ 3scale application-plan show [opts] <remote> <service> <plan>
Copy to Clipboard Toggle word wrap

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

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.10.5. アプリケーションプランの削除
リンクのコピー

以下のコマンドにより、アプリケーションプランが削除されます。 

$ 3scale application-plan delete [opts] <remote> <service> <plan>
Copy to Clipboard Toggle word wrap

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

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

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

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

次の点に注意してください。

  • アプリケーションプランで定義される制限が含まれます。
  • アプリケーションプランで定義される課金ルールが含まれます。
  • 制限および課金ルールで参照されるメトリック/メソッドが含まれます。
  • アプリケーションプランで定義される機能が含まれます。
  • サービスは id または system_name で参照できます。
  • アプリケーションプランは id または system_name で参照できます。
5.10.6.1. ファイルへのアプリケーションプランのエクスポート
リンクのコピー

以下のコマンドにより、アプリケーションプランがエクスポートされます。 

$ 3scale application-plan export [opts] <remote> <service_system_name> <plan_system_name>
Copy to Clipboard Toggle word wrap

例

$ podman run -u root -v $PWD:/tmp registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14 3scale application-plan export --file=/tmp/plan.yaml remote_name service_name plan_name
Copy to Clipboard Toggle word wrap

この例では、Podman ボリュームを使用して、エクスポートされたファイルをコンテナーにマウントし、現在の $PWD フォルダーに出力します。

注記

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:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap
5.10.6.2. ファイルからのアプリケーションプランのインポート
リンクのコピー

以下のコマンドにより、アプリケーションプランがインポートされます。 

$ 3scale application-plan import [opts] <remote> <service_system_name>
Copy to Clipboard Toggle word wrap

例

$ podman run -v $PWD/plan.yaml:/tmp/plan.yaml registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14 3scale application-plan import --file=/tmp/plan.yaml remote_name service_name
Copy to Clipboard Toggle word wrap

この例では、Podman ボリュームを使用して、現在の $PWD フォルダーからインポートされたファイルをコンテナーにマウントします。

5.10.6.3. URL からのアプリケーションプランのインポート
リンクのコピー
$ 3scale application-plan import -f http[s]://domain/resource/path.yaml remote_name service_name
Copy to Clipboard Toggle word wrap
注記

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:
                                       defaults to $HOME/.3scalerc.yaml
    -h --help                          Print help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Print the version of this command
       --verbose                       Verbose mode
Copy to Clipboard Toggle word wrap

5.11. メトリックの作成
リンクのコピー

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

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

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

  • --disabled フラグを使用して、無効な メトリックを作成します。

    • デフォルトでは、有効 になります。
注記

  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

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

以下のコマンドにより、メトリックが作成されます。 

$ 3scale metric create [opts] <remote> <service> <metric-name>
Copy to Clipboard Toggle word wrap

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

Options
       --description=<value>      Set a metric description
       --disabled                 Disable this metric in all application
                                  plans
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml
    -t --system-name=<value>      Set the application plan system name
       --unit=<value>             Metric unit: default hit

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.11.1. メトリックの作成または更新
リンクのコピー

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

  • 同じ名前のメトリックがすでに存在する場合、エラーメッセージが表示されます。
  • --disabled フラグを使用して、無効な メトリックを更新します。
  • --enabled フラグを使用して、有効な メトリックに更新します。
注記

  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

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

  • metric 位置引数はメトリック参照で、メトリックの id またはメトリックの system_name のどちらかです。

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

以下のコマンドにより、メトリックが更新されます。 

$ 3scale metric apply [opts] <remote> <service> <metric>
Copy to Clipboard Toggle word wrap

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

Options
       --description=<value>      Set a metric description
       --disabled                 Disable this metric in all application
                                  plans
       --enabled                  Enable this metric in all application
                                  plans
    -n --name=<value>             This will set the metric name
       --unit=<value>             Metric unit: default hit
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.11.2. メトリックのリスト表示
リンクのコピー

以下のコマンドにより、メトリックがリスト表示されます。 

$ 3scale metric list [opts] <remote> <service>
Copy to Clipboard Toggle word wrap

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

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.11.3. メトリックの削除
リンクのコピー

以下のコマンドにより、メトリックが削除されます。 

$ 3scale metric delete [opts] <remote> <service> <metric>
Copy to Clipboard Toggle word wrap

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

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.12. メソッドの作成
リンクのコピー

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

5.12.1. メソッドの作成
リンクのコピー

メソッドを作成するには、以下の手順に従います。

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

  • --disabled フラグを使用して、無効な メソッドを作成します。

    • デフォルトでは、有効 になります。
注記

  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

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

以下のコマンドにより、メソッドが作成されます。 

$ 3scale method create [opts] <remote> <service> <method-name>
Copy to Clipboard Toggle word wrap

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

Options
       --description=<value>      Set a method description
       --disabled                 Disable this method in all
                                  application plans
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml
    -t --system-name=<value>      Set the method system name

Options for method
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.12.2. メソッドの作成または更新
リンクのコピー

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

  • 同じ名前のメソッドがすでに存在する場合、コマンドはエラーメッセージを返します。
  • --disabled フラグを使用して、無効な メソッドに更新します。
  • --enabled フラグを使用して、有効な メソッドに更新します。
注記

  • service 位置引数はサービスの参照で、サービスの id またはサービスの system_name のどちらかです。

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

  • method 位置引数はメソッド参照で、メソッドの id またはメソッドの system_name のどちらかです。

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

以下のコマンドにより、メソッドが更新されます。 

$ 3scale method apply [opts] <remote> <service> <method>
Copy to Clipboard Toggle word wrap

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

Options
       --description=<value>      Set a method description
       --disabled                 Disable this method in all
                                  application plans
       --enabled                  Enable this method in all
                                  application plans
    -n --name=<value>             Set the method name
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for method
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.12.3. メソッドのリスト表示
リンクのコピー

以下のコマンドにより、メソッドがリスト表示されます。 

$ 3scale method list [opts] <remote> <service>
Copy to Clipboard Toggle word wrap

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

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for method
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.12.4. メソッドの削除
リンクのコピー

以下のコマンドにより、メソッドが削除されます。 

$ 3scale method delete [opts] <remote> <service> <metric>
Copy to Clipboard Toggle word wrap

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

Options for method
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.13. サービスの作成
リンクのコピー

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

5.13.1. 新しいサービスの作成
リンクのコピー

以下のコマンドにより、新しいサービスが作成されます。 

$ 3scale service create [options] <remote> <service-name>
Copy to Clipboard Toggle word wrap

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

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
    -o --output=<value>                  Output format on stdout:
                                         one of json|yaml
    -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:
                                         defaults to $HOME/.3scalerc.yaml
    -h --help                            Print help for this command
    -k --insecure                        Proceed and operate even for
                                         server connections otherwise
                                         considered insecure
    -v --version                         Print the version of this command
       --verbose                         Verbose mode
Copy to Clipboard Toggle word wrap

5.13.2. サービスの作成または更新
リンクのコピー

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

注記

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

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

以下のコマンドにより、サービスが更新されます。 

$ 3scale service apply <remote> <service-id_or_system-name>
Copy to Clipboard Toggle word wrap

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

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
    -o --output=<value>                  Output format on stdout:
                                         one of json|yaml

Options for services
    -c --config-file=<value>             3scale toolbox configuration file:
                                         defaults to $HOME/.3scalerc.yaml
    -h --help                            Print help for this command
    -k --insecure                        Proceed and operate even for
                                         server connections otherwise
                                         considered insecure
    -v --version                         Print the version of this command
       --verbose                         Verbose mode
Copy to Clipboard Toggle word wrap

5.13.3. サービスのリスト表示
リンクのコピー

以下のコマンドにより、サービスがリスト表示されます。 

$ 3scale service list <remote>
Copy to Clipboard Toggle word wrap

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

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for services
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.13.4. サービスの表示
リンクのコピー

以下のコマンドにより、サービスが表示されます。 

$ 3scale service show <remote> <service-id_or_system-name>
Copy to Clipboard Toggle word wrap

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

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for services
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.13.5. サービスの削除
リンクのコピー

以下のコマンドにより、サービスが削除されます。 

$ 3scale service delete <remote> <service-id_or_system-name>
Copy to Clipboard Toggle word wrap

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

Options for services
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.14. ActiveDocs の作成
リンクのコピー

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

5.14.1. 新しい ActiveDocs の作成
リンクのコピー

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

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

    $ 3scale activedocs create <remote> <activedocs-name> <specification>
    Copy to Clipboard Toggle word wrap

    ActiveDocs の OpenAPI 仕様は必須で、以下の値のいずれかでなければなりません。

    • 利用可能なパスのファイル名
    • toolbox がコンテンツをダウンロードすることのできる URL。サポートされるスキームは http および https です。

    • stdin 標準入力ストリームから読み込む。これは、値に - を設定することで制御されます。

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

      Options
    -d --description=<value>        Specify the description of
                                    the ActiveDocs
    -i --service-id=<value>         Specify the Service ID
                                    associated to the ActiveDocs
    -o --output=<value>             Output format on stdout: one
                                    of json|yaml
    -p --published                  Specify to publish the
                                    ActiveDocs on the Developer
                                    Portal. Otherwise it is hidden.
    -s --system-name=<value>        Specify the system-name of
                                    the ActiveDocs
       --skip-swagger-validations   Specify to skip validation
                                    of the Swagger specification
Options for ActiveDocs
    -c --config-file=<value>        toolbox configuration file.
                                    Defaults to $HOME/.3scalerc.yaml
    -h --help                       Print help for this command
    -k --insecure                   Proceed and operate even for
                                    server connections otherwise
                                    considered insecure
    -v --version                    Print the version of this command
       --verbose                    Verbose mode
      Copy to Clipboard Toggle word wrap
  2. デベロッパーポータルに定義を 公開 します。

5.14.2. ActiveDocs の作成または更新
リンクのコピー

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

$ 3scale activedocs apply <remote> <activedocs_id_or_system_name>
Copy to Clipboard Toggle word wrap

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

Options
  -d --description=<value>              Specify the description of the
                                        ActiveDocs
       --hide                           Specify to hide the ActiveDocs
                                        on the Developer Portal
 -i --service-id=<value>                Specify the Service ID associated
                                        to the ActiveDocs
 -o --output=<value>                    Output format on stdout:
                                        one of json|yaml
    --openapi-spec=<value>              Specify the Swagger specification.
                                        Can be a file, a URL or '-' to read
                                        from stdin. This is a mandatory
                                        option when applying the ActiveDoc
                                        for the first time.
 -p --publish                           Specify to publish the ActiveDocs
                                        on the Developer Portal. Otherwise
                                        it is hidden
 -s --name=<value>                      Specify the name of the ActiveDocs
    --skip-swagger-validations=<value>  Specify whether to skip validation
                                        of the Swagger specification: true
                                        or false. Defaults to true.

Options for ActiveDocs
    -c --config-file=<value>           3scale toolbox configuration file:
                                       defaults to $HOME/.3scalerc.yaml
    -h --help                          Print help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Print the version of this command
       --verbose                       Verbose mode
Copy to Clipboard Toggle word wrap
注記

activedocs apply --skip-swagger-validations の動作が、3scale 2.8 で変更されました。activedocs apply を使用する既存のスクリプトを更新しなければならない場合があります。従来は、各 activedocs apply コマンドでこのオプションを指定しない場合、検証はスキップされませんでした。今回、--skip-swagger-validations はデフォルトで true になりました。

5.14.3. ActiveDocs のリスト表示
リンクのコピー

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

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

以下のコマンドにより、定義済みの ActiveDocs がすべてリスト表示されます。 

$ 3scale activedocs list <remote>
Copy to Clipboard Toggle word wrap

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

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml
    -s --service-ref=<value>      Filter the ActiveDocs by service
                                  reference
Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.14.4. ActiveDocs の削除
リンクのコピー

以下のコマンドにより、ActiveDocs が削除されます。 

$ 3scale activedocs delete <remote> <activedocs-id_or-system-name>
Copy to Clipboard Toggle word wrap

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

Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.15. プロキシー設定のリスト表示
リンクのコピー

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

以下のコマンドにより、プロキシー設定がリスト表示されます。 

$ 3scale proxy-config list <remote> <service> <environment>
Copy to Clipboard Toggle word wrap

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

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.15.1. プロキシー設定の表示
リンクのコピー

以下のコマンドにより、プロキシー設定が表示されます。 

$ 3scale proxy-config show <remote> <service> <environment>
Copy to Clipboard Toggle word wrap

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

Options
       --config-version=<value>   Specify the proxy configuration version.
                                  If not specified, defaults to latest
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered
                                  insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.15.2. プロキシー設定のプロモート
リンクのコピー

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

$ 3scale proxy-config promote <remote> <service>
Copy to Clipboard Toggle word wrap

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

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.15.3. プロキシー設定のエクスポート
リンクのコピー

Self-managed APIcast ゲートウェイが 3scale インスタンスに接続されていない場合などに、proxy-config export コマンドを使用します。このシナリオでは、3scale 設定を手動で注入するか、APICast デプロイメントおよび設定オプション を使用して注入します。いずれの場合も、3scale の設定を指定する必要があります。

以下のコマンドは、APIcast ゲートウェイに注入することのできる設定をエクスポートします。 

$ 3scale proxy-config export <remote>
Copy to Clipboard Toggle word wrap

3scale 設定ファイル として使用されるプロバイダーアカウントのプロキシー設定をエクスポートする際に、以下のオプションを指定することができます。 

Options for proxy-config
--environment=<value>      Gateway environment. Must be 'sandbox' or
                           'production' (default: sandbox)
-o --output=<value>        Output format. One of: json|yaml
Copy to Clipboard Toggle word wrap

5.15.4. プロキシー設定のデプロイ
リンクのコピー

以下の deploy コマンドは、Service Mesh を使用している場合に、APIcast 設定を 3scale のステージング環境または実稼働環境にプロモートします。 

$ 3scale proxy deploy <remote> <service>
Copy to Clipboard Toggle word wrap

deploy コマンドを使用して APIcast 設定をステージング環境にプロモートする時に、以下のオプションを指定できます。 

-o --output=<value>        Output format. One of: json|yaml
Copy to Clipboard Toggle word wrap

5.15.5. プロキシー設定の更新
リンクのコピー

以下の update コマンドにより、APIcast の設定が更新されます。 

$ 3scale proxy update <remote> <service>
Copy to Clipboard Toggle word wrap

update コマンドを使用して APIcast 設定を 更新 する場合に、以下のオプションを指定することができます。 

-o --output=<value>           Output format. One of: json|yaml
-p --param=<value>            APIcast configuration parameters. Format:
                              [--param key=value]. Multiple options allowed.
Copy to Clipboard Toggle word wrap

5.15.6. プロキシー設定の表示
リンクのコピー

以下の show コマンドにより、アンデプロイされた APIcast 設定が取得されます。 

$ 3scale proxy show <remote> <service>
Copy to Clipboard Toggle word wrap

show コマンドを使用して、アンデプロイされた APIcast 設定を取得する場合は、以下のオプションを指定できます。 

$ -o --output=<value>           Output format. One of: json|yaml
Copy to Clipboard Toggle word wrap

5.15.7. プロキシー設定のデプロイ (非推奨)
リンクのコピー

注記

3scale 2.12 では、proxy-config deploy コマンドのサポートは非推奨になりました。

以下のコマンドを使用します。

  • proxy deploy
  • proxy update
  • proxy show

詳細は、プロキシー設定のデプロイ を参照してください。

以下の deploy コマンドは、Service Mesh を使用している場合に、APIcast 設定を 3scale のステージング環境または実稼働環境にプロモートします。 

$ 3scale proxy-config deploy <remote> <service>
Copy to Clipboard Toggle word wrap

deploy コマンドを使用して APIcast 設定をステージング環境にプロモートする時に、以下のオプションを指定できます。 

$ -o --output=<value>        Output format. One of: json|yaml
Copy to Clipboard Toggle word wrap

関連情報

5.16. ポリシーレジストリーのコピー
リンクのコピー

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

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

以下のコマンドにより、ポリシーレジストリーがコピーされます。 

$ 3scale policy-registry copy [opts] <source_remote> <target_remote>
Copy to Clipboard Toggle word wrap 
Option for policy-registry
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.17. アプリケーションのリスト表示
リンクのコピー

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

以下のコマンドにより、アプリケーションがリスト表示されます。 

$ 3scale application list [opts] <remote>
Copy to Clipboard Toggle word wrap

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

OPTIONS
       --account=<value>          Filter by account
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml
       --plan=<value>             Filter by application plan. Service
                                  option required.
       --service=<value>          Filter by service

OPTIONS FOR APPLICATION
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.17.1. アプリケーションの作成
リンクのコピー

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

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

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

  • <account> 参照。次のいずれかです。

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

以下のコマンドにより、アプリケーションが作成されます。 

$ 3scale application create [opts] <remote> <account> <service> <application-plan> <name>
Copy to Clipboard Toggle word wrap

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

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 created.
       --description=<value>        Application description
    -o --output=<value>             Output format on stdout:
                                    one of json|yaml
       --redirect-url=<value>       OpenID Connect redirect url
       --user-key=<value>           User Key (API Key) of the application
                                    to be created.

OPTIONS FOR APPLICATION
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.17.2. アプリケーションの表示
リンクのコピー

以下のコマンドにより、アプリケーションが表示されます。 

$ 3scale application show [opts] <remote> <application>
Copy to Clipboard Toggle word wrap

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

  • user_key: API キー
  • App_id: app_id/app_key ペアから、または OAuth および OpenID Connect (OIDC) 認証モードの Client ID
  • アプリケーションの内部 id 
OPTIONS
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

OPTIONS FOR APPLICATION
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode
Copy to Clipboard Toggle word wrap

5.17.3. アプリケーションの作成または更新
リンクのコピー

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

$ 3scale application apply [opts] <remote> <application>
Copy to Clipboard Toggle word wrap

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

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

  • アプリケーションが見つからず作成する必要がある場合は、オプションの account 引数が必要です。次のいずれかです。

    • アカウント id
    • 3scale アカウントの管理ユーザーの username、email、または 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
    -o --output=<value>            Output format on stdout:
                                   one of json|yaml
       --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.

OPTIONS FOR APPLICATION
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode.
Copy to Clipboard Toggle word wrap

5.17.4. アプリケーションの削除
リンクのコピー

以下のコマンドにより、アプリケーションが削除されます。 

$ 3scale application delete [opts] <remote> <application>
Copy to Clipboard Toggle word wrap

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

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

5.18. プロダクトのエクスポート
リンクのコピー

3scale プロダクト定義を .yaml 形式でエクスポートすると、そのプロダクトを、ソース 3scale インスタンスとの接続がない 3scale インスタンスにインポートできます。3scale プロダクトを設定してから、そのプロダクトをエクスポートする必要があります。Creating new products to test API calls を参照してください。

2 つの 3scale インスタンスにネットワーク接続がある場合、両方の 3scale インスタンスで同じ 3scale プロダクトを使用するには、toolbox 3scale copy コマンド を使用します。

説明

3scale プロダクトをエクスポートすると、ツールボックスは、プロダクト および バックエンド のカスタムリソース定義 (CRD) に準拠する .yaml 形式でプロダクト定義をシリアル化します。詳細は、3scale API Management Operator を使用した 3scale の設定とプロビジョニング を参照してください。yaml 出力には、プロダクトの基本情報の他に、以下が含まれます。

  • プロダクトにリンクされたバックエンド。
  • リンクされたバックエンドのメトリック、メソッド、およびマッピングルール。
  • アプリケーションプランで定義される制限および課金ルール。
  • 制限および課金ルールで参照されるメトリックおよびメソッド。

プロダクトのエクスポートは、読み取り専用の操作です。つまり、プロダクトを繰り返しエクスポートしても安全性に問題はありません。toolbox は、エクスポートされるプロダクトを変更しません。必要に応じて、別の 3scale インスタンスにインポートする前に .yaml 出力を変更できます。

3scale プロダクトのエクスポートは、以下の状況を対象としています。

  • 移行元および宛先 3scale インスタンス間の接続がない。たとえば、ネットワークに重大な制限があり、複数の 3scale インスタンスで同じプロダクトを使用するときに toolbox の 3scale copy コマンドを実行できない場合などです。
  • Git またはその他のソースコントロールシステムを使用して、.yaml 形式で 3scale プロダクト定義を維持する。

3scale toolbox の export および import コマンドは、プロダクト定義のバックアップおよび復元にも役立つことがあります。

形式

export コマンドを実行するには、以下の形式を使用します。 

$ 3scale product export [-f output-file] <remote> <product>
Copy to Clipboard Toggle word wrap

export コマンドは、出力を stdout またはファイルに送信できます。デフォルトは stdout です。出力をファイルに送信するには、.yaml ファイルの名前を指定して -f または --file オプションを指定します。

<remote> を、プロダクトのエクスポート元の 3scale インスタンスに関連付けられた 3scale プロバイダーアカウントエイリアスまたは URL に置き換えます。これを指定する方法の詳細は、リモートアクセスクレデンシャルの管理 を参照してください。

<product> を、エクスポートするプロダクトのシステム名または 3scale ID に置き換えます。このプロダクトは、指定した 3scale プロバイダーアカウントに関連付けられている必要があります。プロダクトのシステム名は、3scale 管理ポータルのプロダクトの 概要 ページで確認できます。プロダクトの 3scale ID を取得するには、toolbox 3scale services show コマンド を実行します。

例

以下のコマンドは、my-3scale-1 プロバイダーアカウントに関連付けられた 3scale インスタンスから petstore プロダクトをエクスポートし、それを petstore-product.yaml ファイルに出力します。 

$ 3scale product export -f petstore-product.yaml my-3scale-1 petstore
Copy to Clipboard Toggle word wrap

以下は、Default API プロダクトのシリアライズの例です。 

apiVersion: v1
kind: List
items:
- apiVersion: capabilities.3scale.net/v1beta1
  kind: Product
  metadata:
    annotations:
      3scale_toolbox_created_at: '2021-02-17T10:59:23Z'
      3scale_toolbox_version: 0.17.1
    name: api.xysnalcj
  spec:
    name: Default API
    systemName: api
    description: ''
    mappingRules:
    - httpMethod: GET
      pattern: "/v2"
      metricMethodRef: hits
      increment: 1
      last: false
    metrics:
      hits:
        friendlyName: Hits
        unit: hit
        description: Number of API hits
    methods:
      servicemethod01:
        friendlyName: servicemethod01
        description: ''
    policies:
    - name: apicast
      version: builtin
      configuration: {}
      enabled: true
    applicationPlans:
      basic:
        name: Basic
        appsRequireApproval: false
        trialPeriod: 0
        setupFee: 0.0
        custom: false
        state: published
        costMonth: 0.0
        pricingRules:
        - from: 1
          to: 1000
          pricePerUnit: 1.0
          metricMethodRef:
            systemName: hits
        limits:
        - period: hour
          value: 1222222
          metricMethodRef:
            systemName: hits
            backend: backend_01
    backendUsages:
      backend_01:
        path: "/v1/pets"
      backend_02:
        path: "/v1/cats"
    deployment:
      apicastSelfManaged:
        authentication:
          oidc:
            issuerType: rest
            issuerEndpoint: https://hello:test@example.com/auth/realms/3scale-api-consumers
            jwtClaimWithClientID: azp
            jwtClaimWithClientIDType: plain
            authenticationFlow:
              standardFlowEnabled: false
              implicitFlowEnabled: true
              serviceAccountsEnabled: false
              directAccessGrantsEnabled: true
            credentials: query
            security:
              hostHeader: ''
              secretToken: some_secret
            gatewayResponse:
              errorStatusAuthFailed: 403
              errorHeadersAuthFailed: text/plain; charset=us-ascii
              errorAuthFailed: Authentication failed
              errorStatusAuthMissing: 403
              errorHeadersAuthMissing: text/plain; charset=us-ascii
              errorAuthMissing: Authentication parameters missing
              errorStatusNoMatch: 404
              errorHeadersNoMatch: text/plain; charset=us-ascii
              errorNoMatch: No Mapping Rule matched
              errorStatusLimitsExceeded: 429
              errorHeadersLimitsExceeded: text/plain; charset=us-ascii
              errorLimitsExceeded: Usage limit exceeded
        stagingPublicBaseURL: http://staging.example.com:80
        productionPublicBaseURL: http://example.com:80
- apiVersion: capabilities.3scale.net/v1beta1
  kind: Backend
  metadata:
    annotations:
      3scale_toolbox_created_at: '2021-02-17T10:59:34Z'
      3scale_toolbox_version: 0.17.1
    name: backend.01.pcjwxbdu
  spec:
    name: Backend 01
    systemName: backend_01
    privateBaseURL: https://b1.example.com:443
    description: new desc
    mappingRules:
    - httpMethod: GET
      pattern: "/v1/pets"
      metricMethodRef: hits
      increment: 1
      last: false
    metrics:
      hits:
        friendlyName: Hits
        unit: hit
        description: Number of API hits
    methods:
      mybackendmethod01:
        friendlyName: mybackendmethod01
        description: ''
- apiVersion: capabilities.3scale.net/v1beta1
  kind: Backend
  metadata:
    annotations:
      3scale_toolbox_created_at: '2021-02-17T10:59:34Z'
      3scale_toolbox_version: 0.17.1
    name: backend.02.tiedgjsk
  spec:
    name: Backend 02
    systemName: backend_02
    privateBaseURL: https://b2.example.com:443
    description: ''
    mappingRules:
    - httpMethod: GET
      pattern: "/v1/cats"
      metricMethodRef: hits
      increment: 1
      last: false
    metrics:
      hits:
        friendlyName: Hits
        unit: hit
        description: Number of API hits
    methods:
      backend02_method01:
        friendlyName: backend02_method01
        description: ''
Copy to Clipboard Toggle word wrap

Product CR へのエクスポートおよびパイプ

export コマンドを実行すると、出力をパイプして プロダクトカスタムリソース (CR) を作成できます。この CR が含まれる 3scale インスタンスは以下により異なります。

  • threescale-provider-account シークレットが定義されている場合、3scale Operator はそのシークレットによって識別される 3scale インスタンスにプロダクト CR を作成します。
  • threescale-provider-account シークレットが定義されていない場合は、新規プロダクト CR が置かれている namespace に 3scale インスタンスがインストールされていると、3scale Operator はその namespace にプロダクト CR を作成します。
  • threescale-provider-account シークレットが定義されておらず、新規プロダクト CR が置かれている namespace に 3scale インスタンスが含まれていない場合は、3scale Operator はプロダクト CR を failed 状態とマークします。

threescale-provider-account シークレットが含まれる namespace で以下のコマンドを実行するとします。toolbox は、threescale-provider-account シークレットで識別された 3scale インスタンスに petstore CR をパイプ処理します。 

$ 3scale product export my-3scale-1 petstore | oc apply -f -
Copy to Clipboard Toggle word wrap

関連情報

5.19. プロダクトのインポート
リンクのコピー

移行元および宛先の 3scale インスタンスにネットワーク接続がない場合に、同じ 3scale プロダクトを複数の 3scale インスタンスで使用するには、ある 3scale インスタンスから 3scale プロダクトをエクスポートし、別の 3scale インスタンスにインポートします。プロダクトをインポートするには、toolbox 3scale product import コマンドを実行します。

2 つの 3scale インスタンスにネットワーク接続がある場合、両方の 3scale インスタンスで同じ 3scale プロダクトを使用するには、toolbox 3scale copy コマンド を使用します。

説明

3scale プロダクトをインポートすると、toolbox は、Product および Backend カスタムリソース定義 (CRD) に準拠する、.yaml 形式のシリアライズされたプロダクト定義を想定します。toolbox 3scale product export コマンドを実行するか、.yaml 形式のプロダクト定義を手動で作成して、この .yaml コンテンツを取得できます。

プロダクトをエクスポートした場合、インポートされた定義にはエクスポートされた内容が含まれます。これには以下が含まれます。

  • プロダクトにリンクされたバックエンド。
  • リンクされたバックエンドのメトリック、メソッド、およびマッピングルール。
  • アプリケーションプランで定義される制限および課金ルール。
  • 制限および課金ルールで参照されるメトリックおよびメソッド。

必要であれば、別の 3scale インスタンスにインポートする前に、エクスポートされた .yaml 出力を変更することができます。

import コマンドはべきとう性を持ちます。これを何回でも実行して同じプロダクトをインポートしても、作成される 3scale 設定は同じままとなります。インポートプロセス中にエラーが発生した場合は、コマンドを再実行しても安全性に問題はありません。import プロセスが 3scale インスタンスでプロダクトを見つけられない場合、プロダクトが作成されます。また、.yaml 定義で定義され、3scale インスタンスで見つけられないメトリック、メソッド、またはバックエンドも作成されます。

3scale プロダクトのインポートは、以下の状況を対象としています。

  • 移行元および宛先 3scale インスタンス間の接続がない。たとえば、ネットワークに重大な制限があり、複数の 3scale インスタンスで同じプロダクトを使用するときに toolbox の 3scale copy コマンドを実行できない場合などです。
  • Git またはその他のソースコントロールシステムを使用して、.yaml 形式で 3scale プロダクト定義を維持する。

3scale toolbox の export および import コマンドは、プロダクト定義のバックアップおよび復元にも役立つことがあります。

形式

import コマンドを実行するには、この形式を使用します。 

$ 3scale product import [<options>] <remote>
Copy to Clipboard Toggle word wrap

import コマンドは、.yaml の入力を stdin またはファイルから取得します。デフォルトは stdin です。

以下のオプションを指定することができます。

  • -f または --file の後にファイル名を指定すると、指定した .yaml ファイルから入力が取得されます。このファイルには、3scale の Product および Backend CRD に準拠する 3scale プロダクト定義が含まれる必要があります。
  • -o または --output の後に json または yaml を指定すると、指定した形式でインポートされたものがリストされたレポートが出力されます。デフォルトの出力形式は json です。

<remote> を、プロダクトのインポート先の 3scale インスタンスに関連付けられた 3scale プロバイダーアカウントエイリアスまたは URL に置き換えます。これを指定する方法の詳細は、リモートアクセスクレデンシャルの管理 を参照してください。

例

以下のコマンドは、petstore-product.yaml で定義されたプロダクトを、my-3scale-2 プロバイダーアカウントに関連付けられた 3scale インスタンスにインポートします。デフォルトでは、インポートされた内容のレポートは .json 形式になります。 

$ 3scale product import -f petstore-product.yaml my-3scale-2
Copy to Clipboard Toggle word wrap

import コマンドは、インポートされたアイテムをリスト表示するレポートを出力します。以下に例を示します。 

api:
  product_id: 2555417888846
  backends:
    backend_01:
      backend_id: 73310
      missing_metrics_created: 1
      missing_methods_created: 1
      missing_mapping_rules_created: 1
    backend_02:
      backend_id: 73311
      missing_metrics_created: 0
      missing_methods_created: 2
      missing_mapping_rules_created: 1
  missing_methods_created: 1
  missing_metrics_created: 1
  missing_mapping_rules_created: 2
  missing_application_plans_created: 2
  application_plans:
    basic:
      application_plan_id: 2357356246461
      missing_limits_created: 7
      missing_pricing_rules_created: 7
    unlimited:
      application_plan_id: 2357356246462
      missing_limits_created: 1
      missing_pricing_rules_created: 0
Copy to Clipboard Toggle word wrap

シリアライズされたプロダクト定義の例は、プロダクトのエクスポート の最後にあります。

5.20. プロダクトポリシーチェーンのエクスポートおよびインポート
リンクのコピー

プロダクトのポリシーチェーンを yaml または json コンテンツにエクスポートまたはインポートすることができます。コマンドラインで、id または system の値でプロダクトを参照します。プロダクトのポリシーチェーンをエクスポートまたはインポートする前に、3scale プロダクトを設定する必要があります。API コールをテストするための新規プロダクトの作成 を参照してください。

export コマンドの機能

  • このコマンドは、リモートプロダクトの読み取り専用操作になります。
  • このコマンドは、デフォルトで出力を標準出力 stdout に書き込みます。-f フラグは、コマンドの出力をファイルに書き込むために使用できます。
  • コマンド出力形式は、json または yaml のどちらかです。デフォルトの形式は yaml であることに注意してください。

エクスポートプロダクトポリシーチェーンのヘルプオプション

NAME
    export - export product policy chain
USAGE
    3scale policies export [opts] <remote>
    <product>
DESCRIPTION
    export product policy chain
OPTIONS
    -f --file=<value>             Write to file instead of stdout
    -o --output=<value>           Output format. One of: json|yaml
Copy to Clipboard Toggle word wrap

コマンドの形式

  • ポリシーチェーンを yaml のファイルにエクスポートするコマンドの形式を以下に示します。 

    $ 3scale policies export -f policies.yaml -o yaml remote_name product_name
    Copy to Clipboard Toggle word wrap

import コマンドの機能:

  • コマンドは、標準入力または stdin から入力を読み取ります。-f FILE フラグが設定されている場合、入力はファイルから読み取られます。-u URL フラグが設定されている場合、入力は URL から読み取られます。
  • インポートされたコンテンツは、yaml または json のいずれかになります。toolbox が自動的に検出するため、形式を指定する必要はありません。
  • 既存のポリシーチェーンは、新しくインポートされたポリシーチェーンで上書きされます。SET セマンティクスが実装されます。
  • すべてのコンテンツの検証は、3scale API に委任されます。

インポートプロダクトポリシーチェーンのヘルプオプション

NAME
    import - import product policy chain
USAGE
    3scale policies import [opts] <remote>
    <product>
DESCRIPTION
    import product policy chain
OPTIONS
    -f --file=<value>             Read from file
    -u --url=<value>              Read from url
Copy to Clipboard Toggle word wrap

コマンドの形式

  • 以下は、ファイルからポリシーチェーンをインポートするコマンドの形式です。 

    $ 3scale policies import -f plan.yaml remote_name product_name
    Copy to Clipboard Toggle word wrap

  • 以下は、URI からポリシーチェーンをインポートするコマンドの形式です。 

    $ 3scale policies import -f http[s]://domain/resource/path.yaml remote_name product_name
    Copy to Clipboard Toggle word wrap

5.21. API バックエンドのコピー
リンクのコピー

指定した 3scale システムに、特定のソース API バックエンドのコピーを作成します。ターゲットのシステムは、デフォルトでは、まずソースのバックエンドシステム名で検索されます。

  • 選択したシステム名のバックエンドが見つからない場合は、そのバックエンドが作成されます。
  • 選択したシステム名のバックエンドが見つかった場合は、置き換えられます。不足しているメトリックとメソッドのみが作成され、マッピングルールは完全に新しいものに置き換えられます。

--target_system_name オプションを使用して、システム名を上書きすることができます。

コピーされるコンポーネント

以下の API バックエンドコンポーネントがコピーされます。

  • メトリック
  • メソッド
  • マッピングルール: これらはコピーされ、置き換えられます。

手順

  • 以下のコマンドを入力して API バックエンドをコピーします。 

    $ 3scale backend copy [opts] -s <source_remote> -d <target_remote> <source_backend>
    Copy to Clipboard Toggle word wrap

    3scale インスタンスには、リモート名または URL を指定することができます。

    注記

    1 つのコマンドにつき 1 つの API バックエンドしかコピーすることはできません。複数のコマンドを使用して、複数のバックエンドをコピーすることができます。--target_system_name で異なる名前を指定して、同じバックエンドを複数回コピーすることができます。

API バックエンドのコピー時に、以下のオプションを使用します。 

Options
    -d --destination=<value>             3scale target instance: URL or
                                         remote name (required).
    -s --source=<value>                  3scale source instance: URL or
                                         remote name (required).
    -t --target_system_name=<value>      Target system name: defaults to
                                         source system name.
Copy to Clipboard Toggle word wrap

以下のコマンド例は、--target_system_name で異なる値を指定して、API バックエンドを複数回コピーする方法を示しています。 

$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14 3scale backend copy [-t target_system_name] -s 3scale1 -d 3scale2 api_backend_01
Copy to Clipboard Toggle word wrap

5.22. API プロダクトのコピー
リンクのコピー

ターゲットの 3scale システムに、特定のソース API プロダクトのコピーを作成します。ターゲットのシステムは、デフォルトでは、まずソースの API プロダクトのシステム名で検索されます。

  • 選択した system-name のプロダクトが見つからない場合は、そのプロダクトが作成されます。
  • 選択した system-name のプロダクトが存在する場合は、そのプロダクトが更新されます。不足しているメトリックとメソッドのみが作成され、マッピングルールは完全に新しいものに置き換えられます。

--target_system_name オプションを使用して、システム名を上書きすることができます。

コピーされるコンポーネント

以下の API プロダクトコンポーネントがコピーされます。

  • 定義および設定
  • メトリックおよびメソッド
  • マッピングルール: これらはコピーされ、置き換えられます。
  • アプリケーションプラン、課金ルール、および制限
  • アプリケーションの使用に関するルール
  • ポリシー
  • バックエンド
  • ActiveDocs

手順

  • 以下のコマンドを入力して API プロダクトをコピーします。 

    $ 3scale product copy [opts] -s <source_remote> -d <target_remote> <source_product>
    Copy to Clipboard Toggle word wrap

    3scale インスタンスには、リモート名または URL を指定することができます。

    注記

    1 つのコマンドにつき 1 つの API プロダクトしかコピーすることはできません。複数のコマンドを使用して、複数のプロダクトをコピーすることができます。--target_system_name で異なる名前を指定して、同じプロダクトを複数回コピーすることができます。

API プロダクトのコピー時に、以下のオプションを使用します。 

Options
    -d --destination=<value>             3scale target instance: URL or
                                         remote name (required).
    -s --source=<value>                  3scale source instance: URL or
                                         remote name (required).
    -t --target_system_name=<value>      Target system name: defaults to
                                         source system name.
Copy to Clipboard Toggle word wrap

以下のコマンド例は、--target_system_name で異なる値を指定して、API プロダクトを複数回コピーする方法を示しています。 

$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.14 3scale product copy [-t target_system_name] -s 3scale1 -d 3scale2 my_api_product_01
Copy to Clipboard Toggle word wrap

5.23. SSL および TLS に関する問題のトラブルシューティング
リンクのコピー

このセクションでは、Secure Sockets Layer/Transport Layer Security (SSL/TLS) に関する問題の解決方法を説明します。

自己署名 SSL 証明書に関連する問題が発生している場合、このセクションで説明されているようにリモートホスト証明書をダウンロードして使用することができます。典型的なエラーの例としては、SSL certificate problem: self signed certificate または self signed certificate in certificate chain などがあります。

手順

  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
    Copy to Clipboard Toggle word wrap

  2. curl を使用して、証明書が正常に機能していることを確認します。以下に例を示します。 

    $ SSL_CERT_FILE=self-signed-cert.pem curl -v https://self-signed.badssl.com
    Copy to Clipboard Toggle word wrap

    証明書が正しく機能している場合は、SSL エラーが表示されることはなくなります。証明書が正常に機能していない場合は、-k オプション (または long 形式の --insecure) を使用して curl コマンドの実行を試行します。これは、サーバーコネクションがセキュアでなくても、続行することを示しています。

  3. 3scale コマンドに SSL_CERT_FILE 環境変数を追加します。以下に例を示します。 

    $ podman run --env "SSL_CERT_FILE=/tmp/self-signed-cert.pem" -v $PWD/self-signed-cert.pem:/tmp/self-signed-cert.pem registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.14 3scale service list https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}
    Copy to Clipboard Toggle word wrap

    この例では、Podman ボリュームを使用して、証明書ファイルをコンテナーにマウントします。これは、このファイルが現在の $PWD フォルダーにあることを前提としています。

    これ以外に、ベースイメージとして 3scale toolbox イメージを使用して専用の toolbox イメージを作成し、独自の信頼済み証明書ストアをインストールするアプローチもあります。

関連情報

第6章 3scale API Management での API 環境のマッピング
リンクのコピー

API プロバイダーは、3scale 管理ポータルを通じて管理される API へのアクセスを提供します。続いて、API バックエンドを多くの環境にデプロイします。API バックエンド環境には、以下が含まれます。

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

Red Hat 3scale API Management プロダクトは、単一の API または API のサブセットを表しますが、さまざまな API バックエンド環境のマッピングおよび管理にも使用されます。

3scale プロダクトの API 環境のマッピング方法に関しては、以下のセクションを参照してください。

6.1. 環境ごとのプロダクト
リンクのコピー

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

Production Product => Production Product APIcast gateway => Production Product API upstream
Staging Product => Staging Product APIcast gateway => Staging Product API upstream
Copy to Clipboard Toggle word wrap

API バックエンド環境のプロダクトを以下のように設定します。

開発環境

  • 開発バックエンドの作成

    • 名前: Dev
    • プライベートベース URL: API バックエンドの URL

  • Dev プロダクトの作成

    • 本番パブリックベース URL: https://dev-api-backend.yourdomain.com
    • ステージングパブリックベース URL: https://dev-api-backend.yourdomain.com
    • バックエンドパス / を使用した 開発バックエンドの追加

QA 環境

  • QA バックエンドの作成

    • 名前: QA
    • プライベートベース URL: API バックエンドの URL

  • QA プロダクトの作成

    • 本番パブリックベース URL: https://qa-api-backend.yourdomain.com
    • ステージングパブリックベース URL: https://qa-api-backend.yourdomain.com
    • バックエンドパス / を使用した QA バックエンドの追加

実稼働環境

  • 実稼働環境用のバックエンドの作成

    • 名前: Prod
    • プライベートベース URL: API バックエンドの URL

  • Prod プロダクトの作成

    • 本番パブリックベース URL: https://prod-api-backend.yourdomain.com
    • ステージング環境用の公開ベース URL: https://prod-api-backend.yourdomain.com
    • バックエンドパスを使用して 実稼働バックエンドを追加 する /

関連情報

6.2. オンプレミス型 3scale API Management インスタンス
リンクのコピー

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

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

6.2.1. 環境ごとの 3scale API Management インスタンスの分離
リンクのコピー

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

注記

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

6.2.2. 環境ごとの 3scale API Management テナントの分離
リンクのコピー

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

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

  • 単一のテナント内で、環境と 3scale プロダクト間の 1 対 1 のマッピングを作成します。

  • 必要に応じて、テナントごとに 1 つ以上のプロダクトを使用して、環境とテナントの間に 1 対 1 のマッピングを作成します。

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

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

6.3. 3scale API Management の混合アプローチ
リンクのコピー

オンプレミス型 3scale API Management インスタンス で説明されている方法を組み合わせることができます。以下に例を示します。

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

6.4. APIcast ゲートウェイを使用した 3scale API Management
リンクのコピー

オンプレミス型 3scale インスタンスの場合、API バックエンド環境を管理するために 3scale を設定する選択肢が 2 つあります。

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

6.4.1. APIcast の組み込みデフォルトゲートウェイ
リンクのコピー

APIcast 組み込みゲートウェイを使用する場合、3scale API Management と 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>

6.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
Copy to Clipboard Toggle word wrap

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

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

関連情報

第7章 3scale API Management Operator を使用した 3scale の設定とプロビジョニング
リンクのコピー

Red Hat 3scale API Management の管理者は、3scale Operator を使用して 3scale サービスを設定し、3scale リソースをプロビジョニングすることができます。OpenShift Container Platform(OCP) ユーザーインターフェイスで Operator を使用します。Operator の使用は、管理ポータルで、または 3scale 内部 API を使用して 3scale を設定およびプロビジョニングする代わりとなります。

3scale Operator を使用してサービスを設定するか、リソースをプロビジョニングする場合、そのサービスまたはリソースを更新する唯一の方法は、そのカスタムリソース (CR) を更新することです。

注記

管理ポータルではサービスとリソースが表示されますが、そこでは更新しないでください。同様に、サービスとリソースを更新するために内部 3scale API を使用して更新を行わないでください。CR 以外の方法を使用して更新を行うと、Operator は変更を元に戻し、設定を変更しないままにします。

この章では、Operator アプリケーションの機能の仕組みおよび Operator を使用したカスタムリソースのデプロイ方法を説明します。

さらに、3scale Operator を使用する場合の機能制限に関する情報があります。

7.1. 一般的な前提条件
リンクのコピー

3scale Operator を使用して 3scale を設定およびプロビジョニングするには、以下の要素が必要です。

7.2. 3scale API Management Operator を使用したアプリケーション機能
リンクのコピー

3scale Operator には、以下の機能が含まれています。

  • ベースとなる Red Hat 3scale API Management ソリューションとの対話を可能にする。
  • OpenShift からのカスタムリソースを宣言的に使用して 3scale アプリケーションを管理する。

以下の図は、OpenShift カスタムリソースを宣言的に使用して管理することのできる 3scale エンティティーおよび関係を示しています。プロダクトには 1 つまたは複数のバックエンドが含まれます。プロダクトレベルでは、アプリケーション、アプリケーションプラン、およびマッピングルールを設定できます。バックエンドレベルでは、各バックエンドのメトリクス、メソッド、およびマッピングルールを設定できます。

OpenShift カスタムリソースを使用した管理の対象の 3scale エンティティーおよび関係
View larger image
OpenShift カスタムリソースを使用した管理の対象の 3scale エンティティーおよび関係

以下の図に示すように、3scale Operator は、カスタムリソース定義とその関係を提供します。

OpenShift カスタムリソースを使用した管理の対象の 3scale エンティティーおよび関係
View larger image
OpenShift カスタムリソースを使用した管理の対象の 3scale エンティティーおよび関係

7.3. 最初の 3scale API Management プロダクトおよびバックエンドのデプロイ
リンクのコピー

新しく作成したテナントで OpenShift Container Platform (OCP) を使用して、最初の 3scale プロダクトおよびバックエンドを最低限必要な設定でデプロイします。

前提条件

一般的な前提条件 に記載の条件と同じインストール要件が適用されます。ただし、以下の考慮事項に注意してください。

  • 3scale アカウントは、稼働用の OpenShift namespace のローカルとするか、リモートインストールにすることができます。
  • このアカウントから必要なパラメーターは、3scale 管理ポータル URL アドレスとアクセストークンです。

手順

  1. 3scale 管理ポータルからのクレデンシャルを使用して、3scale プロバイダーアカウントのシークレットを作成します。例: adminURL=https://3scale-admin.example.com および token=123456。 

    $ oc create secret generic threescale-provider-account --from-literal=adminURL=https://3scale-admin.example.com --from-literal=token=123456
    Copy to Clipboard Toggle word wrap

  2. アップストリーム API URL を使用して 3scale バックエンドを設定します。

    1. 以下の内容を含む YAML ファイルを作成します。 

      apiVersion: capabilities.3scale.net/v1beta1
kind: Backend
metadata:
  name: backend1
spec:
  name: "Operated Backend 1"
  systemName: "backend1"
  privateBaseURL: "https://api.example.com"
      Copy to Clipboard Toggle word wrap

    2. カスタムリソースを作成します。 

      $ oc create -f backend1.yaml
      Copy to Clipboard Toggle word wrap

  3. 3scale プロダクトを設定します。

    1. 前のステップで作成したバックエンドに適用したすべてのデフォルト設定でプロダクトを作成します。 

      apiVersion: capabilities.3scale.net/v1beta1
kind: Product
metadata:
  name: product1
spec:
  name: "OperatedProduct 1"
  systemName: "operatedproduct1"
  backendUsages:
    backend1:
      path: /
      Copy to Clipboard Toggle word wrap
      • ファイルを作成すると、Operator はステップが成功したかどうかを確認します。
      • Product CR のフィールドと設定可能な値の詳細は、Product CRD リファレンス を参照してください。

    2. カスタムリソースを作成します。 

      $ oc create -f product1.yaml
      Copy to Clipboard Toggle word wrap

      既存のプロダクト CRD を更新して、バックエンドにリンクすることもできます。 

      $ oc apply -f product.yaml
      Copy to Clipboard Toggle word wrap

  4. 作成したカスタムリソースが 3scale インスタンスに反映されるのに数秒かかります。リソースが同期されるタイミングを確認するには、以下のいずれかの方法を選択できます。

    • オブジェクトの ステータス フィールドを確認する。

    • oc wait コマンドを使用する。 

      $ oc wait --for=condition=Synced --timeout=-1s backend/backend1

$ oc wait --for=condition=Synced --timeout=-1s product/product1
      Copy to Clipboard Toggle word wrap

7.4. 製品の APIcast 設定のプロモート
リンクのコピー

3scale Operator を使用して、製品の APIcast 設定をステージングまたは実稼働に昇格させることができます。ProxyConfigPromote カスタムリソース (CR) は、最新の APIcast 設定をステージング環境にプロモートします。必要に応じて、ProxyConfigPromote CR を設定して、運用環境にも昇格させることができます。

注記

ProxyConfigPromote オブジェクトは、作成されたときにのみ有効になります。作成後、それらの更新は調整されません。

前提条件

以下を含む、一般的な前提条件 に記載されているものと同じインストール要件:

手順

  1. 次の内容で YAML ファイルを作成して保存します。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample
    Copy to Clipboard Toggle word wrap

    APIcast 設定を本番環境にプロモートするには、オプションのフィールド spec.production を true に設定します。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample
  production: true
    Copy to Clipboard Toggle word wrap

    昇格が成功した後に ProxyConfigPromote object を削除するには、オプションのフィールド spec.deleteCR を true に設定します。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample
  deleteCR: true
    Copy to Clipboard Toggle word wrap

  2. ファイルのステータス条件を確認するには、次のコマンドを入力します。 

    oc get proxyconfigpromote proxyconfigpromote-sample -o yaml
    Copy to Clipboard Toggle word wrap

    1. 出力には、ステータスが Ready と表示されます。 

      apiVersion: capabilities.3scale.net/v1beta1
kind: ProxyConfigPromote
metadata:
  name: proxyconfigpromote-sample
spec:
  productCRName: product1-sample
status:
  conditions:
  - lastTransitionTime: "2022-10-28T11:35:19Z"
    status: "True"
    type: Ready
      Copy to Clipboard Toggle word wrap
      注記

      プロキシー設定を変更しない場合、ProxyConfigPromote CR の出力ステータス Failed が返され、メッセージ can’t promote to production as no product changes detected, delete the proxyConfigPromote CR or introduce changes to stage env first to proceed が表示されます。手順を完了するには、その指示に従ってください。

  3. カスタムリソースを作成します。 

    oc create -f proxyconfigpromote-sample.yaml
    Copy to Clipboard Toggle word wrap

    • この例では、出力は以下のようになります。 

      proxyconfigpromote.capabilities.3scale.net/proxyconfigpromote-sample created
      Copy to Clipboard Toggle word wrap

関連情報

7.6. 3scale API Management OpenAPI カスタムリソースのデプロイ
リンクのコピー

OpenAPI カスタムリソース (CR) は、開発者ポータルの ActiveDocs に使用できる OpenAPI Specification(OAS) ドキュメントをインポートする 1 つの方法です。OAS は、API に対して使用できるプログラミング言語が特定のものだけに限定されないようにする規格です。人間とコンピューターは、ソースコードのアクセス、ドキュメント、またはネットワークトラフィックの検査なしに API プロダクトの機能をより簡単に理解することができます。

前提条件

  • オンプレミス型 3scale 2.14 インスタンスの管理者権限を持つユーザーアカウント
  • API を定義する OAS ドキュメント
  • OpenAPI CR がテナントにリンクする方法に関する理解
  • サポートされているセキュリティースキームは、apiKey と openIdConnect/oauth2 です。

OpenID Connect と OAuth2 の制限

OpenAPI 仕様で 3scale を設定するには、OpenAPI カスタムリソース (CR) で次のデータを提供する必要があります。

  • OpenID Connect (OIDC) issuerType:

    • 発行者のタイプを定義します。デフォルトは rest です。このパラメーターは OpenAPI CR でオーバーライドできます。

  • プレーン値の URL として issuerEndpoint を定義するか、issuerEndpoint URL を含む issuerEndpointRef シークレットを定義します。

    • CR で issuerEndpoint プレーン値を定義する場合、これは issuerEndpointRef シークレットよりも優先されます。
    • issuerEndpoint の形式は、OpenID プロバイダーの設定によって異なります。Red Hat Single Sign-On の場合は https://<CLIENT_ID>:<CLIENT_SECRET>@:/auth/realms/<REALM_NAME> です。

  • Flows Object:

    • oauth2 セキュリティースキームを定義すると、OpenAPI ドキュメントにフローが含まれます。ただし、セキュリティースキームが OpenID Connect の場合、OpenAPI ドキュメントではフローが提供されません。この場合、OpenAPI CR でフローを提供できます。

3scale バックエンド および プロダクト を作成できるように、OpenAPI カスタムリソース (CR) をデプロイします。

注記

Operator はシークレットのコンテンツのみを読み取ります。Operator はシークレットのフィールド名を読み取りません。

前提条件

3scale Operator がカスタムリソースのリンク先となるテナントを識別する方法 を理解している。

手順

  1. OAS ドキュメントが含まれるシークレットを定義します。たとえば、以下の内容で myoasdoc1.yaml を作成することができます。 

    openapi: "3.0.2"
info:
  title: "some title"
  description: "some description"
  version: "1.0.0"
paths:
  /pet:
    get:
      operationId: "getPet"
      responses:
        405:
          description: "invalid input"
    Copy to Clipboard Toggle word wrap

  2. シークレットを作成します。以下に例を示します。 

    $ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml

secret/myoasdoc1 created
    Copy to Clipboard Toggle word wrap

  3. OpenAPI CR を定義します。OAS ドキュメントが含まれるシークレットへの参照を指定するようにしてください。たとえば、myopenapicr1.yaml ファイルを作成することができます。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: OpenAPI
metadata:
  name: myopenapicr1
spec:
  openapiRef:
    secretRef:
      name: myoasdoc1
    Copy to Clipboard Toggle word wrap

  4. 定義したばかりのリソースを作成します。以下に例を示します。 

    $ oc create -f myopenapicr1.yaml
    Copy to Clipboard Toggle word wrap

    この例では、出力は以下のようになります。 

    $ openapi.capabilities.3scale.net/myopenapicr1 created
    Copy to Clipboard Toggle word wrap

7.6.2. 3scale API Management OpenAPI カスタムリソース定義の機能
リンクのコピー

OpenAPI カスタムリソース定義 (CRD) のデプロイメント機能に関する知識は、3scale プロダクトの設定、バックエンド、およびその後の開発者ポータル用の ActiveDocs の作成に役立ちます。

  • OAS ドキュメントは、以下から読み込むことができます。

    • Kubernetes シークレット。
    • http 形式と https 形式の URL。
  • OAS ドキュメントでは、info.title 設定は 215 文字を超えることができません。Operator はこの設定を使用して、長さの制限がある OpenShift オブジェクト名を作成します。
  • サーバーリストの最初の servers[0].url 要素のみがプライベート URL として解析されます。OpenAPI Specification(OAS) は、servers[0].url 要素の basePath コンポーネントを使用します。
  • OpenAPI CRD は単一の最上位のセキュリティー要件をサポートしますが、運用レベルのセキュリティーはサポートしません。
  • OpenAPI CRD は、apiKey および openIdConnect/oauth2 セキュリティースキームをサポートします。

関連情報

7.6.3. OpenAPI カスタムリソースを定義する際のインポートルール
リンクのコピー

インポートルールは、3scale デプロイメントの OpenAPI ドキュメントを設定する際に、OpenAPI Specification(OAS) が 3scale とどのように機能するかを指定します。

プロダクト名

デフォルトのプロダクトシステム名は、OpenAPI ドキュメントの info.title フィールドから取得されます。OpenAPI ドキュメントのプロダクト名を上書きするには、OpenAPI カスタムリソース (CR) の spec.productSystemName フィールドを指定します。

プライベートベース URL

プライベートベース URL は OpenAPI CR servers[0].url フィールドから読み込まれます。OpenAPI CR の spec.privateBaseURL フィールドを使用して、これを上書きできます。

3scale メソッド

インポートされた OpenAPI ドキュメントで定義される各操作は、プロダクトレベルで 1 つの 3scale メソッドに変換されます。メソッド名は、操作オブジェクトの operationId フィールドから読み取られます。

3scale のマッピングルール

インポートされた OpenAPI ドキュメントで定義される各操作は、プロダクトレベルで 1 つの 3scale マッピングルールに変換されます。以前の既存のマッピングルールは OpenAPI CR でインポートされたルールに置き換えられました。

OpenAPI ドキュメントでは、paths オブジェクトは動詞およびパターンプロパティーのマッピングルールを提供します。3scale メソッドは operationId に応じて関連付けられます。

delta の値は 1 にハードコーディングされます。

デフォルトでは、Strict マッチング ポリシーが設定されます。マッチングポリシーは、OpenAPI CRD の spec.PrefixMatching フィールドを使用して、接頭辞マッチング に切り替えることができます。

認証

1 つのトップレベルのセキュリティー要件のみがサポートされます。操作レベルのセキュリティー要件はサポートされていません。

サポートされるセキュリティースキームは apiKey です。

apiKey セキュリティースキームタイプ:

  • クレデンシャルの場所 は、セキュリティースキームオブジェクトの OpenAPI ドキュメント in フィールドから読み込まれます。
  • 認証ユーザー キーは、セキュリティースキームオブジェクトの OpenAPI ドキュメント name フィールドから読み込まれます。

以下は、apiKey セキュリティー要件のある OAS 3.0.2 の例の一部です。 

openapi: "3.0.2"
security:
  - petstore_api_key: []
components:
  securitySchemes:
    petstore_api_key:
      type: apiKey
      name: api_key
      in: header
Copy to Clipboard Toggle word wrap

OpenAPI ドキュメントがセキュリティー要件を指定しない場合、以下が適用されます。

  • プロダクト認証が apiKey に設定されます。
  • クレデンシャルの場所 はデフォルトで 3scale の値 As query parameters (GET) or body parameters (POST/PUT/DELETE) に設定されます。
  • Auth ユーザー キーはデフォルトで 3scale の値 user_key に設定されます。

3scale 認証セキュリティー は、OpenAPI CRD の spec.privateAPIHostHeader フィールドおよび spec.privateAPISecretToken フィールドを使用して設定できます。

ActiveDocs

3scale ActiveDoc は作成されていません。

3scale プロダクトポリシーチェーン

3scale ポリシーチェーンは、3scale が作成するデフォルトのポリシーチェーンです。

3scale デプロイメントモード

デフォルトでは、設定した 3scale デプロイメントモードは APIcast 3scale により管理されます。しかし、spec.productionPublicBaseURL または spec.stagingPublicBaseURL、あるいは両方のフィールドが OpenAPI CR にある場合、プロダクトのデプロイメントモードは APIcast で自己管理されます。

カスタム公開ベース URL を持つ OpenAPI CR の例: 

apiVersion: capabilities.3scale.net/v1beta1
kind: OpenAPI
metadata:
  name: openapi1
spec:
  openapiRef:
    url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
  productionPublicBaseURL: "https://production.my-gateway.example.com"
  stagingPublicBaseURL: "https://staging.my-gateway.example.com"
Copy to Clipboard Toggle word wrap

指定した URL から OAS ドキュメントをインポートする OpenAPI カスタムリソースをデプロイできます。その後、この OAS ドキュメントを、デベロッパーポータルで API の ActiveDocs の基礎として使用できます。

前提条件

  • 同じ namespace にある 3scale インスタンスのデフォルトのテナントにリンクしない OpenAPI カスタムリソースを作成する場合、OpenAPI CR が含まれる namespace には、OpenAPI CR がリンクするテナントを特定するシークレットが含まれます。シークレットの名前は以下のいずれかになります。

    • threescale-provider-account
    • ユーザー定義

    このシークレットには、3scale インスタンスの URL と、3scale インスタンスの 1 つのテナントにアクセスするためのクレデンシャルが含まれるトークンが含まれます。

手順

  1. OpenShift アカウントで、Operators > Installed operators に移動します。
  2. 3scale Operator をクリックします。
  3. YAML タブを選択します。

  4. OpenAPI カスタムリソース (CR) を作成します。以下に例を示します。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: OpenAPI
metadata:
  name: openapi1
spec:
  openapiRef:
    url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
  providerAccountRef:
    name: mytenant
    Copy to Clipboard Toggle word wrap
  5. Save をクリックします。3scale Operator が OpenAPI CR を作成するまでに数秒かかります。

検証

  1. OpenShift の 3scale Product Overview ページで、Synced 状態が True とマークされていることを確認します。
  2. 3scale アカウントに移動します。
  3. OAS ドキュメントが存在することを確認します。上記の例では、openapi1 という名前の新しい OAS ドキュメントが表示されます。

7.6.5. 関連情報
リンクのコピー

7.7. 3scale API Management ActiveDoc カスタムリソースのデプロイ
リンクのコピー

Red Hat 3scale API Management ActiveDocs は、OpenAPI Specification に準拠する RESTful Web サービスを定義する API 定義ドキュメントをベースとしています。ActiveDoc カスタムリソース (CR) は、開発者ポータルの ActiveDocs に使用できる OpenAPI Specification(OAS) ドキュメントをインポートする 1 つの方法です。OAS は、API に対して使用できるプログラミング言語が特定のものだけに限定されないようにする規格です。人間とコンピューターは、ソースコードのアクセス、ドキュメント、またはネットワークトラフィックの検査なしに API プロダクトの機能をより簡単に理解することができます。

前提条件

  • オンプレミス型 3scale 2.14 インスタンスの管理者権限を持つユーザーアカウント

  • API を定義する OAS ドキュメント

    • OAS 3.0.2 は、ActiveDocs カスタムリソース定義 (CRD) でサポートされている唯一のバージョンです。
  • ActiveDoc CR がテナントにリンクする方法を理解している。

3scale バックエンド および プロダクト を作成できるように、ActiveDoc カスタムリソース (CR) をデプロイします。

注記

Operator はシークレットのコンテンツのみを読み取ります。Operator はシークレットのフィールド名を読み取りません。たとえば、データは key: value のペアで設定され、value はファイルの内容を表し、key はファイル名です。ファイル名は、ActiveDoc CRD のこのコンテキストで Operator によって無視されます。Operator はファイルの内容のみを読み取ります。

前提条件

  • 3scale API Management Operator がカスタムリソースのリンク先となるテナントを識別する方法 を理解している。

  • OAS(OpenAPI Specification) ドキュメントが含まれるシークレットを定義します。たとえば、以下の内容で myoasdoc1.yaml を作成することができます。 

    openapi: "3.0.2"
info:
  title: "some title"
  description: "some description"
  version: "1.0.0"
paths:
  /pet:
    get:
      operationId: "getPet"
      responses:
        405:
          description: "invalid input"
    Copy to Clipboard Toggle word wrap

手順

  1. シークレットを作成します。以下に例を示します。 

    $ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml

secret/myoasdoc1 created
    Copy to Clipboard Toggle word wrap

  2. ActiveDoc CR を定義します。OAS ドキュメントが含まれるシークレットへの参照を指定するようにしてください。たとえば、myactivedoccr1.yaml ファイルを作成できます。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: ActiveDoc
metadata:
  name: myactivedoccr1
spec:
  name: "Operated ActiveDoc From secret"
  activeDocOpenAPIRef:
    secretRef:
      name: myoasdoc1
    Copy to Clipboard Toggle word wrap

  3. 定義したばかりのリソースを作成します。以下に例を示します。 

    $ oc create -f myactivedoccr1.yaml
    Copy to Clipboard Toggle word wrap

    この例では、出力は以下のようになります。 

    $ activedoc.capabilities.3scale.net/myactivedoccr1 created
    Copy to Clipboard Toggle word wrap

検証

  1. Red Hat OpenShift Container Platform (OCP) 管理者アカウントにログインします。
  2. Operators > Installed Operators に移動します。
  3. Red Hat Integration - 3scale をクリックします。
  4. Active Doc タブをクリックします。
  5. OAS ドキュメントが存在することを確認します。上記の例では、myactivedoccr1 という名前の新しい OAS ドキュメントが表示されます。

7.7.2. 3scale API Management ActiveDoc カスタムリソース定義の機能
リンクのコピー

ActiveDoc カスタムリソース定義 (CRD) は、開発者の OpenAPI ドキュメント形式の製品ドキュメントを考慮します。ActiveDoc CRD デプロイメント機能に関する知識は、デベロッパーポータルの ActiveDocs の作成に役立ちます。

  • ActiveDoc CR は、以下のいずれかから OpenAPI ドキュメントを読み取りできます・

    • シークレット
    • http または https 形式の URL
  • オプションで、productSystemName フィールドを使用して、ActiveDoc CR を 3scale 製品にリンクできます。値は、3scale プ製品の CR の system_name である必要があります。
  • published フィールドを使用して、3scale の ActiveDoc ドキュメントを公開または非表示にすることができます。デフォルトでは、これは hidden に設定されています。
  • skipSwaggerValidations フィールドを使用して、OpenAPI 3.0 検証を省略できます。デフォルトでは、ActiveDoc CR は検証されます。

関連情報

指定した URL から OAS(OpenAPI Specification) ドキュメントをインポートする ActiveDoc カスタムリソース (CR) をデプロイできます。その後、この OAS ドキュメントを、デベロッパーポータルで API の ActiveDocs の基礎として使用できます。

前提条件

手順

  1. OpenShift アカウントで、Operators > Installed operators に移動します。
  2. 3scale Operator をクリックします。
  3. Active Doc タブをクリックします。

  4. ActiveDoc CR を作成します。以下に例を示します。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: ActiveDoc
metadata:
  name: myactivedoccr1
spec:
  openapiRef:
    url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
  providerAccountRef:
    name: mytenant
    Copy to Clipboard Toggle word wrap

  5. オプション。Self-managed APIcast の場合、ActiveDoc CR で productionPublicBaseURL および stagingPublicBaseURL フィールドをデプロイメントの URL に設定します。以下に例を示します。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: ActiveDoc
metadata:
  name: myactivedoccr1
spec:
  openapiRef:
    url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
  productionPublicBaseURL: "https://production.my-gateway.example.com"
  stagingPublicBaseURL: "https://staging.my-gateway.example.com"
    Copy to Clipboard Toggle word wrap
  6. Save をクリックします。3scale Operator が ActiveDoc CR を作成するまでに数秒かかります。

検証

  1. Red Hat OpenShift Container Platform (OCP) 管理者アカウントにログインします。
  2. Operators > Installed Operators に移動します。
  3. Red Hat Integration 3scale をクリックします。
  4. Active Doc タブをクリックします。
  5. OAS ドキュメントが存在することを確認します。上記の例では、myactivedoccr1 という名前の新しい OAS ドキュメントが表示されます。

7.7.4. 関連情報
リンクのコピー

7.11. 3scale API Management CustomPolicyDefinition カスタムリソースのデプロイ
リンクのコピー

CustomPolicyDefinition カスタムリソース定義 (CRD) を使用して、管理ポータルから 3scale プロダクトのカスタムポリシーを設定できます。

3scale Operator が新規の CustomPolicyDefinition カスタムリソース (CR) を見つけると、Operator は、3scale API Management Operator がカスタムリソースのリンク先となるテナントを識別する方法 で説明されているように CR を所有するテナントを識別します。

前提条件

手順

  1. CustomPolicyDefinition CR を定義して保存します (例: my-apicast-custom-policy-definition.yaml ファイル)。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: CustomPolicyDefinition
metadata:
  name: custompolicydefinition-sample
spec:
  version: "0.1"
  name: "APIcast Example Policy"
  schema:
    name: "APIcast Example Policy"
    version: "0.1"
    $schema: "http://apicast.io/policy-v1/schema#manifest#"
    summary: "This is just an example."
    configuration:
      type: object
      properties: {}
    Copy to Clipboard Toggle word wrap

  2. CustomPolicyDefinition CR をデプロイします。 

    $ oc create -f my-apicast-custom-policy-definition.yaml
    Copy to Clipboard Toggle word wrap

関連情報

7.12. テナントカスタムリソースのデプロイ
リンクのコピー

Tenant カスタムリソース (CR) は、プロバイダーアカウント とも呼ばれます。

APIManager CR をデプロイする場合には、3scale Operator を使用して 3scale をデプロイします。デフォルトの 3scale インストール環境には、使用可能なデフォルトのテナントが含まれます。オプションで、Tenant CR をデプロイして他のテナントを作成できます。

前提条件

  • 一般的な前提条件
  • 新規 Tenant CR の namespace に対して create パーミッションが指定された OpenShift ロール。

手順

  1. 3scale がインストールされている OpenShift プロジェクトに移動します。たとえば、プロジェクトの名前が my-3scale-project の場合は、以下のコマンドを実行します。 

    $ oc project my-3scale-project
    Copy to Clipboard Toggle word wrap

  2. 新規テナントの 3scale 管理アカウントのパスワードが含まれるシークレットを作成します。Tenant CR の定義で、passwordCredentialsRef 属性をこのシークレットの名前に設定します。ステップ 4 の Tenant CR 定義の例では、ADMIN_SECRET はこのシークレットのプレースホルダーになります。以下のコマンドは、シークレットの作成例を示しています。 

    $ oc create secret generic ecorp-admin-secret --from-literal=admin_password=<admin password value>
    Copy to Clipboard Toggle word wrap

  3. 3scale マスターアカウントのホスト名を取得します。Operator を使用して 3scale をデプロイする場合、マスターアカウントには、master.${wildcardDomain} のパターンの固定 URL があります。

    3scale がインストールされている namespace にアクセスできる場合は、以下のコマンドでマスターアカウントのホスト名を取得できます。 

    $ oc get routes --field-selector=spec.to.name==system-master -o jsonpath="{.items[].spec.host}"
    Copy to Clipboard Toggle word wrap

    ステップ 4 の Tenant CR 定義の例では、MASTER_HOSTNAME はこの名前のプレースホルダーです。

  4. 新しい Tenant CR を定義するファイルを作成します。

    Tenant CR の定義で、masterCredentialsRef.name 属性を system-seed に設定します。テナント管理タスクは、3scale マスターアカウントのクレデンシャルを使用してのみ実行できます (アクセストークンの使用が推奨されます)。APIManager CR のデプロイメント時に、Operator はマスターアカウントの認証情報が含まれるシークレットを作成します。シークレットの名前は system-seed です。

    3scale がクラスター全体のモードでインストールされている場合には、3scale が含まれる namespace とは異なる namespace に新規テナントをデプロイできます。これには、masterCredentialsRef.namespace を 3scale インストールが含まれる namespace に設定します。

    以下の例では、3scale がクラスター全体のモードにインストールされていることを前提とします。 

    apiVersion: capabilities.3scale.net/v1alpha1
kind: Tenant
metadata:
  name: ecorp-tenant
  namespace: <namespace-in-which-to-create-Tenant-CR>
spec:
  username: admin
  systemMasterUrl: https://<MASTER_HOSTNAME>
  email: admin@ecorp.com
  organizationName: ECorp
  masterCredentialsRef:
    name: system-seed
    namespace: <namespace-where-3scale-is-deployed>
  passwordCredentialsRef:
    name: <ADMIN_SECRET>
  tenantSecretRef:
    name: tenant-secret
    Copy to Clipboard Toggle word wrap

  5. Tenant CR を作成します。たとえば、直前のサンプル CR を mytenant.yaml ファイルに保存した場合は、以下を実行します。 

    $ oc create -f mytenant.yaml
    Copy to Clipboard Toggle word wrap

    このコマンドを実行すると、以下のようになります。

    • Operator は、spec.systemMasterUrl 属性を設定して、3scale インストールのテナントをデプロイします。

    • 3scale Operator は、新規テナントの認証情報が含まれるシークレットを作成します。シークレットの名前は、tenantSecretRef.name 属性に指定した値です。このシークレットには、新規テナントの管理者 URL およびアクセストークンが含まれます。

      参考として、Operator が作成するシークレットの例を以下に示します。 

      apiVersion: v1
kind: Secret
metadata:
  name: tenant-secret
type: Opaque
stringData:
  adminURL: https://my3scale-admin.example.com:443
  token: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
      Copy to Clipboard Toggle word wrap
    • 新規テナントにリンクする Product、Backend、OpenAPI、DeveloperAccount、および DeveloperUser CR をデプロイできるようになりました。

Tenant カスタムリソースのデプロイ

デプロイされた Tenant CR を削除するには、リソース定義が含まれるファイルの名前を指定します。以下はその例です。 

$ oc delete -f mytenant.yaml
Copy to Clipboard Toggle word wrap

または、oc delete コマンドを実行して Tenant CR に名前を指定し、テナントの namespace を指定することもできます。以下に例を示します。 

$ oc delete tenant.capabilities.3scale.net mytenant -n mynamespace
Copy to Clipboard Toggle word wrap

テナントを削除すると、3scale Operator は以下を行います。

  • 3scale インストール環境からテナントを非表示にする。
  • テナントが所有するデプロイ済みのカスタムリソースを削除する。
  • 15 日後に削除するテナントをマークする。

テナントの削除後に復元することはできません。15 日の間に、テナントが所有するリソースをすべてバックアップしてください。この操作は、管理ポータルでのみ実行できます。3scale は 15 日後にテナントを削除します。データ保護法に準拠するために、今後の参照用に一部のデータが保持されます。

重要

Tenant CR を使用してテナントをデプロイした場合は、管理ポータルでテナントを削除しないでください。これを実行する場合に、Operator は削除しようとしているテナントの CR を使用して別のテナントを作成します。

関連情報

7.13. カスタムリソースのデプロイによる 3scale API Management 開発者の管理
リンクのコピー

3scale の管理者は、カスタムリソース (CR) を使用して、個別の開発者ユーザーをグループ化する開発者アカウントをデプロイすることができます。これらのアカウントにより、開発者ポータルで 3scale が管理する API への開発者アクセスを整理および管理できます。

テナントには、任意の数の開発者アカウントを含めることができ、各開発者アカウントは必ず 1 つのテナントにリンクされます。開発者アカウントには、任意の数の開発者ユーザーを含めることができ、各開発者ユーザーは 1 つの開発者アカウントにリンクします。テナントプランは、作成できる開発者アカウントの数と、各開発者アカウントにグループ化できる開発者ユーザーの数の制限を決定します。

開発者カスタムリソースを使用するには、3scale が 3scale Operator によってインストールされている必要があります。開発者カスタムリソースは、3scale Operator が含まれる namespace にのみデプロイできます。開発者カスタムリソースのデプロイは、別の開発者の管理方法で、3scale 管理ポータルまたは 3scale 内部 API を使用します。

重要

カスタムリソースをデプロイして開発者アカウントまたは開発者ユーザーを作成する場合、管理ポータルまたは内部 3scaleAPI を使用してそれらの開発者アカウントまたは開発者ユーザーを更新することはできません。開発者 CR をデプロイした後、管理ポータルの アカウント ページに新しい開発者アカウントまたは新しい開発者ユーザーが表示されるため、注意することが重要となります。管理ポータルまたは API を使用して CR でデプロイされた開発者アカウントまたは開発者ユーザーを更新しようとすると、3scale Operator はデプロイされた CR を反映するために変更を元に戻します。これは、今後のリリースで削除される予定の制限です。ただし、管理ポータルまたは API を使用して、CR をデプロイして作成した開発者アカウントまたは開発者ユーザーを削除することができます。

7.13.1. 前提条件
リンクのコピー

  • 3scale が 3scale Operator によってインストールされている。
  • Account Management API スコープの読み取りおよび書き込み権限を持つアクセストークン (3scale の管理者権限が提供される)

3scale Operator を使用して 3scale をインストールする場合は、DeveloperAccount および DeveloperUser カスタムリソース (CR) をデプロイできます。これらのカスタムリソースを使用して、開発者ポータルで 3scale が管理する API に開発者がアクセスするためのアカウントを作成および更新できます。

新規の DeveloperAccount CR をデプロイするには、admin ロールを持つユーザーの DeveloperUser CR もデプロイする必要があります。ここで提供される手順は、新規 DeveloperAccount CR をデプロイするためのものです。DeveloperAccount CR のデプロイ後、更新または削除する手順は他の CR と同じです。

カスタムリソースは、3scale Operator が含まれる namespace にのみデプロイできます。

前提条件

  • 3scale API Management Operator がカスタムリソースのリンク先となるテナントを識別する方法 を理解している。

  • 同じ namespace にある 3scale インスタンスのデフォルトのテナントにリンクしない DeveloperAccount CR を作成する場合、DeveloperAccount CR が含まれる namespace には、DeveloperAccount CR がリンクするテナントを特定するシークレットが含まれる。シークレットの名前は以下のいずれかになります。

    • threescale-provider-account
    • ユーザー定義

    このシークレットには、3scale インスタンスの URL と、3scale インスタンスの 1 つのテナントにアクセスするためのクレデンシャルが含まれるトークンが含まれます。

  • 新規 DeveloperAccount CR の admin ロールを持つ少なくとも 1 人の開発者ユーザーのユーザー名、パスワード、およびメールアドレスを持っている。

手順

  1. 3scale Operator が含まれる namespace で、新しい開発者アカウントリソースで admin ロールを持つ開発者ユーザーのユーザー名とパスワードが含まれるシークレットを定義するリソースファイルを作成して保存します。たとえば、myusername01.yaml ファイルには以下が含まれます。 

    apiVersion: v1
kind: Secret
metadata:
  name: myusername01
stringData:
  password: "123456"
    Copy to Clipboard Toggle word wrap

  2. シークレットを作成します。以下に例を示します。 

    $ oc create -f myusername01.yaml
    Copy to Clipboard Toggle word wrap

    この例では、出力は以下のようになります。 

    $ secret/myusername01 created
    Copy to Clipboard Toggle word wrap

  3. admin ロールを持つ開発者の DeveloperUser CR を定義する a .yaml ファイルを作成し、保存します。3scale Operator が新規 DeveloperAccount CR をデプロイするには、この DeveloperUser CR が必要です。たとえば、developeruser01.yaml ファイルには以下が含まれる場合があります。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: DeveloperUser
metadata:
  name: developeruser01
spec:
  username: myusername01
  email: myusername01@example.com
  passwordCredentialsRef:
    name: myusername01
  role: admin
  developerAccountRef:
    name: developeraccount1
  providerAccountRef:
    name: mytenant
    Copy to Clipboard Toggle word wrap

    DeveloperUser CR では:

    • 開発者ユーザーのアカウント名、ユーザー名、および電子メールは、含んでいる DeveloperAccount のリンク先のテナントで一意である必要があります。
    • ここで指定する開発者アカウント名は、この手順でデプロイする DeveloperAccount CR の名前に一致する必要があります。DeveloperAccount CR の作成は、この DeveloperUser CR を作成する前でも後でもかまいません。
    • DeveloperUser CR がリンクするテナントは、指定された DeveloperAccount CR リンク先と同じテナントである必要があります。

  4. 定義したばかりのリソースを作成します。以下に例を示します。 

    $ oc create -f developeruser01.yaml
    Copy to Clipboard Toggle word wrap

    この例では、出力は以下のようになります。 

    $ developeruser.capabilities.3scale.net/developeruser01 created
    Copy to Clipboard Toggle word wrap

  5. DeveloperAccount CR を定義する .yaml ファイルを作成および保存します。この .yaml ファイルでは、spec.OrgName フィールドは組織名を指定する必要があります。たとえば、developeraccount01.yaml ファイルには以下が含まれる場合があります。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: DeveloperAccount
metadata:
  name: developeraccount01
spec:
  orgName: Ecorp
  providerAccountRef:
    name: mytenant
    Copy to Clipboard Toggle word wrap

  6. 定義したばかりのリソースを作成します。以下に例を示します。 

    $ oc create -f developeraccount01.yaml
    Copy to Clipboard Toggle word wrap

    この例では、出力は以下のようになります。 

    $ developeraccount.capabilities.3scale.net/developeraccount01 created
    Copy to Clipboard Toggle word wrap

次のステップ

3scale Operator が 3scale 設定を更新して、新規または更新されたカスタムリソースを反映するには、数秒かかります。Operator がカスタムリソース情報を正常に伝搬しているか確認するには、DeveloperAccount CR の status フィールドを確認するか、以下のように oc wait コマンドを実行します。 

$ oc wait --for=condition=Ready --timeout=30s developeraccount/developeraccount1
Copy to Clipboard Toggle word wrap

失敗した場合、カスタムリソースの status フィールドは、エラーが一時的または永続的であるかどうかを示し、問題の修正に役立つエラーメッセージを提供します。

新しい開発者ユーザーに、開発者ポータルにログインできることを通知します。また、ログインクレデンシャルを伝える必要がある場合もあります。

他のカスタムリソースを更新するのと同じ方法で、デプロイされた DeveloperAccount CR を更新できます。たとえば、更新する DeveloperAccount CR を所有するテナントを含む OpenShift プロジェクトでは、次のコマンドを実行して devaccount1 CR を更新します。 

$ oc edit developeraccount devaccount1
Copy to Clipboard Toggle word wrap

7.13.3. DeveloperUser カスタムリソースのデプロイによる 3scale API Management 開発者ユーザーの管理
リンクのコピー

3scale Operator を使用して 3scale をインストールする場合、Developer Portal で 3scale 管理の API への開発者アクセスを管理するために、DeveloperUser カスタムリソース (CR) をデプロイできます。ここで提供される手順は、新規 DeveloperUser CR をデプロイするためのものです。DeveloperUser CR のデプロイ後、更新または削除する手順は他の CR と同じです。

CR は 3scale Operator が含まれる namespace にのみデプロイできます。

前提条件

  • 3scale Operator がカスタムリソースのリンク先となるテナントを識別する方法 を理解している。

  • admin ロールを持つユーザー用に、デプロイされた DeveloperUser CR が少なくとも 1 つ含まれる DeveloperAccount CR が少なくとも 1 つデプロイされている。同じ namespace にある 3scale インスタンスのデフォルトのテナントにリンクしない DeveloperUser CR を作成する場合、DeveloperUser CR が含まれる namespace には、DeveloperUser CR がリンクするテナントを特定するシークレットを含める。シークレットの名前は以下のいずれかになります。

    • threescale-provider-account
    • ユーザー定義

    このシークレットには、3scale インスタンスの URL と、3scale インスタンスの 1 つのテナントにアクセスするためのクレデンシャルが含まれるトークンが含まれます。

  • 新しい DeveloperUser CR の場合、その開発者のユーザー名、パスワード、およびメールアドレスを持っている。

手順

  1. 3scale Operator が含まれる namespace で、開発者ユーザーのユーザー名とパスワードが含まれるシークレットを定義するリソースファイルを作成し、保存します。たとえば、myusername02.yaml ファイルには以下が含まれます。 

    apiVersion: v1
kind: Secret
metadata:
  name: myusername02
stringData:
  password: "987654321"
    Copy to Clipboard Toggle word wrap

  2. シークレットを作成します。以下に例を示します。 

    $ oc create -f myusername02.yaml
    Copy to Clipboard Toggle word wrap

    この例では、出力は以下のようになります。 

    $ secret/myusername02 created
    Copy to Clipboard Toggle word wrap

  3. DeveloperUser CR を定義する .yaml ファイルを作成および保存します。spec.role フィールドには admin または member を指定します。たとえば、developeruser02.yaml ファイルには以下が含まれる場合があります。 

    apiVersion: capabilities.3scale.net/v1beta1
kind: DeveloperUser
metadata:
  name: developeruser02
spec:
  username: myusername02
  email: myusername02@example.com
  passwordCredentialsRef:
    name: myusername02
  role: member
  developerAccountRef:
    name: developeraccount1
  providerAccountRef:
    name: mytenant
    Copy to Clipboard Toggle word wrap

    DeveloperUser CR では:

    • 開発者ユーザー名 (metadata.name フィールドで指定)、ユーザー名、およびメールは、それを含む DeveloperAccount がリンクされているテナント内で一意である必要があります。
    • developerAccountRef フィールドには、デプロイされた DeveloperAccount CR の名前を指定する必要があります。
    • DeveloperUser CR がリンクするテナントは、指定された DeveloperAccount CR リンク先と同じテナントである必要があります。

  4. 定義したばかりのリソースを作成します。以下に例を示します。 

    $ oc create -f developefuser02.yaml
    Copy to Clipboard Toggle word wrap

    この例では、出力は以下のようになります。 

    $ developeruser.capabilities.3scale.net/developeruser02 created
    Copy to Clipboard Toggle word wrap

次のステップ

3scale Operator が 3scale 設定を更新して、新規または更新されたカスタムリソースを反映するには、数秒かかります。Operator がカスタムリソース情報を正常に伝搬しているか確認するには、DeveloperUser CR の status フィールドを確認するか、以下のように oc wait コマンドを実行します。 

$ oc wait --for=condition=Ready --timeout=30s developeruser/developeruser02
Copy to Clipboard Toggle word wrap

失敗した場合、カスタムリソースの status フィールドは、エラーが一時的または永続的であるかどうかを示し、問題の修正に役立つエラーメッセージを提供します。

新しい開発者ユーザーに、開発者ポータルにログインできることを通知します。また、ログインクレデンシャルを伝える必要がある場合もあります。

他のカスタムリソースを更新するのと同じ方法で、デプロイされた DeveloperUser CR を更新できます。

7.13.4. DeveloperAccount または DeveloperUser カスタムリソースの削除
リンクのコピー

3scale 開発者エンティティーを削除するには、管理するカスタムリソース (CR) を削除します。DeveloperAccount CR を削除すると、3scale Operator は、削除された DeveloperAccount CR にリンクするすべての DeveloperUser CR も削除します。

重要

カスタムリソースによって定義された開発者アカウントまたは開発者ユーザーを削除する唯一の方法は、ここで説明する手順に従うことです。管理ポータルまたは 3scale API を使用して、カスタムリソースとしてデプロイされた開発者エンティティーを削除しないでください。

前提条件

  • 削除するカスタムリソースが含まれる namespace の削除パーミッションが指定された 3scale 管理者権限または OpenShift ロール。特定のカスタムリソースを削除できることを確認するには、oc auth can-i delete コマンドを実行します。たとえば、DeveloperAccount CR の名前が devaccount1 の場合は、次のコマンドを実行します。 

    $ oc auth can-i delete developeraccount.capabilities.3scale.net/devaccount1 -n my-namespace
    Copy to Clipboard Toggle word wrap
  • 削除する DeveloperAccount または DeveloperUser CR は、有効なテナントにリンクしています。

手順

  • カスタムリソースがリンクするテナントを含む OpenShift プロジェクトで、oc delete コマンドを実行して、DeveloperAccount または DeveloperUser CR を削除します。たとえば、devaccount1.yaml ファイルで定義された DeveloperAccount CR をデプロイした場合は、次のコマンドを実行します。 

    $ oc delete -f devaccount1.yaml
    Copy to Clipboard Toggle word wrap

    または、oc delete コマンドを実行して、定義で指定した CR の名前を指定します。以下に例を示します。 

    $ oc delete developeraccount.capabilities.3scale.net/devaccount1
    Copy to Clipboard Toggle word wrap

7.14. 3scale API Management Operator の機能の制限
リンクのコピー

Red Hat 3scale API Management 2.14 では、3scale operator には機能に関する以下の制限があります。

  • 管理ポータルの Single Sign-On (SSO) 認証。
  • デベロッパーポータルの SSO 認証。
  • OAS3 を保持する 3scale Operator CRD は、3scale プロダクト設定の信頼できるソースとして参照しません。

7.15. 関連情報
リンクのコピー

詳細は、以下のガイドを参照してください。

第8章 3scale API Management のバックアップおよび復元
リンクのコピー

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

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

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

8.1. 前提条件
リンクのコピー

  • 3scale 2.14 インスタンス。3scale のインストール方法は、OpenShift への 3scale API Management のインストール を参照してください。

  • OpenShift クラスターの以下のいずれかのロールを持つ OpenShift Container Platform 4 ユーザーアカウント。

    • cluster-admin
    • admin
    • edit
注記

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

以下には、永続データのバックアップ手順を設定し、永続データのバックアップから復元を実行する方法に関する情報が含まれています。MySQL データベースの 1 つまたは複数に障害が発生した場合に、3scale を以前の稼働状態に正しく復元することができます。

8.2. 永続ボリュームおよび考慮事項
リンクのコピー

永続ボリューム

OpenShift 上の 3scale API Management デプロイメント の場合:

  • ベースとなるインフラストラクチャーによってクラスターに提供される永続ボリューム (PV)
  • クラスター外のストレージサービス。これは、同じデータセンターまたは別のデータセンターに配置することができます。

留意事項

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

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

8.3. データセットの使用
リンクのコピー

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

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

Expand
名前説明

system-mysql

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

system-storage

ファイル用のボリューム

backend-redis

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

system-redis

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

8.3.1. system-mysql の定義
リンクのコピー

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

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

8.3.2. system-storage の定義
リンクのコピー

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

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

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

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

8.3.3. backend-redis の定義
リンクのコピー

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

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

8.3.4. system-redis の定義
リンクのコピー

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

8.4. システムデータベースのバックアップ
リンクのコピー

以下のコマンドを実行する順序に指定はありませんが、システムデータベースをバックアップしてアーカイブする場合に、必要に応じて使用することができます。

8.4.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
Copy to Clipboard Toggle word wrap

8.4.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
Copy to Clipboard Toggle word wrap

8.4.3. backend-redis のバックアップ
リンクのコピー

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

$ 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
Copy to Clipboard Toggle word wrap

8.4.4. system-redis のバックアップ
リンクのコピー

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

$ 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
Copy to Clipboard Toggle word wrap

8.4.5. zync-database のバックアップ
リンクのコピー

zync_production データベースをバックアップします。 

$ oc rsh $(oc get pods -l 'deploymentConfig=zync-database' -o json | jq -r '.items[0].metadata.name') bash -c 'pg_dump zync_production' | gzip > zync-database-backup.gz
Copy to Clipboard Toggle word wrap

8.4.6. OpenShift シークレットおよび ConfigMap のバックアップ
リンクのコピー

OpenShift シークレットおよび ConfigMap のコマンドリストを以下に示します。

8.4.6.1. OpenShift シークレット
リンクのコピー
$ oc get secrets system-smtp -o json > system-smtp.json
$ oc get secrets system-seed -o json > system-seed.json
$ oc get secrets system-database -o json > system-database.json
$ oc get secrets backend-internal-api -o json > backend-internal-api.json
$ oc get secrets system-events-hook -o json > system-events-hook.json
$ oc get secrets system-app -o json > system-app.json
$ oc get secrets system-recaptcha -o json > system-recaptcha.json
$ oc get secrets system-redis -o json > system-redis.json
$ oc get secrets zync -o json > zync.json
$ oc get secrets system-master-apicast -o json > system-master-apicast.json
Copy to Clipboard Toggle word wrap
8.4.6.2. ConfigMaps
リンクのコピー
$ oc get configmaps system-environment -o json > system-environment.json
$ oc get configmaps apicast-environment -o json > apicast-environment.json
Copy to Clipboard Toggle word wrap

8.5. システムデータベースの復元
リンクのコピー

重要

system-app のような Pod をスケールダウンしたり、ルートを無効にしたりして、レコードが作成されないようにします。

以下のコマンドとスニペットの例では、${DEPLOYMENT_NAME} を 3scale デプロイメントの作成時に定義した名前に置き換えます。

注記

出力に少なくとも中括弧 {} のペアが含まれており、空でないことを確認してください。

手順

  1. 後でスケールアップできるように、現在のレプリカ数を保存します。 

    SYSTEM_SPEC=`oc get APIManager/${DEPLOYMENT_NAME} -o jsonpath='{.spec.system.appSpec}'`
    Copy to Clipboard Toggle word wrap

  2. 前のコマンドの結果を確認し、$SYSTEM_SPEC の内容を確認します。 

    echo $SYSTEM_SPEC
    Copy to Clipboard Toggle word wrap

  3. レプリカの数を 0 にスケールする次のコマンドを使用して、APIManager CR にパッチを適用します。 

    $ oc patch APIManager/${DEPLOYMENT_NAME} --type merge -p '{"spec": {"system": {"appSpec": {"replicas": 0}}}}'
    Copy to Clipboard Toggle word wrap

    あるいは、system-app をスケールダウンするには、次の例に示すように、既存の APIManager/${DEPLOMENT_NAME} を編集し、システムレプリカの数を 0 に設定します。 

    apiVersion: apps.3scale.net/v1alpha1
kind: APIManager
metadata:
  name: <DEPLOYMENT_NAME>
spec:
  system:
    appSpec:
       replicas: 0
    Copy to Clipboard Toggle word wrap

OpenShift シークレットおよびシステムデータベースを復元するには、以下の手順を使用します。

8.5.1. Operator ベースのデプロイメントの復元
リンクのコピー

Operator ベースのデプロイメントを復元するには、以下の手順に従います。

手順

  1. OpenShift に 3scale API Management Operator をインストールします。

  2. APIManager リソースを作成する前に、シークレットを復元します。 

    $ oc apply -f system-smtp.json
$ oc apply -f system-seed.json
$ oc apply -f system-database.json
$ oc apply -f backend-internal-api.json
$ oc apply -f system-events-hook.json
$ oc apply -f system-app.json
$ oc apply -f system-recaptcha.json
$ oc apply -f system-redis.json
$ oc apply -f zync.json
$ oc apply -f system-master-apicast.json
    Copy to Clipboard Toggle word wrap

  3. APIManager リソースを作成する前に、ConfigMaps を復元します。 

    $ oc apply -f system-environment.json
$ oc apply -f apicast-environment.json
    Copy to Clipboard Toggle word wrap
  4. APIManager CR を使用して、Operator で 3scale API Management をデプロイします。

8.5.2. 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
    Copy to Clipboard Toggle word wrap

  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'
    Copy to Clipboard Toggle word wrap

  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'
    Copy to Clipboard Toggle word wrap

8.5.3. system-storage の復元
リンクのコピー

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

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

8.5.4. zync-database の復元
リンクのコピー

3scale Operator デプロイメントの zync-database を復元する手順。

8.5.4.1. Operator ベースのデプロイメント
リンクのコピー
注記

Operator を使用した 3scale API Management のデプロイ (特に APIManager CR のデプロイ) に記載の手順に従って、3scale インスタンスを再デプロイしてください。

手順

  1. ${DEPLOYMENT_NAME} を 3scale デプロイメントの作成時に定義した名前に置き換えて、レプリカ数を保存します。 

    ZYNC_SPEC=`oc get APIManager/${DEPLOYMENT_NAME} -o json | jq -r '.spec.zync'`
    Copy to Clipboard Toggle word wrap

  2. zync DeploymentConfig を 0 Pod にスケールダウンします。 

    $ oc patch APIManager/${DEPLOYMENT_NAME} --type merge -p '{"spec": {"zync": {"appSpec": {"replicas": 0}, "queSpec": {"replicas": 0}}}}'
    Copy to Clipboard Toggle word wrap

  3. 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/
    Copy to Clipboard Toggle word wrap

  4. バックアップファイルをデプロイメントします。 

    $ 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'
    Copy to Clipboard Toggle word wrap

  5. zync データベースのバックアップファイルを復元します。 

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

  6. 元のレプリカ数に復元します。 

    $ oc patch APIManager/${DEPLOYMENT_NAME} --type json -p '[{"op": "replace", "path": "/spec/zync", "value":'"$ZYNC_SPEC"'}]'
    Copy to Clipboard Toggle word wrap

    • 以下のコマンドの出力に replicas キーが含まれていない場合は、 

      $ echo $ZYNC_SPEC
      Copy to Clipboard Toggle word wrap

    • 以下の追加コマンドを実行して zync をスケールアップします。 

      $ oc patch dc/zync -p '{"spec": {"replicas": 1}}'
      Copy to Clipboard Toggle word wrap
8.5.4.2. backend-redis と system-redis での 3scale API Management オプションの復元
リンクのコピー

3scale を復元することで、backend-redis と system-redis が復元されます。これらのコンポーネントには、以下の機能があります。

*backend-redis: 3scale のアプリケーション認証とレート制限をサポートするデータベース。統計ストレージおよび一時ジョブストレージにも使用されます。*system-redis: 3scale のバックグラウンドジョブの一時ストレージを提供し、system-app Pod の Ruby プロセスのメッセージバスとしても使用されます。

backend-redis コンポーネント

backend-redis コンポーネントには、data と queue の 2 つのデータベースがあります。デフォルトの 3scale デプロイメントでは、data および queues は、異なる論理データベースインデックス /0 および /1 で、Redis データベースにデプロイされます。data データベースの復元は問題なく実行されますが、queues データベースを復元すると、ジョブが重複してしまう可能性があります。

ジョブの重複に関して、3scale ではバックエンドワーカーがバックグラウンドジョブを処理します (ミリ秒単位)。最後のデータベーススナップショットの 30 秒後に backend-redis が失敗し、そのスナップショットを復元しようとすると、バックエンドには重複を防ぐためのシステムがないため、30 秒の間に発生したバックグラウンドジョブは 2 回実行されます。

このシナリオでは、/0 データベースインデックスにその他の場所に保存されないデータが含まれているため、バックアップを復元する必要があります。/0 データベースインデックスを復元すると、/1 データベースインデックスを復元する必要もあります。どちらか 1 つだけを復元することはできません。異なるインデックスの 1 つのデータベースではなく、異なるサーバー上のデータベースを分離することを選択した場合、キューのサイズはほぼゼロになるため、バックアップを復元せず、いくつかのバックグラウンドジョブを失うことが望ましくなります。これは、3scale のホスト型設定の場合であるため、両方に異なるバックアップおよび復元ストラテジーを適用する必要があります。

`system-redis` コンポーネント

3scale システムのバックグラウンドジョブの大半はべき等です。つまり、実行する回数に関係なく、同じリクエストが同じ結果を返します。

以下は、システムのバックグラウンドジョブによって処理されるイベントの例のリストです。

  • プランの試用期間の有効期限がまもなく切れる、クレジットカードの有効期限がまもなく切れる、アクティベーションのリマインダー、プランの変更、請求書の状態の変更、PDF レポートなどの通知ジョブ。
  • インボイスや課金などの請求。
  • 複雑なオブジェクトの削除。
  • バックエンド同期ジョブ。
  • たとえば searchd を使用したインデックス作成ジョブ。
  • 請求書 ID などのサニタイゼーションジョブ。
  • 監査、ユーザーセッション、期限切れのトークン、ログエントリーのパージ、非アクティブなアカウントを一時停止するなどの管理タスク。
  • トラフィックの更新。
  • プロキシーの設定変更の監視およびプロキシーのデプロイメント。
  • バックグラウンドのサインアップジョブ。
  • シングルサインオン (SSO) の同期、ルート作成などの Zync ジョブ。

上記のバックグラウンドジョブのリストを復元する場合には、3scale のシステムは復元された各ジョブの状態を維持します。復元の完了後にシステムの整合性を確認することが重要です。

8.5.5. バックエンドとシステム間における情報の一貫性の確保
リンクのコピー

backend-redis の復元後、system からの Config 情報を強制的に同期させ、backend の情報と 信頼できるソース である system の情報の一貫性を確保する必要があります。

8.5.5.1. backend-redis のデプロイメント設定の管理
リンクのコピー

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

手順

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

    $ oc edit configmap redis-config
    Copy to Clipboard Toggle word wrap

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

     #save 900 1
 #save 300 10
 #save 60 10000
    Copy to Clipboard Toggle word wrap

  3. redis-config configmap の appendonly を no に設定します。 

    appendonly no
    Copy to Clipboard Toggle word wrap

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

    $ oc rollout latest dc/backend-redis
    Copy to Clipboard Toggle word wrap

  5. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。 

    $ oc rollout status dc/backend-redis
    Copy to Clipboard Toggle word wrap

  6. dump.rdb ファイルの名前を変更します。 

    $ 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'
    Copy to Clipboard Toggle word wrap

  7. 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'
    Copy to Clipboard Toggle word wrap

  8. バックアップファイルを 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
    Copy to Clipboard Toggle word wrap

  9. backend-redis を再デプロイして、バックアップを読み込みます。 

    $ oc rollout latest dc/backend-redis
    Copy to Clipboard Toggle word wrap

  10. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。 

    $ oc rollout status dc/backend-redis
    Copy to Clipboard Toggle word wrap

  11. appendonly ファイルを作成します。 

    $ oc rsh $(oc get pods -l 'deploymentConfig=backend-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'redis-cli BGREWRITEAOF'
    Copy to Clipboard Toggle word wrap

  12. しばらくしてから、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
    Copy to Clipboard Toggle word wrap
    • aof_rewrite_in_progress = 1 の間は、実行は進行中です。
    • aof_rewrite_in_progress = 0 となるまで、定期的に確認します。ゼロは実行が完了したことを示します。

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

    $ oc edit configmap redis-config
    Copy to Clipboard Toggle word wrap

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

     save 900 1
 save 300 10
 save 60 10000
    Copy to Clipboard Toggle word wrap

  15. redis-config configmap の appendonly を yes に設定します。 

    appendonly yes
    Copy to Clipboard Toggle word wrap

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

    $ oc rollout latest dc/backend-redis
    Copy to Clipboard Toggle word wrap

  17. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。 

    $ oc rollout status dc/backend-redis
    Copy to Clipboard Toggle word wrap
8.5.5.2. system-redis のデプロイメント設定の管理
リンクのコピー

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

手順

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

    $ oc edit configmap redis-config
    Copy to Clipboard Toggle word wrap

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

     #save 900 1
 #save 300 10
 #save 60 10000
    Copy to Clipboard Toggle word wrap

  3. redis-config configmap の appendonly を no に設定します。 

    appendonly no
    Copy to Clipboard Toggle word wrap

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

    $ oc rollout latest dc/system-redis
    Copy to Clipboard Toggle word wrap

  5. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。 

    $ oc rollout status dc/system-redis
    Copy to Clipboard Toggle word wrap

  6. dump.rdb ファイルの名前を変更します。 

    $ 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'
    Copy to Clipboard Toggle word wrap

  7. 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'
    Copy to Clipboard Toggle word wrap

  8. バックアップ ファイルを 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
    Copy to Clipboard Toggle word wrap

  9. system-redis を再デプロイして、バックアップを読み込みます。 

    $ oc rollout latest dc/system-redis
    Copy to Clipboard Toggle word wrap

  10. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。 

    $ oc rollout status dc/system-redis
    Copy to Clipboard Toggle word wrap

  11. appendonly ファイルを作成します。 

    $ oc rsh $(oc get pods -l 'deploymentConfig=system-redis' -o json | jq '.items[0].metadata.name' -r) bash -c 'redis-cli BGREWRITEAOF'
    Copy to Clipboard Toggle word wrap

  12. しばらくしてから、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
    Copy to Clipboard Toggle word wrap
    • aof_rewrite_in_progress = 1 の間は、実行は進行中です。
    • aof_rewrite_in_progress = 0 となるまで、定期的に確認します。ゼロは実行が完了したことを示します。

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

    $ oc edit configmap redis-config
    Copy to Clipboard Toggle word wrap

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

     save 900 1
 save 300 10
 save 60 10000
    Copy to Clipboard Toggle word wrap

  15. redis-config configmap の appendonly を yes に設定します。 

    appendonly yes
    Copy to Clipboard Toggle word wrap

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

    $ oc rollout latest dc/system-redis
    Copy to Clipboard Toggle word wrap

  17. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。 

    $ oc rollout status dc/system-redis
    Copy to Clipboard Toggle word wrap

8.5.6. backend-worker の復元
リンクのコピー

これらの手順は、backend-worker を復元することを目的としています。

手順

  1. 最新バージョンの backend-worker に復元します。 

    $ oc rollout latest dc/backend-worker
    Copy to Clipboard Toggle word wrap

  2. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。 

    $ oc rollout status dc/backend-worker
    Copy to Clipboard Toggle word wrap

8.5.7. system-app の復元
リンクのコピー

これらの手順は、system-app を復元することを目的としています。

手順

  1. system-app をスケールアップするには、既存の APIManager/${DEPLOYMENT_NAME} を編集して、.spec.system.appSpec.replicas を元のレプリカ数に戻すか、次のコマンドを実行して、以前に保存された仕様を適用します。 

    $ oc patch APIManager/${DEPLOYMENT_NAME} --type json -p '[{"op": "replace", "path": "/spec/system/appSpec", "value":'"$SYSTEM_SPEC"'}]'
    Copy to Clipboard Toggle word wrap

    • 以下のコマンドの出力に replicas キーが含まれていない場合は、 

      $ echo $SYSTEM_SPEC
      Copy to Clipboard Toggle word wrap

    • 以下の追加コマンドを実行して system-app をスケールアップします。 

      $ oc patch dc/system-app -p '{"spec": {"replicas": 1}}'
      Copy to Clipboard Toggle word wrap

  2. 最新バージョンの system-app に復元します。 

    $ oc rollout latest dc/system-app
    Copy to Clipboard Toggle word wrap

  3. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。 

    $ oc rollout status dc/system-app
    Copy to Clipboard Toggle word wrap

8.5.8. system-sidekiq の復元
リンクのコピー

これらの手順は、system-sidekiq を復元することを目的としています。

手順

  1. 最新バージョンの system-sidekiq に復元します。 

    $ oc rollout latest dc/system-sidekiq
    Copy to Clipboard Toggle word wrap

  2. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。 

    $ oc rollout status dc/system-sidekiq
    Copy to Clipboard Toggle word wrap
8.5.8.1. system-searchd の復元
リンクのコピー

これらの手順は、system-searchd を復元することを目的としています。

手順

  1. 最新バージョンの system-searchd に復元します。 

    $ oc rollout latest dc/system-searchd
    Copy to Clipboard Toggle word wrap

  2. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。 

    $ oc rollout status dc/system-searchd
    Copy to Clipboard Toggle word wrap
8.5.8.2. zync が管理する OpenShift ルートの復元
リンクのコピー

  • 不足している OpenShift ルートを再作成するように zync に強制します。 

    $ oc rsh $(oc get pods -l 'deploymentConfig=system-sidekiq' -o json | jq '.items[0].metadata.name' -r) bash -c 'bundle exec rake zync:resync:domains'
    Copy to Clipboard Toggle word wrap

第9章 3scale API Management 用 reCAPTCHA の設定
リンクのコピー

この章では、オンプレミス型 Red Hat 3scale API Management に reCAPTCHA を設定して、スパムから保護する方法を説明します。

前提条件

  • サポート対象バージョンの OpenShift にインストールされた設定済みのオンプレミス型 3scale インスタンス。
  • reCAPTCHA v2 のサイトキーと秘密鍵を取得している。新しいサイトを登録する の Web ページを参照してください。
  • ドメイン名の検証を使用する場合は、デベロッパーポータルのドメインを許可リストに追加する。

3scale に reCAPTCHA を設定するには、以下の手順に概略を示すステップを実施します。

9.1. 3scale API Management のスパム保護用 reCAPTCHA の設定
リンクのコピー

スパム保護に reCAPTCHA を設定するには、2 種類の方法で reCAPTCHA が含まれるシークレットファイルにパッチを適用します。これらのオプションには、OpenShift Container Platform (OCP) ユーザーインターフェイスまたはコマンドラインインターフェイス (CLI) を使用します。

手順

  1. OCP 4.x: Project: [Your_project_name] > Workloads > Secrets に移動します。

  2. system-recaptcha シークレットファイルを編集します。

    reCAPTHCA サービスからの PRIVATE_KEY および PUBLIC_KEY は、base64 フォーマットでエンコーディングされている必要があります。鍵を base64 エンコーディングに手動で変換します。

注記

CLI の reCAPTCHA オプションでは、base64 フォーマットのエンコードは必要ありません。

  • CLI: 以下のコマンドを入力します。 

    $ oc patch secret/system-recaptcha -p '{"stringData": {"PUBLIC_KEY": "public-key-from-service", "PRIVATE_KEY": "private-key-from-service"}}'
    Copy to Clipboard Toggle word wrap

手順後のステップ

  • 上記のいずれかのオプションが完了したら、システム Pod を再デプロイします。

  • 3scale 管理ポータルでは、署名されていないユーザーに対するスパム保護を有効にします。

    1. Audience > Developer Portal > Spam Protection の順に移動します。

    2. 以下のオプションのいずれかを選択します。

      • Always

        ログインしていないユーザーにフォームが表示されると、必ず reCAPTCHA が表示されます。

      • Suspicious only

        自動チェックでスパムの可能性が検出された場合にのみ、reCAPTCHA が表示されます。

      • Never

        Spam 保護をオフにします。

system-app が再デプロイされると、デベロッパーポータルのスパム保護が使用されるページには、reCAPTCHA の I'm not a robot チェックボックスが表示されます。

I'm not a robot
View larger image
I'm not a robot

関連情報

  • 詳細、ガイド、およびサポートは、ReCAPTCHA のホームページを参照してください。

第10章 3scale API Management WebAssembly モジュール
リンクのコピー

threescale-wasm-auth モジュールは、Service Mesh にプラグインされ、Red Hat 3scale API Management を使用して受信リクエストを承認できるようにする WebAssembly モジュールです。Service Mesh の機能を拡張し、マイクロサービスの認証、分析、課金などの完全な API 管理機能を提供します。

Service Mesh は、トラフィック管理、サービス検出、負荷分散、セキュリティーなどの機能を備えたインフラストラクチャー層に焦点を当てています。API 管理は、API の作成、公開、管理に重点を置いています。

Service Mesh と 3scale を組み合わせることで、マイクロサービスと API の信頼性、スケーラビリティー、セキュリティー、パフォーマンスを向上させることができます。

注記

threescale-wasm-auth モジュールは、3scale 2.11 以降と Red Hat OpenShift Service Mesh 2.1.0 以降のインテグレーションで実行されます。

前提条件

OpenShift Container Platform (OCP) のクラスター管理者は、WasmPlugin カスタムリソースを介して 3scale への HTTP リクエストを承認するように threescale-wasm-auth モジュールを設定できます。次に、Service Mesh はモジュールをサイドカーに注入してホストサービスを公開し、モジュールを使用してプロキシーリクエストを処理できるようにします。

3scale の観点から見ると、threescale-wasm-auth モジュールはゲートウェイとして機能し、Service Mesh と統合するときに APIcast を置き換えます。これは、一部の APIcast 機能、特にポリシー、ステージング環境、実稼働環境が使用できないことを意味します。

10.1. Bookinfo アプリケーションを Service Mesh にデプロイする
リンクのコピー

Service Mesh のサンプル Bookinfo アプリケーションを使用して、3scale で Service Mesh を設定する手順をデモンストレーションできます。

手順

  1. Bookinfo アプリケーションをデプロイします。

  2. アプリケーションが利用可能であることを確認します。 

    $ export GATEWAY_URL=$(oc -n istio-system get route istio-ingressgateway -o jsonpath='{.spec.host}')

$ curl -I "http://$GATEWAY_URL/productpage"
HTTP/1.1 200 OK
    Copy to Clipboard Toggle word wrap

10.2. 3scale API Management での製品の作成
リンクのコピー

製品とは、バックエンドと呼ばれる複数の内部 API をリダイレクトまたは使用できる顧客向け API のことです。Service Mesh で 3scale を使用する場合、バックエンドは使用されません。製品とプライベートベース URL 間のリンクは、メッシュ内に作成されます。このため、必要なのは製品のみです。

手順

  1. 新しい製品、アプリケーション計画、およびアプリケーションを作成します。Creating new products to test API calls を参照してください。

  2. デプロイメントを Istio に変更します。

    • [Your_product_name] > Integration > Settings の順に移動します。
    • デプロイメントを Istio に変更します。
    • Update Product をクリックして設定を更新します。

  3. 設定をプロモートします。

    • [Your_product_name] > Integration > Configuration の順に移動します。
    • 設定の更新 をクリックします。

10.3. 3scale API Management と Service Mesh の接続
リンクのコピー

重要

ServiceEntry カスタムリソース (CR) と DestinationRule CR を、service-mesh/istio-system namespace または info namespace に作成します。これは、ServiceMeshControlPlane を含む namespace に存在する必要があります。

Service Mesh から 3scale にアクセスするには、ServiceEntry CR および DestinationRule CR を通じて、テナント URL とバックエンド URL の両方を外部サービスとして設定する必要があります。これにより、threescale-wasm-auth モジュールは、リクエストの承認を処理するバックエンドと、製品設定が取得されるシステムの両方にアクセスできるようになります。

10.3.1. 3scale API Management URL を Service Mesh に追加する
リンクのコピー

ServiceEntry は Service Mesh 内からサービスへのリクエストを許可するために必要であり、DestinationRule は 3scale サービスの安全な接続を設定するためにあります。

10.3.1.1. テナント URL を Service Mesh に追加する
リンクのコピー

手順

  1. システムテナント URL を収集します。

    • これは、製品の作成に使用した 3scale 管理ポータルの URL です。

  2. システムの ServiceEntry を作成します。 

    oc apply -n <info> -f -<<EOF
apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: <service_entry_threescale_system>
spec:
  hosts:
  - <system_hostname>
  ports:
  - number: 443
    name: https
    protocol: HTTPS
  location: MESH_EXTERNAL
  resolution: DNS
EOF
    Copy to Clipboard Toggle word wrap

  3. システムの DestinationRule を作成します。 

    oc apply -n <info> -f -<<EOF
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: <destination_rule_threescale_system>
spec:
  host: <system_hostname>
  trafficPolicy:
    tls:
      mode: SIMPLE
      sni: <system_hostname>
EOF
    Copy to Clipboard Toggle word wrap

関連情報

10.4. バックエンド URL を Service Mesh に追加する
リンクのコピー

3scale バックエンド URL を Service Mesh セットアップに組み込むことで、マイクロサービスと 3scale バックエンドの間に安全な通信チャネルを確立できます。このインテグレーションにより、Service Mesh 環境で API を管理するための認証、分析、課金機能の実装が可能になります。バックエンドには、外部からは公開されたルートを使用してアクセスでき、内部的には OpenShift サービスを使用してアクセスできます。

10.4.1. Service Mesh とは別のクラスターで 3scale API Management を使用する
リンクのコピー

手順

  1. バックエンド URL を収集します。

    • 3scale Hosted の場合、バックエンド URL は su1.3scale.net です。

    • オンプレミス型 3scale の場合は、次のコマンドを使用して URL を取得します。 

      $ oc get -n <3scale_namespace> route backend --template="{{.spec.host}}"
      Copy to Clipboard Toggle word wrap

  2. バックエンドの ServiceEntry を作成します。 

    oc apply -n <info> -f -<<EOF
apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: <service_entry_threescale_backend>
spec:
  hosts:
  - <backend_hostname>
  ports:
  - number: 443
    name: https
    protocol: HTTPS
  location: MESH_EXTERNAL
  resolution: DNS
EOF
    Copy to Clipboard Toggle word wrap

  3. バックエンドの DestinationRule を作成します。 

    oc apply -n <info> -f -<<EOF
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: <destination_rule_threescale_backend>
spec:
  host: <backend_hostname>
  trafficPolicy:
    tls:
      mode: SIMPLE
      sni: <backend_hostname>
EOF
    Copy to Clipboard Toggle word wrap

10.5. Service Mesh と同じクラスターで 3scale API Management を使用する
リンクのコピー

注記

次の手順は、Service Mesh へのバックエンド URL の追加 の代替手順です。

threescale-wasm-auth module に 3scale に対するリクエストを承認させるには、モジュールが 3scale サービスにアクセスできる必要があります。これを Red Hat OpenShift Service Mesh 内で行うには、外部 ServiceEntry オブジェクトと、HTTPS プロトコルを使用する TLS 設定の対応する DestinationRule オブジェクトを適用します。

カスタムリソース (CR) は、Service Management API および Account Management API のバックエンドおよびシステムコンポーネントに対して、Service Mesh 内から 3scale への安全なアクセスのためのサービスエントリーと宛先ルールをセットアップします。Service Management API は、各リクエストの承認ステータスのクエリーを受信します。Account Management API は、サービスの API 管理設定を提供します。

手順

  1. バックエンドの ServiceEntry を作成します。 

    oc apply -n <info> -f -<<EOF
apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: <service_entry_threescale_backend>
spec:
  hosts:
  - backend-listener.<3scale_namespace>.svc.cluster.local
  ports:
  - number: 80
    name: http
    protocol: HTTP
  location: MESH_EXTERNAL
  resolution: DNS
EOF
    Copy to Clipboard Toggle word wrap

  2. バックエンドの DestinationRule を作成します。 

    oc apply -n <info> -f -<<EOF
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: <destination_rule_threescale_backend>
spec:
  host: backend-listener.<3scale_namespace>.svc.cluster.local
EOF
    Copy to Clipboard Toggle word wrap

10.6. WasmPlugin カスタムリソースの作成
リンクのコピー

Service Mesh は、WasmPlugin として知られる Proxy-WASM エクステンションを指定してサイドカープロキシーに適用するためのカスタムリソース定義 (CRD) を提供します。Service Mesh は、3scale による HTTP API 管理を必要とする一連のワークロードにカスタムリソース (CR) を適用します。

手順

  1. このモジュールを適用する Service Mesh デプロイメント上の OpenShift Container Platform (OCP) namespace (info プロジェクトなど) を特定します。

  2. registry.redhat.io 認証情報を使用してプルシークレットを取得します。

    • WasmPlugin と同じ namespace に新しいプルシークレットリソースを作成します。

  3. モジュールが適用されるアプリケーションのセットを識別するセレクターとともに、threescale-wasm-auth モジュールがデプロイされる namespace を宣言する必要があります。次の例は、threescale-wasm-auth モジュールの CR の YAML 形式です。 

    apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
 namespace: <namespace>
spec:
  url: oci://registry.redhat.io/3scale-amp2/3scale-auth-wasm-rhel8:0.0.3
  imagePullSecret: <pull_secret_resource>
  phase: AUTHZ
  priority: 100
  match:
   - mode: CLIENT
  selector:
    matchLabels:
      app: <selector>
  pluginConfig:
    api: v1
    system:
      name: system
      upstream:
        name: outbound|443||<system_host>
        url: <system_url>
        timeout: 5000
      token: <access_token>

    backend:
      name: backend
      upstream:
        name: outbound|<backend_port>||<backend_host>
        url: <backend_url>
        timeout: 5000
      extensions:
      - no_body
    services:
    - id: '<product_id>'
      authorities:
      - "*"
      credentials:
        user_key:
          - query_string:
              keys:
                - user_key
          - header:
              keys:
                - user_key
    Copy to Clipboard Toggle word wrap
    • spec.pluginConfig フィールドはアプリケーションによって異なります。その他のフィールドはすべて、このカスタムリソースの複数のインスタンス間で永続します。
    • この特定の WasmPlugin spec.pluginConfig は、クエリー文字列で提供される user_key 認証を使用して設定されています。

    • 説明:

      • name

        3scale 内における WasmPlugin の一意の名前または識別子を指定します。

      • namespace

        ワークロードの namespace。

      • imagePullSecret

        手順 2 で作成したプルシークレットの名前。

      • selector

        ワークロードラベルセレクター。info プロジェクトの製品ページをご利用ください。

      • backend-port

        使用している 3scale により異なります。3scale URL を Service Mesh に追加する を参照してください。たとえば、内部 3scale はポート 80 を使用し、外部 3scale はポート 443 を使用します。

      • backend-host と system-host

        Adding 3scale URLs to Service Mesh で使用したホストと同じホストを使用します。

      • system-url と backend-url

        それぞれのホストを使用してプロトコルを追加します。たとえば、https://<system-host> などです。

      • access-token

        システムテナントへのアクセストークン。

      • product_id

        使用するプロダクトの ID。複数の製品が必要な場合は、サービスセクションで複数の製品を定義します。

    • spec.pluginConfig および残りのカスタムリソースにモジュール設定を追加したら、oc apply コマンドでこれを適用します。 

      $ oc apply -f threescale-wasm-auth-info.yaml
      Copy to Clipboard Toggle word wrap

10.6.1. 3scale API Management WasmPlugin 認証オプション
リンクのコピー

これらは、3scale User key (App id/App key) 認証の設定例です。

ユーザーキー

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
 ...
  pluginConfig:
  ...
    services:
    - id: '<service_id>'
      authorities:
      - "*"
      credentials:
        user_key:
          - query_string:
              keys:
                - user_key
          - header:
              keys:
                - user_key
Copy to Clipboard Toggle word wrap

App ID と App key

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  ...
  pluginConfig:
    ...
    services:
    - id: '<service_id>'
      authorities:
      - "*"
      credentials:
        app_id:
          - query_string:
              keys:
                - app_id
          - header:
              keys:
                - app_id
        app_key:
          - query_string:
              keys:
                - app_key
          - header:
              keys:
                - app_key
Copy to Clipboard Toggle word wrap

OIDC

WasmPlugin 自体とは別に、OpenID Connect (OIDC) が機能するには、RequestAuthentication と呼ばれる追加のカスタムリソースも必要です。RequestAuthentication を適用すると、JWT トークンを検証するネイティブプラグインを使用して Envoy が設定されます。プロキシーは、モジュールを実行する前にすべてを検証します。したがって、失敗したリクエストが 3scale WebAssembly モジュールに実行されません。 

apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
metadata:
  name: jwt-example
  namespace: <info>
spec:
  selector:
    matchLabels:
      app: <productpage>
  jwtRules:
  - issuer: >-
      "<url>/auth/realms/<realm_name>"
    jwksUri: >-
      "<url>/auth/realms/<realm_name>/protocol/openid-connect/certs"
Copy to Clipboard Toggle word wrap

詳細

  • <url>: OIDC インスタンスの URL は、keycloak で設定されている場合、認証設定用の keycloak OIDC プロバイダーのメタデータエンドポイントを指定するために使用されます。
  • <realm_name>: OIDC で使用されるレルムの名前。 
apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  ...
  pluginConfig:
    ...
    services:
    - id: '<service_id>'
      authorities:
      - "*"
      credentials:
  app_id:
    - filter:
        path:
          - envoy.filters.http.jwt_authn
          - "0"
        keys:
          - azp
          - aud
        ops:
          - take:
              head: 1
Copy to Clipboard Toggle word wrap

関連情報

10.7. 設定された API のテスト
リンクのコピー

アプリケーションを呼び出すときに認証チェックを実行することで、API 設定の有効性を検証できます。認証メカニズムを徹底的にテストすることで、承認されたリクエストのみが処理されることを確実にし、アプリケーションのセキュリティーとインテグリティーを維持できます。

手順

  1. WasmPlugin を適用した Bookinfo アプリケーションの呼び出しを試してみます。認証が含まれていないため、拒否されるはずです。 

    $ export GATEWAY_URL=$(oc -n istio-system get route istio-ingressgateway -o jsonpath='{.spec.host}')

$ curl -I "http://$GATEWAY_URL/productpage"
HTTP/1.1 403
    Copy to Clipboard Toggle word wrap

  2. 認証用のユーザーキーを取得します。

    • [Your_product_name] > Applications > Listings に移動します。
    • アプリケーションを選択します。
    • Authentication > User Key を探します。

  3. ユーザーキーがある状態で呼び出しを再試行してください。 

    $ curl -I "http://$GATEWAY_URL/productpage?user_key=$USER_KEY"
HTTP/1.1 200 OK
    Copy to Clipboard Toggle word wrap

  4. 呼び出しがメトリクスに登録されたことを確認します。

    • [Your_product_name] > Analytics > Traffic に移動します。
    • 呼び出しが登録されていることが表示されるはずです。

10.8. 3scale API Management WebAssembly モジュール設定
リンクのコピー

WasmPlugin カスタムリソース仕様は、Proxy-WASM モジュールが読み取る設定を提供します。

仕様はホストに組み込まれ、Proxy-WASM モジュールによって読み取られます。通常は、モジュールが解析するように設定は JSON ファイル形式です。ただし、WasmPlugin リソースは仕様値を YAML として解釈し、モジュールで使用できるように JSON に変換できます。

スタンドアロンモードで Proxy-WASM モジュールを使用する場合は、JSON 形式を使用して設定を作成する必要があります。JSON 形式を使用する場合は、host 設定ファイル内の必要な場所で、エスケープと引用を使用できます (例:Envoy)。WasmPlugin リソースで WebAssembly モジュールを使用する場合、設定は YAML 形式になります。この場合は、無効な設定により、JSON 表現に基づいて診断がモジュールによって強制的にサイドカーコンテナーのロギングストリームに表示されます。

重要

EnvoyFilter カスタムリソース (CR) は一部の 3scale Istio アダプターまたは Service Mesh リリースで使用できますが、このカスタムリソースはサポートされる API ではありません。EnvoyFilter CR の使用は推奨されません。EnvoyFilter CR の代わりに WasmPlugin API を使用します。EnvoyFilter CR を使用する必要がある場合は、仕様を JSON 形式で指定する必要があります。

10.8.1. 3scale API Management WebAssembly モジュールの設定
リンクのコピー

3scale の WebAssembly モジュール設定のアーキテクチャーは、3scale アカウントおよび承認サービスや処理するサービスのリストによって異なります。

前提条件

前提条件は、すべてのケースで最小の必須フィールドのセットです。

  • 3scale アカウントおよび承認サービス:backend-listener URL。
  • 処理するサービスリスト: サービス ID と少なくとも 1 つの認証情報の検索方法、およびその検索場所。
  • userkey、appid、appkey、および OpenID Connect (OIDC) パターンを処理する例があります。
  • WebAssembly モジュールは、静的設定で指定した設定を使用します。たとえば、モジュールにマッピングルール設定を追加する場合は、3scale 管理ポータルにこのようなマッピングルールが設定されていない場合でも、常に適用されます。残りの WasmPlugin リソースは spec.pluginConfig YAML エントリーに存在します。

10.8.2. 3scale WebAssembly API Management モジュールの api オブジェクト
リンクのコピー

3scale WebAssembly モジュールからの api 最上位文字列は、モジュールが使用する設定のバージョンを定義します。

注記

存在しないバージョンまたはサポート対象外のバージョンの api オブジェクトの場合、レンダリングされた 3scale WebAssembly モジュールは操作不能になります。

api 最上位文字列の例

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
  namespace: <info>
spec:
  pluginConfig:
    api: v1
...
Copy to Clipboard Toggle word wrap

api エントリーは、設定の残りの値を定義します。許可される値は v1 のみです。現在の設定との互換性が失われるか、v1 を使用するモジュールが処理できない追加のロジックが必要な新しい設定には、別の値が必要になります。

10.8.3. 3scale API Management WebAssembly モジュールの system オブジェクト
リンクのコピー

system 最上位オブジェクトは、特定のアカウントの 3scale Account Management API にアクセスする方法を指定します。upstream フィールドは、オブジェクトの最も重要な部分です。system オブジェクトはオプションですが、3scale WebAssembly モジュールに完全に静的な設定を提供する場合を除き、推奨されます。後者は、3scale の system コンポーネントへの接続を提供しない場合のオプションです。

system オブジェクトに加えて静的設定オブジェクトを指定する場合は、静的な設定オブジェクトが優先されます。 

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    system:
      name: <saas_porta>
      upstream: <object>
      token: <my_account_token>
      ttl: 300
  ...
Copy to Clipboard Toggle word wrap
Expand
表10.1 system オブジェクトフィールド
名前説明必須

name

3scale サービスの識別子 (現在、参照されていません)。

任意

upstream

問い合わせるネットワークホストの詳細。upstream は、system として知られる 3scale Account Management API ホストを参照します。

はい

token

読み取り権限を持つ 3scale の個人アクセストークン。

はい

ttl

新規の変更を取得する前に、このホストから取得した設定を有効なものと見なす最小時間 (秒数)。デフォルトは 600 秒 (10 分) です。注記: 最大の期間はありませんが、モジュールは通常、この TTL が経過した後に妥当な時間内に設定を取得します。

任意

10.8.4. 3scale API Management WebAssembly モジュールの upstream オブジェクト
リンクのコピー

upstream オブジェクトは、プロキシーが呼び出しを実行できる外部ホストを説明しています。 

apiVersion: maistra.io/v1
upstream:
  name: outbound|443||multitenant.3scale.net
  url: "https://myaccount-admin.3scale.net/"
  timeout: 5000
...
Copy to Clipboard Toggle word wrap
Expand
表10.2 upstream オブジェクトフィールド
名前説明必須

name

name は自由形式の識別子ではありません。これは、プロキシー設定で定義される外部ホストの識別子です。スタンドアロン Envoy 設定の場合は、これは他のプロキシーの upstream とも呼ばれる クラスター 名にマッピングします。注記:Service Mesh および 3scale Istio アダプターコントロールプレーンは、複数のフィールドの区切り文字として垂直バー (|) を使用する形式に従って名前を設定します。この統合の目的上、常に outbound|<port>||<hostname> の形式を使用します。

はい

url

記述されたサービスにアクセスするための完全な URL。スキームによって暗示されていない限り、TCP ポートが含まれている必要があります。

はい

Timeout

応答にかかる時間がこの設定を超えたこのサービスへの接続がエラーとみなされるためのタイムアウト (ミリ秒単位)。デフォルトは 1000 秒です。

任意

10.8.5. 3scale API Management WebAssembly モジュールの backend オブジェクト
リンクのコピー

backend 最上位オブジェクトは、HTTP リクエストの承認および報告のために 3scale Service Management API にアクセスする方法を指定します。このサービスは、3scale の バックエンド コンポーネントによって提供されます。 

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    backend:
      name: backend
      upstream: <object>
    ...
Copy to Clipboard Toggle word wrap
Expand
表10.3 backend オブジェクトフィールド
名前説明必須

name

3scale バックエンドの識別子 (現在、参照されていません)。

任意

upstream

問い合わせるネットワークホストの詳細。これは、system として知られる 3scale Account Management API ホストを参照する必要があります。

有効。最も重要な必須フィールドです。

10.8.6. 3scale API Management WebAssembly モジュールの services オブジェクト
リンクのコピー

services の最上位オブジェクトは、module のこの特定のインスタンスで処理されるサービス識別子を指定します。

アカウントには複数のサービスがあるため、どのサービスが処理されているかを指定する必要があります。残りの設定は、サービスの設定方法に関するものです。

services フィールドは必須です。有用とするサービスを少なくとも 1 つ含める必要がある配列です。 

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - id: "2555417834789"
      token: service_token
      authorities:
        - "*.app"
        - 0.0.0.0
        - "0.0.0.0:8443"
      credentials: <object>
      mapping_rules: <object>
    ...
Copy to Clipboard Toggle word wrap

services 配列の各要素は、3scale サービスを表します。

Expand
表10.4 services オブジェクトフィールド
名前説明必須

id

この 3scale サービスの識別子 (現在、参照されていません)。

はい

token

この token は、System 内のサービスのプロキシー設定にあるか、以下の curl コマンドを使用して System から取得できます。

curl "\https://<system_host>/admin/api/services/<service_id>/proxy/configs/production/latest.json?access_token=<access_token>" | jq '.proxy_config.content.backend_authentication_value'

任意

authorities

文字列の配列。それぞれが一致する URL の認証局 を表します。これらの文字列は、アスタリスク (*)、正符号 (+)、および疑問符 (?) マッチャーに対応する glob パターンを受け入れます。

はい

credentials

検索する認証情報の種類と場所を定義するオブジェクト。

はい

mapping_rules

ヒットするマッピングルールおよび 3scale メソッドを表すオブジェクトの配列。

任意

10.8.7. 3scale API Management WebAssembly モジュールの credentials オブジェクト
リンクのコピー

credentials オブジェクトは service オブジェクトのコンポーネントです。credentials は、検索する認証情報の種類と、このアクションを実行する手順を指定します。

すべてのフィールドはオプションですが、少なくとも 1 つの user_key または app_id を指定する必要があります。各認証情報を指定する順番は、モジュールによって事前確立されているために無関係です。各認証情報の 1 つのインスタンスのみを指定します。 

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - credentials:
        user_key: <array_of_lookup_queries>
        app_id: <array_of_lookup_queries>
        app_key: <array_of_lookup_queries>
    ...
Copy to Clipboard Toggle word wrap
Expand
表10.5 credentials オブジェクトフィールド
名前説明必須

user_key

これは、3scale ユーザーキーを定義する検索クエリーの配列です。ユーザーキーは、一般に API キーと呼ばれます。

任意

app_id

これは、3scale のアプリケーション識別子を定義する検索クエリーの配列です。アプリケーションの識別子は、3scale または Red Hat Single Sign-On (RH-SS0) や OpenID Connect (OIDC) などのアイデンティティープロバイダーを使用して提供されます。成功して 2 つの値に解決するたびに、ここで指定された検索クエリーの解決で、app_id と app_key が設定されます。

任意

app_key

これは、3scale のアプリケーションキーを定義する検索クエリーの配列です。解決される app_id のないアプリケーションキーは無意味なため、app_id が指定されている場合のみこのフィールドを指定します。

任意

10.8.8. 3scale API Management WebAssembly モジュールの lookup queries
リンクのコピー

lookup query オブジェクトは、credentials オブジェクトのフィールドの一部になります。特定の認証情報フィールドが検出され、処理される方法を指定します。評価されると、解決に成功すると、1 つ以上の値が見つかったことを意味します。解決に失敗したことは、値が見つからなかったことを意味します。

lookup queries の配列は、ショートサーキットまたは関係を定義しています。いずれかのクエリーの正常な解決により、残りのクエリーの評価が停止され、値を指定の credential-type に割り当てます。アレイの各クエリーは、互いに独立しています。

lookup query は、1 つのフィールド (ソースオブジェクト) で構成されています。これは、複数のソースタイプの 1 つになります。以下の例を参照してください。 

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - credentials:
        user_key:
          - <source_type>: <object>
          - <source_type>: <object>
          ...
        app_id:
          - <source_type>: <object>
          ...
        app_key:
          - <source_type>: <object>
          ...
    ...
Copy to Clipboard Toggle word wrap

source オブジェクトは、任意の credentials オブジェクトフィールド内のソースの配列の一部として存在します。source-type として参照されるオブジェクトフィールド名は、以下のいずれかになります。

  • header: 検索クエリーは、HTTP リクエストヘッダーを入力として受け取ります。
  • query_string: lookup query は、URL クエリー文字列パラメーターを入力として受け取ります。
  • filter: lookup query は、フィルターメタデータをインプットとして受け取ります。

すべての source-type オブジェクトには、少なくとも以下の 2 つのフィールドがあります。

Expand
表10.6 source-type オブジェクトフィールド
名前説明必須

keys

文字列の配列。それぞれが key で、入力データで検索されたエントリーを参照します。

はい

ops

key エントリーの照合を行う operations の配列。配列は、操作が入力を受け取り、次の操作の出力を生成するパイプラインです。出力に失敗した operation は、lookup query を失敗として解決します。操作のパイプラインの順序により、評価の順序が決定されます。

任意

path

データの検索に使用されるメタデータ内のパスを表示します。ただし、header または query_string ソースタイプを使用する場合は必要ありませんが、filter ソースタイプを使用する場合は必須です。

任意

key が入力データと一致する場合は、残りの鍵は評価されず、ソース解決アルゴリズムは、指定した operations (ops) の実行にジャンプします。ops を指定しないと、一致する key の結果値 (ある場合) が返されます。

Operations は、最初のフェーズが key を検索した後に、入力に対する特定の条件および変換を指定する方法を提供します。プロパティーを変換、デコード、および要求する必要があるときに、operations を使用しますが、すべてのニーズに対応する成熟した言語は提供されず、Turing-completeness はありません。

スタックは operations の出力を保存します。評価されると、認証情報が消費する値の数に応じて、スタックの下部に値を割り当てて、lookup query は終了します。

10.8.9. 3scale API Management WebAssembly モジュールの operations オブジェクト
リンクのコピー

特定の source type に属する ops 配列の各要素は、値に変換を適用するか、テストを実行する operation オブジェクトです。このようなオブジェクトに使用するフィールド名は operation 自体の名前で、値は operation に対するパラメーターです。これは、フィールドと値のマップ、リスト、または文字列など、構造化オブジェクトになります。

ほとんどの operations は、1 つ以上の入力を処理し、1 つ以上の出力を生成します。入力を使用したり、出力を生成したりする場合、それらは値のスタックで作業します。操作によって消費される各値は、値のスタックからポップアップされ、source マッチと共に初期入力されます。出力される値はスタックにプッシュされます。他の operations は、特定のプロパティーを要求する以外、出力を使用または生成しませんが、値のスタックを検査します。

注記

解決が完了すると、次の手順 (値を app_id、app_key、または user_key に割り当てるなど) でピックアップされる値はスタックの下部の値から取得されます。

operations カテゴリーはいくつかあります。

  • decode

    別の形式を取得するために、入力値をデコードして変換します。

  • string

    文字列値を入力として取り、変換を実行し、確認します。

  • stack

    入力の値のセットを取得し、複数のスタック変換とスタック内の特定の位置の選択を実行します。

  • check

    影響を及ぼさない方法で、操作セットに関するプロパティーを要求します。

  • control

    評価フローを変更できる操作を実施します。

  • format

    入力値の形式固有の構造を解析し、その値を検索します。

すべての操作は、name 識別子で文字列として指定されます。

10.8.10. 3scale API Management WebAssembly モジュールの mapping_rules オブジェクト
リンクのコピー

mapping_rules オブジェクトは service オブジェクトの一部です。これは、REST パスパターンのセットならびに関連する 3scale メトリクスおよびパターンが一致する時に使用するカウント増分を指定します。

system 最上位オブジェクトに動的設定が提供されていない場合は、値が必要です。system 最上位エントリーに加えてオブジェクトが提供されると、mapping_rules オブジェクトが最初に評価されます。

mapping_rules は配列オブジェクトです。そのアレイの各要素は mapping_rule オブジェクトです。受信したリクエストの評価されたマッチするマッピングルールにより、承認およびAPIManager へのレポート用の 3scale methods のセットが提供されます。複数のマッチングルールが同じ methods を参照する場合は、3scale への呼び出し時に deltas の合算があります。たとえば、2 つのルールが、1 と 3 の deltas で Hits メソッドを 2 回増やすと、3scale にレポートする Hits の単一のメソッドエントリーの delta は 4 になります。

10.8.11. 3scale API Management WebAssembly モジュールの mapping_rule オブジェクト
リンクのコピー

mapping_rule オブジェクトは mapping_rules オブジェクトの配列の一部です。

mapping_rule オブジェクトフィールドは、以下の情報を指定します。

  • 照合する HTTP 要求メソッド。
  • パスに一致するパターン。
  • 報告する量と共にレポートする 3scale メソッド。フィールドを指定する順番により、評価順序が決定されます。
Expand
表10.7 mapping_rule オブジェクトフィールド
名前説明必須

メソッド

HTTP リクエストメソッド (動詞) を表す文字列を指定します。許可される値は、許可される HTTP メソッド名の 1 つと一致し、大文字と小文字を区別しません。すべてのマッチのすべてのメソッドの特殊な値。

はい

pattern

HTTP リクエストの URI パスコンポーネントに一致するパターン。このパターンは、3scale で説明されている構文に従います。ワイルドカード、アスタリスク (*) 文字の使用、中括弧間の任意の文字シーケンスの使用 ({this} など) が許可されます。

はい

usages

usage オブジェクトのリスト。ルールがマッチすると、deltas を持つすべてのメソッドが、承認およびレポートのために 3scale に送信されるメソッドのリストに追加されます。

以下の必須フィールドに usages オブジェクトを埋め込みます。

  • name: レポートする method のシステム名。注記:name は大文字と小文字を区別します。
  • delta: その method の増分。

はい

last

このルールが正常にマッチした場合に、それ以外のマッピングルールの評価を停止する必要があるかどうか。

任意のブール値。デフォルトは false です。

以下の例は、3scale のメソッド間の既存の階層とは独立しています。つまり、3scale 側で実行されたすべての内容はこれには影響しません。たとえば、Hits メトリクスは、それらすべての親となる可能性があるため、承認されたリクエストで報告されたすべてのメソッドの合計により 4 ヒットを保管し、3scale Authrep API エンドポイントを呼び出します。

以下の例では、すべてのルールに一致する、パス /products/1/sold への GET リクエストを使用します。

mapping_rules GET リクエストの例

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    mapping_rules:
      - method: GET
        pattern: /
        usages:
          - name: hits
            delta: 1
      - method: GET
        pattern: /products/
        usages:
          - name: products
            delta: 1
      - method: ANY
        pattern: /products/{id}/sold
        usages:
          - name: sales
            delta: 1
          - name: products
            delta: 1
    ...
Copy to Clipboard Toggle word wrap

すべての usages は、モジュールが使用状況データを使用して 3scale に実施するリクエストに追加されます。

  • Hits: 1
  • products: 2
  • sales: 1

10.9. 認証情報ユースケースの 3scale API Management WebAssembly モジュールの例
リンクのコピー

ほとんどの時間を費やして、設定手順を適用してサービスへのリクエストの認証情報を取得します。

以下は credentials の例です。これは、特定のユースケースに合わせて変更できます。

複数のソースオブジェクトと独自の lookup queries を指定する場合、これらはすべて組み合わせることができますが、いずれか 1 つが正しく解決されるまで、それらは順番に評価されます。

10.9.1. クエリー文字列パラメーターの API キー (user_key)
リンクのコピー

以下の例では、クエリー文字列パラメーターまたは同じ名前のヘッダーで user_key を検索します。 

credentials:
  user_key:
    - query_string:
        keys:
          - user_key
    - header:
        keys:
          - user_key
Copy to Clipboard Toggle word wrap

10.9.2. アプリケーション ID およびキー
リンクのコピー

以下の例では、クエリーまたはヘッダーの app_key および app_id 認証情報を検索します。 

credentials:
  app_id:
    - header:
        keys:
          - app_id
    - query_string:
        keys:
          - app_id
  app_key:
    - header:
        keys:
          - app_key
    - query_string:
        keys:
          - app_key
Copy to Clipboard Toggle word wrap

10.9.3. 認証ヘッダー
リンクのコピー

リクエストには、authorization ヘッダーに app_id および app_key が含まれます。最後に出力される値が 1 つまたは 2 つある場合は、app_key を割り当てることができます。

ここでの解決は、最後に出力された 1 つまたは 2 つの出力がある場合は app_key を割り当てます。

authorization ヘッダーは承認の種類で値を指定し、その値は Base64 としてエンコードされます。つまり、値を空白文字で分割し、2 番目の出力を取得して、コロン (:) をセパレーターとして使用して再度分割できます。たとえば、app_id:app_key という形式を使用する場合、ヘッダーは以下の credential の例のようになります。 

aladdin:opensesame: Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
Copy to Clipboard Toggle word wrap

次の例に示すように、ヘッダーフィールド名は小文字を使用する必要があります。 

credentials:
  app_id:
    - header:
        keys:
          - authorization
        ops:
          - split:
              separator: " "
              max: 2
          - length:
              min: 2
          - drop:
              head: 1
          - base64_urlsafe
          - split:
              max: 2
  app_key:
    - header:
        keys:
          - app_key
Copy to Clipboard Toggle word wrap

前述のユースケースの例は、authorization のヘッダーを確認します。

  1. これは文字列の値を取り、スペースで分割し、credential-type および credential 自体の少なくとも 2 つの値を生成することを確認してから、credential-type をドロップします。

  2. 次に、必要なデータが含まれる 2 番目の値をデコードし、最初の app_id の後にもしあれば app_key が含まれる操作スタックとなるように、コロン (:) 文字を使用して分割します。

    1. app_key が認証ヘッダーに存在しない場合は、その特定のソースがチェックされます。たとえば、この場合はヘッダーにキー app_key が付いています。
  3. credentials に追加の条件を追加するには、Basic 認証を許可します。ここで、app_id は aladdin もしくは admin、または長さが 8 文字以上の任意の app_id になります。

  4. app_key には値が含まれ、以下の例のように最小で 64 文字を指定する必要があります。 

    credentials:
  app_id:
    - header:
        keys:
          - authorization
        ops:
          - split:
              separator: " "
              max: 2
          - length:
              min: 2
          - reverse
          - glob:
            - Basic
          - drop:
              tail: 1
          - base64_urlsafe
          - split:
              max: 2
          - test:
              if:
                length:
                  min: 2
              then:
                - strlen:
                    max: 63
                - or:
                    - strlen:
                        min: 1
                    - drop:
                        tail: 1
          - assert:
            - and:
              - reverse
              - or:
                - strlen:
                    min: 8
                - glob:
                  - aladdin
                  - admin
    Copy to Clipboard Toggle word wrap
  5. authorization ヘッダーの値を選択したら、タイプが上部に配置されるようにスタックを逆にして Basic credential-type を取得します。
  6. glob マッチを実行します。検証し、認証情報がデコードされ、分割されると、スタックの下部に app_id を取得し、上部に app_key を取得する可能性があります。

  7. test: を実行します。スタックに 2 つの値がある場合は、app_key が取得されたことになります。

    1. app_id および app_key を含め、文字列の長さが 1 から 63 文字になるようにします。キーの長さがゼロの場合は破棄し、キーが存在しないものとして続行します。app_id のみがあり、app_key がない場合、不明なブランチは、テストに成功し、評価が続行されます。

最後の操作は assert で、スタックに副作用がないことを示します。その後、スタックを変更できます。

  1. app_id が最上部になるように、スタックを逆にします。

    1. app_key が存在するかどうかで、スタックを逆にすると、app_id が上部になります。

  2. and を使用して、テスト間でスタックの内容を保持します。

    次に、以下のいずれかの方法を使用します。

    • app_id に 8 文字以上の文字列が設定されていることを確認してください。
    • app_id が aladdin または admin と一致していることを確認します。

10.9.4. OpenID Connect (OIDC) のユースケース
リンクのコピー

Service Mesh および 3scale Istio アダプターの場合は、以下の例のように RequestAuthentication をデプロイし、独自のワークロードデータおよび jwtRules を入力する必要があります。 

apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
metadata:
  name: jwt-example
  namespace: <info>
spec:
  selector:
    matchLabels:
      app: <productpage>
  jwtRules:
  - issuer: >-
      "<url>/auth/realms/<realm_name>"
    jwksUri: >-
      "<url>/auth/realms/<realm_name>/protocol/openid-connect/certs"
Copy to Clipboard Toggle word wrap

RequestAuthentication を適用するとき、JWT トークンを検証するためにネイティブプラグインで Envoy を設定します。プロキシーは、モジュールを実行する前にすべてを検証します。したがって、失敗したリクエストが 3scale WebAssembly モジュールに実行されません。

JWT トークンが検証されると、プロキシーはそのコンテンツを内部メタデータオブジェクトに格納します。エントリーのキーは、プラグインの特定の設定に依存します。このユースケースでは、不明なキー名が含まれる単一のエントリーを持つ構造化オブジェクトを検索できます。

OIDC の 3scale app_id は、OAuth client_id と一致します。これは JWT トークンの azp フィールドまたは aud フィールドにあります。

Envoy のネイティブ JWT 認証フィルターから app_id フィールドを取得するには、以下の例を参照してください。 

credentials:
  app_id:
    - filter:
        path:
          - envoy.filters.http.jwt_authn
          - "0"
        keys:
          - azp
          - aud
        ops:
          - take:
              head: 1
Copy to Clipboard Toggle word wrap

この例では、モジュールに対し、filter ソースタイプを使用して Envoy 固有の JWT 認証ネイティブプラグインからオブジェクトのフィルターメタデータを検索するよう指示します。このプラグインには、1 つのエントリーと事前に設定された名前を持つ構造化オブジェクトの一部として JWT トークンが含まれます。0 を使用して、単一のエントリーのみにアクセスするように指定します。

結果の値は、以下の 2 つのフィールドを解決する構造です。

  • azp: app_id が見つけられる値。
  • aud: この情報も見つけられる値。

この操作により、割り当て用に 1 つの値のみが保持されます。

10.9.5. ヘッダーからの JWT トークンの取得
リンクのコピー

一部のセットアップには、JWT トークンの検証プロセスがあり、検証されたトークンが JSON 形式のヘッダーを介してこのモジュールに到達する場合があります。

app_id を取得するには、以下の例を参照してください。 

credentials:
  app_id:
    - header:
        keys:
          - x-jwt-payload
        ops:
          - base64_urlsafe
          - json:
            - keys:
              - azp
              - aud
          - take:
              head: 1
Copy to Clipboard Toggle word wrap

10.10. 3scale API Management WebAssembly モジュールの機能する最低限の設定
リンクのコピー

以下は、3scale WebAssembly モジュールの機能する最低限の設定の例です。これをコピーアンドペーストし、これを独自の設定で機能するように編集できます。 

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  url: oci://registry.redhat.io/3scale-amp2/3scale-auth-wasm-rhel8:0.0.3
  imagePullSecret: <pull_secret_resource>
  phase: AUTHZ
  match:
    - mode: SERVER
  priority: 100
  selector:
    matchLabels:
      app: <productpage>
  pluginConfig:
    api: v1
    system:
      name: <system_name>
      upstream:
        name: outbound|443||multitenant.3scale.net
        url: https://istiodevel-admin.3scale.net/
        timeout: 5000
      token: <token>
    backend:
      name: <backend_name>
      upstream:
        name: outbound|443||su1.3scale.net
        url: https://su1.3scale.net/
        timeout: 5000
      extensions:
      - no_body
    services:
    - id: '2555417834780'
      authorities:
      - "*"
      credentials:
        user_key:
          - query_string:
              keys:
                - <user_key>
          - header:
              keys:
                - <user_key>
        app_id:
          - query_string:
              keys:
                - <app_id>
          - header:
              keys:
                - <app_id>
        app_key:
          - query_string:
              keys:
                - <app_key>
          - header:
              keys:
                - <app_key>
Copy to Clipboard Toggle word wrap

関連情報

第11章 API インフラストラクチャーに関するトラブルシューティング
リンクのコピー

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

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

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

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

以下のセクションを参照して、発生する可能性のある典型的な問題の特定および修正を行います。

11.1. インテグレーションに関する典型的な問題
リンクのコピー

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

11.1.1. インテグレーションの問題
リンクのコピー

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

11.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 ゲートウェイ以外からの呼び出しを拒否することができます。

  • 設定可能なフォーマットは 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 でこれ以前にサービスを作成したことがある場合は、テストリクエストを行うためのクレデンシャルが設定されたサービスでアプリケーションを作成していることを確認します。これが統合する最初のサービスである場合は、サインアップ時に作成したテストアカウントまたはアプリケーションを削除していないことを確認します。
11.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 ゲートウェイが 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
    Copy to Clipboard Toggle word wrap

    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"
    Copy to Clipboard Toggle word wrap

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

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

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

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

11.1.2. 実稼働環境の問題
リンクのコピー

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

11.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"
Copy to Clipboard Toggle word wrap

断続的に 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";
    Copy to Clipboard Toggle word wrap

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

    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;
}
    Copy to Clipboard Toggle word wrap

  • すべての 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; に置き換えます。

11.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
Copy to Clipboard Toggle word wrap

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"
Copy to Clipboard Toggle word wrap

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"
Copy to Clipboard Toggle word wrap

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

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

11.2. API インフラストラクチャーに関する問題への対応
リンクのコピー

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

11.2.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.
Copy to Clipboard Toggle word wrap
  • 接続できない場合 
telnet su1.3scale.net 443
Trying 174.129.235.69...
telnet: Unable to connect to remote host: Connection timed out
Copy to Clipboard Toggle word wrap

11.2.2. サーバー接続の問題
リンクのコピー

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

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

11.2.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 をブロックします

11.2.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)
---
    Copy to Clipboard Toggle word wrap

  • 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)
---
Copy to Clipboard Toggle word wrap

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

11.3. API へのリクエストに関する問題の特定
リンクのコピー

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

11.3.1. API
リンクのコピー

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

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

11.3.2. API ゲートウェイ > API
リンクのコピー

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

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

11.3.3. API ゲートウェイ
リンクのコピー

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

11.3.3.1. API ゲートウェイの起動および稼働確認
リンクのコピー

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

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

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

11.3.3.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"
    Copy to Clipboard Toggle word wrap

  • 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"
    Copy to Clipboard Toggle word wrap

11.3.4. API ゲートウェイ > 3scale API Management
リンクのコピー

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

11.3.4.1. API ゲートウェイでの 3scale API Management へのアクセスの可否確認
リンクのコピー

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"
Copy to Clipboard Toggle word wrap

ここでは、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 を使用できます。

11.3.4.2. API ゲートウェイが 3scale API Management のアドレスを正しく解決していることの確認
リンクのコピー

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;
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

上記の例は、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
Copy to Clipboard Toggle word wrap

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

11.3.4.3. API ゲートウェイが 3scale API Management を正しく呼び出していることの確認
リンクのコピー

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
}
Copy to Clipboard Toggle word wrap

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"
Copy to Clipboard Toggle word wrap

最初のエントリー (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: "https://54.83.62.94:443/transactions/threescale_authrep.xml?provider_key=REDACTED&service_id=REDACTED&usage[hits]=1&access_token=7c6f24f5") を出力します。この最後の値で、どの 3scale IP が解決されているかと、3scale に行った実際のリクエストも確認できます。

11.3.5. 3scale API Management
リンクのコピー

11.3.5.1. 3scale API Management がエラーを返していることの確認
リンクのコピー

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

11.3.5.2. 3scale API Management デバッグヘッダーの使用
リンクのコピー

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

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

これにより、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
Copy to Clipboard Toggle word wrap
11.3.5.3. インテグレーションエラーの確認
リンクのコピー

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

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

11.3.6. クライアント API ゲートウェイ
リンクのコピー

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

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

11.3.6.2. クライアントから API ゲートウェイにアクセスできるかの確認
リンクのコピー

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

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

11.3.7. クライアント
リンクのコピー

11.3.7.1. 別のクライアントを使用した同じ呼び出しのテスト
リンクのコピー

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

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

11.3.7.2. クライアントから送信されたトラフィックの確認
リンクのコピー

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

11.4. ActiveDocs の問題
リンクのコピー

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

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

11.4.1. petstore.swagger.io の使用
リンクのコピー

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

11.4.2. ファイアウォールが ActiveDocs プロキシーからの接続を許可していることの確認
リンクのコピー

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

11.4.3. 無効なクレデンシャルを使用した API の呼び出し
リンクのコピー

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

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

11.4.4. 呼び出しの比較
リンクのコピー

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

11.5. NGINX でのロギング
リンクのコピー

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

11.5.1. デバッグログの有効化
リンクのコピー

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

11.6. 3scale のエラーコード
リンクのコピー

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

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

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

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

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

  • 403:

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

  • 409:

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

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

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

  • 403
  • 404

法律上の通知
リンクのコピー

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

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

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

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

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat