☸️
Tilt, ctlptlを使ったKubernetesマイクロサービス用ローカル開発環境構築

2024/12/01に公開
Docker
 はじめに本記事では、Tilt、ctlptlを使用してDocker+Kubernetesのローカル開発環境を構築する方法について説明します。

 前提Dockerの実行環境はすでに構築されているものとしています。

 ツールの概要
Tilt: Tiltは、ローカル開発環境でのマイクロサービスのビルド、デプロイ、デバッグを簡素化するツールです。
保存したファイルに関連するコンテナを自動でリビルド・デプロイしてくれるため、稼働確認の負荷が低減できます。


ctlptl: ctlptlは、Kubernetesクラスターの管理を簡素化するツールで、ローカル開発環境でのクラスターの作成や管理を支援します。
Tiltがビルドしたイメージをpushするためのローカルregistryや、コンテナを実行するKubernetesクラスターを起動してくれます。また、Tilt/ローカルregistry/Kubernetesクラスター間の接続設定も行ってくれます。
tiltからローカルregistryにpushするための設定, ローカルRegistryとKubernetesクラスターの接続設定はハマりやすいところなので、それをコマンド一発で構築してくれて便利です。


 環境別インストール方法各環境別のインストール方法は下記の通りです。

 macOS/LinuxTilt
下記のコマンドを実行します。curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash

ctlptl
brewを利用したインストール方法が提供されています。brew install tilt-dev/tap/ctlptl
下記のコマンドを実行することでもインストールできます。# ※armアーキテクチャの場合、x86_64 → arm64 に置換してください
# macOSの場合
CTLPTL_VERSION="0.8.36"
curl -fsSL https://github.com/tilt-dev/ctlptl/releases/download/v$CTLPTL_VERSION/ctlptl.$CTLPTL_VERSION.mac.x86_64.tar.gz | sudo tar -xzv -C /usr/local/bin ctlptl
# Linuxの場合
CTLPTL_VERSION="0.8.36"
curl -fsSL https://github.com/tilt-dev/ctlptl/releases/download/v$CTLPTL_VERSION/ctlptl.$CTLPTL_VERSION.linux.x86_64.tar.gz | sudo tar -xzv -C /usr/local/bin ctlptl


 WindowsTilt
Powershellで下記のコマンドを実行します。iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.ps1'))

ctlptl
scoopを利用したインストール方法が提供されています。scoop bucket add tilt-dev https://github.com/tilt-dev/scoop-bucket
scoop install ctlptl
Powershellで下記のコマンドを実行することでもインストールできます。$CTLPTL_VERSION = "0.8.36"
Invoke-WebRequest "https://github.com/tilt-dev/ctlptl/releases/download/v$CTLPTL_VERSION/ctlptl.$CTLPTL_VERSION.windows.x86_64.zip" -OutFile "ctlptl.zip"
Expand-Archive "ctlptl.zip" -DestinationPath "ctlptl"
Move-Item -Force -Path "ctlptl\ctlptl.exe" -Destination "$home\bin\ctlptl.exe"


 ローカルKubernetes環境の起動
 ctlptlを実行して、Kuberneteクラスターを起動するImage Registryの設定 を参考に、KubernetesクラスターがImageをPullするRegistryを設定します。
以下のコマンドを実行すると、KubernetesクラスターとRegistryをまとめて起動することができます。
ctlptl create cluster kind --registry=ctlptl-registry
毎回起動するのが面倒な場合、.bashrcに以下のコマンドを追加しておけば、簡単に起動できます。
cat <<EOF | ctlptl apply -f - &
apiVersion: ctlptl.dev/v1alpha1
kind: Cluster
product: kind
registry: ctlptl-registry
EOF
minikube等、その他のクラスターの作成方法は、ctlptlのREADMEを参照してください。

 Tiltの稼働確認上記、Kubernetesクラスタの起動が完了したら、Tiltでのコンテナビルド・Kuberenetesクラスタへのデプロイが実行できるようになっているはずです。
tiltのサンプルプロジェクトをcloneして、tiltを実行してみましょう。
git clone https://github.com/tilt-dev/tilt-avatars.git
cd tilt-avatars/
tilt up
tilt up を実行すると、以下のようなメッセージが表示されます。
Tilt started on http://localhost:10350/
v0.33.21, built 2024-11-08

(space) to open the browser
(s) to stream logs (--stream=true)
(t) to open legacy terminal mode (--legacy=true)
(ctrl-c) to exit
http://localhost:10350/ にアクセスすると、TiltのWebUIが表示されます。

api, webコンテナのビルド・実行が成功していればOKです。
http://localhost:5735/ にアクセスすると、アバター作成のサンプルアプリケーション画面が表示されます。

 導入時に必要な設定ここからは、自分のマイクロサービスをTiltでデプロイする際に必要な設定について説明します。

 コンテナイメージのビルド設定tilt-avatersのTiltfileを参考にします。
docker_build(
    'tilt-avatar-api', # コンテナ名(kubernetesマニフェストと対応させる)
    context='.', # Dockerビルドコンテキスト
    dockerfile='./deploy/api.dockerfile', # Dockerfileのパス
    only=['./api/'], # ファイルの変更を監視するディレクトリ（設定しない場合、Dockerビルドコンテキストを監視）
    live_update=[   # ライブアップデートの設定
        sync('./api/', '/app/api/'),  # ローカルのディレクトリとコンテナのディレクトリを同期
        run(
            'pip install -r /app/requirements.txt', # requirements.txtをインストール
            trigger=['./api/requirements.txt'] # ./api/requirements.txtが変更された場合に実行
        )
    ]
)
上記設定は、以下のように働きます。
起動時は tiltfileの存在するディレクトリをビルドコンテキストにして、./deploy/api.dockerfile に従ってコンテナイメージをビルド・実行

./api/ ディレクトリの変更があった場合、コンテナ内の /app/api/ ディレクトリに同期

./api/requirements.txt が変更された場合、コンテナ内で pip install -r /app/requirements.txt を実行

 live_updateの注意点syncコマンドはあくまでローカルのディレクトリとコンテナのディレクトリを同期するだけです。

Dockerfile内で「ビルドステージ→実行ステージ」のようなマルチステージビルドを行っている場合、live_updateを無効化し、ビルドステージにキャッシュを設定するなどの対応が必要です。

（キャッシュを有効にしないと、保存のたびに再ビルドが走るので非常にストレスフルです）
まとめると、以下のようになります。

静的ファイルや、事前コンパイル不要な言語のソースコード：live_updateのsync設定がおすすめ
上記以外（コンパイルが必要な言語のソースコードなど）：sync対象から外した上で、ビルドを高速化する対策が必要（ビルドキャッシュを有効にするなど）
参考までに、Go言語でマルチステージビルドを行っていた際の例を以下に示します。
例：Golangでビルドキャッシュを有効にする例
FROM golang:1.16 AS build

WORKDIR /app
COPY go.mod go.sum ./
ENV GOMODCACHE=/go/pkg/mod
RUN --mount=type=cache,target="/go/pkg/mod" go mod download && go mod verify

COPY . .
ENV GOCACHE=/go/cache
RUN --mount=type=cache,target="/go/cache" \
    --mount=type=cache,target="/go/pkg/mod" \
    go build -o /app/app

FROM golang:1.23
WORKDIR /app
COPY --from=build /app/app /app/app
CMD ["/app/app"]

 Kubernetesマニフェストの設定TiltfileにKubernetesマニフェストを設定します。

こちらも、tilt-avatarsのTiltfileを参考にします。
yamlファイルをひとつずつ読み込む場合は、以下のように記述します。
k8s_yaml('deploy/api-deployment.yaml')
起動したPodにブラウザやPostman等でアクセスする場合は、以下のようにポートフォワーディングを設定します。
# tilt-avatarsの例
k8s_resource(
    'web',
    port_forwards='5735:5173', # 5173 is the port Vite listens on in the container
    labels=['frontend'] # 整理用のラベル設定
)
上記の通り、起動したPodには、整理用のラベルを設定することもできます。
kustomizeやhelmを利用することもできます。

詳細は、Tiltfile API Referenceを参照してください。

 まとめ以上の設定により、ローカル環境でKubernetesを利用したマイクロサービスの稼働確認ができるようになります。
保存したコードをすぐ稼働確認できてとても便利です！ぜひ試してみてください。

 参考ページインストール手順
Tilt
ctlptl


Live Update Reference | Tilt: Tiltの主要機能であるLive Updateの設定方法についてのドキュメント
ctlptl | GitHub

Tiltfile API Reference | Tilt: TiltfileのAPIリファレンス
はじめに

前提

ツールの概要

環境別インストール方法

macOS/Linux

Windows

ローカルKubernetes環境の起動

ctlptlを実行して、Kuberneteクラスターを起動する

Tiltの稼働確認

導入時に必要な設定

コンテナイメージのビルド設定

live_updateの注意点

Kubernetesマニフェストの設定

まとめ

参考ページ

Discussion
