LocalStack でローカル AWS 開発環境構築

Docker 上で S3, DynamoDB, Lambda などの AWS サービスをエミュレートし、AWS API 互換のローカル開発環境を整える手順です。

LocalStack とは

AWS クラウドスタックをローカルで実行するツールです。Docker 上で動作し、S3、DynamoDB、Lambda、SQS などの主要 AWS サービスをエミュレートできます。

主な特徴

クイックスタート

1. Docker Compose で起動

version: '3.8'
services:
  localstack:
    image: localstack/localstack:latest
    ports:
      - "4566:4566"
    environment:
      - SERVICES=s3,dynamodb,lambda,sqs
      - DEBUG=1
    volumes:
      - "./localstack:/tmp/localstack"

2. コンテナ起動

$ docker-compose up -d
$ docker-compose logs -f localstack

AWS CLI でアクセス

プロファイル設定

$ aws configure --profile localstack
AWS Access Key ID: test
AWS Secret Access Key: test
Default region: us-east-1

S3 にアクセス

$ aws --profile localstack --endpoint-url http://localhost:4566 s3 mb s3://my-bucket
$ aws --profile localstack --endpoint-url http://localhost:4566 s3 ls

DynamoDB テーブル作成

$ aws --profile localstack --endpoint-url http://localhost:4566 \
  dynamodb create-table \
  --table-name Users \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

サポートされている AWS サービス

サービス エンドポイント 対応度
S3 localhost:4566 完全
DynamoDB localhost:4566 完全
Lambda localhost:4566 ほぼ完全
SQS localhost:4566 ほぼ完全
SNS localhost:4566 ほぼ完全

Lambda 関数をデプロイ

Python 関数作成

def handler(event, context):
    return {
        'statusCode': 200,
        'body': 'Hello from Lambda!'
    }

ZIP にパッケージ化

$ zip function.zip lambda_function.py

LocalStack にデプロイ

$ aws --profile localstack --endpoint-url http://localhost:4566 \
  lambda create-function \
  --function-name my-function \
  --runtime python3.9 \
  --role arn:aws:iam::000000000000:role/lambda-role \
  --handler lambda_function.handler \
  --zip-file fileb://function.zip

データ永続化

# docker-compose.yml で volumes を設定
volumes:
  - "./localstack:/tmp/localstack"
  
# コンテナ再起動時もデータが保持される

ログ確認

$ docker logs -f localstack
# または
$ docker-compose logs -f localstack

よくあるエラーと対処

エラー 対処方法
接続拒否 (Connection refused) docker-compose up -d でコンテナが起動しているか確認
ポート 4566 が既に使われている lsof -i :4566 で確認、別のポートに変更
API キーエラー aws configure で test / test を設定、endpoint-url を指定

参考リンク