self-managed デプロイメントオプションの 1 つを使用してる場合 は、GUI から設定を保存し、Staging Public Base URL フィールドまたは Production Public Base URL フィールドに正しいホストを追加して、デプロイされた API ゲートウェイをポイントするようにします。運用ゲートウェイへの呼び出しを行う前に、Promote v.x to Production ボタンをクリックします。

ステージングセクションの最後にある curl コマンドの例を確認し、コンソールからコマンドを実行します。

curl "https://XXX.staging.apicast.io:443/v1/word/good.json?user_key=YOUR_USER_KEY"

これで API が 3scale と統合されました。

3scale Hosted APIcast ゲートウェイはクレデンシャルを検証し、アプリケーションのアプリケーションプランで定義した流量制御を適用します。クレデンシャルがない、あるいは無効なクレデンシャルで呼び出しを行うと、エラーメッセージが表示されます。メッセージのコードとテキストは設定できます。詳細については、高度な APIcast 設定 の記事を参照してください。

APIcast デプロイメントに分散トレーシング機能を追加するには、以下の前提条件が満たされている必要があります。

OpenTracing を設定するには、以下の環境変数を使用します。

これらの変数に関する詳細は、APIcast の環境変数 を参照してください。

インテグレーションが適切に機能しているかどうかをテストするには、トレースが Jaeger トレースインターフェースで報告されるかどうかを確認する必要があります。

OpenTracing および Jaeger インテグレーションは、アップストリームプロジェクト (https://github.com/3scale/apicast) で公開されています。

本セクションでは、実行中の OpenShift インスタンスへの Jaeger のインストールについて説明します。

Jaeger の設定は、以下を参照してください。* Jaeger on OpenShift development setup * Jaeger on OpenShift production setup * Distributed tracing on OpenShift Service Mesh を参照してください。

docker run コマンドでは、以下のオプションを使用できます。

使用できるオプションの詳細については、Docker run reference を参照してください。

docker: Cannot connect to the Docker daemon.Is the docker daemon running on this host? というエラーメッセージが表示された場合には、Docker サービスが起動していない可能性があります。sudo systemctl status docker.service コマンドを実行して、Docker デーモンのステータスを確認することができます。

RHEL で Docker コンテナー環境の操作を行う場合、デフォルトでは root 権限が必要なので、このコマンドは必ず root ユーザーとして実行してください。詳細については、このドキュメント を参照してください。

デタッチモードでコンテナーを起動し (-d オプション)、実行中の APIcast インスタンスのログを確認する場合には、log コマンド (sudo docker logs <container>) を使用することができます。ここで、<container> はコンテナー名 (上記の例では「apicast」) またはコンテナー ID です。sudo docker ps コマンドを使用して、実行中のコンテナーならびにその ID および名前を一覧表示することができます。

コンテナーを停止するには、sudo docker stop <container> コマンドを実行します。sudo docker rm <container> コマンドを実行して、コンテナーを削除することもできます。

使用できるコマンドの詳細は、Docker コマンドのリファレンス を参照してください。

Red Hat が提供する Docker 形式のコンテナーイメージは、RHEL の Extras チャンネルの一部としてリリースされています。追加のリポジトリーを有効にするには、Subscription Manager または yum-config-manager を使用できます。詳細は、RHEL の製品ドキュメント を参照してください。

AWS EC2 インスタンスにデプロイされた RHEL 7 では、以下の手順を使用します。

以下のコマンドを使用すると、コンテナーサービスが実行していることを確認できます。

sudo systemctl status docker

OpenShift リリースページ から、クライアントツールの最新の安定版リリース (openshift-origin-client-tools-VERSION-linux-64bit.tar.gz) をダウンロードし、アーカイブから抽出した Linux oc バイナリーを PATH に置きます。

docker コマンドを実行する権限のあるユーザーでターミナルを開き、以下のコマンドを実行します。

oc cluster up

出力の最後に、デプロイされたクラスターの情報が表示されます。

    -- Server Information ...
      OpenShift server started.
      The server is accessible via web console at:
      https://172.30.0.112:8443

      You are logged in as:
        User:     developer
        Password: developer

      To login as administrator:
        oc login -u system:admin

OpenShift サーバーに割り当てられた IP アドレスを書き留めておきます。本チュートリアルでは OPENSHIFT-SERVER-IP をその IP アドレスに置き換えてください。

oc cluster up --public-hostname=ec2-54-321-67-89.compute-1.amazonaws.com --routing-suffix=54.321.67.89.xip.io

3scale Auth Caching ポリシーは、APIcast に送信された認証呼び出しをキャシュします。動作モードを選択して、キャッシュ操作を設定することができます。

3scale Auth Caching では、以下のモードを使用することができます。

1.strict: 承認された呼び出しだけをキャッシュします。

「strict」モードでは、承認された呼び出しだけがキャッシュされます。ポリシーを「strict」モードで実行中に呼び出しが失敗または拒否されると、ポリシーはキャッシュエントリーを無効にします。バックエンドにアクセスできなくなると、キャッシュステータスにかかわらず、キャッシュされたすべての呼び出しが拒否されます。

2.resilient: バックエンドの機能が停止している場合には、最後のリクエストに基づいて承認します。

「resilient」モードでは、承認された呼び出しおよび拒否された呼び出しの両方がキャッシュされます。ポリシーを「resilient」モードで実行中は、呼び出しに失敗しても既存のキャッシュエントリーは無効になりません。バックエンドにアクセスできなくなると、キャッシュにヒットする呼び出しは、キャッシュステータスに応じて承認/拒否の状態を維持します。

3.allow: バックエンドの機能が停止している場合には、過去に拒否されていない限りすべてを許可します。

「allow」モードでは、承認された呼び出しおよび拒否された呼び出しの両方がキャッシュされます。ポリシーを「allow」モードで実行中は、キャッシュされた呼び出しはキャッシュステータスに応じて拒否/許可の状態を維持します。ただし、新規の呼び出しは承認された呼び出しとしてキャッシュされます。

4.none: キャッシュを無効にします。

「none」モードでは、キャッシュが無効になります。ポリシーを有効にしたままキャッシュの使用を止める場合に、このモードが役立ちます。

設定プロパティー

ポリシーオブジェクトの例

{
  "name": "caching",
  "version": "builtin",
  "configuration": {
    "caching_type": "allow"
  }
}

ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。

標準の APIcast 承認メカニズムでは、APIcast が API リクエストを受け取るたびに、3scale バックエンド (Service Management API) に対して 1 回呼び出しが行われます。3scale Batcher ポリシーは、この標準メカニズムの代替手段を提供します。

3scale Batcher ポリシーを使用すると、3scale バックエンドへのリクエスト数が大幅に削減され、レイテンシーが減少しスループットが向上します。そのために、このポリシーは承認ステータスをキャッシュし、使用状況レポートをバッチ処理します。

3scale Batcher ポリシーが有効な場合には、APIcast は以下のフローを使用して承認を行います。

3scale Batcher ポリシーではスループットが向上しますが、精度は低下します。使用上限および現在の使用状況は 3scale に保存され、APIcast は 3scale バックエンドに呼び出しを行う時にのみ正しい承認ステータスを取得することができます。3scale Batcher ポリシーが有効な場合には、APIcast が 3scale に呼び出しを送信しない期間があります。この期間中、呼び出しを行うアプリケーションが定義された限度を超える可能性があります。

流量制御の精度よりもスループットが重要な場合には、高負荷の API に対してこのポリシーを使用します。報告頻度および承認の TTL が流量制御の期間よりはるかに短い場合には、3scale Batcher ポリシーにより優れた精度が得られます。たとえば、流量制御が 1 日あたりで、報告頻度および承認の TTL が数分に設定されている場合などです。

3scale Batcher ポリシーでは、以下の構成設定がサポートされます。

Anonymous Access ポリシーでは、認証をせずにサービスが公開されます。このポリシーは、認証パラメーターを送信するように変更することのできないレガシーアプリケーション等の場合に有用です。Anonymous ポリシーは、API キーおよびアプリケーション ID/アプリケーションキーによる認証オプションを使用するサービスしかサポートしません。クレデンシャルをまったく持たない API リクエストに対してこのポリシーを有効にした場合には、APIcast はポリシーで設定されたデフォルトのクレデンシャルを使用して呼び出しを承認します。API の呼び出しが承認されるためには、クレデンシャルが設定されたアプリケーションが存在しアクティブでなければなりません。

アプリケーションプランを使用して、デフォルトのクレデンシャルに使用されるアプリケーションに流量制御を設定することができます。

ポリシーに必要な設定プロパティーを以下に示します。

図5.1 Anonymous Access ポリシー

Cross Origin Resource Sharing (CORS) request handling ポリシーを使用すると、以下の項目を指定することができるので CORS の動作の制御が可能です。

CORS Request Handling ポリシーにより、指定されていない CORS リクエストはすべてブロックされます。

設定プロパティー

ポリシーオブジェクトの例

{
  "name": "cors",
  "version": "builtin",
  "configuration": {
    "allow_headers": [
      "App-Id", "App-Key",
      "Content-Type", "Accept"
    ],
    "allow_credentials": true,
    "allow_methods": [
      "GET", "POST"
    ],
    "allow_origin": "https://example.com"
  }
}

ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。

Echo ポリシーは、受信したリクエストを出力してクライアントに返します。また、オプションで任意の HTTP ステータスコードを返します。

構成プロパティー

ポリシーオブジェクトの例

{
  "name": "echo",
  "version": "builtin",
  "configuration": {
    "status": 404,
    "exit": "request"
  }
}

ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。

Edge Limiting ポリシーの目的は、バックエンド API に送信されるトラフィックに対する柔軟な流量制御を提供することで、このポリシーをデフォルトの 3scale 承認メカニズムと共に使用することができます。このポリシーでサポートされるユースケースの例を以下に示します。

{
  "key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
  "count": 10,
  "window": 60
}

"condition": {
  "combine_op": "and",
  "operations": [
    {
      "op": "==",
      "right": "GET",
      "left_type": "liquid",
      "left": "{{ http_method }}",
      "right_type": "plain"
    }
  ]
}

Header Modification ポリシーを使用すると、受信したリクエストまたはレスポンスに関して、既存のヘッダーを変更する、補足のヘッダーを定義して追加する、またはヘッダーを削除することができます。レスポンスヘッダーおよびリクエストヘッダーの両方を変更することができます。

Header Modification ポリシーでは、以下の設定パラメーターがサポートされます。

それぞれの操作は、以下のパラメーターで構成されます。

ポリシーオブジェクトの例

{
  "name": "headers",
  "version": "builtin",
  "configuration": {
    "response": [
      {
        "op": "add",
        "header": "Custom-Header",
        "value_type": "plain",
        "value": "any-value"
      }
    ],
    "request": [
      {
        "op": "set",
        "header": "Authorization",
        "value_type": "plain",
        "value": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
      },
      {
        "op": "set",
        "header": "Service-ID",
        "value_type": "liquid",
        "value": "{{service.id}}"
      }
    ]
  }
}

ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。

IP Check ポリシーは、IP のリストに基づいてリクエストを拒否または許可するために使用します。

構成プロパティー

ポリシーオブジェクトの例

{
  "name": "ip_check",
  "configuration": {
    "ips": [ "3.4.5.6", "1.2.3.0/4" ],
    "check_type": "blacklist",
    "client_ip_sources": ["X-Forwarded-For", "X-Real-IP", "last_caller"],
    "error_msg": "A custom error message"
  }
}

ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。

このポリシーは JSON を使用して API リクエストに応答します。コンテキストで利用可能なオブジェクトおよび値を含み、Liquid テンプレートの評価に使用することができます。3scale APIcast または Upstream ポリシーと組み合わせる場合には、正常な動作のためにポリシーチェーンではこれらのポリシーの前に Liquid Context Debug ポリシーを設定する必要があります。循環参照を避けるために、ポリシーには重複するオブジェクトは 1 回だけ含め、それをスタブ値で置き換えます。

このポリシーが有効な時に APIcast が返す値の例を以下に示します。

{
  "jwt": {
    "azp": "972f7b4f",
    "iat": 1537538097,
    ...
    "exp": 1537574096,
    "typ": "Bearer"
  },
  "credentials": {
    "app_id": "972f7b4f"
  },
  "usage": {
    "deltas": {
      "hits": 1
    },
    "metrics": [
      "hits"
    ]
  },
  "service": {
    "id": "2",
    ...
  }
  ...
}

Logging ポリシーにより、各 API サービスの APIcast (NGINX) アクセスログを個別に有効または無効にすることができます。デフォルトでは、このポリシーはポリシーチェーンで有効になっていません。

このポリシーは、enable_access_logs 設定パラメーターしかサポートしません。サービスのアクセスロギングを無効にするには、ポリシーを有効にし、enable_access_logs パラメーターの選択を解除して、Submit ボタンをクリックします。アクセスログを有効にするには、enable_access_logs パラメーターを選択するか、Logging ポリシーを無効にします。

Logging ポリシーとアクセスログの場所のグローバル設定を組み合わせることができます。APIcast アクセスログの場所を設定するには、APICAST_ACCESS_LOG_FILE 環境変数を設定します。デフォルトでは、この変数は標準出力デバイスの /dev/stdout に設定されています。グローバル APIcast パラメーターに関する詳細な情報は、「7章APIcast の環境変数」を参照してください。

OAuth 2.0 Token Introspection ポリシーを使用すると、OpenID Connect 認証オプションを用いるサービスに使用される JSON Web Token (JWT) トークンを検証することができます。この場合、トークン発行者 (Red Hat Single Sign-On) のトークンイントロスペクションエンドポイントを使用します。

トークンイントロスペクションエンドポイントおよびそのエンドポイントに呼び出しを行う際に APIcast が使用するクレデンシャルを定義する場合、auth_type フィールドでは以下の認証タイプがサポートされます。

auth_type フィールドの設定にかかわらず、APIcast は Basic 認証を使用してトークンイントロスペクションの呼び出しを承認します (Authorization: Basic <token> ヘッダー、ここで <token> は Base64 でエンコードされた <client_id>:<client_secret> 設定です)。

トークンイントロスペクションエンドポイントのレスポンスには、active 属性が含まれます。APIcast はこの属性の値を確認します。属性の値に応じて、APIcast は呼び出しを承認または拒否します。

このポリシーを使用すると、トークンのキャッシュを有効にして、同じ JWT トークンに対する呼び出しのたびにトークンイントロスペクションエンドポイントに呼び出しを行うのを避けることができます。Token Introspection ポリシーのトークンキャッシュを有効にするには、max_cached_tokens フィールドを 0 (機能は無効) から 10000 までの値に設定します。さらに、max_ttl_tokens フィールドで、トークンの残存期間 (TTL) の値を 1 から 3600 秒に設定することができます。

Referrer ポリシーを使用すると、参照元フィルター機能が有効になります。サービスポリシーチェーンでこのポリシーが有効な場合には、APIcast は今後のリクエストの Referer ポリシーの値を referrer パラメーターで Service Management API (AuthRep 呼び出し) に送信します。参照元フィルター機能の仕組みの詳細については、Authentication Patterns の Referrer Filtering セクションを参照してください。

OpenID Connect 認証オプションと共に使用した場合、このポリシーによりロールの確認機能が追加されます。このポリシーは、Red Hat Single Sign-On により発行されたアクセストークンのレルムロールおよびクライアントロールを確認します。すべてのクライアントのリソースまたは 3Scale にロールチェックを追加する場合は、レルムロールを指定します。

ポリシー設定の type プロパティーで指定するロールの確認には、以下の 2 つのタイプがあります。

同じポリシーに blacklist および whitelist 両方のチェックを設定することはできませんが、APIcast ポリシーチェーンに複数の RH-SSO/Keycloak Role Check ポリシーインスタンスを追加することができます。

ポリシー設定の scopes プロパティーを使用して、スコープのリストを設定することができます。

それぞれの scope オブジェクトには、以下のプロパティーがあります。

Prometheus はスタンドアロンのオープンソースのシステムモニタリングおよびアラート用ツールキットです。

Prometheus メトリクスの可用性

APIcast と Prometheus のインテグレーションは、以下のデプロイメントオプションで利用することができます。

Prometheus メトリクスのリスト

以下のメトリクスは常に使用可能です。

以下のメトリクスは、3scale Batcher ポリシーを使用する場合にのみ使用可能です。

値を持たないメトリクス

メトリクスが値を持たない場合には、メトリクスは非表示になります。たとえば、nginx_error_log に報告するエラーがない場合、nginx_error_log メトリックは表示されません。値を持った場合にのみ表示されます。

SOAP ポリシーでは、ポリシーで指定したマッピングルールを使用して、HTTP リクエストの SOAPAction または Content-Type ヘッダーにより提供される SOAP アクション URI との照合を行います。

設定プロパティー

ポリシーオブジェクトの例

{
  "name": "soap",
  "version": "builtin",
  "configuration": {
    "mapping_rules": [
      {
        "pattern": "http://example.com/soap#request",
        "metric_system_name": "soap",
        "delta": 1
      }
    ]
  }
}

ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。

Upstream ポリシーでは、正規表現を使用して Host リクエストヘッダーを解析し、プライベートベース URL で定義されたアップストリーム URL を別の URL に置き換えることができます。

例:

正規表現 /foo および URL フィールド newexample.com が設定されたポリシーが、URL https://www.example.com/foo/123/ を newexample.com に置き換える

ポリシーチェーンの参照

ポリシーオブジェクトの例

{
  "name": "upstream",
  "version": "builtin",
  "configuration": {
    "rules": [
      {
        "regex": "^/v1/.*",
        "url": "https://api-v1.example.com",

      }
    ]
  }
}

ポリシーの設定方法に関する情報は、本書の「3scale でのポリシーチェーンの作成」セクションを参照してください。

URL Rewriting ポリシーを使用すると、リクエストのパスおよびクエリー文字列を変更することができます。

3scale APIcast ポリシーと組み合わせる場合には、ポリシーチェーンで URL Rewriting ポリシーを 3scale APIcast ポリシーの前に設定すると、APIcast のマッピングルールは変更したパスに適用されます。ポリシーチェーンで URL Rewriting ポリシーを APIcast ポリシーの後に設定すると、マッピングルールは元のパスに適用されます。

このポリシーでは、以下の 2 つの操作セットがサポートされます。

{
  "name": "url_rewriting",
  "version": "builtin",
  "configuration": {
    "query_args_commands": [
      {
        "op": "add",
        "arg": "addarg",
        "value_type": "plain",
        "value": "addvalue"
      },
      {
        "op": "delete",
        "arg": "user_key",
        "value_type": "plain",
        "value": "any"
      },
      {
        "op": "push",
        "arg": "pusharg",
        "value_type": "plain",
        "value": "pushvalue"
      },
      {
        "op": "set",
        "arg": "setarg",
        "value_type": "plain",
        "value": "setvalue"
      }
    ],
    "commands": [
      {
        "op": "sub",
        "regex": "^/api/v\\d+/",
        "replace": "/internal/",
        "options": "i"
      }
    ]
  }

https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original

https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue

URL Rewriting with Captures ポリシーは「URL Rewriting ポリシー」ポリシーの代替で、API リクエストの URL を API バックエンドに渡す前に書き換えることができます。

URL Rewriting with Captures ポリシーは URL の引数を取得し、その値を書き換えられる URL で使用します。

このポリシーでは transformations 設定パラメーターがサポートされます。これは、リクエスト URL に適用される変換を定義するオブジェクトのリストです。それぞれの変換オブジェクトは、以下の 2 つのプロパティーで構成されます。

元の URL のクエリーパラメータは、template で指定したクエリーパラメータとマージされます。

例

URL Rewriting with Captures ポリシーは、以下のように設定します。

{
  "name": "rewrite_url_captures",
  "version": "builtin",
  "configuration": {
    "transformations": [
      {
        "match_rule": "/api/v1/products/{productId}/details",
        "template": "/internal/products/details?id={productId}&extraparam=anyvalue"
      }
    ]
  }
}

APIcast に送信される元のリクエスト URI:

https://api.example.com/api/v1/products/123/details?user_key=abc123secret

URL の書き換えを適用した後に APIcast が API バックエンドに送信する URI:

https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123

オンプレミスデプロイメントにカスタム APIcast ポリシーを追加するには、カスタムポリシーが含まれる OpenShift イメージをビルドし、それをデプロイメントに追加する必要があります。Red Hat 3scale では、サンプルリポジトリーを提供しています。このリポジトリーを、カスタムポリシーを作成してオンプレミスデプロイメントに追加するためのフレームワークとして使用することができます。

このサンプルリポジトリーには、カスタムポリシー用の正しいディレクトリー構造に加えて、イメージストリームを作成するテンプレート、および作成するカスタムポリシーが含まれる新しい APIcast OpenShift イメージをビルドするための BuildConfigs が含まれています。

カスタムポリシーをオンプレミスデプロイメントに追加するには、以下の手順に従います。

Embedded APIcast のイメージに amp-apicast:latest イメージストリームの変更を追跡するトリガーがある場合には、APIcast の新しいデプロイメントが開始されます。apicast-staging が再開されたら管理ポータルの Integration ページに移動し、Add Policy ボタンをクリックしてご自分のカスタムポリシーがリストに表示されるのを確認します。カスタムポリシーを選択して設定したら、Update & test in Staging Environment をクリックし、カスタムポリシーをステージング APIcast で動作状態にします。

カスタムポリシーを OpenShift Container Platform (OCP) 上の APIcast に追加することができます。そのためには、ご自分のカスタムポリシーが含まれる APIcast イメージを 統合 OpenShift Container レジストリー から取得します。

別の OpenShift Container Platform 上の APIcast にカスタムポリシーを追加します