3scale の操作

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

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

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

水平スケーリング

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

垂直スケーリング

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

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

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

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

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

可用性の問題は、通常、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 の可用性の問題が発生する場合、以下が原因の可能性があります。

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

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

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

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

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 を使用できます。

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 サービスのドメイン名を今後追加することもできます。このため、該当する場合は、インテグレーション中に指定された特定のアドレスに対して必ずテストを行う必要があります。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

X-3scale-matched-rules: /, /api/contacts.json
< X-3scale-credentials: access_token=TOKEN_VALUE
< X-3scale-usage: usage[hits]=2
< X-3scale-hostname: HOSTNAME_VALUE

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

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

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

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

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

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

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

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

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

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

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

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

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

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