📺

Terraform + LocalStack + Python で AWS エミュレーション環境を作る

に公開

迫られたときに書く記事は一種の趣があると信じて。

これはなに?

Terraform で IaC した構成を LocalStack っていう AWS エミュレーター環境に反映させて、その環境に Python からアクセスできるようにしてやろうぜ、って記事です。粗製濫造と言われたらそれまでだけど、俺は誓って Claude はやってません。 ……ちょっとだけ嘘です。記事はマジでお手製だけどセットアップの検証とデバッグは Claude Sonnet を使ってます。

前提

  • 私は Terraform も IaC も何も知りません。そこにあるから使います
  • AWS もよく知らん……あれを分かったという人は Lean のプロとかじゃないんですか……?
  • Docker でどっかーんする必要があるので、ご用意ください
  • uv と mise もつかいます。 uv は Python 環境用、mise は awscli と terraform を入れて、ディレクトリ別に環境変数を管理するのにも使います。
    • uv はともかく aws と terraform コマンドは別で入れます、って人は mise が無くてもオケ。

誰向け?

私向けだよ!!!!!!!!

フェーズ1: LocalStack の準備

ツールチェインと環境変数の準備

ツールチェインの導入について。
Docker の導入は割愛します。 mise を入れた状態で mise use terraform awscli すれば terraform と aws コマンドが使えるようになります。

環境変数について。
mise を使えば特定ディレクトリに居るとき限定で指定した環境変数を使えるように仕込めます。 LocalStack を使うためには aws に接続先を知らせる必要があるので、環境変数で渡すことにします。 AWS_PROFILE が設定されていてもこっちの設定が優先されるようです。

mise.toml
[env]
AWS_ACCESS_KEY_ID = "test"
AWS_SECRET_ACCESS_KEY = "test"
AWS_DEFAULT_REGION = "ap-southeast-1"
AWS_ENDPOINT_URL = "http://localhost:4566"

実は認証なんていらないんですが、都合必要らしいです。

LocalStack の準備

Docker コンテナを使ってサクッと立ち上げられるので、そうします。 SERVICES は適量必要なのをご指定ください。無料バージョンとエンプラバージョンで使えるサービスがわりと異なりますが、別に無料バージョンでも大体困らないと思う。

compose.yaml
services:
  localstack:
    image: localstack/localstack:4.7
    container_name: localstack
    ports:
      - 4566:4566
      - 4510-4559:4510-4559
    environment:
      - DEBUG=1
      - PERSISTENCE=1
      - SERVICES=ec2,s3,sqs,secretsmanager,iam
    volumes:
      - ./localstack:/var/lib/localstack
      - /var/run/docker.sock:/var/run/docker.sock

Terraform 構成の準備

今回は S3 と Secrets Manager の2つを使うものとします。 適当にファイルを分けると、Terraform 構成ファイルは三つ必要になります。 aws.tf はプロパイダ設定、 aws-s3.tf と aws-secretsmanager.tf はサービス固有の設定です。

これらはルートディレクトリ直下に置いてもいいし、よくわからなくなってきたら /infra とかに置いてしまっても良いと思います。ファイルが同じディレクトリにあればどこでも良さげです。

aws.tf
terraform {
  backend "local" {}
}

provider "aws" {
  region = "ap-southeast-1"
  access_key = "test"
  secret_key = "test"

  s3_use_path_style           = true
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true

  endpoints {
    s3 = "http://localhost:4566"
    secretsmanager = "http://localhost:4566"
  }
}
aws-s3.tf
resource "aws_s3_bucket" "localstack-bucket-1" {
  bucket = "localstack-bucket-1"
}

resource "aws_s3_bucket" "localstack-bucket-2" {
  bucket = "localstack-bucket-2"
}
aws-secretsmanager.tf
resource "aws_secretsmanager_secret" "localstack-secrets" {
  name = "localstack-secrets"
}

resource "aws_secretsmanager_secret_version" "localstack-secrets" {
  secret_id     = aws_secretsmanager_secret.localstack-secrets.id
  secret_string = jsonencode({ key = "value" })
}

エミュレーション環境の立ち上げと設定の反映

まずは docker compose up -d とかで LocalStack コンテナを立ち上げたうえで、aws で通信が疎通するか確かめてみてください。 現時点では何の設定も投入されていないので、何を見ても何も無いはずです。

 ❯ aws s3 ls

次に Terraform を使って IaC なスタイルでインフラ構成を LocalStack に反映させます。 terraform plan で反映されるインフラ構成を調べたうえで、terraform apply で実際に環境に設定を適用できます。 一応実行ログのサンプルを次に示します (長いので terraform apply だけです)。

 ❯ terraform apply

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # aws_s3_bucket.localstack-bucket-1 will be created
  + resource "aws_s3_bucket" "localstack-bucket-1" {
      割愛
    }

  # aws_s3_bucket.localstack-bucket-2 will be created
  + resource "aws_s3_bucket" "localstack-bucket-2" {
      割愛
    }

  # aws_secretsmanager_secret.localstack-secrets will be created
  + resource "aws_secretsmanager_secret" "localstack-secrets" {
      割愛
    }

  # aws_secretsmanager_secret_version.localstack-secrets will be created
  + resource "aws_secretsmanager_secret_version" "localstack-secrets" {
      割愛
    }

Plan: 4 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

aws_secretsmanager_secret.localstack-secrets: Creating...
aws_s3_bucket.localstack-bucket-2: Creating...
aws_s3_bucket.localstack-bucket-1: Creating...
aws_secretsmanager_secret.localstack-secrets: Creation complete after 0s [id=arn:aws:secretsmanager:ap-southeast-1:000000000000:secret:localstack-secrets-mbKXXP]
aws_secretsmanager_secret_version.localstack-secrets: Creating...
aws_secretsmanager_secret_version.localstack-secrets: Creation complete after 0s [id=arn:aws:secretsmanager:ap-southeast-1:000000000000:secret:localstack-secrets-mbKXXP|terraform-20260224111852913900000002]
aws_s3_bucket.localstack-bucket-1: Creation complete after 0s [id=localstack-bucket-1]
aws_s3_bucket.localstack-bucket-2: Creation complete after 0s [id=localstack-bucket-2]

Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

成功したっぽく見えたら、再度 aws を実行して Terraform の構成が LocalStack に反映されているか確かめてみてください。

❯ aws s3 ls
2026-02-24 20:36:20 localstack-bucket-1
2026-02-24 20:36:20 localstack-bucket-2

フェーズ2: Python を使ったアクセス

aioboto3 ライブラリの導入

uv add aioboto3 "types-aioboto3[essential,secretsmanager]" を実行して aioboto3 と types-aioboto3 (型スタブ) を入れます。型スタブがないとマジで話にならないので入れたほうが良いです。 一応説明すると、boto3 は Python 用の AWS の SDK で、aioboto3 はその async 版です。

スクリプトを書いて実行する

前述の通りにやっているなら、すべての変数には適切に型ヒントが付いているはずです。

import asyncio

import aioboto3


async def main() -> None:
    endpoint = "http://localhost:4566"
    region = "ap-southeast-1"
    session = aioboto3.Session()

    async with (
        session.client("s3", endpoint_url=endpoint, region_name=region) as s3,
        session.client(
            "secretsmanager", endpoint_url=endpoint, region_name=region
        ) as secretsmanager,
    ):
        print("S3:")
        for bucket in (await s3.list_buckets()).get("Buckets", []):
            bucket_name = bucket.get("Name")
            print(f"    - {bucket_name}")

        print("\n")
        print("Secrets Manager:")
        for secret in (await secretsmanager.list_secrets()).get("SecretList", []):
            if (secret_name := secret.get("Name")) is None:
                continue

            secret_value = (
                await secretsmanager.get_secret_value(SecretId=secret_name)
            ).get("SecretString")

            print(f"    - {secret_name} ({secret_value})")


if __name__ == "__main__":
    asyncio.run(main())
 ❯ uv run main.py 
S3:
    - localstack-bucket-1
    - localstack-bucket-2


Secrets Manager:
    - localstack-secrets ({"key":"value"})

うまくいかなかったら、 aws が実は全然別の環境を指してましたとか、リージョンがズレてて見えないものを見ようとしていたとかそういう線を疑ってみてください。 とりあえずここまでくれば LocalStack で AWS をエミュレーションしつつ、ぱいてょんから AWS っぽいものをいじくるという動きができるようになるはずです。

おわりに

ゼンデブ の記事のアイコンって何にしたらパリっとするんですかね?

Discussion