目次
decK とは
decK は GO 言語で開発された Kong API Gateway（以下 Kong と呼称）の管理を支援する CLI（コマンドラインインターフェース）ツールです。Kong の宣言型設定書式を検査したり Kong クラスターの設定をバックアップ・リストアすることができます。主な機能は以下の通りです。
- Kong クラスターと設定を同期
- 設定の変更差分（diff）を検知
- Kong の設定をバックアップ
decK は宣言型の定義ファイルを扱う為、CI パイプラインの中で Kong に設定をプッシュするという使い方をすることができます。
前提
本記事は以下の環境で確認した内容を解説しています。インストール手順にある Windows と macOS の手順は公式ドキュメントをベースとした内容です。
- CentOS 7.9
- Windows10（インストール手順のみ確認）
- Docker CE 20.10.12 on CentOS 7.9（インストール手順のみ確認）
decK のインストールについて
deck バイナリファイルをインストールする方法を示します。手順は公式ドキュメントをベースとしていますが、アーカイブファイル展開時に解凍したファイルが散らばらないように作業ディレクトリ内で操作する手順を加えています。なお、deck バイナリファイルは新しいバージョンがよくリリースされますので、最新版は https://github.com/Kong/deck/releases を参照ください。
Windows の場合
Windows の場合は Windows PowerShell で操作します。
ダウンロードするアーカイブファイルは 4つほどファイルが含まれています。また、その中の deck.exe というバイナリファイルを置いておくだけで deck コマンドのインストールは終わります。ここではユーザーのホームフォルダ（$env:USERPROFILE）配下に decK というフォルダを作成し、その中でアーカイブファイルを展開します。もし、他のコマンドと同様にコマンド PATH にバイナリファイルをきちんと配置したい場合は、「Get-ChildItem env:Path」などでコマンド PATH の状況を調べて任意にバイナリファイルを配置してください。
New-Item $env:USERPROFILE\decK -ItemType Directory作業フォルダに移動します。
cd $env:USERPROFILE\decKdeck のアーカイブファイルをカレントフォルダにダウンロードします。
curl.exe -sL https://github.com/Kong/deck/releases/download/v1.10.0/deck_1.10.0_windows_amd64.tar.gz -o deck.tar.gzアーカイブファイルを展開します。
tar.exe xzvf .\deck.tar.gzダウンロードした deck.tar.gz アーカイブファイルは、展開後は不要なので削除します。展開されたファイルの中にある deck.exe バイナリファイルが deck コマンドそのものです。
> rm .\deck.tar.gz
> ls
ディレクトリ: C:\Users\admin\decK
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 2021/12/15 8:23 29581 CHANGELOG.md
-a---- 2021/12/15 8:25 10641920 deck.exe
-a---- 2021/12/15 8:23 11380 LICENSE
-a---- 2021/12/15 8:23 4165 README.md
> .\deck.exe version
decK v1.10.0 (27094f2)
>
macOS の場合
brew tap kong/deck
brew install deckLinux の場合
カレントディレクトリに deck のバイナリファイルをダウンロードします。
curl -sL https://github.com/Kong/deck/releases/download/v1.10.0/deck_1.10.0_linux_amd64.tar.gz -o deck.tar.gzカレントディレクトリにダウンロードした deck.tar.gz は以下のように 4 つのファイルが含まれているので、/tmp 配下に作業ディレクトリを作成し、そこでアーカイブファイルを展開します。
$ tar tvf deck.tar.gz
-rw-r--r-- runner/docker 29581 2021-12-15 08:23 CHANGELOG.md
-rw-r--r-- runner/docker 11380 2021-12-15 08:23 LICENSE
-rw-r--r-- runner/docker 4165 2021-12-15 08:23 README.md
-rwxr-xr-x runner/docker 10309632 2021-12-15 08:25 deck
$ mkdir /tmp/decktmp
$ tar xf deck.tar.gz -C /tmp/decktmp/
$/tmp/decktmp 配下に展開した deck バイナリファイルを /usr/local/bin ディレクトリ配下にコピーします。コマンドのバイナリファイルパスが異なる場合は適宜調整ください。
sudo cp /tmp/decktmp/deck /usr/local/bin/Docker image の場合
docker pull kong/deck以下に deck の ping コマンドを実行した動作確認例を示します。
[root@localhost ~]# docker run -d --network kong-ee-net kong/deck ping
2bede3861d0916c52e52756d20e500e8f9189f5c34d8d5ef08a3809ba939ab8c
[root@localhost ~]# docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS
NAMES
df168f93a841 kong-ee "/docker-entrypoint.…" 2 months ago Up 16 minutes 0.0.0.0:8000-8004->8000-8004/tcp, :::8000-8004->8000-8004/tcp, 0.0.0.0:8443-8445->8443-8445/tcp, :::8443-8445->8443-8445/tcp, 8446-8447/tcp kong-ee
52bbd2f5080f postgres:9.6 "docker-entrypoint.s…" 2 months ago Up 17 minutes 0.0.0.0:5432->5432/tcp, :::5432->5432/tcp kong-ee-database
[root@localhost ~]# docker network ls
NETWORK ID NAME DRIVER SCOPE
0566d0cbcbf4 bridge bridge local
384bdf261c65 host host local
7231ccca70c6 kong-ee-net bridge local
9b0a1bed84e7 minikube bridge local
14d6ac6026bc none null local
[root@localhost ~]#decK コマンドの書式
deck コマンドの書式は以下のとおりです。
deck [サブコマンド]コマンドのヘルプは「deck —help」です。サブコマンドに関する詳細なヘルプを見るときは、「deck [サブコマンド名] —help」（例：$ deck ping –help）のように実行します。
deck ping
Kong と通信ができるか確認をするコマンドです。一番シンプルな実行方法は以下の deck ping です。デフォルトでは http://localhost:8001 疎通確認をします。
deck pingdecK コマンドに認証トークンを渡す場合
Kong の管理者が RBAC ユーザーに設定されていて deck 操作時に認証トークンが必要な場合は、「—headers」オプションを付けて Kong-Admin-Token ヘッダーなどでトークン情報を渡します。例では kong のトークンを指定。
deck ping --headers kong-admin-token:kongdecK をリモートにある Kong に対して使う場合
「—kong-addr」オプションを使用します。decK は Admin API を使うので、ポート番号は Admin API が動作する管理ポート番号（例では 8001）を指定します。
deck ping --headers kong-admin-token:kong --kong-addr http://192.168.0.10:8001deck dump
deck dump コマンドは Kong のワークスペース内にある全てのエンティティを読み込み、yaml 形式のファイルを出力します。
deck dumpリモートの Kong に対して deck dump を実行する場合
リモートにある認証トークンを要求する Kong に対して実行する場合は以下のようになります。
deck dump --headers kong-admin-token:kong --kong-addr http://192.168.0.10:8001ワークスペースを指定した deck dump の実行
任意のワークスペースに対して deck dump を実行する場合は以下のように実行します。
deck dump --workspace [ワークスペース名]全てのワークスペースに対して deck dump を実行する場合
「—all-workspaces」オプションを使います。これを実行するとワークスペース毎に yaml ファイルがローカルに作成されます。そのため、任意の作業ディレクトリ内で実行することをおすすめします。
deck dump --all-workspacesdeck diff
deck diff はローカルファイルのエンティティ定義内容と操作対象の Kong エンティティを比較して差分を出力します。別な言い方をすれば、deck sync を実行した場合に何が変更されるか差分を示します。
# deck diff --headers kong-admin-token:kong
Summary:
Created: 0
Updated: 0
Deleted: 0
#deck sync
deck sync は、ローカルファイルのエンティティ定義内容を操作対象の Kong に同期させます。
# deck sync --headers kong-admin-token:kong
Summary:
Created: 0
Updated: 0
Deleted: 0
#$HOME/.deck.yaml ファイルによる decK のパラメーター設定
ここでは deck コマンド自体の設定ファイルについて解説します。decK は yaml 形式の config ファイルから deck コマンドに渡すパラメーター情報を読み込むことができます。たとえば、deck コマンド実行時に毎回「–kong-addr http://192.168.0.10:8001」や「–headers kong-admin-token:kong」など、同じオプション情報を入力するのは非効率です。このような場合、次のように deck コマンドの設定ファイルに毎回使うオプションなどを記述しておくと便利です。
例として「$ vi ~/.deck.yaml」を実行し、以下の内容でファイルを作成してみます。
# sample configuration file for global parameters of deck CLI.
kong-addr: http://192.168.0.10:8001
headers:
- "kong-admin-token:kong"
no-color: false
verbose: 0
# tls-skip-verify: false
# tls-server-name: my-server-name.example.com
# ca_cert : custom PEM encoded CA cert
実行してみます。deck はデフォルトで「~/.deck.yaml」ファイルが存在する場合は、内容を読み込んで動作します。そのため、この場合は —config オプションを使用しなくても「~/.deck.yaml」ファイルを読み込んだ動作になります。当該 yaml ファイルを他のファイルパスに置いた場合は —config オプションで明示的に指定します。
$ deck ping --config ~/.deck.yaml
Successfully connected to Kong!
Kong version: 2.6.0.2-enterprise-edition
$なお、上記で使用した deck.yaml ファイルは下記 URL にあるサンプルを利用して作成しました。