Kong Gateway 3.0.x 最新の変更

アップグレードする前に、現在のインストールに影響するこのバージョンおよび以前のバージョンの構成または下位互換性のない変更を確認してください。

デプロイ方法、使用している機能セット、カスタムプラグインなどに応じて、異なるアップグレード手順を採用する必要がある場合があります。

プラグイン

プラグインの下位互換性のない変更については、お使いのKong GatewayバージョンのKong Gateway変更履歴を参照してください。

Kongプラグイン

インストールに新しいプラグインを追加する場合は、プラグイン名を指定して kong migrations upを実行する必要があります。例えば、 KONG_PLUGINS=tls-handshake-modifier。

3.0リリースには以下の新しいプラグインが含まれています。

OpenTelemetry (opentelemetry)
TLS Handshake Modifier(tls-handshake-modifier)
TLS Metadata Headers(tls-metadata-headers)
WebSocket Size Limit（websocket-size-limit）
WebSocket Validator (websocket-validator)

Kongプラグインは、CREDENTIAL_USERNAME（X-Credential-Username）をサポートしなくなりました。認証情報にアップストリームヘッダーを設定する場合は、定数CREDENTIAL_IDENTIFIER（X-Credential-Identifier）を使用してください。

デプロイメント

Amazon Linux 1 および Debian 8 (Jessie) のコンテナとパッケージは非推奨となり、 Kong Gatewayの新しいバージョンでは生成されなくなりました。

ブルーグリーンデプロイメント

従来モード ：2.8.1 およびそれ以前のバージョンから 3.0.0 へのブルーグリーンアップグレードは現在サポートされていません。これは既知の問題であり、次の 2.8リリースで修正される予定です。2.8 のリリースバージョンがリリースされたら、2.x ユーザーは 3.0 へのブルーグリーンアップグレードを開始する前に、そのバージョンにアップグレードする必要があります。

ハイブリッドモード : 以下のアップグレード手順を参照してください。

依存関係

提供されているバイナリパッケージ（DebianとRHELを除く）を使用している場合は、ゲートウェイに必要なすべての依存関係がバンドルされているため、このセクションは省略できます。

Kong Gateway 3.0以降、DebianとRHELのイメージは最小限の依存関係でビルドされ、公開前に自動セキュリティスキャナを通じて実行されます。これらには、 Kong Gatewayを実行するために必要な最小限のものだけが含まれています。ベースイメージと依存関係をさらにカスタマイズしたい場合は、独自のDockerイメージを構築してください。

Debian、RHELを使用している場合、または手動で依存関係を構築している場合は、以前のリリースから変更が加えられているため、最新のパッチを使用して再構築する必要があります。

Kong Gateway 3.0.x に必要な OpenResty のバージョンは 1.21.4.1 です。アップグレードされた OpenResty に加えて、lua-kong-nginx-module の最新リリースを含む、この新しいバージョン用の正しい OpenResty パッチが必要です。kong-build-tools リポジトリには openresty-build-tools が含まれており、必要なパッチやモジュールを使って OpenResty をより簡単にビルドすることができます。

移住

移行ヘルパーライブラリ（主にCassandraの移行に使用）は、Kong Gatewayでは提供されなくなりました。

PostgreSQLの移行で、Cassandraの移行と同様に、up_f部分を含め、呼び出す関数を指定できるようになりました。up_fの部分はup部分が、PostgreSQLとCassandraの両方データベースに対して実行された後に呼び出されます。

廃止および変更されたパラメータ

StatsD Advancedプラグインは非推奨となり、4.0で削除されます。現在、すべての機能がStatsDプラグインで利用できるようになっています。

以下のプラグインの設定パラメータが変更または削除されました。必要に応じて、設定を慎重に確認し、更新する必要があります。

ACL、Bot Detection、IP Restriction

非推奨のblacklistとwhitelist構成パラメータを削除しました。代わりに allow または deny を使用します。

ACME

設定パラメータのデフォルト値はauth_method tokenになりました。

AWS Lambda

AWSリージョンが必須になりました。aws_regionフィールドパラメータまたは環境変数でプラグインを構成して設定できます。
現在、プラグインではhostフィールドとaws_regionフィールドを同時に設定できるようになり、常にSigV4署名が適用されます。

HTTP Log

以前は値の配列を取っていたheadersフィールドは、ヘッダー名ごとに1つの文字列しか入力できなくなりました。

JWT

認証されたJWTはnginxコンテキスト ( ngx.ctx.authenticated_jwt_token )に入れられなくなりました。その名前で設定されている値に依存するカスタムプラグインは、3.0にアップグレードする前に、代わりにKongの共有コンテキスト（ kong.ctx.shared.authenticated_jwt_token ）を使用するように更新する必要があります。

Prometheus

高カーディナリティメトリックはデフォルトで無効になりました。
次のメトリック名は、可能な限り標準化するために単位を追加するために調整されました。
- http_status http_requests_total へ。
- latencyからkong_request_latency_ms（HTTP）、kong_upstream_latency_ms、kong_kong_latency_ms、session_duration_ms（ストリーム）。 Kongとアップストリームのレイテンシは、それぞれ異なるレベルのコマンドで動作する可能性があります。メモリのオーバーヘッドを削減するには、これらのバケットを分離します。
- kong_bandwidth kong_bandwidth_bytes へ。
- nginx_http_current_connections と nginx_stream_current_connections は nginx_connections_total に統合されました。
- request_countとconsumer_statusは http_requests_totalに統合されました。per_consumer構成がfalseに設定されている場合、 consumerラベルは空になります。per_consumer構成がtrueの場合、consumerラベルが入力されます。
その他のメトリクスの変更：
- 次のメトリックを削除しました: http_consumer_status。
- http_requests_total新しいラベルsourceがあります。exit、error、serviceのいずれかに設定できます。
- すべてのメモリメトリクスに新しいラベルが付けられました: node_id。
- このプラグインはステータスコード、レイテンシ、帯域幅、アップストリームのヘルスチェックメトリクスをデフォルトでエクスポートしませんが、今後も、status_code_metrics、lantency_metrics、bandwidth_metrics、upstream_health_metricsをそれぞれ設定することでこの機能をオンにできます。

Pre-functionプラグインとPost-functionプラグイン

非推奨のconfig.functions構成パラメータをpost-functionとpre-functionプラグインのスキーマから削除しました。代わりに、config.accessフェーズを使用してください。

StatsD

サービスに関連するすべてのメトリック名に service.プレフィックス kong.service.<service_identifier id="sl-md0000000">.request.count が付くようになりました。
- メトリクスkong.<service_identifier id="sl-md0000000">.request.status.<status id="sl-md0000000">はkong.service.<service_identifier id="sl-md0000000">.status.<status id="sl-md0000000">に改名されました。
- メトリクスkong.<service_identifier id="sl-md0000000">.user.<consumer_identifier id="sl-md0000000">.request.status.<status id="sl-md0000000">はkong.service.<service_identifier id="sl-md0000000">.user.<consumer_identifier id="sl-md0000000">.status.<status id="sl-md0000000">に改名されました。
メトリクスstatus_countおよびstatus_count_per_userからメトリクス*.status.<status id="sl-md0000000">.totalが削除されました。

Proxy Cache、Proxy Cache Advanced、GraphQL Proxy Cache Advanced

上記プラグインはngx.ctx.proxy_cache_hitに応答データを保存しなくなりました。
現在、応答データを必要とするログ取得プラグインは、データをkong.ctx.shared.proxy_cache_hitから読み取る必要があります。

カスタムプラグインとPDK

プラグインのDAOは、読み込み順序が明示的になるように、配列にリストされなければなりません。ハッシュのようなテーブルへの読み込みは、サポートされなくなりました。
プラグインの handler.lua ファイル内には、有効な PRIORITY（整数）および VERSION（「x.y.z」形式）フィールドが必要です。無い場合は、プラグインは読み込みに失敗します。
古いkong.plugins.log-serializers.basicライブラリは PDK に置き換えられて削除されました関数kong.log.serialize 。 PDK を使用するにはプラグインをアップグレードしてください。
非推奨となっていたレガシーのプラグインスキーマのサポートは削除されました。カスタムプラグインがいまだに古い（0.x era）スキーマを使用している場合は、それらをアップグレードする必要があります。
一部のプラグインの優先度を更新しました。

これはプラグインの実行順序に影響する可能性があるため、カスタムプラグインを実行するユーザーにとって重要ですが、 Kong Gatewayの標準的なインストールにおけるプラグインの実行順序は変更されません。

古いプラグインと新しいプラグインの優先度の値：
- acmeを1007から次の値へ変更：1705
- basic-authを1001から次の値へ変更：1100
- canaryを13から次の値へ変更：20
- degraphqlを1005から次の値へ変更：1500
- graphql-proxy-cache-advancedを100から次の値へ変更：99
- hmac-authを1000から次の値へ変更：1030
- jwtを1005から次の値へ変更：1450
- jwt-signerは999から1020に変更されました。
- key-authを1003から次の値へ変更：1250
- key-auth-advancedを1003から次の値へ変更：1250
- ldap-authを1002から次の値へ変更：1200
- ldap-auth-advancedを1002から次の値へ変更：1200
- mtls-authを1006から次の値へ変更：1600
- oauth2を1004から次の値へ変更：1400
- openid-connectを1000から次の値へ変更：1050
- rate-limitingを901から次の値へ変更：910
- rate-limiting-advancedを902から次の値へ変更：910
- route-by-headerを2000から次の値へ変更：850
- route-transformer-advancedを800から次の値へ変更：780
- pre-functionを+infから次の値へ変更：1000000
- vault-auth1003から変更1350
kong.request.get_path() PDK関数は、呼び出し元に返される文字列においてパスの正規化を行うようになりました。未加工の非正規化バージョンリクエストパスはkong.request.get_raw_path()経由で取得できます。
pdk.response.set_header()、pdk.response.set_headers()、pdk.response.exit()は、手動で設定されたTransfer-Encodingヘッダーを無視し、警告を発するようになりました。
PDKのバージョン管理は終了しました。
JavaScript PDKは、kong.request.getRawBody、kong.response.getRawBody、kong.service.response.getRawBodyでUint8Arrayを返すようになりました。 Python PDKは、kong.request.get_raw_body、kong.response.get_raw_body、kong.service.response.get_raw_bodyでbytesを返します。以前は、これらの関数は文字列を返していました。
go_pluginserver_exeおよびgo_plugins_dirディレクティブはサポートされなくなりました。 Goプラグインサーバーを使用している場、アップグレードする前に Go PDKを使用するにはプラグインを移行してください。
3.0以降、Kong Gatewayのスキーマライブラリのprocess_auto_fields機能は、所与のコンテキストがselectである場合、渡されるデータをディープコピーしません。その理由は、ほとんどの場合、データがpgmoonやlmdbのようなドライバーから取得されるとKongが考えるテーブルを過度にディープコピーしないようにするためです。

カスタムプラグインが指定されたテーブルをオーバライドしないprocess_auto_fieldsに依存していた場合は、今すぐ関数に渡す前に独自のコピーを作成する必要があります。
KongプラグインまたはDAOスキーマの非推奨のshorthandsフィールドは削除され、代わりに入力されたshorthand_fieldsが使用されます。カスタムスキーマでまだshorthandsを使用している場合は、 shorthand_fieldsを使用するよう更新する必要があります。
legacy = true/false属性のサポートは、KongスキーマおよびKongフィールドスキーマから削除されました。
Kongシングルトンモジュールkong.singletonsは、PDK kong.*が優先されたため削除されました。

新しいルーター

現在、 Kong Gatewayでは、route.pathが正規表現パターンかどうかの推測にヒューリスティックを使用していません。3.0以降は、すべての正規表現パスは"~"プレフィックスで始める必要があり、"~"で始まらないパスはすべてプレーンテキストと見なされます。移行プロセスでは、2.xから3.0にアップグレードする際に、正規表現パスが自動的に変換されます。

route.pathの正規化ルールが変更されました。Kong Gateway は正規化されていないパスを保存するようになりましたが、正規表現のパスは常に正規化されたURIとパターンマッチします。以前は、Kong Gateway がパーセントエンコーディングに置き換えられました正規表現のパスパターンを使用して、さまざまな形式のURIが一致するようにします。これはサポートされなくなりました。で定義されている予約文字を除き、 RFC3986 、その他のすべての文字はパーセントエンコードなしで書き込みます。

宣言型とDBレス

宣言型構成のバージョン番号（_format_version）は、route.pathの変更により 3.0に引き上げられました。古いバージョンの宣言型構成は、移行中に3.0にアップグレードされます。

宣言型構成ファイルを 2.8 以前から 3.0 に同期しないでください ( deck gateway sync )。 古い構成ファイルは構成を上書きし、互換性の問題を引き起こします。更新された構成を取得するには、移行が完了した後に 3.0 ファイルをdeck gateway dumpます。

.lua形式を使用してkongCLI ツールから宣言型構成ファイルをインポートすることはできなくなりました。JSON形式とYAML形式のみがサポートされています。Kong Gatewayでのアップデート手順にkong config db_import config.luaの実行が含まれる場合、config.luaファイルをconfig.jsonまたはconfig.ymlファイルに変換してからアップグレードします。

Admin API

Admin APIエンドポイント /vitals/reportsは削除されました。

POSTリクエストが/targetsエンドポイントに対するものである場合、既存エンティティを更新できなくなりました。このリクエストでは新しいエンティティの作成のみできます。 /targetsを変更するためにPOSTリクエストを使用するスクリプトがある場合、適切なエンドポイントへのPUTリクエストに変更してからKong 3.0に更新します。

サーバーで利用できると報告されたプラグインのリストは、ブール値のtrueではなく、プラグインごとのメタデータのテーブルを帰すようになりました。

構成

X-Credential-Usernameの値を持つKong定数CREDENTIAL_USERNAMEは削除されました。

システム CA ストアから信頼された CA リストを自動的に読み込むために、デフォルト値の lua_ssl_trusted_certificate が system に変更されました。

データプレーンの構成キャッシュメカニズムとそれに関連する構成オプション（data_plane_config_cache_modeとdata_plane_config_cache_path）は削除され、代わりにLMDBが使用されます。

ngx.ctx.balancer_addressは、ngx.ctx.balancer_dataが優先されたため削除されました。

Kubernetes向けKongに関する考慮事項

Helm チャートはアップグレード移行プロセスを自動化します。helm upgrade を実行すると、チャートは、kong migrations up を実行するための初期ジョブを生成し、更新されたバージョンで新しい Kong ポッドを生成します。これらのポッドの準備が整うと、トラフィックの処理が開始され、古いポッドは終了されます。これが完了すると、チャートは別のジョブを生成して kong migrations finish を実行します。

移行自体は自動化されていますが、チャートは、推奨されているアップグレードパスに従うことを自動的に保証するものではありません。複数のマイナー Kong Gatewayバージョンからさかのぼってアップグレードする場合は、推奨されるアップグレードパスを確認してください。

必須ではありませんが、ユーザーはチャートのバージョンとKong Gatewayバージョンを個別にアップグレードする必要があります。問題が発生した場合、これは問題がKubernetesリソースの変更に起因するものか、Kong Gatewayの変更変更に起因するものかを明確にするのに役立ちます。

Kong for Kubernetesのバージョンアップグレードに関する具体的な考慮事項については、アップグレードに関する考慮事項を参照してください。

Kongデプロイメントは複数のリリースに分割

標準のチャートアップグレード自動化プロセスでは、Kong Gatewayクラスタ内でKong Gatewayリリースが1つだけであると想定しており、migrations upとmigrations finishの両方のジョブを実行します。

Kong Gatewayデプロイメントを複数のHelmリリースに分割する場合（たとえば、プロキシ専用ノードや管理者専用ノードなど）、アップグレードの順番に応じて、どの移行ジョブを実行するかを設定する必要があります。

複数のリリースに分割されたクラスタを処理するには、次の操作を行う必要があります。

次のいずれかのリリースをアップグレードします。

helm upgrade RELEASENAME -f values.yaml \
--set migrations.preUpgrade=true \
--set migrations.postUpgrade=false

残りのリリースのうち 1 つを除くすべてを次のようにアップグレードします。

helm upgrade RELEASENAME -f values.yaml \
--set migrations.preUpgrade=false \
--set migrations.postUpgrade=false

最終リリースを次のようにアップグレードします。

helm upgrade RELEASENAME -f values.yaml \
--set migrations.preUpgrade=false \
--set migrations.postUpgrade=true

これにより、すべてのインスタンスが、kong migrations finishを実行する前に新しい Kong Gatewayパッケージを使用していることが保証されます。

ハイブリッドモードに関する考慮事項

重要: 現在ハイブリッドモードで実行している場合は、最初にコントロールプレーン（CP）をアップグレードし、次にデータプレーン（DP）をアップグレードします。

現在、クラシック（従来モード）で2.8.xバージョンを実行している場合で、ハイブリッドモードの実行に切り替えたい場合は、移行を行った後、ハイブリッドモードインストール手順に従ってください。
カスタムプラグイン（独自のプラグインまたはKong Gatewayに付属していないサードパーティ製プラグイン）は、ハイブリッドモードでコントロールプレーン（CP）とデータプレーン（DP）の両方にインストールする必要があります。プラグインは、最初にコントロールプレーン（CP）にインストールし、次にデータプレーン（DP）にインストールします。
Rate Limiting Advancedプラグインは、ハイブリッドモードでのclusterストラテジをサポートしていません。代わりに、redisストラテジを使用する必要があります。

テンプレートの変更

2.0.x以降のKong Gatewayのマイナーバージョンとメジャーバージョンの間では、Nginx構成ファイルに変更があります。

3.0.xで非推奨のKong.serve_admin_apiエイリアスが削除されました。カスタムNginxテンプレートをまだ使用している場合は、Kong.admin_contentに変更してください。

OSS

Enterprise

バージョン間のすべての構成変更を表示するには、Kong リポジトリを複製し、構成テンプレート上で git diff を実行します。読みやすくするためには -w を使用します。

次の方法で、以前のバージョンと3.0.xの違いを確認できます。

git clone https://github.com/kong/kong
cd kong
git diff -w 2.0.0 3.0.0 kong/templates/nginx_kong*.lua

開始バージョン番号（例では2.0.0）を現在使用しているバージョン番号に調整します。

パッチファイルを生成するには、次のコマンドを使用します。

git diff 2.0.0 3.0.0 kong/templates/nginx_kong*.lua > kong_config_changes.diff

開始バージョン番号を、現在使用しているバージョン番号 (例では 2.0.0) に調整します。

Kong Gatewayのデフォルトテンプレートは、このコマンドを使用して見つけることができます。 Kong Gatewayインスタンスを実行しているシステム: find / -type d -name "templates" | grep kong .

アップグレードするときは、必ず古いクラスタと新しいクラスタの両方でこのコマンドを実行してください。ファイルを比較して変更箇所を特定し、必要に応じて適用します。

前へ Kong Gateway 2.8.x およびそれ以前の重大な変更

次へ Kong Gateway 3.1.x 最新の変更