第4章 APIcast ポリシー

ポリシーチェーンの設定例を以下に示します。

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.camel",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8080/",
          "http_proxy": "http://192.168.15.103:8080/",
          "https_proxy": "http://192.168.15.103:8443/"
      }
    }
]

http_proxy または https_proxy が定義されていない場合は、all_proxy の値が使用されます。

Conditional ポリシーチェーンでポリシーを実行するかどうかを判断する条件は、JSON を使用して表現でき、Liquid テンプレートを使用します。

以下の例では、リクエストパスが /example_path かどうかを確認します。

{
  "left": "{{ uri }}",
  "left_type": "liquid",
  "op": "==",
  "right": "/example_path",
  "right_type": "plain"
}

左側のオペランドと右のオペランドの両方を Liquid または plain 文字列として評価できます。デフォルトは、Plain 文字列です。

and または or を使用した操作を組み合わせることができます。この設定では、以前の例の内容に加え、Backend ヘッダーの値を確認します。

{
  "operations": [
    {
      "left": "{{ uri }}",
      "left_type": "liquid",
      "op": "==",
      "right": "/example_path",
      "right_type": "plain"
    },
    {
      "left": "{{ headers['Backend'] }}",
      "left_type": "liquid",
      "op": "==",
      "right": "test_upstream",
      "right_type": "plain"
    }
  ],
  "combine_op": "and"
}

詳細は、policy config schema を参照してください。

{
   "name":"conditional",
   "version":"builtin",
   "configuration":{
      "condition":{
         "operations":[
            {
               "left":"{{ headers['Backend'] }}",
               "left_type":"liquid",
               "op":"==",
               "right":"staging"
            }
         ]
      },
      "policy_chain":[
         {
            "name":"upstream",
            "version": "builtin",
            "configuration":{
               "rules":[
                  {
                     "regex":"/",
                     "url":"http://my_staging_environment"
                  }
               ]
            }
         }
      ]
   }
}

NGINX の proxy_cache_valid ディレクティブ情報は、APICAST_CACHE_STATUS_CODES および APICAST_CACHE_MAX_TIME ではグローバルにしか設定することができません。タイムアウトに関してアップストリームが異なる動作を要求する場合は、Cache-Control ヘッダーを使用します。

以下のチャートは、認証がキャッシュされていない場合のリクエストフローの例と、認証がキャッシュされている場合のフローを示しています。

このポリシーは、アップストリーム API が 400 のステータスを返すと、ヘッダーインクリメントだけメトリクス error のカウントを増やします。

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "error",
        "increment": "{{ resp.headers['increment'] }}",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "400",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

このポリシーは、アップストリーム API が 200 のステータスを返すと、status_code 情報により hits メトリクスのカウントを増やします。

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "hits_{{status}}",
        "increment": "1",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "200",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

このポリシーでは、lua-resty-limit-traffic ライブラリーにより提供される以下の制限タイプがサポートされます。

すべての制限をサービスごとまたはグローバルに適用することができます。

リミッターはキーを持ち、制限を定義するのに使用するエンティティーをこのキーでエンコードします (IP アドレス、サービス、エンドポイント、ID、特定ヘッダーの値、その他のエンティティー等)。このキーは、リミッターの key パラメーターで指定します。

key は以下のプロパティーで定義されるオブジェクトです。

それぞれの制限は、そのタイプに応じたパラメーターも持ちます。

サービスごとにさまざまな制限を定義することができます。複数の制限を定義した場合には、少なくとも 1 つの制限に達すると、リクエストは拒否または遅延されます。

Edge Limiting ポリシーではキーに Liquid 変数がサポートされるので、動的なキーに制限を指定することができます。そのためには、キーの name_type パラメーターを liquid に設定する必要があります。これにより、name パラメーターに Liquid 変数を使用することができます。たとえば、クライアント IP アドレスの場合は {{ remote_addr }}、JWT トークンの sub クレームの場合は {{ jwt.sub }} を設定します。

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

Liquid のサポートに関する詳細な情報は、「ポリシーでの変数およびフィルターの使用」を参照してください。

各リミッターには、リミッターが適用されるタイミングを定義する条件がなければなりません。条件は、リミッターの condition プロパティーで指定します。

以下のプロパティーで condition を定義します。

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

デフォルトでは、Edge Limiting ポリシーは流量制御カウンターに OpenResty 共有ディクショナリーを使用します。ただし、共有ディクショナリーの代わりに外部の Redis サーバーを使用することができます。この設定は、複数の APIcast インスタンスがデプロイされている場合に役立ちます。redis_url パラメーターを使用して Redis サーバーを設定することができます。

リミッターでは、エラーの処理方法を設定するために以下のパラメーターがサポートされます。

JWT クレームの値に基づいてルーティングするためには、ポリシーチェーンには、ポリシーが共有するコンテキストで JWT を検証してクレームを格納するポリシーが必要です。

JWT Claim Check ポリシーがリソースおよびメソッドをブロックしている場合には、ポリシーは JWT 操作も検証します。一方、メソッドおよびリソースがマッチしない場合には、リクエストはバックエンド API に送信されます。

以下の GET リクエストの例では、JWT には管理者として role クレームが必要です。もしなければ、リクエストは拒否されます。一方、GET 以外のリクエストは JWT 操作を検証しないため、POST リソースは JWT の制約なしに許可されます。

{
  "name": "apicast.policy.jwt_claim_check",
  "configuration": {
      "error_message": "Invalid JWT check",
      "rules": [
          {
              "operations": [
                  {"op": "==", "jwt_claim": "role", "jwt_claim_type": "plain", "value": "admin"}
              ],
              "combine_op":"and",
              "methods": ["GET"],
              "resource": "/resource",
              "resource_type": "plain"
          }
      ]
  }
}

ポリシーチェーンで JWT Claim Check ポリシーを設定するには、以下を行います。

Logging オプションは、API でログが正しくフォーマットされない問題を避けるのに役立ちます。カスタム APIcast 環境変数を設定して、すべての API に Logging ポリシーを実装することができます。すべてのサービスに読み込まれるポリシーの例を以下に示します (custom_env.lua)。

local cjson = require('cjson')
local PolicyChain = require('apicast.policy_chain')
local policy_chain = context.policy_chain

local logging_policy_config = cjson.decode([[
{
  "enable_access_logs": false,
  "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}"
}
]])

policy_chain:insert( PolicyChain.load_policy('logging', 'builtin', logging_policy_config), 1)

return {
  policy_chain = policy_chain,
  port = { metrics = 9421 },
}

この特定の環境を指定して APIcast を実行するには、以下のコマンドを実行します。

docker run --name apicast --rm -p 8080:8080 \
    -v $(pwd):/config \
    -e APICAST_ENVIRONMENT=/config/custom_env.lua \
    -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@ADMIN_PORTAL_DOMAIN \
    quay.io/3scale/apicast:master

考慮すべき Docker コマンドの重要な概念を以下に示します。

本セクションでは、Logging ポリシーを使用した例について説明します。ここに示す例では、以下の条件を考慮しています。

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "[{{time_local}}] {{host}}:{{server_port}} {{remote_addr}}:{{remote_port}} \"{{request}}\" {{status}} {{body_bytes_sent}} ({{request_time}}) {{post_action_impact}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "enable_json_logs": true,
    "json_object_config": [
      {
        "key": "host",
        "value": "{{host}}",
        "value_type": "liquid"
      },
      {
        "key": "time",
        "value": "{{time_local}}",
        "value_type": "liquid"
      },
      {
        "key": "custom",
        "value": "custom_method",
        "value_type": "plain"
      }
    ]
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"}
      ],
      "combine_op": "and"
    }
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"},
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "500"}
      ],
      "combine_op": "or"
    }
  }
}

カスタムロギングでは、エクスポートした変数と共に Liquid テンプレートを使用することができます。この変数の例を以下に示します。

ポリシーチェーンの設定例を以下に示します。

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.http_proxy",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8888/",
          "https_proxy": "https://192.168.15.103:8888/",
          "http_proxy": "https://192.168.15.103:8888/"
      }
    }
]

http_proxy または https_proxy が定義されていない場合は、all_proxy の値が使用されます。

以下の RateLimit ヘッダーがそれぞれのメッセージに追加されます。

デフォルトでは、Rate Limit Headers ポリシーが設定されていない場合やアプリケーションプランに流量制御が設定されていない場合、レスポンスメッセージには流量制御に関するヘッダーがありません。

以下の設定では、パスが /accounts の場合に http://example.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、ヘッダー Test-Header の値が 123 の場合に http://example.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、クエリー引数 test_query_arg の値が 123 の場合に http://example.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "query_arg",
                "query_arg_name": "test_query_arg",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

JWT クレームの値に基づいてルーティングするためには、ポリシーチェーンには、ポリシーが共有するコンテキストで JWT を検証して格納するポリシーが必要です。

以下の設定では、JWT クレーム test_claim の値が 123 の場合に http://example.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "jwt_claim",
                "jwt_claim_name": "test_claim",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

ルールに複数の演算を設定し、すべてが true と評価される場合にだけ (andcombine_op を使用) 指定したアップストリームにルーティングすることや、少なくとも 1 つが true と評価される場合に (orcombine_op を使用) 指定したアップストリームにルーティングすることができます。combine_op のデフォルト値は and です。

以下の設定では、リクエストのパスが /accounts で、かつヘッダー Test-Header の値が 123 の場合に、http://example.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "and",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

以下の設定では、リクエストのパスが /accounts であるか、またはヘッダー Test-Header の値が 123 の場合に、http://example.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "or",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

ルールを組み合わせることができます。複数のルールがある場合、選択されるアップストリームは、true と評価される最初のルールです。

複数のルールで設定される設定を以下に示します。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/users"
              }
            ]
          }
        }
      ]
    }
  }

演算のないルールは常にマッチします。これは、キャッチオールルールを定義するのに役立ちます。

以下の設定では、パスが /abc の場合にはリクエストを http://some_upstream.com にルーティングし、パスが /def の場合には http://another_upstream.com にルーティングし、上記ルールのどちらも true と評価されない場合には http://default_upstream.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/abc"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/def"
              }
            ]
          }
        },
        {
          "url": "http://default_upstream.com",
          "condition": {
            "operations": []
          }
        }
      ]
    }
  }

サポートされる演算は、==、!=、および matches です。最後の演算は正規表現を使用する文字列との照合を行い、ngx.re.match を使用して実装されます。

以下の設定では、!= が使用されています。パスが /accounts ではない場合に http://example.com にルーティングします。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "!=",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

設定の値に liquid テンプレートを使用することができます。これにより、チェーン内のポリシーがコンテキストにキー my_var を保存する場合には、動的な値を使用してルールを定義することができます。

以下の設定では、リクエストをルーティングするのにその値が使用されています。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "{{ my_var }}",
                "value_type": "liquid"
              }
            ]
          }
        }
      ]
    }
  }

リクエストがルーティングされる際に、デフォルトでは、ポリシーはマッチしたルールの URL のホストを使用して Host ヘッダーを設定します。host_header 属性を使用して別のホストを指定することができます。

以下の設定では、Host ヘッダーのホストに some_host.com が指定されています。

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "host_header": "some_host.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/"
              }
            ]
          }
        }
      ]
    }
  }

TLS を終端するように APIcast を設定する必要があります。以下の手順に従って、Client Certificate Validation ポリシーが設定された APIcast でユーザーが提供するクライアント証明書を検証するように設定します。

ポリシーチェーンで TLS Client Certificate Validation を設定するには、以下を行います。

TLS Client Certificate Validation ポリシーの機能を確認するには、以下を実行します。

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/client.crt --key ca/keys/client.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/server.crt --key ca/keys/server.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt

ホワイトリストから証明書を削除するには、以下を行います。

証明書の操作についての詳細は、Red Hat Certificate System のドキュメント を参照してください。

本セクションでは、ポリシーチェーンに TLS Termination ポリシーを設定するための前提条件および手順について説明します。なお、設定には Privacy Enhanced Mail (PEM) 形式の証明書を使用します。

本セクションでは、TLS Termination ポリシーから証明書およびキーファイルを削除する手順について説明します。

本セクションでは、ポリシーチェーンで Upstream Connection ポリシーを設定する手順を説明します。

本セクションでは、ポリシーチェーンで Upstream Mutual TLS ポリシーを設定する手順を説明します。

変更をプロモートするには、以下の手順を実施します。

commands リストの各コマンドは、以下の設定パラメーターで設定されます。

query_args_commands リストの各コマンドは、以下の設定パラメーターで設定されます。

例

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

{
  "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"
      }
    ]
  }

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

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

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

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

以下の変換が適用されます。

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