旧バージョンのドキュメントを参照しています。最新のドキュメントはこちらをご参照ください。

kong.service

サービスモジュールには、特定のホスト、IPアドレス/ポートへの接続、ロードバランシングとヘルスチェックのための特定のアップストリームエンティティの選択など、サービスへの要求の接続側面を操作する一連の関数が含まれています。

kong.service.set_upstream(host)

このリクエストに対して、ロードバランシングの処理を担当する希望のアップストリームエンティティを設定します。このメソッドを使用することは、 host プロパティがアップストリームエンティティと同等のサービスを作成することと同じです（この場合、リクエストは、そのアップストリームに関連するターゲットの 1 つにプロキシされます）。

host引数は、現在設定されているUpstreamエンティティの1つの名前と等しい文字列を受け取る必要があります。

フェーズ

access

パラメータ

ホスト （string）：

戻り値

boolean|nil：trueで成功、または見つかった場所にアップストリームエンティティがない場合は nilとなります。
string|nil: エラーがあった場合、その内容を説明するエラーメッセージ。

使用法

local ok, err = kong.service.set_upstream("service.prod")
if not ok then
  kong.log.err(err)
  return
end

kong.service.set_target(host, port)

リクエストをプロキシするために接続するホストとポートを設定します。このメソッドを使用することは、このリクエストに対して負荷分散フェーズを実行しないようにKongに要求するのと同等であり、手動でオーバーライドすることを検討します。再試行やヘルスチェックのような負荷分散コンポーネントも、このリクエストでは無視される。

The host argument expects the hostname or IP address of the upstream server, and the port expects a port number.

フェーズ

access

パラメータ

ホスト （string）：
port (number):

使用法

kong.service.set_target("service.local", 443)
kong.service.set_target("192.168.130.1", 80)

kong.service.set_tls_cert_key(chain, key)

サービスとのハンドシェイク中に使用されるクライアント証明書を設定します。

chain引数は、ngx.ssl.parse_pem_certなどの関数によって返されるクライアント証明書と中間チェーン（存在する場合）です。

key引数は、ngx.ssl.parse_pem_priv_keyなどの関数によって返される、クライアント証明書に対応する秘密鍵です。

フェーズ

rewrite、access、balancer、preread

パラメータ

チェーン （cdata）: クライアント証明書チェーン
キー（cdata）：クライアント証明書の秘密鍵

戻り値

boolean|nil：操作が成功した場合はtrue 、エラーが発生した場合はnil。
string|nil: エラーがあった場合、その内容を説明するエラーメッセージ

使用法

local chain = assert(ssl.parse_pem_cert(cert_data))
local key = assert(ssl.parse_pem_priv_key(key_data))

local ok, err = kong.service.set_tls_cert_key(chain, key)
if not ok then
  -- do something with error
end

kong.service.set_tls_verify(on)

サービスとのハンドシェイク中にTLS検証が有効かどうかを設定します。

on引数はブール型フラグです。trueの場合、アップストリーム検証が有効であり、falseの場合は無効です。

この呼び出しは、現在のリクエストのみに影響します。信頼された証明書ストアがまだ設定されていない場合（proxy_ssl_trusted_certificateまたはkong.service.set_upstream_ssl_trusted_store経由）、TLS検証は常に「ローカル発行者証明書を取得できません」というエラーで失敗します。

フェーズ

rewrite、access、balancer、preread

パラメータ

on （boolean）：現在のリクエストにTLS証明書の検証を有効にするかどうか

戻り値

boolean|nil：操作が成功した場合はtrue 、エラーが発生した場合はnil。
string|nil: エラーがあった場合、その内容を説明するエラーメッセージ

使用法

local ok, err = kong.service.set_tls_verify(true)
if not ok then
  -- do something with error
end

kong.service.set_tls_verify_depth(depth)

アップストリームサーバーのTLS証明書を検証する際の、検証の最大深度を設定します。

この呼び出しは、現在のリクエストのみに影響します。実際に使用する深さについては、検証次のいずれかで有効にする必要があります proxy_ssl_verify ディレクティブを使用するか、 kong.service.set_tls_verify関数。

フェーズ

rewrite、access、balancer、preread

パラメータ

depth （number）：検証時に使用される深さ。値は負でない必要があります。

戻り値

boolean|nil：操作が成功した場合はtrue 、エラーが発生した場合はnil。
string|nil: エラーがあった場合、その内容を説明するエラーメッセージ

使用法

local ok, err = kong.service.set_tls_verify_depth(3)
if not ok then
  -- do something with error
end

kong.service.set_tls_verify_store(store)

アップストリームサーバーのTLS証明書を検証するときに使用するCA信頼ストアを設定します。

この呼び出しは、現在のリクエストのみに影響します。実際に利用される店舗については、検証次のいずれかで有効にする必要があります proxy_ssl_verify ディレクティブを使用するか、 kong.service.set_tls_verify関数。

resty.openssl.x509.store オブジェクトは、Kong/lua-Kong-nginx-moduleリポジトリの例に従って作成できます。

フェーズ

rewrite、access、balancer、preread

パラメータ

store （table）使用するresty.openssl.x509.storeオブジェクト

戻り値

boolean|nil：操作が成功した場合はtrue 、エラーが発生した場合はnil。
string|nil: エラーがあった場合、その内容を説明するエラーメッセージ

使用法

local store = require("resty.openssl.x509.store")
local st = assert(store.new())
-- st:add(...certificate)

local ok, err = kong.service.set_tls_verify_store(st)
if not ok then
  -- do something with error
end