@exabugs/dynamodb-client 1.19.0 → 1.21.0

package/terraform/ops-notify/versions.tf

@@ -0,0 +1,18 @@
+# provider の版: astro（5.x）と asanowa（6.x）の両方で使う。
+# 下限は Lambda の logging_config（5.x の途中で追加）。上限は data.aws_region の name（6.x で非推奨）が消える 7.x の前まで
+terraform {
+  required_version = ">= 1.5"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 5.30, < 7.0"
+      # us-east-1 のアラームの転送（us-east-1.tf）。呼び出し側は providers = { aws.us_east_1 = aws.us_east_1 } を常に渡す
+      configuration_aliases = [aws.us_east_1]
+    }
+    archive = {
+      source  = "hashicorp/archive"
+      version = ">= 2.0"
+    }
+  }
+}

package/terraform/system-change-recorder/README.md

@@ -0,0 +1,71 @@
+# システム変更履歴の記録 Lambda Terraformモジュール
+
+ADR 0006 の (b)（1.21.0）。asanowa・astro の `infra/modules/system-change-recorder` を 1 つにしたもの。使い方の詳細は [docs/SYSTEM_CHANGES.md](../../docs/SYSTEM_CHANGES.md)。
+
+## 作るもの
+
+- Lambda `<project>-<env>-system-change-recorder`（Node.js 22、arm64、15 秒、256 MB。構造化ログ JSON）と、そのロググループ・実行ロール
+- 権限: Records の IAM 版 URL の呼び出し（`lambda:InvokeFunctionUrl`）、Slack の webhook のパラメータの読み取り（`slack_webhook_param_name` があるときだけ）。DynamoDB には直接触れない
+- 非同期の呼び出しの再試行 0（同じ入力の再試行は、同じ変更が 2 件になる）
+- 作らないもの: Function URL・EventBridge・`aws_lambda_permission`（呼び出しは人・CI の AWS の認証。`dynamodb-system-change` の CLI）
+
+## 前提
+
+- 参照は `node_modules` のパス（版は npm の版で固定される。git の `ref` ではない）。例: アプリの infra が `infra/` なら `source = "../node_modules/@exabugs/dynamodb-client/terraform/system-change-recorder"`、`infra/apps/<app>/` なら `"../../../node_modules/..."`
+- **Lambda の成果物はアプリが作り、`source_file`（バンドル済みの 1 ファイル）と `handler` で渡す**。エントリはアプリの数行（`createSystemChangeHandler`。アプリ名や、権限チェック層を通すアプリの包み方を渡す）なので、ライブラリの dist は使わない
+- zip は `${path.root}/.terraform/archives/system-change-recorder.zip` に作る（`path.module` を使わない。pnpm の版つきのパスが state に入ると、版を上げるたびに差分が出るため）
+- pnpm では、版を上げた後に `.terraform/modules` を消してから `terraform init` する（[../README.md](../README.md) の注意）
+- モジュール全体の `depends_on` は使わない（依存先に変更があると、中のデータソースが apply 時の読み取りになり、既存のリソースが作り直しになる）。依存は、出力の値（`log_group_name` など）で渡す
+
+## 使い方
+
+```hcl
+module "system_change_recorder" {
+  source = "../node_modules/@exabugs/dynamodb-client/terraform/system-change-recorder"
+
+  project_name             = var.project_name
+  environment              = var.environment
+  records_iam_function_url = module.records.iam_function_url
+  records_iam_alias_arn    = module.records.iam_alias_arn
+  log_retention_days       = var.log_retention_days
+
+  # アプリのバンドル（エントリは createSystemChangeHandler の数行）
+  source_file = "${path.root}/../apps/server/dist/system-change-recorder.cjs"
+  handler     = "system-change-recorder.handler"
+
+  slack_webhook_param_name = "/${var.project_name}/${var.environment}/ops/slack-webhook"
+  admin_base_url           = var.ops_admin_base_url
+}
+```
+
+## 変数
+
+| 変数                                                 | 既定    | 説明                                                                          |
+| ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------- |
+| `project_name` / `environment`                       | 必須    | 名前の接頭辞 `<project>-<env>`。環境変数 `PROJECT_NAME` / `ENV_NAME`          |
+| `records_iam_function_url` / `records_iam_alias_arn` | 必須    | Records の IAM 版 Function URL と、そのエイリアスの ARN（呼び出し権限の対象） |
+| `source_file` / `handler`                            | 必須    | アプリのバンドル（1 ファイル）と、ハンドラ                                    |
+| `log_retention_days`                                 | 7       | ロググループの保持日数                                                        |
+| `slack_webhook_param_name`                           | `""`    | Slack の webhook の SSM パラメータ名（SecureString）。空なら Slack に送らない |
+| `admin_base_url`                                     | `""`    | 管理画面の URL（Slack の通知に詳細のリンクを付ける）                          |
+| `notify_started`                                     | `false` | 「開始」も Slack に送るか                                                     |
+
+## 出力
+
+`function_name`（CLI の `--function` の既定と同じ名前）、`function_arn`、`log_group_name`（ops-notify に購読させる）
+
+## アプリに残るもの
+
+- 上の module ブロック（`source`・`source_file`・`handler` と設定の値）
+- Lambda のエントリ（`createSystemChangeHandler` を呼ぶ数行）とバンドルの作成（esbuild など）
+- 秘密（webhook の URL など）の SSM パラメータの作成
+
+## アプリのモジュールからの移行（置き換えを起こさない）
+
+リソースのアドレス・名前は、asanowa / astro の旧モジュール（`infra/modules/system-change-recorder`）と同じ。**module ブロックの名前（`module "system_change_recorder"`）を変えずに `source` だけを差し替え**、`source_file`・`handler` を足す。アドレスが変わらないので `moved` は要らない（ラッパーのモジュールで包むと、アドレスが変わり `moved` が要る）。
+
+1. `terraform init`（モジュールの取り直し）→ `terraform plan`
+2. **0 to add / 0 to destroy、`must be replaced` が無い**ことを確かめる。出てよいのは in-place の更新だけ（文言の差。asanowa / astro では Lambda の description の ADR の番号が消える）
+3. 確認のうえ apply。旧モジュールのディレクトリを消す
+
+詳細と実機の確認は [ADR 0006](../../docs/adr/0006-library-owns-table-operations.md) の段階 6。

package/terraform/system-change-recorder/main.tf

@@ -0,0 +1,122 @@
+# システム変更履歴（systemChanges）の記録 Lambda（ADR 0006 の (b)。docs/SYSTEM_CHANGES.md）
+#
+# 入力（直接呼び出し）を検証し、Records の IAM URL で systemChanges に書く（削除しない）。
+# Lambda の成果物（バンドル済みの 1 ファイル）はアプリが作り、source_file で渡す（エントリでアプリの設定・
+# 権限チェック層を渡すため。実装は `createSystemChangeHandler`）。
+#
+# 呼び出しは、人・CI の AWS の認証（lambda:InvokeFunction）で行う。Function URL・EventBridge・
+# リソースベースのポリシー（aws_lambda_permission）は作らない。
+# 失敗は構造化ログ（warn / error）に出す。このロググループは、通知（../ops-notify）に購読させる。
+#
+# リソースのアドレス・名前は、asanowa / astro の旧モジュール（infra/modules/system-change-recorder）と同じ
+# （module ブロックの名前を変えずに source だけを差し替えれば、moved なしで置き換えが起きない）。
+
+locals {
+  prefix = "${var.project_name}-${var.environment}"
+}
+
+data "aws_caller_identity" "current" {}
+data "aws_region" "current" {}
+
+data "archive_file" "recorder" {
+  type        = "zip"
+  source_file = var.source_file
+  output_path = "${path.root}/.terraform/archives/system-change-recorder.zip"
+}
+
+resource "aws_cloudwatch_log_group" "recorder" {
+  name              = "/aws/lambda/${local.prefix}-system-change-recorder"
+  retention_in_days = var.log_retention_days
+}
+
+resource "aws_iam_role" "recorder" {
+  name = "${local.prefix}-system-change-recorder-role"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Action    = "sts:AssumeRole"
+      Effect    = "Allow"
+      Principal = { Service = "lambda.amazonaws.com" }
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "recorder_logs" {
+  role       = aws_iam_role.recorder.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
+}
+
+# Records Lambda の IAM 認証版 URL（エイリアス）を呼ぶ権限だけ（最小権限）。DynamoDB には直接触れない
+resource "aws_iam_role_policy" "recorder_invoke_records" {
+  name = "${local.prefix}-system-change-recorder-invoke-records"
+  role = aws_iam_role.recorder.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = ["lambda:InvokeFunctionUrl"]
+      Resource = [var.records_iam_alias_arn]
+    }]
+  })
+}
+
+# Slack の webhook（SecureString）を読む権限だけ。通知 Lambda と同じ（暗号化は、AWS 管理の鍵で、追加の KMS 権限は不要。PoC で確認）
+resource "aws_iam_role_policy" "recorder_read_slack_webhook" {
+  count = var.slack_webhook_param_name == "" ? 0 : 1
+  name  = "${local.prefix}-system-change-recorder-read-slack-webhook"
+  role  = aws_iam_role.recorder.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = ["ssm:GetParameter"]
+      Resource = ["arn:aws:ssm:${data.aws_region.current.name}:${data.aws_caller_identity.current.account_id}:parameter${var.slack_webhook_param_name}"]
+    }]
+  })
+}
+
+resource "aws_lambda_function" "recorder" {
+  function_name    = "${local.prefix}-system-change-recorder"
+  description      = "Record a system change (release, OTA, infra, Lambda) to the systemChanges records"
+  role             = aws_iam_role.recorder.arn
+  filename         = data.archive_file.recorder.output_path
+  source_code_hash = data.archive_file.recorder.output_base64sha256
+  handler          = var.handler
+  runtime          = "nodejs22.x"
+  architectures    = ["arm64"]
+  # HTTP の時間切れ（RECORD_HTTP_TIMEOUT_MS = 5 秒）より長く
+  timeout     = 15
+  memory_size = 256
+
+  environment {
+    variables = merge(
+      {
+        PROJECT_NAME    = var.project_name
+        ENV_NAME        = var.environment
+        RECORDS_IAM_URL = var.records_iam_function_url
+      },
+      var.slack_webhook_param_name == "" ? {} : {
+        SLACK_WEBHOOK_PARAM = var.slack_webhook_param_name
+        NOTIFY_STARTED      = tostring(var.notify_started)
+      },
+      var.admin_base_url == "" ? {} : { ADMIN_BASE_URL = var.admin_base_url },
+    )
+  }
+
+  logging_config {
+    log_format = "JSON"
+    log_group  = aws_cloudwatch_log_group.recorder.name
+  }
+
+  depends_on = [aws_iam_role_policy_attachment.recorder_logs]
+}
+
+# 非同期の呼び出し（--invocation-type Event）の再試行は 0
+# （同じ入力の再試行は、同じ変更が 2 件になる。失敗はログ → 通知で知る）
+resource "aws_lambda_function_event_invoke_config" "recorder" {
+  function_name          = aws_lambda_function.recorder.function_name
+  maximum_retry_attempts = 0
+}

package/terraform/system-change-recorder/outputs.tf

@@ -0,0 +1,14 @@
+output "function_name" {
+  description = "システム変更履歴の記録 Lambda の関数名（aws lambda invoke で呼ぶ）"
+  value       = aws_lambda_function.recorder.function_name
+}
+
+output "function_arn" {
+  description = "システム変更履歴の記録 Lambda の ARN"
+  value       = aws_lambda_function.recorder.arn
+}
+
+output "log_group_name" {
+  description = "システム変更履歴の記録 Lambda のロググループ名（通知 Lambda が購読する）"
+  value       = aws_cloudwatch_log_group.recorder.name
+}

package/terraform/system-change-recorder/variables.tf

@@ -0,0 +1,53 @@
+variable "project_name" {
+  description = "プロジェクト名"
+  type        = string
+}
+
+variable "environment" {
+  description = "環境識別子（dev, prd）"
+  type        = string
+}
+
+variable "records_iam_function_url" {
+  description = "Records Lambda の AWS_IAM 認証版 Function URL（systemChanges に書く）"
+  type        = string
+}
+
+variable "records_iam_alias_arn" {
+  description = "Records Lambda の IAM 認証用エイリアスの ARN（lambda:InvokeFunctionUrl の Resource）"
+  type        = string
+}
+
+variable "log_retention_days" {
+  description = "CloudWatch Logsの保持期間（日数）"
+  type        = number
+  default     = 7
+}
+
+variable "slack_webhook_param_name" {
+  description = "Slack の webhook の SSM パラメータ名（SecureString。通知 Lambda と同じもの）。空なら、Slack に送らない"
+  type        = string
+  default     = ""
+}
+
+variable "admin_base_url" {
+  description = "管理画面の URL（Slack の通知に、システム変更履歴の詳細へのリンクを付ける）。空ならリンクを付けない"
+  type        = string
+  default     = ""
+}
+
+variable "notify_started" {
+  description = "「開始」も Slack に送るか。既定は false（1 回の適用で 2 通になるため。結果だけを送る）"
+  type        = bool
+  default     = false
+}
+
+variable "source_file" {
+  description = "Lambda の成果物（バンドル済みの 1 ファイル。例: apps/server/dist/system-change-recorder.cjs）。zip にして使う"
+  type        = string
+}
+
+variable "handler" {
+  description = "Lambda のハンドラ（例: system-change-recorder.handler）"
+  type        = string
+}

package/terraform/system-change-recorder/versions.tf

@@ -0,0 +1,16 @@
+# provider の版: astro（5.x）と asanowa（6.x）の両方で使う。
+# 下限は Lambda の logging_config（5.x の途中で追加）。上限は data.aws_region の name（6.x で非推奨）が消える 7.x の前まで
+terraform {
+  required_version = ">= 1.5"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 5.30, < 7.0"
+    }
+    archive = {
+      source  = "hashicorp/archive"
+      version = ">= 2.0"
+    }
+  }
+}