LocalStackとTerraformでAWSをローカルテストする方法｜アカウント不要の開発・デバッグ環境設計

この記事のポイント

・LocalStackはDockerで起動できるAWSモックサーバーで、S3・EC2・IAM・SQSなどに対応
・TerraformのproviderにLocalStack用のエンドポイントを設定することで接続できる
・ダミー認証情報（access_key / secret_key = "test"）を使えば本物のAWSクレデンシャルは不要
・variable + tfvarsで本番AWSとLocalStackを環境ごとに切り替える設計が実用的

# Dockerの動作確認
docker --version
docker info | head -5

# 作業ディレクトリを作成
mkdir ~/localstack-tf && cd ~/localstack-tf

# docker-compose.yml を作成
cat > docker-compose.yml << 'EOF'
version: "3.8"
services:
  localstack:
    container_name: localstack-main
    image: localstack/localstack:latest
    ports:
      - "127.0.0.1:4566:4566"
    environment:
      - SERVICES=s3,ec2,iam,sts
      - DEFAULT_REGION=ap-northeast-1
    volumes:
      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"
EOF

# コンテナを起動
docker compose up -d

curl -s http://localhost:4566/_localstack/health | python3 -m json.tool

{
    "services": {
        "ec2": "available",
        "iam": "available",
        "s3": "running",
        "sts": "available"
    },
    "version": "3.8.0"
}

# provider.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region                      = "ap-northeast-1"
  access_key                  = "test"
  secret_key                  = "test"
  skip_credentials_validation = true
  skip_requesting_account_id  = true
  skip_metadata_api_check     = true

  endpoints {
    s3  = "http://localhost:4566"
    ec2 = "http://localhost:4566"
    iam = "http://localhost:4566"
    sts = "http://localhost:4566"
  }
}

# main.tf
resource "aws_s3_bucket" "example" {
  bucket = "my-test-bucket-localstack"
}

terraform init
terraform apply -auto-approve

aws_s3_bucket.example: Creating...
aws_s3_bucket.example: Creation complete after 0s [id=my-test-bucket-localstack]

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

aws --endpoint-url=http://localhost:4566 s3 ls

2026-01-01 00:00:00 my-test-bucket-localstack

# variables.tf
variable "localstack_endpoint" {
  description = "LocalStackのエンドポイント。空文字列にすると本番AWSを使用する"
  type        = string
  default     = "http://localhost:4566"
}

# provider.tf（切り替え対応版）
provider "aws" {
  region = "ap-northeast-1"

  # LocalStack用ダミー認証（本番ではIAMロールや環境変数を使用）
  access_key                  = var.localstack_endpoint != "" ? "test" : null
  secret_key                  = var.localstack_endpoint != "" ? "test" : null
  skip_credentials_validation = var.localstack_endpoint != "" ? true : false
  skip_requesting_account_id  = var.localstack_endpoint != "" ? true : false
  skip_metadata_api_check     = var.localstack_endpoint != "" ? true : false

  dynamic "endpoints" {
    for_each = var.localstack_endpoint != "" ? [1] : []
    content {
      s3  = var.localstack_endpoint
      ec2 = var.localstack_endpoint
      iam = var.localstack_endpoint
      sts = var.localstack_endpoint
    }
  }
}

# local.tfvars（LocalStack用）
localstack_endpoint = "http://localhost:4566"

# production.tfvars（本番AWS用）
localstack_endpoint = ""

# LocalStackで確認
terraform apply -var-file=local.tfvars

# 本番AWSに適用
terraform apply -var-file=production.tfvars

# コンテナの状態確認
docker compose ps
docker compose logs localstack | tail -20

# ポートが使用中かを確認
ss -tlnp | grep 4566