本記事は「Kong Advent Calendar 2025」の8日目のエントリとして、kongctlの概要について解説する。
先日kongctlというツールが公開された。
従来Kong Gatewayを管理するツールとしてdeck CLIがあったが、これはKong Gatewayにのみフォーカスしたツールであり、Konnectの管理は出来なかった。
今回公開されたkongctlはKong GatewayおよびKonnectの両方を管理できるCLIツールであり、将来的はkongctlに統合されるようだが、今はSaaS部分の管理にフォーカスされているようである。
今回はこれを試してみる。
なお、12月時点ではTech Previewなので、今後仕様が変わる可能性があることに注意。
TL;DR
- 現時点ではGateway設定、Dev Portal、APIsあたりの設定の取得・作成・更新などが可能
- 現時点のメインの想定ユースケースはDev PortalとAPIsの修正（APIOpsの簡略化）
- KAi(KonnectのAIアシスタント)と対話が可能
- プロファイル管理に対応。ただし機能は限定的。
前提
以下が前提となる。
- Kong Konnectが利用できること
- MacまたはLinux環境が利用できること
まだWindowsはサポートされていないようなので、Windowsユーザの人はWSLなどを利用する必要がある。
なお、利用するバージョンは0.3.4である。
準備
インストール
GitHubのInstallationを参照しインストールする。
自分はMacを利用しているので以下のコマンドでインストールする。
brew install --cask kong/kongctl/kongctl
インストール後、以下のコマンドでバージョンが表示されれば成功。
$ kongctl version --full
0.3.4 (727aef4 : 2025-12-03T17:35:21Z)
Completionの適用
コマンド補完が効くよう、completionを設定する。
なお、自分はMacでBashを使っていたが、デフォルトのBashだとバージョンが古くて動かったので、以下の手順で新しいバージョンを導入した。
brew install bash
sudo sh -c "echo $(brew --prefix)/bin/bash >> /etc/shells"
chsh -s $(brew --prefix)/bin/bash
completionが使えそうだったら、Bashの人は以下のような感じでcompletion設定を.bashrc等に記載する。
source <(kongctl completion bash)
Macだとzsh使いの方が多いと思うので、自分のShellにあわせて変更して欲しい。
completionが効くようになると以下の様な感じでタブを押せば候補が出てくるようになる。
$ kongctl get
api (List or get Konnect APIs) organization (Get current organization information)
auth-strategy (List or get Konnect authentication strategies) portal (List or get Konnect portals)
gateway (Manage Konnect Kong Gateway resources) profile (Manage CLI profiles)
konnect (Manage Konnect resources) regions (List available Konnect regions)
me (Get current user information)
Konnectへのログイン
kongctlでKonnectにログインする。
kongctl login
すると以下のようにデバイスのアクティベーションを求められる。
Logging your CLI into Kong Konnect with the browser...
To login, go to the following URL in your browser:
https://cloud.konghq.com/device-activate?code=XXXX-XXXX
Or copy this one-time code: XXXX-XXXX
And open your browser to https://cloud.konghq.com/device-activate
(Code expires in 899 seconds)
Waiting for user to Login...
ブラウザで指定されたURLにアクセスし、先に進んでいくとアクティベーションが完了し、以下のメッセージが表示されてログインが完了する。
User successfully authorized
動作確認として、ログインしているユーザを確認してみる。
$ kongctl get me
ID EMAIL FULL NAME PREFERRED NAME ACTIVE INFERRED REGION LOCAL CREATED TIME LOCAL UPDATED TIME
2033… hoge.fuggaa@example.com Hogee Fugaga Hogee Fugaga true n/a 2024-04-04 16:38:59 2024-04-04 16:38:59
先程認証したアカウントの情報が表示された。
なお、トークンなどの接続のための情報は.config/kongctl/.<プロファイル名>-konnect-token.jsonに保存される模様。
デフォルトのプロファイル名はdefaultなので、今回実行したものついては.config/kongctl/.default-konnect-token.jsonに保存される。
ログアウトするにはkongctl logoutを実行するか当該のファイルを削除するとよい。
また、後述するがトークンの期限が15分しか持たない。
--patオプションを使ってPAT（パーソナルアクセストークン）を指定する、もしくはexport KONGCTL_DEFAULT_KONNECT_PAT=kpat_sHa...のようにPATを使うのをデフォルトにする方法を使えばログインは不要なので、トークンの期限に悩みそうな人はPATを利用するとよい。
検証
ここでは以下の機能を試してみる。
- Profileの切り替え
- KAiとの対話
- Konnect上のリソースの取得・作成・更新
メインは3番目のKonnect上のリソースの取得・作成・更新なので、読むのが面倒な人は3番目まで飛んで欲しい。
Profileの切り替え
プロファイルとはAWS CLIなどでおなじみの、接続先などを環境ごとに切り替えるための仕組みである。
$HOME/.config/kongctl/config.yamlにプロファイルを記載することが出来る。
恐らく準備の手順を踏んでいれば以下の内容のものが作成済みだと思う。
default:
log-file: /Users/<アカウント名>/.config/kongctl/logs/kongctl.log
output: text
試しに以下のような感じでtestというプロファイルを足してみる。
default:
log-file: /Users/<アカウント名>/.config/kongctl/logs/kongctl.log
output: text
test:
log-file: /tmp/kongctl_test.log
output: json
ログの出力先およびoutputを変えている。
アクセストークンはプロファイルごとに管理されるため、testプロファイルを使ってまずはログインする。
kongctl login konnect --profile test
ログインが完了したら、先ほどと同じようにユーザ情報を取得してみる。
$ kongctl get me --profile test
{
"active": true,
"created_at": "2024-04-04T07:38:59Z",
"email": "hoge.fuggaa@example.com",
"full_name": "Hogee Fugaga",
"id": "203366e7-5f6c-4845-983c-de1112e1861f",
"inferred_region": "",
"preferred_name": "Hogee Fugaga",
"updated_at": "2024-04-04T07:38:59Z"
}
json形式で情報が取得できた。
またログファイルも作成された。
$ ls /tmp/kongctl_test.log
/tmp/kongctl_test.log
デフォルトのプロファイルでdefault以外を利用したい場合は環境変数KONGCTL_PROFILEにプロファイル名を指定する。
export KONGCTL_PROFILE=test
ただ、現状設定できる項目が少ない（出力系の加工、OrganizationとRegionの切り替えくらい？）ので、あまりプロファイルを切り替える意味は無いかもしれない。
KAiとの対話
KAiはKonnect上で動作するKong公式のAIアシスタントで、Konnectの設定や状態を見ながら、問題の検出や改善提案をしてくれる機能である。
現状はベータ版であり、Konnect Plusやトライアル版を使っている場合は自由に使えるが、Enterprise版の場合は申請してFeature Flagを有効化してもらう必要がある。
この機能だが、kongctlから利用できるので触ってみる。
Feature Flagで有効化されている場合、Organization->Settings->AI SettingsでAI機能が有効可出来るので有効化する。
次にkongctl kaiを実行する。
すると対話形式でAIと会話できるようになる。
例えば「今全てのControl PlaneのService数を教えて」と聞いてみると、以下のような感じで回答が返ってくる。
対話型でAI活用してKonnectの状態を確認したい時などに利用できそう。
Konnect上のリソースの取得・作成・更新
リソースの取得
kongctlでは現時点でgetで以下のリソースが取得できる。
| オプション | 取得できる情報 |
|---|---|
| api | Konnect APIs |
| auth-strategy | DevPortalのApplication Auth |
| gateway | Konnect Kong Gatewayリソース |
| konnect | Konnectリソース |
| me | 現在のユーザ情報 |
| organization | 現在のOrganization |
| portal | Konnectポータル |
| profile | kongctlのプロファイル |
| regions | 利用可能なKonnectリージョン |
gatewayについてはサブコマンドみたいな感じになっていて、control-planeやconsumerなど追加のオプションを指定することで情報が取得できる。
konnectもサブコマンドみたいな感じだが、kongctl get meとkongctl get konnect meで同じ情報が取れる。明示的にkonnectを操作しているとコマンドに残したい時に利用する模様。
試しにapi情報を取得してみる。
$ kongctl get api
結果は以下のようになった。
kongctl get api
ID NAME DESCRIPTION VERSION COUNT PUBLICATION COUNT LOCAL CREATED TIME LOCAL UPDATED TIME
bb4e… httpbin n/a n/a 1 2025-08-10 21:29:11 2025-09-16 16:20:31
48ef… delme n/a n/a 0 2025-08-25 14:04:11 2025-08-26 12:03:10
f80c… 00-sample n/a n/a 1 2025-09-12 13:12:04 2025-09-12 14:07:10
6a12… MyAPI n/a n/a 0 2025-09-12 15:32:30 2025-09-12 16:00:38
9821… Bookinfo n/a n/a 2 2025-09-22 11:21:45 2025-10-28 15:23:53
8478… auto_created_api n/a n/a 0 2025-09-30 16:19:26 2025-09-30 16:19:26
2e99… BanKonG API n/a n/a 1 2025-12-01 13:37:55 2025-12-01 14:03:42
なおkubectlのようにYAMLやJSON形式での出力も可能。
$ kongctl get api -o yaml
- api_spec_ids:
- ed8cb241-1b84-4d40-9e46-bc2b05d753b1
attributes: {}
created_at: "2025-08-10T12:29:11.324Z"
current_version_summary: null
id: bb4ea885-5c2a-4207-bb55-7f013320848a
labels: {}
name: httpbin
portals:
- display_name: MPD
id: e32970d0-3169-4c4c-adcc-0cde681a833c
name: My Permanent DevPortal
slug: httpbin-0
updated_at: "2025-09-16T07:20:31.35Z"
version: "0.8"
- api_spec_ids:
：（省略）
ちなみに表示系のコマンドとして、kongctl dumpもある。
$ kongctl dump declarative --resources=api
apis:
- name: 00-sample
ref: f80c17bc-0227-4c58-8834-8813349b5767
slug: 00-sample-0
version: "0.2"
- name: BanKonG API
ref: 2e994445-81dd-414c-847b-56cfba351427
slug: ban-kong-api-v1
version: v1
：（省略）
こちらは設定ファイルとして再利用するためのコマンドで作成時刻などの生きている情報は含まれない。（作成時のIDはrefに設定されるが、リソース間の参照用文字列みたいなものでIDとして使われる訳では無い）
あと、kongctl viewを使うとTUIで情報を確認できる。
以下はkongctl viewからControl Planeを表示した時の例である。
k9sぽくていい感じである。
地味に取得が難しいcontrol_plane_endpointがここから確認できるのも嬉しい。
リソースの作成・更新
リソースの作成・更新についてはKubernetesと同じようにYAMLファイルで行うことが出来る。
YAMLファイルは公式のリポジトリ内にいくつかサンプルがあるので、これを使って試してみる。
最初にAPIsにAPIを作成する。
echo '
apis:
- ref: simple-api
name: My Simple API
description: The simplest API example
kongctl:
namespace: kongctl-demo
' | kongctl apply -f -
refは設定ファイル内で相互参照する際に必要なID的なものになる。
なお、元のサンプルからnamespaceを追加している。
これを付与するとラベルが自動的に割り当たる。
実行すると、以下のように変更点が表示され、本当に変更してよいか回答する形になる。
RESOURCE CHANGES
----------------------------------------------------------------------
Namespace: kongctl-demo (1 changes: 1 create)
api (1 resources):
+ simple-api
SUMMARY
----------------------------------------------------------------------
Total changes: 1
Namespaces affected: 1
Resources to create: 1
Resource breakdown:
api: 1
CONFIRM?
----------------------------------------------------------------------
Do you want to continue? Type 'yes' to confirm:
yesを入力すると作成が実行される。
Konnect UIからも確認できる。
作成したものを変更してみる。
nameが一致するものに対して変更が掛けられるようなので、descriptionを変更し、versionsとOASも追加する。
またコマンドには--auto-approveを追加し、確認プロンプトをスキップするようにする。
echo '
apis:
- ref: simple-api
name: My Simple API
description: My KongCTL Simple API example
versions:
- ref: user-service-v1
version: "1.0.0"
spec:
openapi: 3.0.0
info:
title: User Service API
version: 1.0.0
paths:
/users:
get:
summary: List users
/users/{id}:
get:
summary: Get user by ID
kongctl:
namespace: kongctl-demo
' | kongctl apply --auto-approve -f -
Konnect UIから確認すると、変更した箇所が取り込まれており、OASも確認できる。
なお、OASをベタ書きしたが、ファイル参照という形で引っ張ってくることも可能。
まずOASをファイルに出力する。(updateをかけるためにversionを1.0.1に変更している)
cat <<EOF > ./user-service.yaml
openapi: 3.0.0
info:
title: User Service API
version: 1.0.1
paths:
/users:
get:
summary: List users
/users/{id}:
get:
summary: Get user by ID
EOF
次に先程のYAMLをファイルを参照する形に変更する。
echo '
apis:
- ref: simple-api
name: My Simple API
description: My KongCTL Simple API example
versions:
- ref: user-service-v1
version: "1.0.1"
spec: !file ./user-service.yaml
kongctl:
namespace: kongctl-demo
' | kongctl apply --auto-approve -f -
!fileの後にファイルパスを指定することでファイル参照できる。
なお、ファイルパスは何故か絶対パスが使用できないので注意。
実行すると、OASが更新される。
次にDev Portalも追加してみる。
echo '
portals:
- ref: simple-portal
name: My Simple Portal
display_name: Simple Portal
description: The simplest Portal example
apis:
- ref: simple-api
name: My Simple API
description: My KongCTL Simple API example
versions:
- ref: user-service-v1
version: "1.0.1"
spec: !file ./user-service.yaml
kongctl:
namespace: kongctl-demo
publications:
- ref: simple-api-to-simple-portal
portal_id: !ref simple-portal#id
visibility: public
' | kongctl apply --auto-approve -f -
PortalとAPIの紐づけはpublicationsで行う。
ここのportal_idでrefを指定し、上にあるportalの設定を引っ張るようにしている。
また#idを付与することで、どのフィールドを参照するか指定できる。
実行するとDev Portalが作成され、APIも紐づけられる。
検証（応用編）
最後に、サンプルの中に実用的なものが1つあったのでこれを試してみる。
利用するサンプルはこちら。
以下サンプルサイトからのコピペだが、プラットフォームチームがDev PortalやAPIsを管理し、開発チーム（team-a, team-b）がAPIsの一部とOAS、ドキュメントを管理するような構成を想定している。
またDev PortalのUIのデザインもリポジトリ内に含めている。
external/
├── platform/ # Platform team manages the shared portal
│ ├── portal.yaml # Portal definition with pages and customization
│ ├── api.yaml # Platform API published to their portal
│ ├── pages/ # Portal content pages
│ ├── snippets/ # Reusable portal content snippets
│ ├── specs/ # OpenAPI specifications
│ └── docs/ # API documentation
├── team-a/ # Team A manages customer analytics
│ ├── api.yaml # API + external portal reference
│ ├── specs/ # API specifications
│ └── docs/ # API documentation
├── team-b/ # Team B manages payment processing
│ ├── api.yaml # API + external portal reference
│ ├── specs/ # API specifications
│ └── docs/ # API documentation
└── README.md # This file
これを適用するためにファイルをコピーする。
git clone https://github.com/Kong/kongctl.git
cd kongctl/docs/examples/declarative/external
READMEの手順に従って適用する。
cd platform/
kongctl apply --auto-approve portal.yaml api.yaml
cd ../team-a/
kongctl apply --auto-approve api.yaml
cd ../team-b/
kongctl apply --auto-approve api.yaml
デプロイすると3つのAPIが作成され、Dev Portalも作成されて紐づけられる。
またDev PortalのUIもカスタマイズされた形でデプロイされる。
実際に利用する際の構成等の参考になりそうだ。
所感
従来APIOpsでAPIsやDev Portalを変更していくのはAPIベースで実装する必要があってかなり大変であり、構成などもYAML管理は出来なかったのでGitOps的なアプローチが難しかった。
今回のkongctlの登場により、Konnect内のコンポーネントがYAML管理が可能になり、GitOps的な運用もやりやすくなった。
APIOpsのパイプラインの実装がかなり楽になると思う。
また、deckとの統合が今後予定されているようなので、Gateway設定との連携もよりやすくなりそうである。
なお、触っていて1つ辛かったのが、やたらトークンが切れるのが早かった点である。
トークン内には1時間持つような設定が書いてあるのだが、JWTの中では15分に設定されていて、15分起きに認証し直さないといけないのがかなり面倒だった。
将来的に仕様が変わるのを期待したい。
あとDev PortalのWebページもMDCファイルとしてファイル管理出来るが、現時点ではkongctlでダンプする機能もなく、VSCodeでMDCファイルをプレビューする拡張もないので、結局Konnect UI上で編集する必要があるのが痛い。
Dev PortalのWebページにGitOps的なアプローチを行うのはもう少し待った方が良いと思われる。
※12/9追記：
kongctl get portal pages --portal-name "<Dev Portal名>" <Page ID>でMDCファイルをダンプ出来る模様。
ただ一括ダンプなどは出来ないので、UIで作った環境をダンプするにはkongctl get portal pages --portal-name "<Dev Portal名>"で一覧取得後にfor文を回すなど、プログラマブルなアプローチが必要そう。