設定ファイル (pocket.toml)¶

デプロイに関する全ての設定は pocket.toml に記述します。

基本構造¶

[general]           # 全ステージ共通の設定
[vpc]               # VPC設定（単一、トップレベル）
[s3]                # S3設定（全ステージ共通）
[neon]              # Neon設定（全ステージ共通）
[tidb]              # TiDB Serverless設定（全ステージ共通）
[rds]               # RDS Aurora設定（全ステージ共通）
[ses]               # SES設定（全ステージ共通）
[awscontainer]      # Lambda設定（全ステージ共通）
[cloudfront]        # CloudFront設定（全ステージ共通）
[scheduler]         # EventBridge Scheduler 設定（全ステージ共通）

[dev.awscontainer]  # dev ステージ固有のLambda設定
[prod.s3]            # prod ステージ固有のS3設定

general（必須）¶

全ステージ共通の設定です。

[general]
region = "ap-northeast-1"
stages = ["dev", "prod"]

[general]
region = "ap-northeast-1"
stages = ["dev", "prod"]

[dev.general]
region = "ap-southeast-1"

general.django_fallback¶

ローカル環境で使うDjango設定を記述します。設定項目は awscontainer.django と同じです。

[general.django_fallback.storages]
default = { store = "filesystem" }
staticfiles = { store = "filesystem", static = true }

vpc¶

VPC設定をトップレベルで定義します。[vpc] を定義すると、awscontainer と rds は自動的に VPC 内に配置されます。

VPC名は {ref}-{namespace} 形式（例: main-pocket）になります。

[vpc]
ref = "main"
zone_suffixes = ["a", "c"]

EFS設定

VPC の共有（外部 VPC）¶

別プロジェクトが管理する VPC を利用する場合、manage = false を指定します。

VPC 所有者（Project A）:

[vpc]
ref = "main"
zone_suffixes = ["a", "c"]
sharable = true  # 共有を許可

VPC 利用者（Project B）:

[vpc]
ref = "main"        # 同じ ref → 同じ VPC
manage = false       # zone_suffixes 不要（自動取得）

use_vpc（awscontainer / rds）¶

awscontainer や rds セクションで use_vpc を指定すると、VPC の利用を明示的に制御できます。

[vpc]
ref = "main"
zone_suffixes = ["a"]

[awscontainer]
dockerfile_path = "pocket.Dockerfile"
use_vpc = false  # VPC を使わない

s3¶

S3バケットの設定です。

[s3]

bucket_name_format で使える変数:

• {namespace} — 名前空間
• {stage} — ステージ名
• {project} — プロジェクト名

[s3]
bucket_name_format = "{project}-{namespace}"
[prod.s3]
bucket_name_format = "{stage}-{project}-{namespace}"

cors¶

ブラウザから S3 presigned URL で直接アップロードする場合に必要な CORS 設定を宣言できます。

[s3]
cors = { methods = ["PUT", "GET"], cloudfront = "web" }

cloudfront で指定した [cloudfront.xxx] のドメインが AllowedOrigins に設定されます。

• カスタムドメインがある場合: https://dev.example.com
• カスタムドメインがない場合: https://*.cloudfront.net

AllowedHeaders は ["*"]、MaxAgeSeconds は 3600 で固定です。

[s3]
cors = { methods = ["PUT", "GET"], cloudfront = ["web", "media"] }

versioning¶

versioning = true で S3 バケットの versioning を有効化します。pocket resource s3 create (再実行可能) で既存バケットにも冪等に適用されます。

[s3]
versioning = true

lifecycle_rules¶

Non-current version expiration を中心とした S3 Lifecycle ルールを宣言できます。pocket resource s3 create で冪等に reconcile されます。

[[s3.lifecycle_rules]]
id = "expire-non-current-static"
prefix = "static/"
noncurrent_version_expiration_days = 1

[[s3.lifecycle_rules]]
id = "expire-non-current-media"
prefix = "media/"
noncurrent_version_expiration_days = 1

[s3]
versioning = true

[[s3.lifecycle_rules]]
id = "expire-non-current-static"
prefix = "static/"
noncurrent_version_expiration_days = 1

[[s3.lifecycle_rules]]
id = "expire-non-current-media"
prefix = "media/"
noncurrent_version_expiration_days = 1

neon¶

Neon PostgreSQLの設定です。Neon プロジェクトは事前に Neon Console で作成しておく必要があります。magic-pocket はプロジェクト内にブランチ・データベース・ロールを作成します。

[neon]
project_name = "dev-myproject"

[prod.neon]
project_name = "prod-myproject"

NEON_API_KEY 環境変数（または .env）が必要です。ステージごとにNeonプロジェクトを分ける場合は、デプロイ時に環境変数を切り替えてください。

[dev.neon]
project_name = "dev-myproject"
provisioning = "command"

[dev.awscontainer.secrets.user]
# store-url の保存先。pocket が正準名を導出する（stored mode）。
DATABASE_URL = { type = "neon_database_url" }

tidb¶

TiDB Serverless（MySQL 互換）の設定です。

[tidb]
project = "1234567890123456789"

[prod.tidb]
project = "9876543210987654321"

TIDB_PUBLIC_KEY と TIDB_PRIVATE_KEY 環境変数（または .env）が必要です。TiDB Cloud のコンソールから API キーを取得してください。

upstash¶

Upstash Redis（サーバーレス Redis）の設定です。VPC 不要で Lambda から直接利用できます。

[upstash]

[awscontainer.secrets.managed]
REDIS_URL = { type = "upstash_redis_url" }

[awscontainer.django.caches]
default = { store = "redis" }

UPSTASH_EMAIL と UPSTASH_API_KEY 環境変数（または .env）が必要です。Upstash Console の Account > Management API で API Key を取得してください。これらはデプロイ時のみ必要で、Lambda 実行時には不要です。

データベースは {project_name}-{stage} の名前で自動作成されます。プライマリリージョンは ap-southeast-1（シンガポール）に固定です。

dsql¶

Amazon Aurora DSQL の設定です。[dsql] を追加するだけでクラスターが自動作成されます。VPC は不要です。

[dsql]

Lambda 環境変数として POCKET_DSQL_ENDPOINT と POCKET_DSQL_REGION が自動設定されます。 set_envs() の呼び出し時に、IAM 認証トークンが POCKET_DSQL_TOKEN に設定されます。

from pocket.runtime import refresh_dsql_token

token = refresh_dsql_token()  # POCKET_DSQL_TOKEN を最新化し、最新トークンを返す
conn = psycopg.connect(
    host=os.environ["POCKET_DSQL_ENDPOINT"],
    user="admin",
    password=token,
    dbname="postgres",
    sslmode="require",
)

rds¶

RDS Aurora PostgreSQL Serverless v2 の設定です。[vpc] と組み合わせてクラスターが自動作成されます。

[vpc]
ref = "main"
zone_suffixes = ["a", "c"]  # managed VPC では RDS に 2AZ 以上必須

[rds]

[awscontainer]
dockerfile_path = "pocket.Dockerfile"

[rds]
min_capacity = 1.0
max_capacity = 8.0

snapshot からの復元¶

既存の RDS / Aurora データを新クラスタに持ち込みたい場合、snapshot_identifier を指定すると 初回作成時のみ snapshot から復元されます。awsde などの他ツールからの本番移行、手動バックアップからの起動に利用できます。

[prod.rds]
snapshot_identifier = "myapp-prod-migration-20260410"

ID でも ARN でも指定可能¶

snapshot_identifier は 1 フィールドで ID / ARN 両対応 です。AWS の RestoreDBClusterFromSnapshot API が同じパラメータに ID・ARN どちらも受け付けるため、用途に応じて書き分けてください。

初回作成のみ / 2 回目以降は無視される¶

マスターパスワードの扱い¶

snapshot から復元すると Aurora のマスターパスワードは snapshot 内のものが引き継がれます。pocket はこれを検出し、復元直後に自動で AWS 管理シークレットに切り替えます:

1. RestoreDBClusterFromSnapshot で復元
2. クラスタ available まで待機
3. ModifyDBCluster(ManageMasterUserPassword=True, ApplyImmediately=True) を実行
4. 再度 available まで待機

この結果、DATABASE_URL は引き続き Secrets Manager から動的に構築され、パスワードローテーションも有効になります。ユーザー側で追加の手順は不要です。

復元で注意すべきこと¶

既存 RDS への接続 (managed = false)¶

pocket が作成・管理しない既存の RDS クラスタに Lambda から接続する場合、managed = false を指定します。pocket はクラスタの作成・削除を行わず、IAM と SG ingress のみを設定します。

[rds]
managed = false
secret_arn = "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:my-db-secret"
security_group_id = "sg-0123456789abcdef0"

ses¶

Amazon SES によるメール送信の設定です。設定すると、Lambda に AmazonSESFullAccess IAM ポリシーが付与されます。

[ses]
from_email = "noreply@example.com"

[ses]
from_email = "noreply@example.com"
region = "us-east-1"
configuration_set = "my-tracking-set"

awscontainer¶

AWS Lambda コンテナの設定です。

[awscontainer]
dockerfile_path = "pocket.Dockerfile"

build（ビルドバックエンド）¶

コンテナイメージのビルド方法を指定します。文字列で backend のみ指定するショートハンドと、テーブルでの詳細指定の両方が使えます。

[awscontainer]
build = "docker"   # ショートハンド

# または詳細指定
[awscontainer.build]
backend = "codebuild"
compute_type = "BUILD_GENERAL1_MEDIUM"

# プロジェクトルートの pocket.toml
[awscontainer]
dockerfile_path = "backend/pocket.Dockerfile"

# ビルドコンテキスト = プロジェクトルート
COPY uv.lock pyproject.toml backend/pyproject.toml ./
RUN uv sync --frozen --no-dev --no-install-project --package my-backend

COPY backend/src/ .

pocket runtime-config¶

pocket.toml からビルド専用の設定（dockerfile_path, managed_assets, build_dir 等）を除外した TOML を生成します。

# 標準出力に出力
pocket runtime-config

# ファイルに出力
pocket runtime-config pocket.runtime.toml

pocket deploy 時にはビルド前に自動生成され、Lambda image に COPY されます。 手動実行は生成内容の確認やデバッグ用途で使えます。

Lambda 上では pocket.runtime.toml が pocket.toml より優先して読み込まれます。

# magic-pocket: deploy のたび再生成される副産物 (git 管理不要)
/pocket.runtime.toml
/src/pocket.runtime.toml   # project_dir = "src" の場合
/pocket_cache/

awscontainer.handlers¶

Lambda関数の設定を記述します。キー名がハンドラー名になります。

[awscontainer.handlers.wsgi]
command = "pocket.django.lambda_handlers.wsgi_handler"

[awscontainer.handlers.management]
command = "pocket.django.lambda_handlers.management_command_handler"
timeout = 600

command は Lambda コンテナイメージの CMD を上書きする値です（CloudFormation の ImageConfig.Command にマップされます）。ENTRYPOINT はオーバーライドしません。

• Django: Python モジュールパス形式のハンドラー関数を指定します（例: pocket.django.lambda_handlers.wsgi_handler）
• Rust: コンテナ内のバイナリパスを指定します（例: myapp-lambda）

handlers.name.apigateway¶

API Gatewayの設定です。

# API Gatewayを有効にする（URLは自動生成）
[dev.awscontainer.handlers.wsgi]
apigateway = {}

# 独自ドメインを利用する場合
[prod.awscontainer.handlers.wsgi]
apigateway = { domain = "example.com" }

handlers.name.sqs¶

SQSキューの設定です。マネジメントコマンドの非同期実行に使えます。

[awscontainer.handlers.sqsmanagement]
command = "pocket.django.lambda_handlers.management_command_handler"
timeout = 600
sqs = {}

awscontainer.secrets¶

シークレット管理の設定です。保存先として Secrets Manager (sm) と SSM Parameter Store (ssm) を選択できます。

[awscontainer.secrets]
store = "sm"  # "sm" (Secrets Manager) or "ssm" (SSM Parameter Store)
pocket_key_format = "{stage}-{project}-{namespace}"

secrets.managed¶

magic-pocketが自動生成・管理するシークレットを定義します。

[awscontainer.secrets.managed]
SECRET_KEY = { type = "password", options = { length = 50 } }
DJANGO_SUPERUSER_PASSWORD = { type = "password", options = { length = 16 } }
DATABASE_URL = { type = "auto_database_url" }

type = "auto_database_url"

pocket.toml 内の DB 設定（[neon] / [rds] / [tidb]）を自動検出し、適切な DATABASE_URL を生成します。 DB が1つだけ定義されている場合はそれを使用し、複数定義されている場合はエラーになります。 ステージごとに DB を切り替える場合に便利です。オプションはありません。

[awscontainer.secrets.managed]
DATABASE_URL = { type = "auto_database_url" }

[dev.neon]
project_name = "dev-myproject"

[prod.rds]

type = "password"

パスワードを自動生成します。

オプション	型	デフォルト	説明
length	int	16	パスワードの長さ

type = "neon_database_url"

NeonのDB接続URLをAPI経由で取得し保存します（computed）。オプションはありません。 deploy 環境に管理 API key を置きたくない場合は、同じ type を secrets.user に置く stored mode も使えます（DB 接続 URL の computed / stored 参照）。

type = "tidb_database_url"

TiDB ServerlessのDB接続URLを取得し保存します（computed）。オプションはありません。 stored mode も利用可（同上）。

type = "rds_database_url"

RDS Aurora の DATABASE_URL を設定します。実際の URL は Lambda 起動時に POCKET_RDS_SECRET_ARN から動的に構築されます（パスワードローテーション対応）。オプションはありません。

type = "rsa_pem_base64"

RSA鍵ペアを生成しbase64で保存します。環境変数はキー名+suffixで2つ登録されます。

オプション	型	説明
pem_base64_environ_suffix	str	秘密鍵の環境変数名suffix
pub_base64_environ_suffix	str	公開鍵の環境変数名suffix

[awscontainer.secrets.managed.JWT_RSA]
type = "rsa_pem_base64"
options = { pem_base64_environ_suffix = "_PEM_BASE64", pub_base64_environ_suffix = "_PUB_BASE64" }

→ 環境変数 JWT_RSA_PEM_BASE64 と JWT_RSA_PUB_BASE64 が登録されます。

type = "cloudfront_signing_key"

CloudFront 署名付き URL 用の RSA 鍵ペアを生成しbase64で保存します。 秘密鍵と公開鍵は Secrets Manager/SSM 経由で環境変数として登録されます。 CloudFront PublicKey の ID は CloudFormation のクロススタック参照（Fn::ImportValue）で Lambda 環境変数に自動設定されるため、書き戻しは不要です。

オプション	型	説明
pem_base64_environ_suffix	str	秘密鍵の環境変数名suffix
pub_base64_environ_suffix	str	公開鍵の環境変数名suffix
id_environ_suffix	str	CloudFront PublicKey ID の環境変数名suffix

[awscontainer.secrets.managed.CF_MEDIA_KEY]
type = "cloudfront_signing_key"
options = { pem_base64_environ_suffix = "_PEM_BASE64", pub_base64_environ_suffix = "_PUB_BASE64", id_environ_suffix = "_ID" }

→ 環境変数 CF_MEDIA_KEY_PEM_BASE64, CF_MEDIA_KEY_PUB_BASE64 が secrets 経由で、CF_MEDIA_KEY_ID が CloudFormation ImportValue 経由で登録されます。

type = "spa_token_secret"

SPA トークン認証用の HMAC-SHA256 シークレット（256-bit hex 文字列）を自動生成します。 CloudFront の token_secret で参照し、require_token ルートのトークン検証に使用されます。 オプションはありません。

[awscontainer.secrets.managed]
SPA_TOKEN_SECRET = { type = "spa_token_secret" }

→ 環境変数 SPA_TOKEN_SECRET が secrets 経由で登録されます。Django 側で pocket.django.spa_auth を使ってトークン生成・検証が可能です。

secrets.user¶

自分で作成したシークレットを参照する場合に使います。 指定すると、GetSecretValue / GetParameter 権限が自動付与されます。

[awscontainer.secrets.user]
MY_API_KEY = { name = "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:my-secret" }

name と type はどちらか一方を指定します（両方／どちらも無しはエラー）。

name には {stage} / {project} / {namespace} の format 変数が使えます （bucket_name_format / pocket_key_format と同じ仕組み）。ステージ単位で SSM パスや SM シークレットを分けたい場合に便利です。

[awscontainer.secrets.user]
# prod stage の Lambda は /svc/prod-token を、dev stage は /svc/dev-token を読む
SERVICE_TOKEN = { name = "/svc/{stage}-token", store = "ssm" }

DB 接続 URL の computed mode と stored mode¶

DB の接続 URL (DATABASE_URL) は 2 通りの解決方法があります。

stored mode は「provider の管理 API key を deploy 環境に置きたくない」「provisioning と deploy を分離したい」「deploy を外部 API に依存させたくない（CI など）」場合に使います。

[neon]
project_name = "dev-myproject"
provisioning = "command"   # deploy は Neon に触れない

[awscontainer.secrets.user]
# 事前に provision した接続 URL を参照するだけ（pocket は deploy 時に API を叩かない）
DATABASE_URL = { type = "neon_database_url" }

secret の provision は pocket resource neon store-url --stage <stage> / pocket resource tidb store-url --stage <stage> が便利です（branch/cluster/role/db を ensure し、接続 URL を上記 user secret の正準名へ保存）。[<db>] provisioning = "command" と組み合わせると、provisioning （管理 API key 必要）と deploy（credential 不要）を分離できます。手動で正準名に値を投入 しても構いません。

• 対象 type は neon_database_url / tidb_database_url の 2 つ。これらは computed だと deploy 時に管理 API key を要求するため、stored 化の利点が大きい type です。
• rds_database_url は user 側で使えません。RDS は元々 deploy 時に管理 API key を要求せず、 接続 URL を Lambda 起動時に POCKET_RDS_SECRET_ARN から動的構築してパスワード ローテーションに追従します。静的な stored URL にするとローテで失効するため対象外です。
• secret は deploy 前に provision しておく必要があります。 type 指定時、pocket は secret 名を自動導出します（managed の pocket_store パスとは衝突しない別名）。未 provision のまま deploy すると、pocket が期待する正準名を示して deploy 時にエラーで止まります （runtime まで遅延しません）。エラーメッセージに出る名前にその store（sm/ssm）で値を 投入してください。値は接続 URL 文字列です。

secrets.extra_resources¶

追加のシークレットARN（正規表現可）に対してGetSecretValue / GetParameter 権限を付与します。

[awscontainer.secrets]
extra_resources = ["arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:my-prefix-*"]

secrets の即時反映 (pocket resource awscontainer reload-env)¶

SSM / Secrets Manager 側でシークレット値を更新しても、warm container は 旧値を抱えたまま再利用されるため、新値の反映は次の cold start を待つ 形になります (典型的には 5〜15 分のラグ)。feature flag の即時切替、secret rotation 後の即時反映、hotfix で env 1 つだけ変えたい等のユースケースで このラグが許容できない場合は、pocket resource awscontainer reload-env を使います。

# 全 handler の env を SSM/SM の最新値で再構築 + 即時反映
pocket resource awscontainer reload-env --stage=prod

# 特定 handler のみ
pocket resource awscontainer reload-env --stage=prod --handler=wsgi

# 現状確認 (Lambda 側の env と SSM/SM の宣言値が drift してないか)
pocket resource awscontainer status-env --stage=prod

仕組み:

1. pocket.toml の [awscontainer.secrets.managed/user] から「現在の宣言上の secret キー一式」を構築
2. SSM / Secrets Manager から最新値を boto3 で取得
3. Lambda の現在 Environment.Variables に secrets を merge して update_function_configuration で上書き
4. AWS Lambda が warm container を 強制的に再生成 するため、新しい値が 次の invocation から即座に反映される

pocket waf ip と同じ side-channel pattern です。CFn template の Environment.Variables は deploy 時 snapshot として残り、CFn 視点では drift しますが、次の pocket deploy で自然と再同期 されます (CFn template が SSM の最新値を読み直して再注入するため)。

status-env は drift 検出専用 (副作用なし)。Lambda 側の env と SSM/SM 側の宣言値を比較し、差分のあるキーだけ表示します。

awscontainer.iam¶

Lambda execution role に追加で IAM 権限を注入します。use_s3 / use_route53 / secrets.allowed_*_resources 等の built-in な仕組みでカバーできない権限を、ユーザーが宣言的に与えるための逃げ道です。

[awscontainer.iam]
managed_policy_arns = [
    "arn:aws:iam::aws:policy/AdministratorAccess",
]

[awscontainer.iam.inline_policies.cross-account-assume]
Version = "2012-10-17"

[[awscontainer.iam.inline_policies.cross-account-assume.Statement]]
Effect = "Allow"
Action = "sts:AssumeRole"
Resource = "arn:aws:iam::*:role/provisioner-role"

inline_policies の value は標準的な IAM PolicyDocument の形式 (Version / Statement を含む dict) です。TOML の制約から Statement を複数行で書く場合は [[awscontainer.iam.inline_policies.<name>.Statement]] 形式の table array を使います。

awscontainer.django¶

Lambda環境で利用するDjango設定を記述します。

storages¶

Djangoの STORAGES に設定する内容です。

[awscontainer.django.storages]
default = { store = "s3", location = "media" }
staticfiles = { store = "s3", location = "static", static = true, manifest = true }

store, static, manifest, distribution の組み合わせで以下のバックエンドが選択されます。

[awscontainer.django.storages]
default = { store = "s3", location = "", distribution = "media" }
staticfiles = { store = "s3", location = "static", static = true, manifest = true, distribution = "main" }

caches¶

Djangoの CACHES に設定する内容です。

[awscontainer.django.caches]
default = { store = "locmem" }

• locmem → django.core.cache.backends.locmem.LocMemCache
• efs → django.core.cache.backends.filebased.FileBasedCache（VPC + EFS設定が必要）

settings¶

環境毎にDjangoの任意のsettingsを設定できます。

[dev.awscontainer.django.settings]
DEFAULT_FROM_EMAIL = '"Dev" <test@example.com>'
CORS_ALLOWED_ORIGINS = ["https://dev.example.com"]

[prod.awscontainer.django.settings]
DEFAULT_FROM_EMAIL = '"Production" <noreply@example.com>'
CORS_ALLOWED_ORIGINS = ["https://www.example.com"]

settings.py での読み込み方法は「Django連携」を参照してください。

cloudfront¶

CloudFrontディストリビューションの設定です。名前付きサブテーブル [cloudfront.xxx] で複数のディストリビューションを定義できます。 S3バケットは [s3] で定義したものを共有し、origin_path でパスを分離します。

[cloudfront.main]
domain = "www.example.com"
origin_path = "/spa"
routes = [
    { is_default = true, is_spa = true },
    { path_pattern = "/static/*", ref = "static", versioning = "content_hash" },
]

[cloudfront.media]
domain = "media.example.com"
origin_path = "/media"
signing_key = "CF_MEDIA_KEY"
routes = [
    { is_default = true, signed = true },
]

managed_assets¶

favicon.ico や robots.txt など、ステージごとに異なるファイルを CloudFront 経由で配信できます。

[cloudfront.web]
managed_assets = "assets/managed"
routes = [
    { is_default = true, is_spa = true, origin_path = "/web" },
]

ディレクトリ構成:

assets/managed/
├── default/           # フォールバック
│   ├── favicon.ico
│   └── robots.txt
├── sandbox/           # sandbox ステージ用
│   ├── favicon.ico    # 開発用アイコン
│   └── robots.txt     # Disallow: /
└── prod/               # 本番用
    ├── favicon.ico
    └── robots.txt     # Allow: /

pocket deploy --stage=sandbox 実行時:

1. assets/managed/sandbox/ が存在すればそのディレクトリを使用
2. 存在しなければ assets/managed/default/ にフォールバック
3. ファイルを S3 の pocket_managed/ にアップロード
4. ファイルごとに CloudFront の CacheBehavior を自動生成（/favicon.ico, /robots.txt 等）

ファイル単位のマージは行いません。ステージディレクトリがあればそれだけ、なければ default だけが配信されます。

waf¶

CloudFront に WAFv2 の IP allowlist 専用 WebACL を attach します。 admin.example.com のような社内向け管理 UI を「固定 IP 以外からは到達不能」 にする用途を想定しています。

[cloudfront.admin]
domain = "admin.example.com"
routes = [
    { is_default = true, is_spa = true, origin_path = "/admin" },
]

# block を書くだけで WAF が enable になる (デフォルトは IP allowlist モード)
[cloudfront.admin.waf]
# (optional) AWS managed rules を併用する場合
managed_rule_groups = ["AWSManagedRulesCommonRuleSet"]

[cloudfront.<name>.waf] block を書くと us-east-1 に AWS::WAFv2::WebACL が CFn で作成され、CloudFront distribution の WebACLId に attach されます。 block 自体が無い場合は WAF 未 attach (既存挙動と完全互換)。

モード 1: IP allowlist (デフォルト)¶

enable_ip_set = true (省略可) の場合、AWS::WAFv2::IPSet (Scope=CLOUDFRONT, Addresses=[]) と「IPSet にマッチしたら Allow」ルールを生成し、 DefaultAction = Block にします。初回 deploy 直後は IPSet が空なので deny-all 状態。pocket waf ip add self ... で CIDR を投入してください。

社内 admin UI を固定 IP から到達可能にする、というのが想定ユースケースです。

モード 2: managed rules のみ (enable_ip_set = false)¶

IP 制限はしたくないが AWS managed rules による検査だけ走らせたい場合は:

[cloudfront.admin.waf]
enable_ip_set = false
managed_rule_groups = ["AWSManagedRulesCommonRuleSet"]

このとき:

• AWS::WAFv2::IPSet は 生成されない (pocket waf ip ... CLI も使用不可)
• DefaultAction = Allow で、managed rules にマッチした怪しいリクエスト のみ block される (「許可ベース + 攻撃シグネチャだけ弾く」構成)

enable_ip_set = false でかつ managed_rule_groups も空、という構成は WebACL が何もしない pass-through 状態になるので、settings の validator が エラーで reject します。

IP リテラルは toml に書かない¶

ip_allow_list_default のような「IP アドレスを toml で宣言する」フィールドは 意図的に提供していません。pocket.toml に IP リテラルを書いた場合は extra = "forbid" で validation エラーになります。

理由は 真実源を一系統に絞るため:

• 実 IP リストは pocket waf ip ... CLI で日常的に更新される (社内 IP 追加、 外出先からの一時許可など、操作頻度が高い)
• toml にも書けるようにすると、toml と IPSet の値が drift し「toml に書いた はずなのに反映されていない」「CLI で消したはずなのに再 deploy で復活」の 事故が起きる

CFn template も Addresses=[] で固定し、再 deploy のたびに空が出力されます。 CFn 視点では IPSet の中身は常に drift しますが、これは仕様です。CLI が side-channel で書いた CIDR は CFn update で消えません。

CLI: pocket waf ip ...¶

IPSet の中身 (実際の CIDR) は専用 CLI で更新します。update_ip_set boto3 を直接叩くため、CFn stack を回さずに秒オーダーで反映されます。

# 一覧表示
pocket waf ip list --name admin --stage prod

# 自分の Global IP を /32 で追加 (checkip.amazonaws.com → ipify fallback)
pocket waf ip add self --name admin --stage prod

# 任意 CIDR を追加
pocket waf ip add 203.0.113.0/24 --name admin --stage prod

# 削除
pocket waf ip remove 203.0.113.0/24 --name admin --stage prod

# 全削除 (deny-all 状態に戻す。確認プロンプトあり)
pocket waf ip clear --name admin --stage prod

初回 pocket deploy の直後は IPSet が空 (deny-all) なので、最低 1 件 CIDR を追加するまで CloudFront は全リクエストを 403 で拒否します。デプロイ直後に pocket waf ip add self ... を実行してください。

必要な IAM 権限¶

pocket.toml に [cloudfront.<name>.waf] block を 1 つでも書くと、 wafv2:* が pocket permissions list の出力に追加されます (AWS 権限 を 参照)。

origin verify (enable_origin_verify)¶

CloudFront 配下の origin (lambda / API Gateway、将来は Fargate/ALB) で、 アクセス元 client IP を詐称耐性をもって取得し、かつ origin への直叩きを 禁止する仕組みを一括で有効化します。

[cloudfront.web]
routes = [
    { type = "lambda", handler = "wsgi", is_default = true },
]
enable_origin_verify = true

enable_origin_verify = true で deploy すると magic-pocket が次の 3 点を turnkey で 構成します。secret header 名 / env 名 / viewer IP header 名はすべて magic-pocket の 内部実装詳細で、利用者が知る必要はありません (repo 跨ぎの名前合わせを発生させない)。

1. secret の自動生成・管理: managed secret POCKET_ORIGIN_VERIFY_SECRET (type = "origin_verify_secret") を自動注入し、生成・保存 (SM/SSM)・IAM・Lambda runtime env 注入の既存経路に乗せます。利用者が secret を宣言する必要はありません。
2. origin 直叩き禁止: CloudFront → origin のリクエストに secret custom header (X-Pocket-Origin-Verify) を付与します。viewer が同名 header を送っても CloudFront が上書きするため詐称不可。同じ secret 値が Lambda runtime env にも入るので、 バックエンドは「自分宛のリクエストが CloudFront 経由か」をバックエンド非依存に 判定できます (Lambda でも Fargate でも同じコード)。
3. 検証 + REMOTE_ADDR 正規化 middleware: 同梱の pocket.django.origin_verify.OriginVerifyMiddleware が secret header を検証し、 CloudFront 経由のときだけ詐称耐性のある viewer IP を REMOTE_ADDR に上書きします。

詐称耐性 client IP (デフォルト ON、flag 非依存)¶

lambda route には、enable_origin_verify の有無に関わらず CloudFront Function が event.viewer.ip (CloudFront が TCP 接続から取得する viewer IP。viewer が詐称不可) を X-Pocket-Viewer-Ip header に載せて origin に転送します。これは純粋に加算的で キャッシュにも影響しないため、デフォルト挙動です。

• requestContext.sourceIp (API GW) は CloudFront エッジの IP で真の client ではなく、 API GW 固有なので Fargate 移行で消えます。
• X-Forwarded-For 左端は viewer が prepend して詐称可能です。
• magic-pocket は managed AllViewerExceptHostHeader origin request policy を使い続け (API GW の Host 整合性を壊さないため)、viewer IP は CloudFront Function が付与する 通常 header として転送します。origin request policy の差し替えは行いません。

Django middleware の組み込み¶

MIDDLEWARE の 最前段 に追加してください (REMOTE_ADDR を読む django-axes / DRF throttling / ratelimit / access log より前に走らせる必要があるため)。

MIDDLEWARE = [
    "pocket.django.origin_verify.OriginVerifyMiddleware",
    "django.middleware.security.SecurityMiddleware",
    # ...
]

middleware の挙動:

redirect_from¶

[prod.cloudfront.main]
domain = "www.example.com"
redirect_from = [{ domain = "example.com" }]

routes¶

CloudFrontのキャッシュ動作ルーティングを定義します。

[prod.cloudfront.main]
domain = "www.example.com"
routes = [
    { is_default = true, is_spa = true },
    { path_pattern = "/assets/*", versioning = "content_hash" },
]

Django 単体構成（CloudFront → Lambda のみ）¶

SPA を持たず、Django テンプレートで完結するプロジェクトを CloudFront 経由で配信する構成です。 is_default = true の type = "lambda" ルートを 1 つだけ定義します。

[awscontainer.handlers.wsgi]
command = "pocket.django.lambda_handlers.wsgi_handler"
apigateway = {}

[prod.cloudfront.web]
domain = "www.example.com"
routes = [
    { is_default = true, type = "lambda", handler = "wsgi" },
]

CloudFront の DefaultCacheBehavior が API Gateway オリジンを直接ターゲットにし、X-Forwarded-Host が付与されるため、Django 側ではカスタムドメインがそのまま request.get_host() で取得できます。

バージョニング（キャッシュバスティング）¶

versioning フィールドで静的アセットのキャッシュバスティング方式を選択できます。

content_hash — ファイル内容ハッシュ¶

Django の ManifestStaticFilesStorage と組み合わせる方式。collectstatic 時にファイル名にハッシュが付与されるため、ファイル名が変わればキャッシュが自然に更新されます。

[cloudfront.web]
routes = [
    { is_default = true, is_spa = true, origin_path = "/app" },
    { path_pattern = "/static/*", ref = "static", versioning = "content_hash", origin_path = "/static" },
]

deploy_hash — デプロイ時 git hash¶

ManifestStaticFilesStorage を使わず、デプロイ時の git hash を URL prefix に付与する方式。manifest 計算が不要で高速、動画など大きなファイルにも適しています。

[general]
region = "ap-northeast-1"
stages = ["sandbox", "prod"]
project_name = "myproject"

[s3]

[awscontainer]
dockerfile_path = "pocket.Dockerfile"

[awscontainer.handlers.wsgi]
command = "pocket.django.lambda_handlers.wsgi_handler"
apigateway = {}

[awscontainer.handlers.management]
command = "pocket.django.lambda_handlers.management_command_handler"
timeout = 600

[awscontainer.django.storages]
default = { store = "filesystem" }
staticfiles = { store = "s3", static = true, distribution = "web", route = "static" }

[awscontainer.secrets]
store = "ssm"

[awscontainer.secrets.managed]
SECRET_KEY = { type = "password", options = { length = 50 } }

[sandbox.cloudfront.web]
domain = "sandbox.myproject.example.com"
routes = [
    { type = "lambda", handler = "wsgi", is_default = true },
    { path_pattern = "/static/*", ref = "static", versioning = "deploy_hash", origin_path = "/static" },
]

import os

DEPLOY_HASH = os.environ.get("DEPLOY_HASH", "dev")
STATIC_URL = f"static/{DEPLOY_HASH}/"

from pocket.django.utils import get_storages
STORAGES = get_storages()

pocket django deploy --stage sandbox -y

動作:

1. pocket がデプロイ時に git rev-parse --short HEAD で hash を取得（DEPLOY_HASH 環境変数があればそちらを優先）
2. Lambda 環境変数 DEPLOY_HASH に自動注入
3. CloudFront Function が自動生成され、/static/{hash}/foo.js → /static/foo.js に変換してオリジンに転送
4. CloudFront のキャッシュキーはフル URL (hash 込み) なので、デプロイごとにキャッシュが自然に更新される
5. versioned_max_age（デフォルト 1 年）の長期キャッシュが付与される

Django 側は settings.py に以下を書くだけです:

DEPLOY_HASH = os.environ.get("DEPLOY_HASH", "dev")
STATIC_URL = f"static/{DEPLOY_HASH}/"

from pocket.django.utils import get_storages
STORAGES = get_storages()

get_storages() は deploy_hash route を検出し、Lambda 上では自動的に StaticFilesStorage を選択します（STATIC_URL のパスがそのまま {% static %} タグの出力になります）。deploystatic 時は S3 backend が使われるため、アップロードは正常に動作します。

S3 へのアップロードは hash prefix なし（/static/foo.js）のまま行います。collectstatic は通常の StaticFilesStorage で OK です（manifest = true は不要）。

CloudFront 経由の API Gateway（Cookie 認証）¶

SPA と API を同一ドメインで配信し、Cookie（session + CSRF）認証を使う構成です。 /api/* → API Gateway、/* → S3（SPA）というルーティングを実現します。

Browser → CloudFront (example.com)
             ├─ /*       → S3 (SPA)
             └─ /api/*   → API Gateway → Lambda (Django)

[awscontainer.handlers.wsgi]
command = "pocket.django.lambda_handlers.wsgi_handler"
apigateway = {}

[cloudfront.main]
domain = "example.com"
routes = [
    { is_default = true, is_spa = true },
    { path_pattern = "/api/*", type = "lambda", handler = "wsgi" },
]

type = "lambda" のルートでは以下が自動設定されます:

• CachePolicyId: CachingDisabled（API レスポンスはキャッシュしない）
• OriginRequestPolicy: Cookie 全転送、allViewerExceptHostHeader、QueryString 全転送
• AllowedMethods: 全7メソッド（GET, HEAD, OPTIONS, PUT, PATCH, POST, DELETE）
• Origin: API Gateway（https-only、CloudFormation のクロススタック参照で接続）

CSRF_COOKIE_DOMAIN = ".example.com"
CSRF_TRUSTED_ORIGINS = ["https://example.com"]

SPA トークン認証¶

SPA に HMAC-SHA256 トークンによるログイン必須機能を追加できます。 未認証ユーザーは CloudFront Function（viewer-request）でログインページにリダイレクトされます。 シークレットは CloudFront KeyValueStore (KVS) に格納され、Function コードには埋め込まれません。

未認証ユーザー → CloudFront
  → viewer-request: CloudFront Function (async)
    → SPA fallback（URI 書き換え）
    → KVS からシークレット取得
    → Cookie 'pocket-spa-token' の HMAC-SHA256 検証
    → 失敗 → 302 リダイレクト → login_path
  → 成功 → S3 オリジンへ

[awscontainer.secrets.managed]
SECRET_KEY = { type = "password", options = { length = 50 } }
SPA_TOKEN_SECRET = { type = "spa_token_secret" }

[cloudfront.main]
token_secret = "SPA_TOKEN_SECRET"
routes = [
    { is_default = true, is_spa = true, require_token = true, origin_path = "/app" },
    { path_pattern = "/api/*", type = "lambda", handler = "wsgi" },
]

トークンの形式は {user_id}:{expiry_unix}:{hmac_hex} です。 Django 側では pocket.django.spa_auth モジュールでトークンの生成・検証・Cookie 設定が可能です。 詳細は「実行環境 - SPA トークン認証」を参照してください。

scheduler¶

EventBridge Scheduler (AWS::Scheduler::Schedule) で Lambda handler を定期実行します。 旧来の EventBridge Rule (AWS::Events::Rule) ではなく、AWS が現在推奨する EventBridge Scheduler を採用しています。Lambda Permission が不要、1 schedule = 1 リソース、IAM role ベースで invoke するため、構成がシンプルでスケーラビリティも高いです。

基本¶

[scheduler.schedules.rotate_logs]
rate = "1 hour"
handler = "worker"
input = { task = "rotate_logs" }

[scheduler.schedules.daily_digest]
scheduler = "pocket.django.management_lambda_scheduler"
cron = "0 18 * * ? *"
handler = "management"
manage = "send_daily_digest --verbose"

各 entry は [scheduler.schedules.{key}] の dict 形式で書きます。{key} (例: rotate_logs) はそのまま CloudFormation logical ID と物理名の素材になるため、並び順に依存しない安定した命名が得られます。

entry の共通フィールド¶

cron と rate は どちらか一方を必ず指定します（両方や両方無しはエラー）。

pocket.lambda_scheduler (default)¶

汎用の Lambda invoke。任意の dict を input フィールドで EventBridge Target Input にそのまま渡します。

[scheduler.schedules.rotate_logs]
rate = "1 hour"
handler = "worker"
input = { task = "rotate_logs", target = "primary" }

handler 側では event["task"] のように直接読めます。

pocket.django.management_lambda_scheduler¶

Django management command を呼び出すショートカット。manage に shell-style コマンドラインをそのまま書きます。

[scheduler.schedules.daily_digest]
scheduler = "pocket.django.management_lambda_scheduler"
cron = "0 18 * * ? *"
handler = "management"
manage = "send_daily_digest some_param --verbose --batch-size 100"

制約: 参照する handler は command = "pocket.django.lambda_handlers.management_command_handler" でなければなりません（deploy 前にバリデーションエラーになります）。

実装的には、Lambda には {"manage": "<コマンド文字列>"} が渡され、handler 側で shlex.split → call_command を行います。既存の {command, args, kwargs} 形式と完全に共存しており、後方互換性は壊しません。

ステージ別 schedule¶

dict 形式は deep merge が効くため、entry 単位で stage オーバーライド・追加・調整が自然に書けます。

# 全 stage 共通
[scheduler.schedules.rotate_logs]
rate = "1 hour"
handler = "worker"
input = { task = "rotate_logs" }

[scheduler.schedules.daily_digest]
scheduler = "pocket.django.management_lambda_scheduler"
cron = "0 18 * * ? *"
handler = "management"
manage = "send_daily_digest"

# sandbox では rotate_logs の頻度だけ落とす
[sandbox.scheduler.schedules.rotate_logs]
rate = "1 day"

# prod だけで動く追加 schedule
[prod.scheduler.schedules.month_end_invoice]
scheduler = "pocket.django.management_lambda_scheduler"
cron = "0 0 L * ? *"
handler = "management"
manage = "send_monthly_invoice"

命名のコツ¶

• handler key は「何をする Lambda か」(management, worker, mailer)
• entry key は「いつ動くか」(nightly, hourly, month_end, rotate_logs)

cron のような AWS 用語を key に使うと、cron 式そのものとの混同が起きやすいので避けてください。

CloudFormation リソース構成¶

各 entry に対して 1 つの AWS::Scheduler::Schedule が出力されます。Lambda Permission は不要で、共有の AWS::IAM::Role ({resource_prefix}scheduler) が EventBridge Scheduler に対して lambda:InvokeFunction を許可します。Resource は schedule で参照されている Lambda 関数 ARN に絞り込まれます。

wsgi handler のウォームアップは非対応¶

wsgi_handler は API Gateway proxy event 形式を期待するため、scheduler が渡す任意 input dict では呼び出せません。Lambda のコールドスタートを抑えたい場合は Provisioned Concurrency を利用してください（reserved_concurrency や warmup の handler を別途書くより堅牢です）。