コンテンツにスキップ
|
Kong Gateway
3.8.x
report-issue問題を報告する
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。

DBレスで宣言型構成

従来、Kong Gateway は、ルート、サービス、プラグインなどの構成されたエンティティを保存するためにデータベースを常に必要としていました。Kongは、kong.conf という構成ファイルを使用して、データベースの利用とそのさまざまな設定を指定します。

Kong Gateway 、エンティティのメモリ内ストレージのみを使用して、データベースなしで実行できます。 これをDBレスモードと呼んでいます。Kong Gateway DB-Lessを実行している場合、エンティティの構成は、 宣言型設定を使用して、YAMLまたはJSONの2つ目の設定ファイルで行われます。

 
flowchart TD

A( Kong Gateway instance)
B( Kong Gateway instance)
C( Kong Gateway instance)

A2(fa:fa-file kong1.yml)
B2(fa:fa-file kong2.yml)
C2(fa:fa-file kong3.yml)

A2 --> A
B2 --> B
C2 --> C

style A stroke:none,fill:#0E44A2,color:#fff
style B stroke:none,fill:#0E44A2,color:#fff
style C stroke:none,fill:#0E44A2,color:#fff

*図1：DBレスモードでは、YAMLファイルを介して構成が適用されます。

Kong Gatewayノードはデータベースにも他のノードにも接続されていません。*

DBレス・モードと宣言的コンフィギュレーションの組み合わせには、次のような利点があります。

  • 依存関係の数の削減：ユースケースの設定全体がメモリ内に収まる場合は、データベースのインストールを管理する必要はありません。
  • CI/CD シナリオにおける自動化: エンティティの構成は、Git リポジトリを通して管理される信頼できる唯一の情報源内に保持できます。
  • Kong Gatewayのデプロイメントオプションの幅が広がります。

注： decKは構成を宣言型でも管理します。ただし、その場合はデータベースが同期、ダンプ、または同様の操作を実行する必要があります。 そのためDBレスモードではdecKを使用できません。

宣言型構成

宣言型構成の重要な考え方は、それが 命令型 ではなく、その逆の 宣言型 であるということです。「命令型」とは、構成が「これを実行して、それからあれを実行しなさい」という一連のものとして与えられることを意味します。「宣言型」とは、「私はこれが世界の現状であると宣言する」といったように、構成が一度に与えられることを意味します。

Kong Admin APIは、命令型構成ツールの例です。構成の 最新状態は、一連のAPI呼び出しで獲得できます。1つの呼び出しはサービスを 生成し、もう1つの呼び出しはルートを生成し、その他の呼び出しはプラグイン などを追加します。

このような段階的な設定は、 中間状態 が発生するという望ましくない 副作用をもたらします。上の例では、ルートを作成してからプラグインを追加するまでの間、ルートには適用されるプラグインがないという時間枠があります。

一方、宣言型設定ファイルには 必要なすべてのエンティティ用の設定が1つのファイルにまとめられています。そのファイルが読み込まれると

Kong Gateway 、構成全体が置き換えられます。段階的な変更の場合、 それらは宣言型構成ファイルに入れられます。そして 完全にリロードされます。常に、 Kong にロードされるファイルに記述されている構成が、システムの構成状態です。

DB レスモードでKongを設定

DBレスモードでKong Gatewayを使用するには、 kong.confのdatabaseディレクティブをoffに設定します。 通常どおり、kong.confを編集してdatabase=offを設定するか、環境変数を使用してこれを実行できます。その後、通常どおりKongを起動できます。

export KONG_DATABASE=off
kong start -c kong.conf

Kongが起動したら、Admin APIの/エンドポイントにアクセスして、データベースなしで 実行されていることを確認します。Kongの構成全体が返されます。 databaseがoffに設定されていることを確認します。

コマンド：

curl -i -X GET http://localhost:8001

応答例：

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 6342
Content-Type: application/json; charset=utf-8
Date: Wed, 27 Mar 2019 15:24:58 GMT
Server: kong/3.8.1
{
    "configuration:" {
       ...
       "database": "off",
       ...
    },
    ...
    "version": "3.8.1"
}

Kong Gatewayは実行中ですが、宣言型構成はまだ読み込まれていません。これは 、このノードの構成が空であることを意味します。ルート、 サービス、またはどんな種類のエンティティもありません。

コマンド：

curl -i -X GET http://localhost:8001/routes

応答例：

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 23
Content-Type: application/json; charset=utf-8
Date: Wed, 27 Mar 2019 15:30:02 GMT
Server: kong/3.8.1

{
    "data": [],
    "next": null
}

宣言型構成ファイルの作成

DBレスKongにエンティティをロードするには、宣言型の構成ファイルが必要です。次のコマンドで、開始するためのスケルトンファイルを作成します。

kong config -c kong.conf init

このコマンドを実行すると、エンティティとその関係を宣言する構文の例が含まれるkong.ymlファイルが現在のディレクトリに作成されます。 このファイルのすべての例はデフォルトでコメントアウトされています。 例のコメント機能を解除（#マーカーを削除）したりその値を変更したりして実験できます。

宣言型構成形式

Kong Gateway の宣言型設定フォーマットは エンティティとその属性のリストで構成されます。これは小さいながらも完全な例で、 多くの機能を説明します。

_format_version: "3.0"
_transform: true

services:
- name: my-service
  url: https://example.com
  plugins:
  - name: key-auth
  routes:
  - name: my-route
    paths:
    - /

consumers:
- username: my-user
  keyauth_credentials:
  - key: my-key

すべての設定オプションについては、宣言型設定スキーマ を参照してください。

必須のメタデータは_format_version: "3.0"のみであり、 宣言型構成構文形式のバージョン番号を指定します。 これは、ファイルを解析するために必要なKongの最小バージョンとも一致します。

_transformメタデータはオプションのブーリアン（デフォルトはtrue）であり、スキーマの変換がインポート中に実行されるかどうかを制御します。このフィールドを使用する場合の大まかなルールは、プレーンテキストの認証情報（例：パスワード）をインポートする場合、Kongがデータベースにその情報を保存する前に暗号化/ハッシュできるよう、trueに設定することです。 すでにハッシュ/暗号化された 認証情報をインポートする場合は、暗号化が2回行われないように_transformをfalseに設定します。

最上位では、コアエンティティなど、 上記の例のようにservicesとconsumers、またはkeyauth_credentialsのようなプラグインによって作成されたカスタムエンティティ で任意のKongエンティティを指定できます。これにより、宣言型 構成フォーマットは本質的に拡張可能であり、宣言型構成を処理する kong config コマンドがkong.conf を必要とするのは、 plugins ディレクティブが考慮されるようにするためです。

サービスを指すルートなど、エンティティが関係を持つ場合、この関係はネストによって指定できます。

ネストで指定できるのは 1 対 1 の関係だけです。上記の例のようにサービスに適用されるプラグインは、ネストを使ってその関係を示すことができます。サービスとコンシューマの両方に適用されるプラグインのように、2 つ以上のエンティティが関わる関係は、トップレベルのエントリ経由で行う必要があります。その場合、エンティティはプライマリキーや識別名（Admin API で参照する際に使用できる同じ識別子）で特定できます。以下は、サービスとコンシューマに適用されたプラグインの例です。

plugins:
- name: syslog
  consumer: my-user
  service: my-service

ファイルのチェック

ファイルの編集が終わったら、Kong Gateway への読み込み前に構文のエラーがないか確認できます。

kong config -c kong.conf parse kong.yml

レスポンス:

parse successful

ファイルの読み込み

宣言型構成ファイルをKongにロードするには、次の2つの方法があります。\nkong.confまたは Admin APIです。

Kong の起動時に宣言型構成ファイルを読み込むには、kong.conf 内で declarative_config ディレクティブ（または、通常の kong.conf エントリと同じく、同等の環境変数 KONG_DECLARATIVE_CONFIG）を使用します。

export KONG_DATABASE=off \
export KONG_DECLARATIVE_CONFIG=kong.yml \
kong start -c kong.conf

Admin APIで/configエンドポイントを 使用して、宣言型構成ファイルを実行中のKongノードにロードすることもできます。次の 例ではkong.ymlをロードします。

curl -i -X POST http://localhost:8001/config \
  --form config=@kong.yml

/config エンドポイントはメモリ内のエンティティのセット全体を、指定されたファイルに記述されたエンティティのセットで置き換えます。

KongをDBレスモードで起動するもう一つの方法は、KONG_DECLARATIVE_CONFIG_STRING環境変数を使用して、宣言型構成全体を文字列に含めることです。

export KONG_DATABASE=off
export KONG_DECLARATIVE_CONFIG_STRING='{"_format_version":"1.1", "services":[{"host":"httpbin.org","port":443,"protocol":"https", "routes":[{"paths":["/"]}]}],"plugins":[{"name":"rate-limiting", "config":{"policy":"local","limit_by":"ip","minute":3}}]}'
kong start

Helm を使用した DB レス（KIC が無効）

Kong Gatewayを、Kubernetesでイングレスコントローラ（ingressController.enabled: false）を使用せずDB-lessモード（env.database: "off"）でデプロイする場合、実行するためのKong Gatewayの宣言型構成を提供する必要があります。既存のConfigMap（dblessConfig.configMap）を提供するか、構成全体をvalues.yaml（dblessConfig.config）パラメータに配置することができます。詳細については、デフォルトのvalues.yamlの構成例を参照してください。

完全な宣言型構成ファイルを置き換えるには、Helm コマンドで--set-file dblessConfig.config=/path/to/declarative-config.yaml使用します。

外部から提供されたConfigMapは、デプロイメントアノテーションでハッシュ化または追跡されません。それ以降のConfigMapの更新では、新しい構成を適用するためにユーザーが開始するデプロイメントロールアウトが必要になります。外部から提供されたConfigMapコンテンツを更新した後、 kubectl rollout restart deployを実行します。

DB-lessモードでKongを使用

DB レスモードで Kong を使用する際には注意すべき点がいくつかあります。

メモリキャッシュの要件

エンティティの構成全体がKongキャッシュ内に収まる必要があります。メモリ内キャッシュが適切に構成されていることを確認します。kong.confのmem_cache_sizeディレクティブを参照してください。

中央データベースでの調整を排除

中央のデータベースがないため、複数の Kong ノードは中央の調整ポイントを持たず、クラスタのデータ伝播も行われません。つまり、ノード同士は完全に独立しています。

これは、宣言型構成を各ノードに個別にロードする必要があることを意味します。ノードは互いを認識していないため、/config エンドポイントを使用しても他の Kong ノードへの影響はありません。

読み取り専用Admin API

エンティティを構成する唯一の方法は宣言的な構成であるため、エンティティに 対するCRUD操作のエンドポイントは、DB-lessモードでKongを実行中の 場合、Admin APIでは実質的に読み取り専用です。エンティティの検査のためのGET 操作は通常通り機能しますが、/servicesや/pluginsのようなエンドポイントでのPOST、 PATCH、PUTまたはDELETEの試行では HTTP 405 Not Allowedを返します。

この制限は、それ以外のデータベース操作に限定されます。特に、 POSTを使用してターゲットのヘルス状態を設定することは、ノード固有の メモリ内操作であるため、引き続き有効です。

Kong Manager の互換性

Kong Manager は、DB レスモードで動作するKong Gatewayとの互換性を保証できません。Kong Gatewayがこのモードで実行されている場合、Kong Managerを使用してエンティティを作成、更新、または削除することはできません。グローバルページとワークスペース概要ページの「概要」セクションにあるエンティティカウンターも正しく機能しません。

プラグインの互換性

KongのすべてのプラグインがDBレスモードと互換性があるわけではありません。設計上、一部のプラグインでは中央データベースでの調整やエンティティの動的作成が必要になります。

現在のプラグイン互換性については、プラグインの互換性を参照してください。

参照