localstack

LocalStack のライフサイクル管理

現在の LocalStack CLI である lstk を使用して、LocalStack エミュレーターのライフサイクル（ローカルクラウド環境の起動、停止、監視）を管理します。

機能

• カスタム設定で LocalStack を起動する
• 実行中の LocalStack インスタンスを停止、再起動、リセットする
• LocalStack のステータスとヘルスを確認する
• エミュレーターのボリュームと永続化された状態を管理する
• LocalStack プラットフォームで認証する

前提条件

• Docker がインストールされ、実行中であること
• LocalStack アカウント（lstk は localstack/localstack-pro イメージを取得し、有効なライセンスが必要です）
• lstk CLI：

# Homebrew (macOS/Linux)
brew install localstack/tap/lstk

# npm
npm install -g @localstack/lstk

# Verify
lstk --version

従来の localstack CLI は非推奨で、今後のバージョンで削除される予定です。lstk の使用を推奨します。一部の機能は引き続き従来の CLI でのみ利用できます。従来の CLI の代替手段を参照してください。

認証

# Interactive browser login; stores the token in the system keyring
lstk login

# Remove stored credentials
lstk logout

CI または TTY 以外の環境では、代わりに認証トークンを設定してください（CI 認証トークンを使用してください。個人用の Developer Auth Token は CI では機能しません）。

export LOCALSTACK_AUTH_TOKEN=<token>
lstk --non-interactive start

トークンの解決順序：システムのキーリング（lstk login から）→ LOCALSTACK_AUTH_TOKEN → 対話型ブラウザーログイン。キーリングは環境変数より優先されるため、切り替えが必要な場合は先に lstk logout を実行してください。

よく使うコマンド

LocalStack を起動する

# Start the emulator (bare `lstk` is equivalent to `lstk start`)
lstk start

# Start and keep state across restarts
lstk start --persist

# Start with debug logging (note the LOCALSTACK_ prefix)
LOCALSTACK_DEBUG=1 lstk start

# Pick the emulator type
lstk start --type aws          # also: snowflake, azure

# Plain output for scripts/CI, with a startup deadline
lstk --non-interactive --timeout 90s start

lstk start はコンテナーをバックグラウンドで実行し、エミュレーターの準備が整うと戻ります。-d フラグはありません。

ステータスを確認する

# Emulator state plus the resources currently deployed in it
lstk status

# Plain-text output for scripts
lstk --non-interactive status

# Service health endpoint
curl http://localhost:4566/_localstack/health | jq

停止と再起動

lstk stop
lstk restart
lstk restart --persist

状態をリセットする

# Discard all in-memory resources; the emulator keeps running
lstk reset
lstk reset --force        # skip the confirmation prompt

ログを表示する

lstk logs                 # print available logs
lstk logs -f              # follow in real time
lstk logs -n 100          # last 100 lines
lstk logs -v              # unfiltered output

ボリュームを管理する

lstk volume path          # print the volume directory
lstk volume clear         # wipe certificates, cached tools, persisted data
lstk volume clear --force

lstk reset はメモリー内の状態を消去し、lstk volume clear はディスク上のボリュームを消去します。ボリュームを消去する前に、エミュレーターを停止してください。

設定

環境変数の指定

lstk は、ホストの環境変数のうち LOCALSTACK_ をプレフィックスに持つものをエミュレーターに渡します。以前はプレフィックスなしで指定していた LocalStack 設定変数には、今後このプレフィックスを付ける必要があります。

LOCALSTACK_DEBUG=1 lstk start
LOCALSTACK_SERVICES=s3,sqs lstk start
LOCALSTACK_ENFORCE_IAM=soft lstk start

ホストの LOCALSTACK_AUTH_TOKEN は意図的に転送されないため、lstk が解決したトークンを上書きできません。

config.toml の環境プロファイル

毎回の実行で適用する設定には、config.toml で名前付きプロファイルを定義し、コンテナーブロックから参照します。プロファイル内のキーには LOCALSTACK_ プレフィックスを付ける必要はありません。

[[containers]]
type = "aws"
tag  = "latest"
port = "4566"
env  = ["debug", "ci"]

[env.debug]
DEBUG = "1"
PERSISTENCE = "1"

[env.ci]
SERVICES = "s3,sqs"
EAGER_SERVICE_LOADING = "1"

設定ファイルの解決順序：./.lstk/config.toml（プロジェクトローカル）→ $HOME/.config/lstk/config.toml → OS のデフォルトの場所。有効なパスは lstk config path で表示できます。

よく使う設定オプション

変数	説明	設定方法
DEBUG	デバッグログを有効にする	LOCALSTACK_DEBUG=1 lstk start または [env.*] プロファイル
PERSISTENCE	再起動後も状態を保持する	lstk start --persist（推奨）またはプロファイル
SERVICES	起動するサービスを制限する	LOCALSTACK_SERVICES=s3,sqs lstk start
GATEWAY_LISTEN	バインドするアドレス／ポート	プロファイルで GATEWAY_LISTEN = "0.0.0.0:4566"
LOCALSTACK_AUTH_TOKEN	プラットフォーム認証トークン	環境変数、または lstk login
LOCALSTACK_HOST	lstk aws などが使用するエンドポイントホストを上書きする	環境変数

config.toml の tag でイメージのバージョンを固定する（例：tag = "2026.4"）か、エアギャップ環境では image に内部レジストリーを指定します。

従来の CLI の代替手段

lstk は、まだ従来の機能すべてをカバーしているわけではありません。次の機能が必要な場合に限り、従来の CLI（pip install localstack）を lstk と併せてインストールしてください。

• 拡張機能 — lstk extensions コマンド一式はありません。localstack-extensions スキルを参照してください
• localstack aws iam stream / summary — IAM ポリシーのストリームとサマリー。localstack-iam スキルを参照してください
• 高度な DNS 設定（systemd-resolved との統合）と一時的なクラウドインスタンス

lstk は独自の Docker コンテナーを管理するため、Docker Compose の LocalStack セットアップや、従来の localstack start で起動したコンテナーと併用することはできません。自分で管理しているエミュレーターを lstk の接続先にするには、--endpoint-url を使用してください。

トラブルシューティング

• Error: runtime not healthy：Docker が実行されていません。Docker Desktop またはデーモンを起動するか、カスタムソケットを使用する場合は DOCKER_HOST を設定してください。
• ポート 443 の競合：環境プロファイルで GATEWAY_LISTEN = "0.0.0.0:4566" を設定し、4566 のみをバインドしてください。
• CI での認証エラー：lstk start の前に LOCALSTACK_AUTH_TOKEN を設定してください。TTY のない環境ではブラウザー認証フローを実行できません。
• ライセンスの期限切れ：lstk logout && lstk login。
• 不明な環境変数が反映されない：ホスト上で LOCALSTACK_ がプレフィックスとして付いていること、または [env.*] プロファイルに移動されていることを確認してください。
• 診断：lstk は設定ファイルと同じ場所に lstk.log を書き込みます。lstk config path で場所を確認してください。