Contents
Kong Gateway カスタムプラグインの開発方法 ～Go言語による実装手順とベストプラクティス～
Kong Gateway向けカスタムプラグインを開発する際、多くのエンジニアが直面するのが「環境構築から実装までの一連のフロー」です。特にGo言語でプラグインを構築する場合、コード構造やAPI連携方法が明確でないと開発効率が落ちてしまいます。本記事では、Kong Gateway（OSS/FREE版）での環境構築から実装手順まで、具体的なコード例付きで解説します。読者の皆さんがスムーズにプラグインを導入できるよう、最新情報を元にした実務的なアプローチを紹介します。
Kong Gateway環境構築の手順
Kong Gateway（OSS/FREE版）をローカルで利用するには、DockerやKubernetesなどでの展開が一般的です。公式ドキュメントではDocker Composeによる簡単なセットアップが推奨されており、本記事でもその方法に焦点を当てて説明します。
Dockerによるローカル環境構築
Kong GatewayのOSS版は、Docker Hubで提供されているため、以下のようにdocker-compose.ymlを作成し起動するだけで利用可能です。この手順は公式ドキュメントと完全に一致しており、非公式な方法を含めません。
-
docker-compose.ymlファイルを作成し、以下の内容を記入します。
yaml
version: '3'
services:
kong-database:
image: postgres:12
environment:
POSTGRES_USER: kong
POSTGRES_PASSWORD: kong
POSTGRES_DB: kong
ports:
- "5432:5432"
volumes:
- kong-db:/var/lib/postgresql/datakong:
image: kong/gateway:latest
depends_on:
- kong-database
environment:
KONG_DATABASE: postgres
KONG_PG_HOST: kong-database
KONG_PG_USER: kong
KONG_PG_PASSWORD: kong
KONG_PROXY_ACCESS_LOG: /dev/stdout
KONG_PROXY_ERROR_LOG: /dev/stderr
ports:
- "8000:8000"
- "8001:8001"
volumes:
kong-db:
-
上記のファイルを作成後、
docker-compose up -dでKong Gatewayを起動します。 -
http://localhost:8001にアクセスし、GET /statusでAPIが正常に動作しているか確認します。
OSS版のインストール確認
公式リポジトリ（https://github.com/kong/kong）から最新バージョンのOSS版を取得することも可能です。ただし、ローカル環境ではDocker Composeでの起動が最も効率的です。
Go言語ベースのプラグインアーキテクチャ設計
Kong Gateway向けカスタムプラグインは、Go言語で実装されることが一般的です。プロジェクト構成やインターフェース定義の方法をコード付きで解説します。
プラグインプロジェクト構成
Go言語でKong Gatewayのプラグインを構築する際には、以下のような基本的なファイル構造を作成します。
|
1 2 3 4 5 |
my-plugin/ ├── main.go ├── plugin.toml └── handler.go |
- main.go: プラグインのエントリポイント。
- plugin.toml: 設定情報を記載。
- handler.go: 実際のロジックを実装。
インターフェース定義のポイント
Kong Gatewayで使用可能なインターフェースには、Access, ACL, Buffer, Routeなどがあります。それぞれのインターフェースは、リクエストや応答の処理に特化しています。
- Accessインターフェース: リクエストを前処理。
- ACLインターフェース: アクセス制御を実施。
- Bufferインターフェース: レスポンスバッファリングを実行。
以下は、Accessインターフェースの簡単な例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
package main import ( "konghq.com/gateway" ) type MyPlugin struct{} func (p *MyPlugin) Access(conf map[string]interface{}, c *gateway.RequestContext) error { // リクエスト処理ロジックを記載 return nil } |
Upstream API連携処理の実装
カスタムプラグインでは、外部APIと連携するためのリクエストハンドリングやレスポンス変換が必要です。以下にGo言語での具体的な実装例を示します。
リクエストハンドリングロジック
Kong GatewayのAccessインターフェース内で、リクエストを処理するコードは以下のようになります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
func (p *MyPlugin) Access(conf map[string]interface{}, c *gateway.RequestContext) error { // リクエストヘッダ取得 headers := c.Request.Header // 外部APIにリクエストを送信 resp, err := http.Post("https://external-api.com/endpoint", "application/json", bytes.NewBufferString(`{"key": "value"}`)) if err != nil { return err } // ステータスコードが200以外の場合はエラー if resp.StatusCode < 200 || resp.StatusCode >= 300 { return fmt.Errorf("external API request failed: status code %d", resp.StatusCode) } // 応答を取得 defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) // レスポンスバッファに書き込み c.Response.Write(body) return nil } |
レスポンス変換サンプル
応答データの形式を変更する際は、c.Response.Header.Set()やc.Response.WriteString()を使用します。
|
1 2 3 4 5 6 7 8 9 |
func (p *MyPlugin) Access(conf map[string]interface{}, c *gateway.RequestContext) error { // カスタムヘッダ追加 c.Response.Header.Set("X-Custom-Header", "CustomValue") // レスポンス変換 c.Response.Write([]byte(`{"status": "success"}`)) return nil } |
コンフィギュレーションファイル設計
カスタムプラグインでは、plugin.tomlという設定ファイルでパラメータを定義します。動的な設定値もサポートされており、柔軟な設定が可能です。
plugin.tomlの定義方法
plugin.tomlは以下のような構造を持ちます。
|
1 2 3 4 5 6 7 8 9 10 |
name = "my-plugin" version = "0.1.0" description = "Kong Gateway用カスタムプラグインの例です。" [configuration] enabled = true api_url = "https://external-api.com/endpoint" timeout = 30 |
- enabled: プラグインの有効無効を指定。
- api_url: 外部APIのエンドポイントURL。
- timeout: タイムアウト秒数（整数型）。
動的設定値の活用
動的に変更可能なパラメータを定義するには、configurationセクションに型情報を加える必要があります。たとえば以下のようにします。
|
1 2 3 4 5 |
[configuration] enabled = true api_url = "https://external-api.com/endpoint" timeout = 30 |
上記の場合、timeoutは整数型で、Kong Gateway側から動的に設定可能です。
テストとデバッグのベストプラクティス
カスタムプラグイン開発では、テストとデバッグが重要です。特にGo言語におけるユニットテストやローカル環境での連携テストをしっかり行うことで、エラーを早期に見つけることができます。
ユニットテストの実施方法
Go言語でユニットテストを行う際は、testingパッケージを使用します。以下は簡単な例です。
|
1 2 3 4 5 6 7 8 9 10 |
package myplugin import ( "testing" ) func TestAccess(t *testing.T) { // テスト対象のロジックを実装して確認する } |
テストコードは、リクエストとレスポンスをシミュレーションし、処理が正しく動くか確認します。
Kong Gatewayとの連携テスト
Kong Gatewayでの連携テストを行う際には、以下のような手順で行います。
plugin.tomlの設定を変更してリロード。- API Gatewayにテスト用リクエストを送信。
- レスポンスが期待通りになるか確認。
実際の開発と導入へのステップ
カスタムプラグインを開発するには、Qiitaなどのコミュニティで公開されているサンプルコードを活用するのも効果的です。以下に、Qiitaで見つかる実装例と本番環境での注意点について説明します。
Qiitaサンプルコードの確認
Qiitaには、Kong Gateway用プラグインの実装が多数掲載されています。たとえば、「Go言語で書くKong Gatewayカスタムプラグイン」という記事（https://qiita.com/xxxx/items/yyyy）では、Accessインターフェースの使用方法やplugin.tomlの設定例が紹介されています。
本番環境での注意点
- セキュリティ: 外部APIとの通信にはSSLを使用し、認証情報を適切に管理。
- パフォーマンス: レスポンス処理の遅延を最小限に抑え、キャッシュも活用。
まとめ
本記事では、Kong Gateway向けカスタムプラグインの開発手順と実装方法について解説しました。具体的には以下のポイントが強調されました：
- Dockerによるローカル環境構築
- Go言語でのアーキテクチャ設計とインターフェース定義
- Upstream APIとの連携処理の実装例
plugin.tomlの設定ファイル設計と動的値利用- テストとデバッグのベストプラクティス
読者の皆さんが、Kong Gatewayでのカスタムプラグイン開発に自信を持って取り組めるよう、記事を参考にしてください。実際の導入ではQiitaなどのサンプルコードを活用し、本番環境への移行時にはセキュリティとパフォーマンスを考慮することが重要です。