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

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

基本構造¶

[general]           # 全ステージ共通の設定
[vpc]               # VPC設定（単一、トップレベル）
[s3]                # S3設定（全ステージ共通）
[neon]              # Neon設定（全ステージ共通）
[tidb]              # TiDB Serverless設定（全ステージ共通）
[rds]               # RDS Aurora設定（全ステージ共通）
[ses]               # SES設定（全ステージ共通）
[container.main]      # Lambda設定（全ステージ共通）
[cloudfront]        # CloudFront設定（全ステージ共通）
[scheduler]         # EventBridge Scheduler 設定（全ステージ共通）
[iam]               # IAM role を pocket が作るか（全ステージ共通）

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

[dsql]
# dev はこのまま

[prod.dsql]
deletion_protection = true

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設定を記述します。設定項目は container.main.django と同じです。

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

vpc¶

VPC設定をトップレベルで定義します。[vpc] を定義すると、container と 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（container / rds）¶

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

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

[container.main]
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¶

S3 Lifecycle ルールを宣言できます。pocket resource s3 create で冪等に reconcile されます。

# 旧バージョンの期限切れ (versioning 有効時の掃除)
[[s3.lifecycle_rules]]
id = "expire-non-current-static"
prefix = "static/"
noncurrent_version_expiration_days = 1

# 現行オブジェクトの日数削除 (trash prefix の自動削除など)
[[s3.lifecycle_rules]]
id = "trash-expire"
prefix = "trash/"
expiration_days = 30

expiration_days と noncurrent_version_expiration_days は少なくとも一方の指定が必要です（両方の同時指定も可）。

[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.container.main.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]

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

[container.main.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]

[dsql]
# dev はこのまま

[prod.dsql]
deletion_protection = true

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

定期バックアップ¶

DSQL に組み込みの自動バックアップ（PITR や日次スナップショット）はありません。何も宣言しなければ、誤削除・論理破壊からの復元手段はゼロです（宣言が無い stage では deploy が毎回警告します）。定期バックアップはトップレベルの [backup.dsql] で宣言してください（1 行書くだけで daily / weekly / monthly の GFS 階層保持が有効になります）。

単発のバックアップは pocket resource dsql backup で取得できます（CLI リファレンス 参照）。--retention-days を省略した単発バックアップは、[backup.dsql] の最長階層（monthly）の delete_after_days を継承します（宣言が無い stage では 1095 日）。定期と単発で長期保持ポリシーが一致します。

復元は AWS Backup が常に新規クラスターを作成する形で行われます（元のクラスターは変更されません）。pocket resource dsql restore を参照してください。

from pocket.naming import DSQL_ENDPOINT, stored_user_secret_name

name = stored_user_secret_name(
    project="myprj", stage="dev", secret_type=DSQL_ENDPOINT, store="ssm"
)
# -> "/dev-myprj-pocket-user/dsql_endpoint"

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]

[container.main]
dockerfile_path = "pocket.Dockerfile"

[rds.backup]
retention_days = 14   # 短くしたい場合

[rds]
min_capacity = 1.0
max_capacity = 8.0

ローテーション窓¶

AWS 既定の窓は「7 日周期・UTC の 1 日全体」で、ローテーションはその日のどこかで起きます。JST では 09:00〜翌 08:59 にあたり、営業時間を必ず含みます。上の自己修復があっても、古い版の稼働中や DB backend を自前で組んでいる場合はローテーションの瞬間に認証エラーになりうるため、影響の小さい時間帯へ窓を寄せることを推奨します。

[prod.rds]
rotation_schedule = "cron(0 15 ? * TUE *)"   # UTC。火 15:00 UTC = 水 00:00 JST
rotation_duration = "4h"                     # 15:00〜19:00 UTC の間に実行

• 式は UTC で解釈されます（Secrets Manager にタイムゾーン指定はありません）。書式は Secrets Manager のスケジュール式 に従います。
• 宣言すると deploy のたびに managed secret の窓と比べ、差分があるときだけ RotateSecret（RotateImmediately=False）で当てます。deploy の瞬間にローテーションが走ることはありません。
• クラスタの作り直しや snapshot からの復元で managed secret が作り直されても、次の deploy で宣言どおりに戻ります（手動で rotate-secret を当てた窓は、secret の作り直しで既定に戻ります）。
• 宣言を外しても pocket は窓を既定へ戻しません（未宣言 = 窓に触れない）。
• password_strategy = "static" はローテーションしないため、宣言するとエラーになります。

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 から動的に構築され、パスワードローテーションも有効になります。ユーザー側で追加の手順は不要です。

復元で注意すべきこと¶

[prod.rds]
snapshot_identifier = "myapp-prod-migration-20260410"
database = "prod_myapp"  # 復元元 (snapshot) の実 DB 名に合わせる

既存 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"

backup¶

DB 層の定期バックアップ（AWS Backup の backup plan）です。pocket が管理する AWS ネイティブ DB をエンジン別に [backup.dsql] / [backup.rds] で宣言します（opt-in。未宣言なら AWS Backup は使いません）。宣言だけで GFS（Grandfather-Father-Son）階層保持が既定で有効になります: 短期は細かく、古くなるほど間引いて長期保持する定石構成です。

[backup.dsql]         # この 1 行で dsql の GFS 既定（daily / weekly / monthly）
[backup.rds]          # この 1 行で rds の GFS 既定（weekly / monthly。daily は PITR が担当）

既定の階層は以下です:

各階層は上書きできます（フィールドは cron / delete_after_days、dsql のみ cold_storage_after_days）:

[backup]
deletable = false     # true で pocket からのバックアップデータ削除を許可
timezone = "UTC"      # 全階層の cron を解釈するタイムゾーン

[backup.dsql]
[backup.dsql.monthly]
delete_after_days = 1825   # monthly だけ 5 年に伸ばす

[backup.rds]
[backup.rds.weekly]
cron = "0 4 ? * 7 *"       # 土曜に変更

deploy が AWS Backup の vault（{stage}-{project}-{namespace}-backup）・サービスロール（…-backup-role）・エンジン別の backup plan / selection（…-backup-dsql / -rds）を冪等に provision します。いずれも他リソースと同じ stage 単位の名前で、account 内の他 stage・他 project とは共有しません。plan をエンジン別に分けるのは、AWS Backup の rule が selection 全体に一律適用されるためです（rds に daily を作らない・cold storage を使わない、をエンジン単位でしか表現できません）。

[sandbox.backup.dsql.daily]
delete_after_days = 7          # 7 日で失効
[sandbox.backup.dsql.weekly]
cold_storage_after_days = 0
delete_after_days = 14
[sandbox.backup.dsql.monthly]
cold_storage_after_days = 0
delete_after_days = 31

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"

container¶

AWS Lambda コンテナの設定です。[container.<name>] の dict 形式で、1 プロジェクトに 複数の container を宣言できます（0.29.0 で旧 [awscontainer]（単数）から リネーム・一般化。移行手順は CHANGELOG 0.29.0 を参照）。

[container.main]
dockerfile_path = "pocket.Dockerfile"

<name> は英小文字始まりの英小文字 + 数字（最大 32 文字、hyphen 不可）です。 Lambda 関数名 ({prefix}{name}-{handler}) や ECR リポジトリ名 ({prefix}{name}-lambda)、container stack 名 ({slug}-container-{name}) の slot として使われます。

| use_vpc | bool | None | None | VPC利用の制御（use_vpc 参照） | | ecr_name | str | None | None | ECRリポジトリ名の上書き。省略時は {stage}-{project}-{namespace}-{name}-lambda | | build | str | dict | "codebuild" | コンテナイメージのビルドバックエンド（下記参照） | | permissions_boundary | str | None | None | Lambda 実行ロール / CodeBuild ロールに適用する IAM Permissions Boundary の ARN（IAM 権限 参照） |

複数 container（strangler 移行 / 異 runtime 並行稼働）¶

同一 CloudFront distribution の path 単位で別 runtime の Lambda origin を足す （例: Django を残したまま /v2/* だけ Rust 実装に切り替える）には、container を 複数宣言し、cloudfront routes の handler を "<container>.<handler>" の ドット記法で参照します。

[container.mydjango]
dockerfile_path = "Dockerfile"
[container.mydjango.handlers.wsgi]
command = "pocket.django.lambda_handlers.wsgi_handler"
apigateway = {}

[container.v2]
dockerfile_path = "v2/Dockerfile"
[container.v2.handlers.wsgi]
command = "admin-v2"          # Rust バイナリ名
apigateway = {}

[cloudfront.web]
routes = [
    { path_pattern = "/v2/*", type = "lambda", handler = "v2.wsgi" },
    { type = "lambda", handler = "mydjango.wsgi", is_default = true },
]

• handler 参照（cloudfront routes / scheduler）は container が 1 つでも常に ドット記法です
• 各 Lambda には POCKET_CONTAINER=<name> が注入され、runtime は自分の [container.<name>] を自動選択します
• CLI の container 単位コマンド（pocket resource container ... / pocket resource image ...）は --container <name> で対象を指定します （container が 1 つだけなら省略可）
• 自 container の handler は従来どおり POCKET_<HANDLER>_HOST 等で参照でき、 他 container の handler は POCKET_<CONTAINER>_<HANDLER>_HOST / _ENDPOINT / _QUEUEURL の修飾名で参照します
• managed secret は既定で container ごとに独立です（保存先は {stage}-{project}-{name}-{namespace} の container store で、同名の宣言も container ごとに別の値が生成されます）。複数 container で値を共有したい 場合は全宣言に shared = true を付けます（保存先は {stage}-{project}-{namespace} の shared store。strangler 移行で Django の SECRET_KEY を新旧 container が共有する用途）。 詳細は container.secrets を参照

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

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

[container.main]
build = "docker"   # ショートハンド

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

# プロジェクトルートの pocket.toml
[container.main]
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/ .

# --chmod はディレクトリにも同じ mode が付くため、traverse に x が必要な 755 を使う
COPY --chmod=755 . .

pocket runtime-config¶

pocket.toml からビルド専用の設定（dockerfile_path, managed_assets, build, upload_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/

container.handlers¶

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

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

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

envs を使うと、同一イメージ・同一バイナリを環境変数でモード切替して複数の Lambda に並べられます（Rust バイナリなど、Django の management ハンドラーのようなモジュールパス切替が使えない場合に有用です）:

[container.main.handlers.web]
command = "myapp-lambda"

[container.main.handlers.admin]
command = "myapp-lambda"
timeout = 600
envs = { MYAPP_MODE = "admin" }

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.container.main.handlers.wsgi]
apigateway = {}

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

handlers.name.sqs¶

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

[container.main.handlers.sqsmanagement]
command = "pocket.django.lambda_handlers.management_command_handler"
timeout = 600
sqs = { dead_letter_alert = { email = "ops@example.com" } }

sqs.dead_letter_alert（必須）¶

pocket は queue と DLQ を自動生成しますが、リトライ・失敗系を DLQ に一元化する 設計は「その DLQ を見る手段」があって初めて成立します。dead_letter_alert は 宣言必須で、未宣言の pocket.toml は設定ロード時にエラーになります （うっかり無監視の防止）。

# 通知する（SNS topic + email 購読 + CloudWatch アラームを生成）
sqs = { dead_letter_alert = { email = "ops@example.com" } }

# 意図的に通知しない（リソースは queue / DLQ のみ）
sqs = { dead_letter_alert = { enabled = false } }

email を宣言すると、handler ごとに SNS topic（{queue名}-dead-letter-alert）と email 購読、および DLQ の ApproximateNumberOfMessagesVisible >= 1（period 300 秒 × 1 datapoint、欠測は正常扱い）で鳴る CloudWatch アラームが生成されます。DLQ が 空に戻ったとき（redrive / purge 後）の OK 通知も届きます。

aws sns confirm-subscription --topic-arn <topic-arn> \
  --token <token> --authenticate-on-unsubscribe true

container.secrets¶

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

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

store と pocket_key_format は全 container で一致が必要です（複数 container 構成でも保存の起点を 1 つに保つため）。

secrets.managed¶

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

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

各 spec は shared = true を付けると shared store (project 共有パス) に保存され、 同名 + 同 spec で宣言した複数 container が同じ値を共有します。shared なしの 同名宣言 (複数 container) はそれぞれの container store に独立した値として 生成されます (spec が違ってもかまいません)。shared の有無が混在する同名宣言も 可能で、shared を付けた container 同士だけが値を共有し、無印の container は 独立した値を持ちます (「2 container で共有 + 1 container は独立」のような構成)。 ただし cloudfront から key 名で参照される secret (token_secret / basic_auth / signing_key) は値の候補が 1 つに決まる必要が あるため、その key に限り「無印の複数宣言」や「shared と無印の混在」はエラーに なります。

# strangler 移行: 新旧 container で Django の署名 secret を共有する
[container.mydjango.secrets.managed]
SECRET_KEY = { type = "password", options = { length = 50 }, shared = true }

[container.v2.secrets.managed]
SECRET_KEY = { type = "password", options = { length = 50 }, shared = true }

type = "auto_database_url"

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

[container.main.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

[container.main.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

[container.main.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 ルートのトークン検証に使用されます。 オプションはありません。

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

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

type = "basic_auth_credential"

CloudFront の Basic 認証用 credential（user:pass 形式）を生成します。 CloudFront の basic_auth で参照します。 username は必須、password は省略時に英数字ランダム（length、既定 16 文字）で生成されます。

[container.main.secrets.managed]
BASIC_AUTH = { type = "basic_auth_credential", options = { username = "preview" } }
# password を固定したい場合 (値が pocket.toml = git に入る点に注意):
# BASIC_AUTH = { type = "basic_auth_credential", options = { username = "preview", password = "shared-pass" } }

→ 生成値は pocket resource container secrets list --show-values で確認できます。

secrets.user¶

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

[container.main.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 シークレットを分けたい場合に便利です。

[container.main.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 に触れない

[container.main.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 文字列です。
• 導出名は type 基準（/{pocket_key}-user/{type}）で、env var 名（このテーブルの キー）には依存しません。env var をリネームしても保存先は動かず、同一 type の user secret は 1 stage につき 1 個までです。この規約は 0.12.0 で導入されました。0.11 以前で provision 済みの環境は、pocket migrate secret-paths --stage <stage>（または引数なしの pocket migrate）で旧パス（キー基準）から新パス（type 基準）へ移設できます（冪等）。
• pocket resource <db> url --stage <stage> は保存済み URL を stdout に出力します （移行ツール等が $(...) で食える純テキスト）。type 基準で解決するため、consumer の DATABASE_URL が別 backend を指していても「その backend の保存 URL」を引けます。

secrets.extra_resources¶

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

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

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

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

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

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

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

仕組み:

1. pocket.toml の [container.main.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 側の宣言値を比較し、差分のあるキーだけ表示します。

container.iam¶

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

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

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

[[container.main.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 を複数行で書く場合は [[container.main.iam.inline_policies.<name>.Statement]] 形式の table array を使います。

container.django¶

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

storages¶

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

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

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

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

[container.main.django.storages]
staticfiles = { store = "s3", location = "static", static = true, publish = "command" }

[container.main.django.storages]
staticfiles = { store = "s3", location = "static", static = true, link = true }

caches¶

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

[container.main.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.container.main.django.settings]
DEFAULT_FROM_EMAIL = '"Dev" <test@example.com>'
CORS_ALLOWED_ORIGINS = ["https://dev.example.com"]

[prod.container.main.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 },
]

cloudfront.basic_auth¶

一般公開前の sandbox / stg サイト全体を Basic 認証で隠せます。distribution 単位の設定で、S3 / SPA / lambda を含む全 behavior に適用されます。

[container.main.secrets.managed]
BASIC_AUTH = { type = "basic_auth_credential", options = { username = "preview" } }

[sandbox.cloudfront.web]
domain = "www.sandbox.example.com"
basic_auth = "BASIC_AUTH"   # managed secret のキー名を参照 (token_secret と同じ方式)

• 検証は viewer-request の CloudFront Function が行い、期待する Authorization ヘッダ値（Basic <base64>）を KVS から読んで文字列比較します。不一致は 401 + WWW-Authenticate を返します
• credential は deploy 時に KVS へ書き込まれるため、rotation（secret の再生成 → 再 deploy）にスタック更新は不要です
• redirect_from や SPA トークン認証（require_token）とは併用可能です（各 Function に認証処理が合成されます）

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 も action = "block" の rate_limits も無い構成は、WebACL が何も遮断しない pass-through 状態になるので、 settings の validator がエラーで reject します（rate_limits だけの WebACL は rate_limits を参照）。

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 ... を実行してください。

allow_rules¶

IP allowlist で閉じた stage でも、外形 smoke・uptime チェックなど特定の経路 だけを宣言的に開けられます。allow_rules は IPSet / managed rules より先に 評価される allow で、match したら通し、しなければ従来どおりの判定に落ちます。

[prod.cloudfront.web.waf]
enable_ip_set = true

# (a) path 素通し: IP に関係なく誰でも通す (公開しても実害が無いもの向け)
[[prod.cloudfront.web.waf.allow_rules]]
path = "/api/health"

# (b) secret header: pocket が managed secret を自動生成し、
#     固定ヘッダ x-pocket-waf-allow に同値を載せた呼び手だけ通す
[[prod.cloudfront.web.waf.allow_rules]]
path = "/api/smoke/*"
header = "SMOKE_ALLOW_SECRET"

• path / header の少なくとも一方が必要です。両方指定した場合は AND (その path かつ secret 持ちのみ allow) になります
• header の secret は toml に値を書かず、pocket が自動生成して SSM に保存します (enable_origin_verify の POCKET_ORIGIN_VERIFY_SECRET と 同じ managed secret 経路)。ヘッダ名は x-pocket-waf-allow 固定です
• header を使う場合は [container.main] が必要です (secret の保存先のため)
• allow_rules は WAF を弱める宣言なので、deploy のたびに一覧が表示されます。 pocket settings --stage=<stage> の出力でも確認できます

CI (GitHub Actions 等) から secret header 付きで叩く例:

# store = "ssm" の場合 (パラメータ名は /{pocket_key}/<KEY>)
SECRET=$(aws ssm get-parameter \
  --name "/{stage}-{project}-pocket/SMOKE_ALLOW_SECRET" \
  --with-decryption --query Parameter.Value --output text)
curl -H "x-pocket-waf-allow: $SECRET" https://example.com/api/smoke/health

rate_limits¶

送信元 IP ごとのレートリミット（AWS WAF の rate-based rule）を宣言します。 window_sec 秒あたり limit 回を超えた送信元 IP に、超過している間 action を 適用します。

[prod.cloudfront.web.waf]
enable_ip_set = false
rate_limits = [
    # 認証系だけ厳しく (先に書いたものから評価される)
    { limit = 30, window_sec = 300, path = "/api/auth/*" },
    # 全体: 5 分 1,000 回超で 429
    { limit = 1000, window_sec = 300 },
    # 観測だけ (止めずに CloudWatch メトリクスに記録)
    { limit = 100, window_sec = 60, path = "/api/*", action = "count" },
]

• 全ルールの先頭で評価されます。allow_rules の秘密ヘッダを持つ呼び手や IP allowlist 済みの IP も、超過すれば止まります。漏れた秘密ヘッダや侵害された 内部経路からの大量引き抜きに、送信元 IP ごとの速度の上限を付けるためです。 CI の E2E テストや負荷試験が上限を超えると CI 側が 429 で落ちるので、上限は 実態に合わせて決めてください（まず count で入れて CloudWatch のルール別 メトリクスを見てから block に切り替えるのが安全です）
• 宣言順 = 評価順です。各ルールは「自分まで到達したリクエスト」だけを数えます。 先のルールで 429 になったリクエストは、後のルールの集計にも allow_rules にも 届きません。狭い path のルールを先に書いてください
• block は 429 を返します（WAF の既定の 403 だと IP allowlist 外の拒否と 区別できないため）。CloudFront の手前で止まるので Lambda は呼ばれません
• 集計キーは送信元 IP 固定です。CloudFront 配下では WAF が見る IP が viewer の IP なので、X-Forwarded-For の設定は不要です
• enable_ip_set = false で managed_rule_groups が無い場合、action = "block" の ルールが 1 つ以上必要です（count だけでは何も遮断しないため）
• 1 つの WebACL に宣言できるのは 10 件まで（AWS WAF の quota）
• rate_limits も allow_rules と同じく deploy のたびに一覧が表示されます

CLI: pocket waf ratelimit list¶

deploy 済みの WebACL から rate rule を読み、ルールごとに レート超過として 追跡中の IP（WAF の managed keys）を表示します。action = "block" のルール なら 429 で止めている IP、count なら止めずに数えているだけの IP です。

pocket waf ratelimit list --name web --stage prod

ratelimit-0: 30 req / 300 秒, path=/api/auth/*, action=block
  203.0.113.45/32
ratelimit-1: 1000 req / 300 秒, path=(全リクエスト), action=block
  (レート超過として追跡中の IP はありません)

「429 が出る」という問い合わせでその IP が制限中かを確かめる、NAT 越しの拠点や 正規のクローラが相乗りで引っかかっていないかを見る、count のまま「block に したら今どの IP が止まるか」を確かめる、といった用途です。表示は pocket.toml では なく deploy 済みのルール定義に従います（deploy していない変更は反映されません）。

必要な IAM 権限¶

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

WAF を外す¶

[cloudfront.<name>.waf] block を消して deploy すると CloudFront から WebACL が 外れますが、WAF の stack 自体は残ります。現状の pocket resource cloudfront-waf destroy は pocket.toml に waf 宣言が残っていないと cloudfront_waf '<name>' is not configured で使えないため、外す手順は次の順になります。

1. [cloudfront.<name>.waf] block を消して pocket deploy する（CloudFront の WebACLId が空になる。WebACL が紐付いたままだと WAF の stack は削除できない）

2. 残った stack <stage>-pocket-<project>-<cf name>-waf を us-east-1 で削除する

   aws cloudformation delete-stack --region us-east-1 \
     --stack-name <stage>-pocket-<project>-<cf name>-waf
   

宣言を消した後でも pocket resource cloudfront-waf destroy --name <cf name> で 削除できるようにする改善は予定しています。

origin verify (enable_origin_verify)¶

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

[cloudfront.web]
routes = [
    { type = "lambda", handler = "main.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 の挙動:

axum (Rust) middleware の組み込み¶

Rust container には pocket-rs 同梱の axum middleware (feature axum) を使います。 挙動は Django 版と同じで、secret の env 注入は set_envs() が自動で行います。 組み込み方は「Rust 連携」を参照してください。 rotate 直後は、新 header を受け取る warm Lambda がまだ旧 env を保持する一瞬の窓で 403 になり得ます (cold start で解消)。無停止 rotation が必要な場合は別途検討します。

redirect_from¶

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

redirect_from に指定したドメインは、その CloudFront ディストリビューションの 別名（Alias）として同じ配信に載り、証明書も domain の証明書に SAN として まとめられます。リクエストは viewer-request の CloudFront Function が判定し、 canonical な domain へ 301 (path・query 保持) でリダイレクトします （専用のリダイレクト用ディストリビューションや S3 バケットは作りません）。

routes¶

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

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

routes = [
    { is_default = true, is_spa = true, origin_path = "/spa" },  # catch-all は必須
    { path_pattern = "/static/*", ref = "static" },              # origin_path 省略 → static/
    { path_pattern = "/media/*", ref = "media" },                # origin_path 省略 → media/
]

routes = [
    # NG: origin_path = "/" は設定エラー。catch-all で origin_path 省略も同様
    { is_default = true, is_spa = true, origin_path = "/spa" },  # OK
]

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

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

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

[prod.cloudfront.web]
domain = "www.example.com"
routes = [
    { is_default = true, type = "lambda", handler = "main.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" },
]

deploy_hash — デプロイ時 git hash¶

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

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

[s3]

[container.main]
dockerfile_path = "pocket.Dockerfile"

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

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

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

[container.main.secrets]
store = "ssm"

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

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

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 に自動注入（deploy_hash route の有無に関係なく、全 container に常に注入されます。下記参照）
3. CloudFront Function が自動生成され、/static/{hash}/foo.js → /static/foo.js に変換してオリジンに転送
4. Function は外した hash をリクエストヘッダ x-pocket-deploy-hash に載せ、route 専用の CachePolicy がそれをキャッシュキーに含める。hash が変われば別のキャッシュになるので、デプロイごとにキャッシュが自然に更新される
5. versioned_max_age（デフォルト 1 年）の長期キャッシュ（cache-control: public, max-age=..., immutable）が成功応答（2xx / 304）にだけ付与される。403 / 404 などのエラー応答には付かないため、エラーがブラウザに長期保存されることはない（content_hash も同じ）

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)

[container.main.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 = "main.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 オリジンへ

[container.main.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 = "main.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 = "main.worker"
input = { task = "rotate_logs" }

[scheduler.schedules.daily_digest]
scheduler = "pocket.django.management_lambda_scheduler"
cron = "0 18 * * ? *"
handler = "main.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 = "main.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 = "main.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} 形式と完全に共存しており、後方互換性は壊しません。

pocket.sqs_scheduler¶

Lambda を直接 invoke せず、handler の SQS queue へ SendMessage します（EventBridge Scheduler の universal target。message が JSON 化されて MessageBody になります）。定期実行を queue に載せることで、リトライは SQS の visibility timeout / redrive に一元化され、失敗系の監視は queue の DLQ 1 箇所だけになります。worker handler は SQS event だけを受ければよく、「EventBridge 直接 invoke と SQS event の両受け」を実装する必要がありません。その 1 箇所の監視は sqs.dead_letter_alert（宣言必須。上記）が担います。

[container.main.handlers.sqsmanagement]
command = "pocket.django.lambda_handlers.sqs_management_command_report_failures_handler"
timeout = 60
sqs = { dead_letter_alert = { email = "ops@example.com" } }

[scheduler.schedules.cleanup]
scheduler = "pocket.sqs_scheduler"
rate = "15 minutes"
handler = "main.sqsmanagement"
message = { command = "clearsessions", args = [], kwargs = {} }

制約: 参照する handler は sqs を設定している必要があります（deploy 前にバリデーションエラーになります）。

message の形式は受け側の worker が決めます。Django の SQS management handler (sqs_management_command_report_failures_handler) へ送る場合は command / args / kwargs の 3 キーが必須です。Rust worker の場合はアプリ側で定義した Job 型（serde タグ付き enum 等）に一致する形を書きます。

ステージ別 schedule¶

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