3scale の操作

Red Hat 3scale API Management 2.10

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

概要

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

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

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

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

注記

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

本章では、Red Hat 3scale API Management 2.10 インストール環境での操作とスケーリングタスクについて説明します。

前提条件

3scale の操作およびスケーリングタスクを実施するには、以下のセクションに概略を示す手順を実施します。

1.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 は、設定された頻度でプロモートされた更新を取得しパブリッシュします。

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

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

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

oc edit pv <pv_name>

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

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

手順

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

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

1.2.2. 方法 2: 3scale をバックアップして再デプロイする

手順

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

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

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

パフォーマンスのスケールアップは、Pod の合計数に応じて行われます。ハードウェアリソースが多いほど、デプロイする Pod 数が増えます。

以下のコマンドを使用して、Pod の数によりパフォーマンスのスケールアップを行います。

oc scale dc dc-name --replicas=X

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

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

  • 実稼働環境用 APIcast
  • バックエンドリスナー
  • バックエンドワーカー

1.2.4.1. OCP コマンドラインインターフェースを使用したスケーリング

OpenShift Container Platform (OCP) コマンドラインインターフェース (CLI) を使用して、デプロイメント設定をスケールアップまたはスケールダウンできます。

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

  • 以下のコマンドを使用して、実稼働環境用 APIcast のデプロイメント設定をスケールアップします。

    oc scale dc apicast-production --replicas=X
  • 以下のコマンドを使用して、バックエンドリスナーのデプロイメント設定をスケールアップします。

    oc scale dc backend-listener --replicas=Y
  • 以下のコマンドを使用して、バックエンドワーカーのデプロイメント設定をスケールアップします。

    oc scale dc  backend-worker --replicas=Z

1.2.4.2. ハードウェアの垂直スケーリングと水平スケーリング

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

水平スケーリング

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

垂直スケーリング

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

注記

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

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

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

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

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

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

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

前提条件

  • 3scale 2.10 デプロイメント

手順

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

留意事項

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

1.3.2. 監査ロギングの有効化

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

前提条件

  • OpenShift でのクラスター管理者アクセス権限を持っている必要があります。

手順

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

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

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

    oc patch dc system-app -p $PATCH_SYSTEM_VOLUMES
    oc patch dc system-sidekiq -p $PATCH_SYSTEM_VOLUMES

1.3.3. EFK ロギングの設定

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

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

1.3.4. ログへのアクセス

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

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

手順

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

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

    oc logs <pod>

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

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

1.3.5. ジョブキューの確認

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

oc get jobs
oc logs <job>

1.3.6. 単調増加の防止

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

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

以下の表は例外で、データベース管理者が手動でパージする必要があります。

  • alerts

表1.1 SQL パージコマンド

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

MySQL

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

PostgreSQL

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

Oracle

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

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

その他のリソース

第2章 3scale のモニタリング

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

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

重要

Prometheus はオープンソースのシステム監視ツールキットで、Grafana はオープンソースのダッシュボードツールキットです。Prometheus および Grafana に対する Red Hat のサポートは、Red Hat の製品ドキュメントに記載されている推奨設定に限定されます。

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

注記

3scale operator は監視リソースを作成しますが、これらのリソースの変更は妨げません。

前提条件

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

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

    • Prometheus operator v0.37.0
    • Prometheus イメージ: quay.io/prometheus/prometheus:v2.16.0
  • Grafana operator がクラスターにインストールされている。Grafana operator は、Grafana インスタンスを作成および管理します。3scale の監視に必要な GrafanaDashboard カスタムリソース定義を提供します。

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

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

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

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

2.1. 3scale のモニタリングの有効化

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

手順

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

    1. .3scale-monitoring.yml という名前の APIManager カスタムリソースを作成し、監視を有効にします。

      apiVersion: apps.3scale.net/v1alpha1
      kind: APIManager
      metadata:
        name: apimanager1
      spec:
        wildcardDomain: example.com
        monitoring:
          enabled: true
    2. OpenShift クラスターにログインします。3scale の OpenShift プロジェクトのクラスター 編集 ロールを持つユーザーとしてログインする必要があります (例: cluster-admin)。

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

      oc project <project_name>
    4. カスタムリソースをデプロイします。

      $ oc apply -f 3scale-monitoring.yml

その他のリソース

2.2. 3scale を監視するための Prometheus の設定

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

注記

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

手順

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

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

      apiVersion: monitoring.coreos.com/v1
      kind: Prometheus
      metadata:
        name: example
      spec:
        podMonitorSelector: {}
        ruleSelector: {}
    • 3scale と Prometheus operator を同じ OpenShift プロジェクトにデプロイし、APP_LABEL の値がデフォルトの 3scale-api-management に設定されている場合は、以下の手順に従って 3scale リソースを監視します。

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

         podMonitorSelector:
          matchExpressions:
          - key: app
              operator: In
              values:
              - 3scale-api-management
      2. spec.ruleSelector 属性を以下のように設定します。

           matchExpressions:
           - key: app
             operator: In
             values:
             - 3scale-api-management

        たとえば、以下のカスタムリソースを適用します。

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

      1. 3scale がデプロイされている OpenShift プロジェクトに MYLABELKEY=MYLABELVALUE のラベルを付けます。
      2. podMonitorNamespaceSelector フィルターを使用して、3scale Pod を選択します。たとえば、以下のカスタムリソースを適用します。

        apiVersion: monitoring.coreos.com/v1
        kind: Prometheus
        metadata:
          name: example
        spec:
         podMonitorSelector: {}
         ruleSelector: {}
         podMonitorNamespaceSelector:
           matchExpressions:
           - key: MYLABELKEY
             operator: In
             values:
             - MYLABELVALUE
  2. ダッシュボードおよびアラートが予想通りに機能するようにするには、以下のいずれかを実行して Kubernetes メトリクス (kube-state-metrics) を取り込む必要があります。

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

その他のリソース

2.3. 3scale を監視するための Grafana の設定

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

手順

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

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

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

    app: 3scale-api-management
    monitoring-key: middleware
  2. Grafana operator が 3scale 以外の namespace にインストールされている場合は、--namespaces または --scan-all operator フラグを使用して、namespace 外部のリソースを監視するように設定します。Operator フラグについての詳細は、Grafana のドキュメント を参照してください。
  3. タイプが prometheusGrafanaDataSource カスタムリソースを作成し、Grafana で Prometheus データを使用できるようにします。以下に例を示します。

    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"

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

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

その他のリソース

2.4. 3scale のメトリクスの表示

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

手順

  1. Grafana コンソールにログインします。
  2. 以下についてのメトリクスを表示できることを確認します。

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

その他のリソース

第3章 3scale toolbox

3scale toolbox は、コマンドラインから 3scale プロダクトを管理できる Ruby クライアントです。

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

3.1. toolbox のインストール

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

3.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!
  2. toolbox のコンテナーイメージをプルします。

    $ podman pull registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10
  3. インストールを確認します。

    $ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale help

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

手順

その他のリソース

3.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
    update               [DEPRECATED] update super command

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

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

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

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

以下の情報が必要です。

  • 3scale 管理アカウント: {3SCALE_ADMIN}
  • 3scale インスタンスが実行されているドメイン: {DOMAIN_NAME}

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

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

$ podman run -v $PWD/examples/import_example.csv:/tmp/import_example.csv registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale import csv --destination=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --file=/tmp/import_example.csv

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

3.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-rhel7:3scale2.10 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}

注記

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

3.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-rhel7:3scale2.10 3scale update [opts] service --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} {SERVICE_ID} {DEST_ID}

3.6. OpenAPI 定義のインポート

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

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

3scale import openapi [opts] -d=<destination> <specification>

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

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

$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale import openapi [opts] -d=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}  my-test-api.json

コマンドオプション

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 のインポートルール

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

  • 定義は OpenAPI 2.0 または OpenAPI 3.0 として検証される。
  • 3scale製品のすべてのマッピングルールが削除されます。
  • 置き換えるためには、パターンの完全一致の使用により、すべてのメソッドの名前が OpenAPI 定義 (operation.operationId) で定義されるメソッドと同一でなければならない。
  • OpenAPI 定義に含まれるメソッドのみが変更される。
  • OpenAPI 定義にしか存在していなかったすべてのメソッドが、Hits メトリクスにアタッチされる。
  • OpenAPI 定義のすべてのマッピングルールがインポートされる。これらについては API > Integration で確認できます。
  • サポートされるセキュリティースキームは、apiKey および oauth2 (任意の OAuth フロータイプに対応) です。
  • OpenAPI 仕様は、以下の値のいずれかでなければなりません。

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

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

OpenAPI 3.0 の制約

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

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

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

リモートの 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>

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

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

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

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

$ podman commit toolbox-container toolbox

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

$ podman run toolbox 3scale remote list
instance_a https://example_a.net 123456789

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

警告

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

その他のリソース

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

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

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

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

このコマンドにより、追加されたリモート 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

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

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

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

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

$ podman run <toolbox_image_with_remote_added> 3scale remote remove instance_a

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

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

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

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

$ podman run <toolbox_image_with_remote_added> 3scale remote rename instance_a instance_b

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

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

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

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

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

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

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

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

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

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

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

Options
       --approval-required=<value>    The application requires approval:
                                      true or false
       --cost-per-month=<value>       Cost per month
       --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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

$ podman run -u root -v $PWD:/tmp registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale application-plan export --file=/tmp/plan.yaml remote_name service_name plan_name

この例では、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

3.8.6.2. ファイルからのアプリケーションプランのインポート

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

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

$ podman run -v $PWD/plan.yaml:/tmp/plan.yaml registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale application-plan import --file=/tmp/plan.yaml remote_name service_name

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

3.8.6.3. URL からのアプリケーションプランのインポート

3scale application-plan import -f http[s]://domain/resource/path.yaml remote_name service_name
注記

import コマンドに固有の事項

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

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

    • -p オプションで指定されていない場合、デフォルトでは、system_name コンテンツからのプラン属性 yaml によってアプリケーションプランが参照されます。
  • 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

3.9. メトリクスの作成

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3.9.3. メトリクスの削除

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

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

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

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

3.10. メソッドの作成

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

3.10.1. メソッドの作成

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3.10.3. メソッドの一覧表示

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

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

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

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

3.10.4. メソッドの削除

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

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

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

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

3.11. サービスの作成

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

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

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

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

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

Options
    -a --authentication-mode=<value>     Specify authentication mode of
                                         the service:
                                          - '1' for API key
                                          - '2' for App Id/App Key
                                          - 'oauth' for OAuth mode
                                          - 'oidc' for OpenID Connect
    -d --deployment-mode=<value>         Specify the deployment mode of
                                         the service
       --description=<value>             Specify the description of the
                                         service
    -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

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

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

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

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

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

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

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

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

3.11.3. サービスの一覧表示

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

3scale service list <remote>

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

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

3.11.4. サービスの表示

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

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

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

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

3.11.5. サービスの削除

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

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

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

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

3.12. ActiveDocs の作成

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

3.12.1. 新しい ActiveDocs の作成

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

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

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

    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
  2. デベロッパーポータルに定義を 公開 します。

3.12.2. ActiveDocs の作成または更新

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

3scale activedocs apply <remote> <activedocs_id_or_system_name>

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

Options
  -d --description=<value>              Specify the description of the
                                        ActiveDocs
       --hide                           Specify 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
注記

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

3.12.3. ActiveDocs の一覧表示

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

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

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

3scale activedocs list <remote>

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

3.12.4. ActiveDocs の削除

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

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

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

Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file:
                                  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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3.14. ポリシーレジストリーのコピー

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

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

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

3scale policy-registry copy [opts] <source_remote> <target_remote>
Option for policy-registry
    -c --config-file=<value>      3scale toolbox configuration file:
                                  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

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

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

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

3scale application list [opts] <remote>

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

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

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

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

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

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

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

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

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

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

OPTIONS
       --application-id=<value>     App ID or Client ID (for OAuth and
                                    OpenID Connect authentication modes)
                                    of the application to be created.
       --application-key=<value>    App Key(s) or Client Secret (for OAuth
                                    and OpenID Connect authentication
                                    modes) of the application 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

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

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

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

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

  • 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

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

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

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

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

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

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

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

OPTIONS
       --account=<value>           Application's account. Required when
                                   creating
       --application-key=<value>   App Key(s) or Client Secret (for OAuth
                                   and OpenID Connect authentication
                                   modes) of the application to be
                                   created. Only used when application
                                   does not exist.
       --description=<value>       Application description
       --name=<value>              Application name
    -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.

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

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

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

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

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

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

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

  • 選択したシステム名のバックエンドが見つからない場合は、そのバックエンドが作成されます。
  • 選択したシステム名のバックエンドが存在する場合は、そのバックエンドが更新されます。メトリクス、メソッド、マッピングルールなど、足りないコンポーネントだけが作成されます。

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

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

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

  • メトリクス
  • メソッド
  • マッピングルール

手順

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

    3scale backend copy [opts] -s <source_remote> -d <target_remote> <source_backend>

    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.

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

+

$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale backend copy [-t target_system_name] -s 3scale1 -d 3scale2 api_backend_01

3.16.1. 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>

    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.

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

+

$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale product copy [-t target_system_name] -s 3scale1 -d 3scale2 my_api_product_01

3.17. 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
  2. curl を使用して、証明書が正常に機能していることを確認します。以下に例を示します。

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

    証明書が正しく機能している場合は、SSL エラーが表示されることはなくなります。証明書が正常に機能していない場合は、-k オプション (または長い形式 --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 egistry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.10 3scale service list https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}

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

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

その他のリソース

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

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

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

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

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

4.1. 環境ごとのプロダクト

このメソッドでは、API バックエンド環境ごとに個別の 3scale プロダクトが使用されます。各プロダクトで、実稼働ゲートウェイとステージングゲートウェイを設定します。これにより、ゲートウェイ設定への変更を安全にテストし、API バックエンドで行うように実稼働環境設定にプロモートできます。

Production Product => Production Product APIcast gateway => Production Product API upstream
Staging Product => Staging Product APIcast gateway => Staging Product API upstream

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

開発環境

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

    • 名前: Dev
    • プライベートベース URL: API バックエンドの URL
  • 開発プロダクトの作成

    • 実稼働公開ベース 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
  • 実稼働製品の作成

    • 実稼働公開ベース URL: https://prod-api-backend.yourdomain.com
    • ステージング公開ベース URL: https://prod-api-backend.yourdomain.com
    • バックエンドパス / での実稼働バックエンドの追加

その他のリソース

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

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

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

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

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

注記

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

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

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

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

  • 単一テナント内で、環境と 3scale プロダクト間で 1 対 1 のマッピングを作成します。
  • 必要に応じて、テナントごとに 1 つまたは複数のプロダクトを持つ環境とテナント間の 1 対 1 のマッピングを作成します。

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

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

4.3. 3scale の混合アプローチ

3scale On-premises instances」に記載されているアプローチを組み合わせることができます。以下に例を示します。

  • 実稼働用の別個の 3scale インスタンス
  • dev および qa の非実稼働環境での個別のテナントを持つ個別の 3scale インスタンス

4.4. 3scale と APIcast ゲートウェイ

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

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

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

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

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

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

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

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

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

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

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

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

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

その他のリソース

第5章 Automating API lifecycle with 3scale toolbox

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

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

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

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

API lifecycle stages
注記

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

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

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

表5.1 API プロバイダーライフサイクルのステージ

ステージ目的成果

1. ストラテジー

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

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

2. 設計

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

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

3. モック

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

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

4. テスト

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

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

5. 実装

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

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

6. デプロイ

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

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

7. 保護

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

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

8. 管理

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

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

5.1.2. API 利用者サイクル

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

表5.2 API 利用者ライフサイクルのステージ

ステージ目的成果

9. 検出

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

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

10. 開発

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

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

11. 利用

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

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

12. 監視

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

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

13. 収益化

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

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

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

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

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

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

表5.3 サンプル Jenkins 共有ライブラリーパイプライン

サンプルパイプラインターゲット環境セキュリティー

SaaS - API key

ホスト型 3scale

API キー

Hybrid - open

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

なし

Hybrid - OpenID Connect

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

OpenID Connect (OIDC)

Multi-environment

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

API キー

Semantic versioning

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

API キー、なし、OIDC

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

重要

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

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

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

注記

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

前提条件

  • Linux ワークステーションが必要です。
  • ホスト型 3scale 環境が必要です。
  • OpenShift 3.11 クラスターが必要です。現在、OpenShift 4 はサポートされていません。

  • OpenShift のドキュメント で説明されているように、必ず OpenShift ルーターでワイルドカードルートを有効にします。

手順

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

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

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

    export SAAS_DEVELOPER_ACCOUNT_ID=123...456

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

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

注記

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

前提条件

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

  • OpenShift のドキュメント で説明されているように、必ず OpenShift ルーターでワイルドカードルートを有効にします。

手順

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

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

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

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

    OPENSHIFT_ROUTER_SUFFIX の値を OpenShift ルーターのサフィックスに設定する必要があります (たとえば、app.openshift.test)。

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

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

    export ONPREM_DEVELOPER_ACCOUNT_ID=5

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

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

手順

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

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

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

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

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

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

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

手順

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

    ホスト型 3scale

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

    オンプレミス型 3scale

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

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

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

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

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

手順

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

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

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

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

    • Multi-environment
    • Semantic versioning

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

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

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

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

手順

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

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

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

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

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

手順

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

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

    oc start-build saas-usecase-apikey

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

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

OpenShift のサポート
サンプルパイプラインは OpenShift 3.11 でのみサポートされます。現在、OpenShift 4 はサポートされていません。サポート対象構成の情報については、「Red Hat 3scale API Management Supported Configurations」のアーティクルを参照してください。
アプリケーションの更新
  • アプリケーション用 3scale application apply toolbox コマンドを使用して、アプリケーションの作成と更新の両方を行うことができます。作成コマンドは、アカウント、プラン、サービス、およびアプリケーションキーをサポートします。
  • 更新コマンドは、アカウント、プラン、またはサービスに対する変更をサポートしません。変更が渡されると、パイプラインがトリガーされエラーは表示されませんが、これらのフィールドは更新されません。
サービスのコピー
3scale copy service toolbox コマンドを使用してカスタムポリシーが設定されたサービスをコピーする場合、先に個別にカスタムポリシーをコピーする必要があります。
API プロダクト
3scale toolbox は、すべての API プロダクト (APIaaP) 機能をサポートする訳ではありません。詳細は、3scale の『リリースノート』の「既知の問題」を参照してください。

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

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

重要

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

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

前提条件

手順

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

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

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

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

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

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

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

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

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

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

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

重要

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

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

前提条件

手順

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

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

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

    この関数は、Kubernetes オブジェクトテンプレートを使用して 3scale toolbox を実行するもので、必要に応じて調整できます。3scale toolbox CLI 引数を設定し、結果の Kubernetes ジョブ定義を YAML ファイルに記述し、toolbox の以前の実行をクリーンアップし、Kubernetes ジョブを作成して、待機します。

    • 待機時間は、Pod が Created から Running 状態に移行するのに要する時間に一致するように、サーバー速度に合わせて調整することができます。このステップは、ポーリングループを使用して調整できます。
    • OpenAPI 仕様ファイルは、openapi という ConfigMap から取得されます。
    • 3scale 管理ポータルのホスト名とアクセストークンは、「3scale toolbox のインストールおよびアクセスの有効化」に示すように、3scale-toolbox というシークレットから取得されます。
    • ConfigMap は、ステップ 3 でパイプラインによって作成されます。ただし、シークレットはすでにパイプライン外にプロビジョニングされており、セキュリティーを強化するロールベースのアクセス制御 (RBAC) の対象です。
  2. Jenkins パイプラインステージで 3scale toolbox で使用するグローバル環境変数を定義します。以下に例を示します。

    ホスト型 3scale

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

    オンプレミス型 3scale

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

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

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

    • targetSystemName: 作成されるサービスの名前
    • targetInstance: この変数は、「3scale toolbox のインストールおよびアクセスの有効化」で作成された 3scale リモートインスタンスの名前と一致します。
    • privateBaseURL: API バックエンドのエンドポイントホスト
    • testUserKey: インテグレーションテストの実行に使用されるユーザー API キー。これは、例のようにハードコーディングされる場合と、HMAC 機能から生成される場合があります。
    • developerAccountId: テストアプリケーションが作成されるターゲットアカウントの ID
    • publicStagingBaseURL: 作成されるサービスのステージング環境用公開ベース URL
    • publicProductionBaseURL: 作成されるサービスの実稼働環境用公開ベース URL
  3. 以下のように、OpenAPI 仕様ファイルを取得して OpenShift で ConfigMap としてプロビジョニングするパイプラインステージを追加します。

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

    ホスト型 3scale

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

    オンプレミス型 3scale

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

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

    stage("Create an Application Plan") {
      runToolbox([ "3scale", "application-plan", "apply", targetInstance, targetSystemName, "test", "-n", "Test Plan", "--default" ])
    }
    
    stage("Create an Application") {
      runToolbox([ "3scale", "application", "apply", targetInstance, testUserKey, "--account=${developerAccountId}", "--name=Test Application", "--description=Created by Jenkins", "--plan=test", "--service=${targetSystemName}" ])
    }
    stage("Run integration tests") {
      def proxyDefinition = runToolbox([ "3scale", "proxy", "show", targetInstance, targetSystemName, "sandbox" ])
      def proxy = readJSON text: proxyDefinition
      proxy = proxy.content.proxy
    
      sh """set -e
      echo "Public Staging Base URL is ${proxy.sandbox_endpoint}"
      echo "userkey is ${testUserKey}"
      curl -vfk ${proxy.sandbox_endpoint}/beer -H 'api-key: ${testUserKey}'
      curl -vfk ${proxy.sandbox_endpoint}/beer/Weissbier -H 'api-key: ${testUserKey}'
      curl -vfk ${proxy.sandbox_endpoint}/beer/findByStatus/available -H 'api-key: ${testUserKey}'
      """
    }
  6. toolbox を使用して API を実稼働環境にプロモートするステージを追加します。

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

第6章 operator を使用した 3scale の設定およびプロビジョニング

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

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

重要

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

本章では、operator アプリケーションの capabilities がどのように機能するか、また以下の項目をデプロイする手順について説明します。

また、3scale operator を使用した機能の制限についても説明します。

6.1. 一般的な前提条件

operator を使用した 3scale の設定およびプロビジョニングには、以下の必須要素があります。

6.2. 3scale operator を使用したアプリケーション capabilities

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

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

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

3scale entities and relations eligible for management using OpenShift custom resources.

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

3scale entities and relations eligible for management using OpenShift custom resources.

6.3. 最初の 3scale プロダクトおよびバックエンドのデプロイ

新しく作成したテナントで Openshift Container Platform を使用して、最初の 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
  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"
      • ファイルを作成すると、operator はステップが成功したかどうかを確認します。
      • Backend カスタムリソースのフィールドおよび設定可能な値の詳細は、Backend CRD field Reference を参照してください。
    2. カスタムリソースを作成します。

      oc create -f backend1.yaml
  3. 3scale プロダクトを設定します。

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

      apiVersion: capabilities.3scale.net/v1beta1
      kind: Product
      metadata:
        name: product1
      spec:
        name: "OperatedProduct 1"
        systemName: "operatedproduct1"
        backendUsages:
          backend1:
            path: /
      • ファイルを作成すると、operator はステップが成功したかどうかを確認します。
      • Product カスタムリソースのフィールドおよび設定可能な値の詳細は、Product CRD field Reference を参照してください。
    2. カスタムリソースを作成します。

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

    • オブジェクトの ステータス フィールドを確認する。
    • oc wait コマンドを使用する。

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

6.6. テナントカスタムリソースのデプロイ

テナントカスタムリソースは、プロバイダーアカウント とも呼ばれます。

APIManager カスタムリソースを作成すると、3scale をデプロイすることが operator に示されます。デフォルトの 3scale インストール環境には、使用可能なデフォルトのテナントが含まれます。オプションで、その他のテナントを作成してテナントカスタムリソースオブジェクトを作成することができます。

前提条件

3scale インスタンスに新規テナントをデプロイするには、準備手順が必要です。

  1. 3scale マスタークレデンシャルシークレット MASTER_SECRET を取得または作成します。

    テナント管理タスクは、3scale マスターアカウントのクレデンシャルを使用してのみ実行できます (アクセストークンの使用が推奨されます)。以下のオプションを使用できます。

    • テナントリソースが 3scale と同じ namespace に作成される場合には、system-seed と呼ばれるマスターアカウントのクレデンシャルを使用するシークレットがすでに作成されています。
    • テナントリソースが 3scale と同じ namespace に作成されない場合には、マスターアカウントのクレデンシャルでシークレットを作成します。以下のコマンドでは、シークレットの名前は任意です。シークレット名はテナントカスタムリソースで使用されます。

      oc create secret generic system-seed --from-literal=MASTER_ACCESS_TOKEN=<master access token>
  2. 新規テナントの管理アカウントのパスワードを保存する新しいシークレット ADMIN_SECRET を作成します。以下のコマンドでは、シークレットの名前は任意です。シークレット名はテナントカスタムリソースで使用されます。

    oc create secret generic ecorp-admin-secret --from-literal=admin_password=<admin password value>
  3. 3scale マスターアカウントのホスト名 MASTER_HOSTNAME を取得します。operator を使用して 3scale をデプロイする場合、マスターアカウントには、master.${wildcardDomain} のパターンの固定 URL があります。

    • 3scale がインストールされている namespace にアクセスできる場合は、マスターアカウントのホスト名を取得します。

      oc get routes --field-selector=spec.to.name==system-master -o jsonpath="{.items[].spec.host}"

手順

  1. 新規テナントカスタムリソースをデプロイします。

    apiVersion: capabilities.3scale.net/v1alpha1
    kind: Tenant
    metadata:
      name: ecorp-tenant
    spec:
      username: admin
      systemMasterUrl: https://<MASTER_HOSTNAME>
      email: admin@ecorp.com
      organizationName: ECorp
      masterCredentialsRef:
        name: <MASTER_SECRET>
      passwordCredentialsRef:
        name: <ADMIN_SECRET*>
      tenantSecretRef:
        name: tenant-secret
  2. テナントリソースを作成します。

    oc create -f <yaml-name>
    • このコマンドにより、3scale ソリューションでの新規テナントの作成がトリガーされます。
    • 3scale operator は新しいシークレットを作成し、新しいテナントのクレデンシャルをシークレットに保存します。
    • 新たなテナントの provider_key および admin domain url はシークレットに保存されます。
    • シークレットの場所は、tenantSecretRef テナント仕様キーを使用して指定できます。

参照として、作成されたシークレットのコンテンツの例を以下に示します。

apiVersion: v1
kind: Secret
metadata:
  name: tenant-secret
type: Opaque
stringData:
  adminURL: https://my3scale-admin.example.com:443
  token: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

テナントカスタムリソースのフィールドおよび設定可能な値の詳細は、Tenant CRD field reference を参照してください。

6.7. 3scale operator を使用した capabilities の制限

Red Hat 3scale API Management 2.10 では、3scale operator には機能に関する以下の制限があります。

  • バックエンドカスタムリソース定義 (CRD) の削除は調整されません。3scale の既存のバックエンドは削除されません。
  • プロダクト CRD の削除は調整されません。3scale の既存プロダクトは削除されません。
  • プロダクト CRD は、管理ポータルおよびデベロッパーポータルのシングルサインオン (SSO) 認証をサポートしません。
  • プロダクト CRD は OpenID Connect の認証をサポートしません。
  • ActiveDocs CRD は現在利用できません。
  • ゲートウェイポリシー CRD は現在利用できません。
  • プロダクト CRD ゲートウェイはレスポンスのカスタムコードおよびエラーをサポートしません。
  • OAS3 を保持する 3scale operator CRD は、3scale プロダクト設定の信頼できるソースとして参照しません。

6.8. その他のリソース

詳細は、以下のガイドを参照してください。

第7章 テンプレートを使用した 3scale のバックアップと復元

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

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

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

7.1. 前提条件

  • 3scale 2.10 インスタンス。3scale のインストール方法については、『3scale のインストール』の「OpenShift への 3scale のインストール」を参照してください。
  • jq: JSON データの抽出または変換用です。
  • OpenShift クラスターの以下のいずれかのロールを持つ OpenShift Container Platform 4 ユーザーアカウント

    • cluster-admin
    • admin
    • edit
注記

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

以降のセクションで、永続ボリューム、データセットの使用、永続データのバックアップ手順の設定、ならびにシステムデータベースおよび OpenShift シークレットの復元について説明します。

7.2. 永続ボリュームおよび考慮事項

永続ボリューム

OpenShift 上の 3scale デプロイメント の場合:

  • ベースとなるインフラストラクチャーによってクラスターに提供される永続ボリューム (PV)
  • クラスター外のストレージサービス。これは、同じデータセンターまたは別のデータセンターに配置することができます。

留意事項

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

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

7.3. データセットの使用

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

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

名前説明

system-mysql

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

system-storage

ファイル用のボリューム

backend-redis

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

system-redis

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

7.3.1. system-mysql の定義

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

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

7.3.2. system-storage の定義

注記

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

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

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

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

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

7.3.3. backend-redis の定義

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

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

7.3.4. system-redis の定義

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

7.4. システムデータベースのバックアップ

以下のコマンドを実行する順序に指定はありませんが、システムデータベースをバックアップしてアーカイブする場合に、必要に応じて使用することができます。

7.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

7.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

7.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

7.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

7.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

7.4.6. OpenShift シークレットおよび ConfigMap のバックアップ

OpenShift シークレットおよび ConfigMap のコマンドリストを以下に示します。

7.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

7.4.6.2. ConfigMaps

oc get configmaps system-environment -o json > system-environment.json
oc get configmaps apicast-environment -o json > apicast-environment.json

7.5. システムデータベースの復元

重要

system-app のように Pod をスケールダウンしたり、ルートを無効にしたりして、レコードが作成されないようにします。

OpenShift シークレットおよびシステムデータベースを復元するには、以下の手順を使用します。

7.5.1. テンプレートベースのデプロイメントの復元

テンプレートベースのデプロイメントを復元するには、以下の手順に従います。

手順

  1. デプロイ用テンプレートを作成する前に、シークレットを復元します。
oc apply -f system-smtp.json
  1. テンプレートパラメーターは、コピーされたシークレットおよび configmaps から読み込まれます。

    oc new-app --file /opt/amp/templates/amp.yml \
        --param APP_LABEL=$(cat system-environment.json | jq -r '.metadata.labels.app') \
        --param TENANT_NAME=$(cat system-seed.json | jq -r '.data.TENANT_NAME' | base64 -d) \
        --param SYSTEM_DATABASE_USER=$(cat system-database.json | jq -r '.data.DB_USER' | base64 -d) \
        --param SYSTEM_DATABASE_PASSWORD=$(cat system-database.json | jq -r '.data.DB_PASSWORD' | base64 -d) \
        --param SYSTEM_DATABASE=$(cat system-database.json | jq -r '.data.URL' | base64 -d | cut -d '/' -f4) \
        --param SYSTEM_DATABASE_ROOT_PASSWORD=$(cat system-database.json | jq -r '.data.URL' | base64 -d | awk -F '[:@]' '{print $3}') \
        --param WILDCARD_DOMAIN=$(cat system-environment.json | jq -r '.data.THREESCALE_SUPERDOMAIN') \
        --param SYSTEM_BACKEND_USERNAME=$(cat backend-internal-api.json | jq '.data.username' -r | base64 -d) \
        --param SYSTEM_BACKEND_PASSWORD=$(cat backend-internal-api.json | jq '.data.password' -r | base64 -d) \
        --param SYSTEM_BACKEND_SHARED_SECRET=$(cat system-events-hook.json | jq -r '.data.PASSWORD' | base64 -d) \
        --param SYSTEM_APP_SECRET_KEY_BASE=$(cat system-app.json | jq -r '.data.SECRET_KEY_BASE' | base64 -d) \
        --param ADMIN_PASSWORD=$(cat system-seed.json | jq -r '.data.ADMIN_PASSWORD' | base64 -d) \
        --param ADMIN_USERNAME=$(cat system-seed.json | jq -r '.data.ADMIN_USER' | base64 -d) \
        --param ADMIN_EMAIL=$(cat system-seed.json | jq -r '.data.ADMIN_EMAIL' | base64 -d) \
        --param ADMIN_ACCESS_TOKEN=$(cat system-seed.json | jq -r '.data.ADMIN_ACCESS_TOKEN' | base64 -d) \
        --param MASTER_NAME=$(cat system-seed.json | jq -r '.data.MASTER_DOMAIN' | base64 -d) \
        --param MASTER_USER=$(cat system-seed.json | jq -r '.data.MASTER_USER' | base64 -d) \
        --param MASTER_PASSWORD=$(cat system-seed.json | jq -r '.data.MASTER_PASSWORD' | base64 -d) \
        --param MASTER_ACCESS_TOKEN=$(cat system-seed.json | jq -r '.data.MASTER_ACCESS_TOKEN' | base64 -d) \
        --param RECAPTCHA_PUBLIC_KEY="$(cat system-recaptcha.json | jq -r '.data.PUBLIC_KEY' | base64 -d)" \
        --param RECAPTCHA_PRIVATE_KEY="$(cat system-recaptcha.json | jq -r '.data.PRIVATE_KEY' | base64 -d)" \
        --param SYSTEM_REDIS_URL=$(cat system-redis.json | jq -r '.data.URL' | base64 -d) \
        --param SYSTEM_MESSAGE_BUS_REDIS_URL="$(cat system-redis.json | jq -r '.data.MESSAGE_BUS_URL' | base64 -d)" \
        --param SYSTEM_REDIS_NAMESPACE="$(cat system-redis.json | jq -r '.data.NAMESPACE' | base64 -d)" \
        --param SYSTEM_MESSAGE_BUS_REDIS_NAMESPACE="$(cat system-redis.json | jq -r '.data.MESSAGE_BUS_NAMESPACE' | base64 -d)" \
        --param ZYNC_DATABASE_PASSWORD=$(cat zync.json | jq -r '.data.ZYNC_DATABASE_PASSWORD' | base64 -d) \
        --param ZYNC_SECRET_KEY_BASE=$(cat zync.json | jq -r '.data.SECRET_KEY_BASE' | base64 -d) \
        --param ZYNC_AUTHENTICATION_TOKEN=$(cat zync.json | jq -r '.data.ZYNC_AUTHENTICATION_TOKEN' | base64 -d) \
        --param APICAST_ACCESS_TOKEN=$(cat system-master-apicast.json | jq -r '.data.ACCESS_TOKEN' | base64 -d) \
        --param APICAST_MANAGEMENT_API=$(cat apicast-environment.json | jq -r '.data.APICAST_MANAGEMENT_API') \
        --param APICAST_OPENSSL_VERIFY=$(cat apicast-environment.json | jq -r '.data.OPENSSL_VERIFY') \
        --param APICAST_RESPONSE_CODES=$(cat apicast-environment.json | jq -r '.data.APICAST_RESPONSE_CODES') \
        --param APICAST_REGISTRY_URL=$(cat system-environment.json | jq -r '.data.APICAST_REGISTRY_URL')

7.5.2. operator ベースのデプロイメントの復元

operator ベースのデプロイメントを復元するには、以下の手順に従います。

手順

  1. 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
  2. APIManager リソースを作成する前に、ConfigMaps を復元します。

    oc apply -f system-environment.json
    oc apply -f apicast-environment.json

7.5.3. system-mysql の復元

手順

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

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

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

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

7.5.4. 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

7.5.4.1. backend-redis および system-redis での 3scale オプションの復元

3scale を復元すると、backend-redis および system-redis が復元されます。これらのコンポーネントには以下があります。

*backend-redis: 3scale のアプリケーション認証とレート制限をサポートするデータベース。また、統計ストレージや一時的なジョブストレージにも使用されます。 *system-redis :3scaleのバックグラウンドジョブ用の一時ストレージを提供し、のRubyプロセスのメッセージバスとしても使用されます。system-appポッド。

backend-redis コンポーネント

backend-redis コンポーネントには、dataqueues の 2 つのデータベースがあります。デフォルトの 3scale デプロイメントでは、data および queues は、異なる論理データベースインデックス /0 および /1 で、Redis データベースにデプロイされます。data データベースの復元は問題なく実行されますが、queues データベースを復元すると、ジョブが重複してしまう可能性があります。

3scale では、ジョブの重複に関して、バックエンドワーカーがバックグラウンドジョブを数ミリ秒で処理します。最後のデータベーススナップショットの 30 秒後に backend-redis が失敗し、そのスナップショットを復元しようとすると、バックエンドには重複を防ぐためのシステムがないため、30 秒の間に発生したバックグラウンドジョブは 2 回実行されます。

このシナリオでは、/0 データベースインデックスにその他の場所に保存されないデータが含まれているため、バックアップを復元する必要があります。/0 データベースインデックスを復元すると、/1 データベースインデックスを復元する必要もあります。どちらか 1 つだけを復元することはできません。異なるインデックスの 1 つのデータベースではなく異なるサーバー上のデータベースを分離する場合、キューのサイズはほぼ 0 になるので、バックアップを復元せず、バックグラウンドジョブの一部を失わないようにすることが推奨されます。これは、ホスト型 3scale の設定に該当するため、両方に異なるバックアップおよび復元ストラテジーを適用する必要があります。

`system-redis` コンポーネント

3scale システムのバックグラウンドジョブの大半は冪等です。つまり、同一のリクエストは何回実行しても同じ結果を返します。

以下は、システムのバックグラウンドジョブによって処理されるイベントの例です。

  • 終了間近であるプランの試用期間、期限切れ間近のクレジットカード、アクティベーションのリマインダー、プランの変更、請求書の状態の変更、PDF 報告書などの通知ジョブ。
  • 請求や課金などの請求書作成。
  • 複雑なオブジェクトの削除。
  • バックエンドの同期ジョブ。
  • インデックス作成ジョブ (sphinx など)。
  • サニタイズジョブ (請求書 ID など)。
  • 監査、ユーザーセッション、期限切れのトークン、ログエントリーの消去や、非アクティブなアカウントの一時停止などの管理タスク。
  • トラフィックの更新。
  • プロキシー設定変更の監視とプロキシーデプロイメント。
  • バックグラウンドサインアップジョブ。
  • シングルサインオン (SSO) の同期、ルートの作成などの Zync ジョブ。

上記のバックグラウンドジョブのリストを復元する場合、3scale のシステムは復元された各ジョブの状態を維持します。復元が完了した後にシステムの整合性を確認することが重要です。

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

backend-redis の復元後、システム からの設定情報と同期させ、バックエンド の情報と 信頼できるソース である システム の情報の一貫性を確保する必要があります。

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

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

手順

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

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

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

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

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

    oc rollout status dc/backend-redis
  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'
  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'
  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
  9. backend-redis を再デプロイして、バックアップを読み込みます。

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

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

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

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

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

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

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

    oc rollout status dc/backend-redis

7.5.5.2. system-redis のデプロイメント設定の管理

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

手順

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

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

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

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

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

    oc rollout status dc/system-redis
  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'
  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'
  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
  9. system-redis を再デプロイして、バックアップを読み込みます。

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

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

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

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

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

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

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

    oc rollout status dc/system-redis

7.5.6. backend-worker の復元

最新バージョンの backend-worker に復元します。

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

    oc rollout status dc/backend-worker

7.5.7. system-app の復元

最新バージョンの system-app に復元します。

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

    oc rollout status dc/system-app

7.5.8. system-sidekiq の復元

  1. 最新バージョンの system-sidekiq に復元します。

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

    oc rollout status dc/system-sidekiq

7.5.8.1. system-sphinx の復元

  1. 最新バージョンの system-sphinx に復元します。

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

    oc rollout status dc/system-sphinx

7.5.8.2. Zync によって管理される OpenShift ルートの復元

  1. 不足している 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'

第8章 operator を使用した 3scale のバックアップと復元

本章では、APIManager カスタムリソース (CR) を使用してデプロイされた Red Hat 3scale API Management インストールのバックアップおよび復元機能について説明します。ここでは、CRD は 3scale operator によって提供されます。

operator 機能からのカスタムリソースは、3scale インストールの一部ではありません。このため、3scale インストールのバックアップおよび復元機能の一部としてカスタムリソースは含まれません。

重要

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

前提条件

  • 3scale インストール環境

以降のセクションでは、operator を使用して 3scale のバックアップおよび復元を行う手順を説明します。

8.1. operator を使用した 3scale のバックアップ

以下のセクションでは、APIManager カスタムリソースによってデプロイされた 3scale インストールのバックアップに必要な情報および手順を説明します。

8.1.1. バックアップの可能なシナリオ

バックアップが可能な 3scale インストール設定については、以下のセクションを参照してください。

前提条件

  • 3scale 外部データベースのバックアップ

    • backend-redis
    • system-redis
    • system-database: MySQL または PostgreSQL
  • PVC がバックアップデータを保管するのに十分な容量のプロビジョニング
注記

APIManager を使用してデプロイされた 3scale デプロイメントは、S3 を System の FileStorage として使用してバックアップすることはできません。

8.1.2. バックアップシナリオのスコープ

バックアップ機能は、以下のデータベースが外部で設定されている場合に利用できます。

  • バックエンド Redis データベース
  • システム Redis データベース
  • システムデータベース: MySQL または PostgreSQL

8.1.3. バックアップされるデータ

以下の表は、バックアップされるデータの一覧を示しています。

表8.1 バックアップされるデータ

ObjectObject-type データ

Secret

  • system-smtp
  • system-seed
  • backend-internal-api
  • backend-listener
  • system-events-hook
  • system-app
  • system-recaptcha
  • zync
  • system-master-apicast
  • system-memcache
  • system-database
  • backend-redis
  • system-redis

ConfigMaps

  • system-environment
  • apicast-environment

APIManager

APIManager カスタムリソース Kubernetes オブジェクト定義: json スキーマ定義

System FileStorage

System FileStorage の場所が PersistentVolumeClaim (PVC) にある場合

8.1.4. 3scale のバックアップ

既存の APIManager を使用してデプロイされた 3scale インストールのバックアップを作成するには、以下の手順に従います。

手順

  1. 以下の Kubernetes Secret のバックアップを作成します。

    • backend-redis
    • system-redis
    • system-database
  2. 例 1 に示すように、APIManager オブジェクトで管理される 3scale インストールがデプロイされるのと同じ namespace に、APIManagerBackup カスタムリソースを作成します。

    例 1

      apiVersion: apps.3scale.net/v1alpha1
      kind: APIManagerBackup
      metadata:
       name: example-apimanagerbackup-pvc
      spec:
        backupDestination:
          persistentVolumeClaim:
            resources:
              requests: "10Gi"

    例 2 は、既存の PersistentVolume 名を提供します。

      apiVersion: apps.3scale.net/v1alpha1
      kind: APIManagerBackup
      metadata:
       name: example-apimanagerbackup-pvc
      spec:
        backupDestination:
          persistentVolumeClaim:
            # resources specification is required but ignored when providing a volumeName as per K8s PVCs requirements behavior
            resources:
              requests: "10Gi"
            volumeName: "my-preexisting-persistent-volume"

  3. APIManagerBackup 完了するまで待ちます。APIManagerBackup の内容を取得し .status.completed フィールドが true に設定されるまで待機して、これを確認します。

バックアップの内容の詳細は、「バックアップされるデータ」を参照してください。

APIManagerBackup のステータスセクションのその他のフィールドは、設定されたバックアップ先が PVC の場合にデータがバックアップされている PVC の名前等、バックアップの詳細が表示されます。

後で参照するために、status.backupPersistentVolumeClaimName フィールドの値を書き留めておきます。APIManagerRestoreAPIManager インストールを復元する場合、必要なフィールドの 1 つは PersistentVolumeClaimName バックアップソースです。

8.2. operator を使用した 3scale の復元

以下のセクションでは、APIManager カスタムリソースによってデプロイされ APIManagerBackup によりバックアップを行っている 3scale インストールの復元に必要な情報および手順を説明します。

8.2.1. 復元の可能なシナリオ

復元が可能な 3scale インストール設定については、以下のセクションを参照してください。

前提条件

  • 3scale 外部データベースの復元

    • backend-redis
    • system-redis
    • system-database: MySQL または PostgreSQL

8.2.2. 復元シナリオのスコープ

3scale operator の復元機能は、APIManagerBackup カスタムリソースから生成されたバックアップを使用して利用できます。

バックアップ可能な 3scale ソリューションのシナリオのリストは、「バックアップされるデータ」を参照してください。

以下は、operator の復元機能のスコープではありません。

  • APIManagerBackup カスタムリソースを使用せずに実行されたバックアップデータの復元
  • 異なる 3scale バージョンの APIManagerBackup から提供されたバックアップデータの復元

8.2.3. 復元されるデータ

以下の表は、復元されるデータの一覧を示しています。

表8.2 復元されるデータ

ObjectObject-type データ

Secret

  • system-smtp
  • system-seed
  • backend-internal-api
  • system-events-hook
  • system-app
  • system-recaptcha
  • zync
  • system-master-apicast

ConfigMaps

  • system-environment
  • apicast-environment

APIManager

APIManager カスタムリソース Kubernetes オブジェクト定義: json スキーマ定義

System FileStorage

System FileStorage の場所が PersistentVolumeClaim (PVC) にある場合

Routes

3scale 関連の OpenShift ルート (例: マスターおよびテナント)

8.2.4. 3scale の復元

APIManager によってデプロイされ APIManagerBackup カスタムリソースによりバックアップを行っている 3scale インストールを復元するには、以下の手順に従います。

  1. 復元を実行するプロジェクトには APIManager カスタムリソースとそれに対応する 3scale インストールが含まれないようにします。
  2. 以下の Kubernetes シークレットを復元します。

    • backend-redis
    • system-redis
    • system-database
  3. APIManagerRestore カスタムリソースを作成し、前の手順で APIManagerBackup カスタムリソースによってバックアップを行ったインストールのバックアップデータを指定します。

    詳細は、「バックアップシナリオのスコープ」を参照してください。

    APIManagerRestore カスタムリソースの例を以下に示します。

      apiVersion: apps.3scale.net/v1alpha1
      kind: APIManagerRestore
      metadata:
        name: example-apimanagerrestore-pvc
      spec:
       restoreSource:
         persistentVolumeClaim:
           claimSource:
             claimName: example-apimanagerbackup-pvc # Name of the PVC produced as the backup result of an `APIManagerBackup`
             readOnly: true
  4. APIManagerRestore 完了するまで待ちます。APIManagerRestore の内容を取得し .status.completed フィールドが true に設定されるまで待機して、これを確認します。

    新しい APIManager カスタムリソースが作成され、3scale インストールがデプロイされたことが確認できるはずです

第9章 3scale 用 reCAPTCHA の設定

本章では、オンプレミス型 Red Hat 3scale API Management に reCAPTCHA を設定して、スパムから保護する方法を説明します。

前提条件

  • サポート対象バージョンの OpenShift にインストールされた設定済みのオンプレミス型 3scale インスタンス
  • reCAPTCHA v2 のサイトキーと秘密鍵を取得していること。「新しいサイトを登録する」の Web ページを参照してください。
  • ドメイン名の検証を使用する場合は、デベロッパーポータルのドメインを許可リストに追加します。

3scale に reCAPTCHA を設定するには、以下の手順に概略を示すステップを実施します。

9.1. 3scale のスパム保護用 reCAPTCHA の設定

スパム保護に reCAPTCHA を設定するには、reCAPTCHA が含まれるシークレットファイルにパッチを適用する方法が 2 つあります。これらのオプションには、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"}}'

手順後のステップ

  • 上記のいずれかのオプションが完了したら、システム 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

その他のリソース

  • 詳細、ガイド、およびサポートについては、ReCAPTCHA のホームページを参照してください。

第10章 API インフラストラクチャーに関するトラブルシューティング

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

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

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

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

以下のセクションを参照して、発生する可能性のある典型的な問題の特定および修正を行います。

10.1. インテグレーションに関する典型的な問題

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

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

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

10.1.1.1. Hosted APIcast

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

  • Test request failed: execution expired

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

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

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

  • Test request failed with HTTP code XXX

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

10.1.1.2. Self-managed APIcast

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

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

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

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

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

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

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

  • service not found for host apicast.example.com

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

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

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

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

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

10.1.2. 実稼働環境の問題

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

10.1.2.1. 可用性の問題

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

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

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

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

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

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

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

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

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

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

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

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

10.1.3. デプロイ後の問題

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

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

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

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

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


* Closing connection #0

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

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

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

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

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

これらをすべて確認してもなお問題の原因と解決策が見つからない場合は、「API へのリクエストに関する問題の特定」で説明するより詳細なトラブルシューティングに進む必要があります。問題のある箇所の特定を試みるため、API から始めてクライアントまで遡って作業します。

10.2. API インフラストラクチャーに関する問題への対応

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

10.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.
  • 接続できない場合
telnet su1.3scale.net 443
Trying 174.129.235.69...
telnet: Unable to connect to remote host: Connection timed out

10.2.2. サーバー接続の問題

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

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

10.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」をブロックします

10.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)
    ---
  • SSLv3 のサポート (3scale ではサポートされません)

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

    出力

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

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

10.3. API へのリクエストに関する問題の特定

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

10.3.1. API

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

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

10.3.2. API ゲートウェイ > API

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

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

10.3.3. API ゲートウェイ

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

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

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

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

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

10.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"
  • 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"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  resolver 8.8.8.8 8.8.4.4;

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

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

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

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

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

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

10.3.4.3. API ゲートウェイが 3scale を正しく呼び出しているか調べる

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

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

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

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

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

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

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

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

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

両方がオリジナルのリクエスト (GET /api/contacts.json?access_token=7c6f24f5) とサブリクエストの位置 (/threescale_authrep)、ならびにアップストリームリクエスト (upstream: "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 に行った実際のリクエストも確認できます。

10.3.5. 3scale

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

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

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

たとえば、以下のように 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

10.3.5.3. インテグレーションエラーを確認する

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

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

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

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

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

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

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

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

10.3.7. クライアント

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

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

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

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

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

10.4. ActiveDocs の問題

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

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

10.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 のバージョンに関する既知の問題を確認できます。

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

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

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

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

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

10.4.4. 呼び出しを比較する

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

10.5. NGINX でのロギング

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

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

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

10.6. 3scale のエラーコード

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

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

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

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

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

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

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

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

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

  • 403
  • 404