kongctlの基本的な使い方

Last updated at 2026-11-05Posted at 2026-11-05

この記事について

本記事は、kongctlについて解説するものです。kongctlは、Kong Konnectを操作・管理できるコマンドラインツールです。

本記事では以下のことを説明します。

Kong Konnectについて
kongctlについて
kongctlの設定方法について
具体的なコード例と使い方について

想定読者は以下のような人です

Kong Konnectを使用している人
Kong Konnect、Kong Gatewayについてある程度の知識がある人

今回作成したコードは、以下のリポジトリで公開しています。

Kong Konnectについて

Kong Konnectは、API、LLM、イベント、マイクロサービスを一元的に管理できる統合APIプラットフォームです。
本記事ではAPI GatewayのControl Plane（以下、CP）にしか触れませんが、他の要素については公式ドキュメントをご参照ください。

今回の環境

decK 1.69.0
kongctl 1.21.0
Kong Konnect
Ubuntu 24.04.5(WSL)

kongctlについて

kongctl is a command line tool that enables you to manage Konnect resources programmatically.

kongctlは、Konnect上のリソースをプログラムで管理できるようにする、ステートレスのコマンドラインツールです。

kongctlはKonnect上のリソースを管理し、その中でdecKを呼び出すことで、GatewayのEntityを操作することができます。2つのツールを連携させて使うことで、統括的な管理が可能になります。
kongctl and decK

どのような場面でkongctlを使うと便利なのか

複数のCPをKonnect上で管理する場合に、共通設定と個別設定を管理・適用させたい場合に有用です。

共通の設定をcommon.ymlに切り出し、個別の設定はcp1.yml cp2.ymlなどとして分割しておくことが可能です。

kongctlの設定方法について

公式ドキュメントを参照し、インストールを行います。今回はmiseを使用してインストールを行いました。

mise use -g github:Kong/kongctl@latest

インストールが完了したら、kongctl loginで認証を行います。
私の経験則にはなりますが、もしすでにKonnectのタブを開いている場合は、閉じてから認証を進めることをおすすめします。

kongctlがdecKを呼ぶため、decKも同様にインストールし、PATHで呼べるように設定する必要があります。

実行モードについて

apply,sync,deleteの3種類の実行モードがあります。

apply⇒リソースの作成・更新のみ行い、削除をしない
sync⇒作成・更新・削除を行い、設定ファイルの状態に完全同期する
delete⇒入力設定ファイルに定義されたリソースをすべて削除する

今回はsyncのみを使っています。syncを使用する場合は意図しないdeleteが発生しないようにdiffで実行前の確認をすることをおすすめします。

具体的なコード例と使い方について

今回は一例として、Konnect上にCPを2つ作成し、それぞれに共通のPlugin（key-auth）と別個のService、Pluginを設定します。

今回使用するディレクトリ構造は以下となります。

.
├ gateway/            # CP内設定
│　└ common.yml       # 共通設定
│　└ cp1.yml          # CP1用設定
│　└ cp2.yml          # CP2用設定
├ platform_cp1.yml    # CP1作成用
└ platform_cp2.yml    # CP2作成用

platform_cp1.yml、platform_cp2.ymlでKonnect上にCPを作成した後、その中の設定をdecKで流し込むことになります。
common.ymlには、共通で反映させるGlobalのkey-authの記述を行います。
そのほかのGateway ServiceやPluginは、それぞれcp1.yml、cp2.ymlで設定します。

platform_cp1.yml

_defaults:
  kongctl:
    namespace: default

control_planes:
  - ref: cp1 
    name: "fuka-test-cp1"            # Konnect上に表示される名前
    _deck:
      files:
        - "gateway/common.yml"      # 共通設定
        - "gateway/cp1.yml"         # CP1 固有設定

platform_cp2.yml

_defaults:
  kongctl:
    namespace: fuka-test

control_planes:
  - ref: cp2
    name: "fuka-test-cp2"          # Konnect上に表示される名前
    kongctl:
      namespace: fuka-test
    _deck:
      files:
        - "gateway/common.yml"    # 共通設定（同じファイルを参照）
        - "gateway/cp2.yml"       # CP2 固有設定

common.yml

_format_version: "3.0"
_info:
  select_tags:
    - platform-team

plugins:
  - name: key-auth
    tags:
      - platform-team

cp1.yml

_format_version: "3.0"
_info:
  select_tags:
    - platform-team

services:
  - name: test-service1
    url: https://backend.internal-1
    tags:
      - platform-team
    routes:
      - name: test-route1
        paths:
          - /route1
        tags:
          - platform-team

plugins:
  - name: rate-limiting-advanced
    service: test-service1
    config:
      limit:
        - 500
      window_size:
        - 3600
      window_type: sliding
      disable_penalty: false
      namespace: platform-team
      strategy: local
    tags:
      - platform-team

cp2.yml

_format_version: "3.0"
_info:
  select_tags:
    - platform-team

services:
  - name: test-service2
    url: https://backend.internal-2
    tags:
      - platform-team
    routes:
      - name: test-route2
        paths:
          - /route2
        tags:
          - platform-team
  
  - name: test-service3
    url: https://backend.internal-3
    tags:
      - platform-team
    routes:
      - name: test-route3
        paths:
          - /route3
        tags:
          - platform-team

plugins:
  - name: service-protection
    service: test-service2
    config:
      window_size:
        - 60
      limit:
        - 10
      namespace: platform-team
    tags: 
      - platform-team

設定反映の方法

今回はCPごとにplatform.ymlを分けて作成したため、2回設定反映を行います。

kongctlはplanで実行用のjsonファイルを作成し、それをもとに実行します。planを作成するときの--modeと、反映の時のモードは一致している必要があります。applyで作成したplanは、applyでしか実行できません。

CP1を反映

この時に参照されるファイルは、platform_cp1.yml、common.yml、cp1.ymlの3つです。

kongctl plan --mode sync -f platform_cp1.yml --output-file plan_cp1.json # json作成
kongctl diff --plan plan_cp1.json  # 差分確認
kongctl sync --plan plan_cp1.json  # 反映

CP2を反映

この時に参照されるファイルは、platform_cp2.yml、common.yml、cp2.ymlの3つです。

kongctl plan --mode sync -f platform_cp2.yml --output-file plan_cp2.json # json作成
kongctl diff --plan plan_cp2.json  # 差分確認
kongctl sync --plan plan_cp2.json  # 反映