magic-pocket-cli 0.26.0__tar.gz → 0.28.0__tar.gz

{magic_pocket_cli-0.26.0 → magic_pocket_cli-0.28.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: magic-pocket-cli
-Version: 0.26.0
+Version: 0.28.0
 Summary: CLI and deploy tools for magic-pocket.
 Requires-Python: >=3.10
 Requires-Dist: awscrt>=0.19.0
 Requires-Dist: click>=8.1.7
 Requires-Dist: deepdiff>=6.7.1
 Requires-Dist: jinja2>=3.1.3
-Requires-Dist: magic-pocket<0.27,>=0.26.0
+Requires-Dist: magic-pocket<0.29,>=0.28.0
 Requires-Dist: pathspec>=1.0.4
 Requires-Dist: python-on-whales>=0.68.0
 Requires-Dist: pyyaml>=6.0.1

magic_pocket_cli-0.28.0/pocket_cli/cli/backup_cli.py

@@ -0,0 +1,68 @@
+import click
+
+from pocket.context import Context
+from pocket.utils import echo
+from pocket_cli.resources.backup import Backup
+
+
+def _get_backup_resource(stage: str) -> Backup:
+    context = Context.from_toml(stage=stage)
+    if context.backup is None:
+        raise click.ClickException(
+            "この stage には AWS Backup の対象 DB (dsql / managed rds) がありません。"
+        )
+    if not context.backup.declared:
+        raise click.ClickException(
+            "[backup] が宣言されていません。バックアップデータの削除には"
+            " [backup] の deletable = true 宣言が必要です。"
+        )
+    if not context.backup.deletable:
+        raise click.ClickException(
+            "バックアップデータ (recovery point) の削除には [backup] に"
+            " deletable = true の宣言が必要です。誤操作でデータを失わないための"
+            " ガードなので、削除する時だけ宣言することを推奨します。"
+        )
+    return Backup(context.backup, dsql_context=context.dsql, rds_context=context.rds)
+
+
+@click.group()
+def backup():
+    pass
+
+
+@backup.command()
+@click.option("--stage", envvar="POCKET_DEPLOY_STAGE", prompt=True)
+@click.option(
+    "--yes", "-y", is_flag=True, default=False, help="確認プロンプトをスキップ"
+)
+def cleanup(stage: str, yes: bool):
+    """この stage のバックアップデータ (recovery point) を削除する。
+
+    [backup] deletable = true の宣言が必要。pocket 管理 vault (pocket-backup)
+    にある、現存する対象 DB (dsql / managed rds) の recovery point だけを消す。
+    削除済み cluster の分は ARN で引けないため対象外 (AWS Backup コンソールから
+    削除する)。plan (スケジュール) には触らない。
+    """
+    r = _get_backup_resource(stage)
+    points = r.list_recovery_points()
+    if points is None:
+        raise click.ClickException(
+            "recovery point を列挙する権限がありません (backup:*)。"
+        )
+    if not points:
+        echo.info("削除対象の recovery point はありません。")
+        return
+    echo.warning("以下の recovery point を削除します:")
+    for point in points:
+        created = point.get("CreationDate")
+        echo.info(
+            "  - %s (%s)"
+            % (point["RecoveryPointArn"], created.isoformat() if created else "-")
+        )
+    echo.danger("この操作は取り消せません！")
+    if not yes:
+        click.confirm(
+            "%d 件の recovery point を削除しますか？" % len(points), abort=True
+        )
+    deleted = r.delete_recovery_points(points)
+    echo.success("%d 件の recovery point を削除しました。" % deleted)

{magic_pocket_cli-0.26.0 → magic_pocket_cli-0.28.0}/pocket_cli/cli/deploy_cli.py

@@ -10,6 +10,7 @@ from pocket_cli.cli.removed_flags import removed_skip_check_existing
 from pocket_cli.mediator import Mediator
 from pocket_cli.resources.aws.state import StateStore, create_state_store
 from pocket_cli.resources.awscontainer import AwsContainer
+from pocket_cli.resources.backup import Backup
 from pocket_cli.resources.cloudfront import CloudFront
 from pocket_cli.resources.cloudfront_acm import CloudFrontAcm
 from pocket_cli.resources.cloudfront_keys import CloudFrontKeys
@@ -32,6 +33,10 @@ def _append_infra_resources(resources, context: Context, state_bucket: str):
         resources.append(Dsql(context.dsql))
     if context.rds:
         resources.append(Rds(context.rds))
+    if context.backup and context.backup.declared:
+        resources.append(
+            Backup(context.backup, dsql_context=context.dsql, rds_context=context.rds)
+        )
     for _name, cf_ctx in context.cloudfront.items():
         if cf_ctx.signing_key:
             resources.append(CloudFrontKeys(cf_ctx))

{magic_pocket_cli-0.26.0 → magic_pocket_cli-0.28.0}/pocket_cli/cli/destroy_cli.py

@@ -9,6 +9,7 @@ from pocket_cli.resources.aws.state import (
     create_state_store,
 )
 from pocket_cli.resources.awscontainer import AwsContainer
+from pocket_cli.resources.backup import Backup
 from pocket_cli.resources.cloudfront import CloudFront
 from pocket_cli.resources.cloudfront_acm import CloudFrontAcm
 from pocket_cli.resources.cloudfront_keys import CloudFrontKeys
@@ -88,6 +89,11 @@ def _warn_command_provisioned(label: str, hint: str):
 
 def _collect_aws_database_targets(context: Context) -> list[str]:
     targets: list[str] = []
+    if context.backup:
+        for plan_name in Backup(context.backup).existing_plan_names():
+            targets.append(
+                "AWS Backup plan: %s (recovery point と vault は残ります)" % plan_name
+            )
     if context.dsql:
         dsql = Dsql(context.dsql)
         if dsql.status != "NOEXIST":
@@ -223,6 +229,40 @@ def _destroy_awscontainer(context: Context, with_secrets: bool):
         echo.success("Pocket managed secrets were deleted.")
 
 
+def _destroy_backup(context: Context, yes: bool):
+    """backup plan / selection を削除し、recovery point の扱いを案内する。
+
+    plan は [backup] 宣言の有無に関わらず削除する (宣言を外した後の destroy でも
+    残さない)。selection が削除済み cluster の ARN を指したまま残ると以後の
+    backup job が失敗し続けるため、cluster 削除より先に消す。
+
+    recovery point (バックアップデータ) は既定では消さない。deletable = true の
+    宣言下で、対話の [y/N] に明示的に yes と答えた場合のみ削除する (--yes での
+    一括承認では削除しない。データ削除だけは暗黙に通さない)。cluster 削除後は
+    ARN で引けなくなるため、この確認も cluster 削除より先に行う。
+    """
+    if not context.backup:
+        return
+    backup = Backup(context.backup, dsql_context=context.dsql, rds_context=context.rds)
+    backup.delete()
+    points = backup.list_recovery_points()
+    if not points:  # None (権限なし) or 空
+        return
+    if context.backup.declared and context.backup.deletable and not yes:
+        echo.warning(
+            "バックアップデータ (recovery point) が %d 件あります。" % len(points)
+        )
+        if click.confirm("recovery point も削除しますか？", default=False):
+            backup.delete_recovery_points(points)
+            return
+    echo.warning(
+        "バックアップデータ (recovery point %d 件) は削除されず残ります"
+        " (保持期限まで課金対象)。削除するには [backup] deletable = true を"
+        " 宣言して `pocket backup cleanup` を実行するか、AWS Backup の"
+        " コンソールから削除してください。" % len(points)
+    )
+
+
 def _destroy_dsql(context: Context):
     """DSQL クラスターを削除"""
     if not context.dsql:
@@ -352,7 +392,12 @@ def _destroy_cloudfront_and_acm(context: Context):
                 echo.success("CloudFront ACM '%s' was destroyed." % name)
 
 
-def _destroy_resources(context: Context, with_secrets: bool, with_state_bucket: bool):
+def _destroy_resources(
+    context: Context,
+    with_secrets: bool,
+    with_state_bucket: bool,
+    yes: bool = False,
+):
     """リソースをデプロイの逆順で削除"""
     # 1. CloudFront + ACM
     _destroy_cloudfront_and_acm(context)
@@ -360,6 +405,9 @@ def _destroy_resources(context: Context, with_secrets: bool, with_state_bucket:
     # 2. AwsContainer (CFNスタック + ECR + secrets)
     _destroy_awscontainer(context, with_secrets)
 
+    # 2.4. backup plan（DSQL / RDS の cluster 削除より先）
+    _destroy_backup(context, yes)
+
     # 2.5. DSQL
     _destroy_dsql(context)
 
@@ -434,5 +482,5 @@ def destroy(stage: str, without_secrets: bool, with_state_bucket: bool, yes: boo
     if not yes:
         click.confirm("stage '%s' の全リソースを削除しますか？" % stage, abort=True)
 
-    _destroy_resources(context, with_secrets, with_state_bucket)
+    _destroy_resources(context, with_secrets, with_state_bucket, yes=yes)
     echo.success("stage '%s' の全リソースを削除しました。" % stage)

{magic_pocket_cli-0.26.0 → magic_pocket_cli-0.28.0}/pocket_cli/cli/dsql_cli.py

@@ -6,10 +6,10 @@ from botocore.exceptions import ClientError
 from pocket.context import Context
 from pocket.utils import echo
 from pocket_cli.cli.resource_helper import require_configured
+from pocket_cli.resources.aws.backup_common import BACKUP_ROLE_NAME, BACKUP_VAULT_NAME
 from pocket_cli.resources.dsql import (
-    BACKUP_ROLE_NAME,
     BACKUP_TERMINAL_STATES,
-    BACKUP_VAULT_NAME,
+    DEFAULT_ON_DEMAND_RETENTION_DAYS,
     Dsql,
 )
 
@@ -87,9 +87,12 @@ def endpoint(stage, format_):
 )
 @click.option(
     "--retention-days",
-    type=int,
+    type=click.IntRange(min=0),
     default=None,
-    help="recovery point の保持日数 (省略時: vault のライフサイクル既定)",
+    help="recovery point の保持日数"
+    " (省略時: [backup] の delete_after_days、宣言が無ければ %d 日。"
+    "0 を指定すると無期限保持だが pocket からは削除できなくなる)"
+    % DEFAULT_ON_DEMAND_RETENTION_DAYS,
 )
 @click.option("--watch", is_flag=True, help="バックアップ完了まで待機する")
 def backup(stage, vault, iam_role_arn, retention_days, watch):

{magic_pocket_cli-0.26.0 → magic_pocket_cli-0.28.0}/pocket_cli/cli/main_cli.py

@@ -4,6 +4,7 @@ from pocket import __version__
 from pocket_cli import django_cli
 from pocket_cli.cli import (
     awscontainer_cli,
+    backup_cli,
     cloudfront_cli,
     cloudfront_keys_cli,
     cloudfront_waf_cli,
@@ -80,6 +81,7 @@ main.add_command(runtime_config_cli.runtime_config)
 main.add_command(migrate_cli.migrate)
 main.add_command(permissions_cli.permissions)
 main.add_command(waf_cli.waf)
+main.add_command(backup_cli.backup)
 
 
 @main.group()

magic_pocket_cli-0.28.0/pocket_cli/resources/aws/backup_common.py

@@ -0,0 +1,84 @@
+"""AWS Backup の前提リソース (vault / サービスロール) の共有 ensure。
+
+定期バックアップ (resources/backup.py の Backup) と dsql のオンデマンド
+バックアップ (resources/dsql.py) の両方が使うため、どちらからも import できる
+場所に置く (backup.py は Dsql / Rds を import するので、dsql.py が backup.py を
+import すると循環になる)。
+"""
+
+from __future__ import annotations
+
+import json
+import time
+
+from botocore.exceptions import ClientError
+
+from pocket.utils import echo
+
+# pocket 管理のバックアップ前提リソース。AWS Backup の Default vault /
+# AWSBackupDefaultServiceRole は console 初回操作で作られるもので、API しか
+# 使わないアカウントには存在しないため、pocket 側で冪等に ensure する。
+# ロール名の forge- prefix は codebuild ロールの命名に合わせている
+BACKUP_VAULT_NAME = "pocket-backup"
+BACKUP_ROLE_NAME = "forge-pocket-backup-role"
+_BACKUP_ROLE_POLICIES = (
+    "arn:aws:iam::aws:policy/service-role/AWSBackupServiceRolePolicyForBackup",
+    "arn:aws:iam::aws:policy/service-role/AWSBackupServiceRolePolicyForRestores",
+)
+
+
+def ensure_backup_vault(backup_client, name: str) -> None:
+    """pocket 管理の vault を冪等に確保する。
+
+    describe → 無ければ create の順は不可。vault が 1 つも無いアカウントでは
+    AWS Backup が存在しない vault への Describe に ResourceNotFoundException
+    ではなく AccessDeniedException を返すため「未作成」を判定できない。
+    CreateBackupVault は同名 vault があると AlreadyExistsException を返すので
+    create を先に撃って握る (既存なら noop = 冪等)。
+    """
+    try:
+        backup_client.create_backup_vault(BackupVaultName=name)
+    except ClientError as e:
+        if e.response["Error"]["Code"] == "AlreadyExistsException":
+            return
+        raise
+    echo.log("Created backup vault: %s" % name)
+
+
+def ensure_backup_role(iam_client, permissions_boundary: str | None) -> str:
+    """AWS Backup サービスロールを冪等に ensure して ARN を返す。
+
+    codebuild の _ensure_role と同型。boundary 必須のアカウントでも作成
+    できるよう permissions_boundary を付与する。
+    """
+    try:
+        return iam_client.get_role(RoleName=BACKUP_ROLE_NAME)["Role"]["Arn"]
+    except ClientError as e:
+        if e.response["Error"]["Code"] != "NoSuchEntity":
+            raise
+    echo.log("Creating AWS Backup service role: %s" % BACKUP_ROLE_NAME)
+    assume_role_policy = json.dumps(
+        {
+            "Version": "2012-10-17",
+            "Statement": [
+                {
+                    "Effect": "Allow",
+                    "Principal": {"Service": "backup.amazonaws.com"},
+                    "Action": "sts:AssumeRole",
+                }
+            ],
+        }
+    )
+    create_kwargs: dict = {
+        "RoleName": BACKUP_ROLE_NAME,
+        "AssumeRolePolicyDocument": assume_role_policy,
+    }
+    if permissions_boundary:
+        create_kwargs["PermissionsBoundary"] = permissions_boundary
+    role_arn: str = iam_client.create_role(**create_kwargs)["Role"]["Arn"]
+    for policy_arn in _BACKUP_ROLE_POLICIES:
+        iam_client.attach_role_policy(RoleName=BACKUP_ROLE_NAME, PolicyArn=policy_arn)
+    # IAM ロールの伝播待ち (作成直後の StartBackupJob 失敗を避ける)
+    echo.log("Waiting for IAM role propagation...")
+    time.sleep(10)
+    return role_arn

magic_pocket_cli-0.28.0/pocket_cli/resources/backup.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import boto3
+from botocore.exceptions import ClientError
+
+from pocket.resources.base import ResourceStatus
+from pocket.utils import echo
+from pocket_cli.resources.aws.backup_common import (
+    BACKUP_VAULT_NAME,
+    ensure_backup_role,
+    ensure_backup_vault,
+)
+from pocket_cli.resources.dsql import Dsql
+from pocket_cli.resources.rds import Rds
+
+if TYPE_CHECKING:
+    from pocket.context import (
+        BackupContext,
+        BackupPlanContext,
+        DsqlContext,
+        RdsContext,
+    )
+
+# backup plan の drift 判定で比較する項目。AWS が既定値で補完する項目
+# (StartWindowMinutes / RuleId 等) を含めると毎 deploy で update が走るため、
+# pocket が宣言した項目だけを見る
+_PLAN_RULE_KEYS = (
+    "TargetBackupVaultName",
+    "ScheduleExpression",
+    "ScheduleExpressionTimezone",
+)
+_PLAN_LIFECYCLE_KEYS = ("MoveToColdStorageAfterDays", "DeleteAfterDays")
+
+
+def _rules_by_name(rules: list[dict]) -> dict[str, dict]:
+    return {rule.get("RuleName", ""): rule for rule in rules}
+
+
+def _plan_matches(current: dict, desired: dict) -> bool:
+    """rule 名で突き合わせて宣言項目を比較する (GetBackupPlan の順序に依存しない)。"""
+    current_rules = _rules_by_name(current.get("Rules", []))
+    desired_rules = _rules_by_name(desired["Rules"])
+    if set(current_rules) != set(desired_rules):
+        return False
+    for name, want in desired_rules.items():
+        cur = current_rules[name]
+        if any(cur.get(key) != want.get(key) for key in _PLAN_RULE_KEYS):
+            return False
+        cur_lifecycle = cur.get("Lifecycle", {})
+        want_lifecycle = want["Lifecycle"]
+        if any(
+            cur_lifecycle.get(key) != want_lifecycle.get(key)
+            for key in _PLAN_LIFECYCLE_KEYS
+        ):
+            return False
+    return True
+
+
+class Backup:
+    """[backup.dsql] / [backup.rds] 宣言に沿った AWS Backup plan の管理。
+
+    エンジンごとに rule 構成が違う (rds は daily を PITR が担う / cold storage
+    不可) ため、plan はエンジン別に provision する。plan 管理は cluster の
+    作成後に走る必要があるため、実作業は ensure_post_deploy_state で行う
+    (status は常に COMPLETED)。
+
+    バックアップ「データ」(recovery point) は原則触らない。削除できるのは
+    [backup] deletable = true の宣言下で、利用者が明示的に確認した場合のみ
+    (`pocket backup cleanup` / destroy の確認プロンプト)。
+    """
+
+    context: BackupContext
+
+    def __init__(
+        self,
+        context: BackupContext,
+        dsql_context: DsqlContext | None = None,
+        rds_context: RdsContext | None = None,
+    ) -> None:
+        self.context = context
+        self._dsql_context = dsql_context
+        self._rds_context = rds_context
+        self._backup = boto3.client("backup", region_name=context.region)
+        self._iam = boto3.client("iam", region_name=context.region)
+
+    @property
+    def status(self) -> ResourceStatus:
+        # plan は cluster 作成後でないと selection を張れないため、作成・更新は
+        # ensure_post_deploy_state で冪等に行う
+        return "COMPLETED"
+
+    @property
+    def description(self):
+        return "Configure AWS Backup plans: %s" % ", ".join(
+            plan.plan_name for plan in self.context.plans
+        )
+
+    def deploy_init(self):
+        pass
+
+    def create(self):
+        self.ensure_post_deploy_state()
+
+    def update(self):
+        self.ensure_post_deploy_state()
+
+    def state_info(self):
+        return {
+            "backup": {
+                "plans": [plan.plan_name for plan in self.context.plans],
+            }
+        }
+
+    def _service_target_arn(self, service: str) -> str | None:
+        if service == "dsql" and self._dsql_context:
+            return Dsql(self._dsql_context).backup_target_arn
+        if service == "rds" and self._rds_context:
+            return Rds(self._rds_context).backup_target_arn
+        return None
+
+    def target_arns(self) -> list[str]:
+        """recovery point 操作の対象 ARN 一覧 (未作成 cluster は除く)。
+
+        [backup] の宣言に依らず、stage に存在する対象 DB 全部を返す
+        (destroy 時のデータ残存案内は宣言を外した後も出すため)。
+        """
+        arns = [self._service_target_arn(s) for s in ("dsql", "rds")]
+        return sorted(arn for arn in arns if arn is not None)
+
+    def ensure_post_deploy_state(self):
+        """宣言されたエンジンごとに plan / selection を冪等に確保する。
+
+        未宣言なら何もしない (opt-in。宣言を外した後の既存 plan にも触らない。
+        plan の掃除は destroy の責務)。
+        """
+        if not self.context.plans:
+            return
+        try:
+            targets = [
+                (plan, arn)
+                for plan in self.context.plans
+                if (arn := self._service_target_arn(plan.service)) is not None
+            ]
+            if not targets:
+                return
+            ensure_backup_vault(self._backup, BACKUP_VAULT_NAME)
+            role_arn = ensure_backup_role(self._iam, self.context.permissions_boundary)
+            for plan, arn in targets:
+                plan_id = self._ensure_plan(plan)
+                self._ensure_selection(plan, plan_id, role_arn, [arn])
+        except ClientError as e:
+            if e.response["Error"]["Code"] != "AccessDeniedException":
+                raise
+            echo.warning(
+                "AWS Backup の設定に必要な権限が無いため、定期バックアップの"
+                " provisioning をスキップしました: %s" % e
+            )
+            echo.warning(
+                "  deploy role に backup:* を付与してください"
+                " (`pocket permissions list` 参照)。"
+            )
+
+    def _plan_document(self, plan: BackupPlanContext) -> dict:
+        rules = []
+        for rule in plan.rules:
+            lifecycle: dict = {"DeleteAfterDays": rule.delete_after_days}
+            if rule.cold_storage_after_days:
+                lifecycle["MoveToColdStorageAfterDays"] = rule.cold_storage_after_days
+            rules.append(
+                {
+                    "RuleName": rule.name,
+                    "TargetBackupVaultName": BACKUP_VAULT_NAME,
+                    "ScheduleExpression": rule.schedule_expression,
+                    "ScheduleExpressionTimezone": self.context.timezone,
+                    "Lifecycle": lifecycle,
+                }
+            )
+        return {"BackupPlanName": plan.plan_name, "Rules": rules}
+
+    def _find_plan_id(self, plan_name: str) -> str | None:
+        paginator = self._backup.get_paginator("list_backup_plans")
+        for page in paginator.paginate():
+            for plan in page["BackupPlansList"]:
+                if plan["BackupPlanName"] == plan_name:
+                    return plan["BackupPlanId"]
+        return None
+
+    def existing_plan_names(self) -> list[str]:
+        """destroy の対象一覧表示用 (権限が無ければ「無し」扱い)。"""
+        try:
+            return [
+                name
+                for name in self.context.cleanup_plan_names
+                if self._find_plan_id(name) is not None
+            ]
+        except ClientError as e:
+            if e.response["Error"]["Code"] != "AccessDeniedException":
+                raise
+            return []
+
+    def _ensure_plan(self, plan: BackupPlanContext) -> str:
+        document = self._plan_document(plan)
+        plan_id = self._find_plan_id(plan.plan_name)
+        if plan_id is None:
+            echo.log("Creating backup plan: %s" % plan.plan_name)
+            return self._backup.create_backup_plan(BackupPlan=document)["BackupPlanId"]
+        # 宣言が変わっていれば追従する (cron / lifecycle の drift 収束)
+        current = self._backup.get_backup_plan(BackupPlanId=plan_id)["BackupPlan"]
+        if not _plan_matches(current, document):
+            echo.log("Updating backup plan: %s" % plan.plan_name)
+            self._backup.update_backup_plan(BackupPlanId=plan_id, BackupPlan=document)
+        return plan_id
+
+    def _ensure_selection(
+        self,
+        plan: BackupPlanContext,
+        plan_id: str,
+        role_arn: str,
+        arns: list[str],
+    ) -> None:
+        """対象 DB の ARN を指した selection を確保する。
+
+        selection には更新 API が無いため、対象 ARN が変わっていたら
+        (cluster 再作成など) 作り直す。
+        """
+        selections = self._backup.list_backup_selections(BackupPlanId=plan_id)
+        for item in selections["BackupSelectionsList"]:
+            if item["SelectionName"] != plan.plan_name:
+                continue
+            detail = self._backup.get_backup_selection(
+                BackupPlanId=plan_id, SelectionId=item["SelectionId"]
+            )
+            if sorted(detail["BackupSelection"].get("Resources", [])) == arns:
+                return
+            self._backup.delete_backup_selection(
+                BackupPlanId=plan_id, SelectionId=item["SelectionId"]
+            )
+        echo.log("Creating backup selection for %s" % plan.plan_name)
+        self._backup.create_backup_selection(
+            BackupPlanId=plan_id,
+            BackupSelection={
+                "SelectionName": plan.plan_name,
+                "IamRoleArn": role_arn,
+                "Resources": arns,
+            },
+        )
+
+    def delete(self) -> None:
+        """backup plan / selection を削除する。
+
+        recovery point と vault は消さない。バックアップ「設定」は stack の
+        付属物だが、バックアップ「データ」は stack より長生きさせるべきで、
+        cluster を消した後こそ必要になりうるため。
+
+        [backup] の宣言の有無に関わらず、stage に存在しうる全 plan 名を走査する
+        (宣言を外した後の destroy でも plan を残さないため)。backup 権限を
+        持たない deploy role でも destroy 自体は完遂させたいので、権限エラーは
+        警告に留める。
+        """
+        for plan_name in self.context.cleanup_plan_names:
+            try:
+                plan_id = self._find_plan_id(plan_name)
+            except ClientError as e:
+                if e.response["Error"]["Code"] != "AccessDeniedException":
+                    raise
+                echo.warning(
+                    "backup plan を確認する権限がないため、削除をスキップしました"
+                    " (backup:ListBackupPlans)。plan が残っている場合は手動で"
+                    " 削除してください。"
+                )
+                return
+            if plan_id is None:
+                continue
+            selections = self._backup.list_backup_selections(BackupPlanId=plan_id)
+            for item in selections["BackupSelectionsList"]:
+                self._backup.delete_backup_selection(
+                    BackupPlanId=plan_id, SelectionId=item["SelectionId"]
+                )
+            self._backup.delete_backup_plan(BackupPlanId=plan_id)
+            echo.log("Deleted backup plan: %s" % plan_name)
+
+    def list_recovery_points(self) -> list[dict] | None:
+        """対象 DB の recovery point 一覧 (pocket-backup vault 内のもの)。
+
+        現存する cluster の ARN でしか引けない (削除済み cluster の分は対象外 =
+        console でしか消せない)。権限が無ければ None を返す (呼び出し側が案内を
+        スキップできるように、空リストと区別する)。
+        """
+        points: list[dict] = []
+        try:
+            for arn in self.target_arns():
+                paginator = self._backup.get_paginator(
+                    "list_recovery_points_by_resource"
+                )
+                for page in paginator.paginate(ResourceArn=arn):
+                    points.extend(page["RecoveryPoints"])
+        except ClientError as e:
+            if e.response["Error"]["Code"] != "AccessDeniedException":
+                raise
+            return None
+        # pocket 管理の vault 分だけを扱う (--vault で利用者の vault に取った
+        # オンデマンド分は利用者の管理物とみなし、pocket からは消さない)
+        return [p for p in points if p.get("BackupVaultName") == BACKUP_VAULT_NAME]
+
+    def delete_recovery_points(self, points: list[dict]) -> int:
+        """recovery point を削除して件数を返す。
+
+        [backup] deletable = true + 利用者の明示確認を経た経路 (cleanup CLI /
+        destroy の確認プロンプト) からのみ呼ぶこと。
+        """
+        for point in points:
+            self._backup.delete_recovery_point(
+                BackupVaultName=point["BackupVaultName"],
+                RecoveryPointArn=point["RecoveryPointArn"],
+            )
+        if points:
+            echo.log("Deleted %d recovery point(s)." % len(points))
+        return len(points)

{magic_pocket_cli-0.26.0 → magic_pocket_cli-0.28.0}/pocket_cli/resources/dsql.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import json
-import time
 from functools import cached_property
 from typing import TYPE_CHECKING
 
@@ -15,6 +14,11 @@ from pocket.secret_store import (
     read_stored_value,
 )
 from pocket.utils import echo
+from pocket_cli.resources.aws.backup_common import (
+    BACKUP_VAULT_NAME,
+    ensure_backup_role,
+    ensure_backup_vault,
+)
 from pocket_cli.resources.aws.poll import wait_until
 
 if TYPE_CHECKING:
@@ -25,44 +29,13 @@ BACKUP_TERMINAL_STATES = {"COMPLETED", "FAILED", "ABORTED", "EXPIRED", "PARTIAL"
 # restore job の終端状態
 RESTORE_TERMINAL_STATES = {"COMPLETED", "FAILED", "ABORTED"}
 
-# pocket 管理のバックアップ前提リソース。AWS Backup の Default vault /
-# AWSBackupDefaultServiceRole は console 初回操作で作られるもので、API しか
-# 使わないアカウントには存在しないため、pocket 側で冪等に ensure する。
-# ロール名の forge- prefix は codebuild ロールの命名に合わせている
-BACKUP_VAULT_NAME = "pocket-backup"
-BACKUP_ROLE_NAME = "forge-pocket-backup-role"
-_BACKUP_ROLE_POLICIES = (
-    "arn:aws:iam::aws:policy/service-role/AWSBackupServiceRolePolicyForBackup",
-    "arn:aws:iam::aws:policy/service-role/AWSBackupServiceRolePolicyForRestores",
-)
-# backup plan の drift 判定で比較する項目。AWS が既定値で補完する項目
-# (StartWindowMinutes / RuleId 等) を含めると毎 deploy で update が走るため、
-# pocket が宣言した項目だけを見る
-_PLAN_RULE_KEYS = (
-    "RuleName",
-    "TargetBackupVaultName",
-    "ScheduleExpression",
-    "ScheduleExpressionTimezone",
-)
-_PLAN_LIFECYCLE_KEYS = ("MoveToColdStorageAfterDays", "DeleteAfterDays")
-
-
-def _plan_matches(current: dict, desired: dict) -> bool:
-    current_rules = current.get("Rules", [])
-    desired_rules = desired["Rules"]
-    if len(current_rules) != len(desired_rules):
-        return False
-    for cur, want in zip(current_rules, desired_rules, strict=True):
-        if any(cur.get(key) != want.get(key) for key in _PLAN_RULE_KEYS):
-            return False
-        cur_lifecycle = cur.get("Lifecycle", {})
-        want_lifecycle = want["Lifecycle"]
-        if any(
-            cur_lifecycle.get(key) != want_lifecycle.get(key)
-            for key in _PLAN_LIFECYCLE_KEYS
-        ):
-            return False
-    return True
+# オンデマンドバックアップで保持日数の指定が無く [backup] も未宣言なときの既定。
+# AWS Backup の vault は既定ライフサイクルを持たないため、Lifecycle を渡さないと
+# recovery point は無期限に残る。pocket にも deploy role にもデータ削除権限が無く
+# (destroy も recovery point を残す)、console 作業でしか消せなくなるため、
+# 「いつかは失効する」ことを既定で保証する。3 年は復元要件として十分長く、
+# 意図せず消えるより増え続けるほうが困る、という判断
+DEFAULT_ON_DEMAND_RETENTION_DAYS = 1095
 
 
 class Dsql:
@@ -149,7 +122,7 @@ class Dsql:
             "DSQL には自動バックアップ (PITR / スナップショット) がありません。"
         )
         echo.warning(
-            "  定期バックアップは [dsql.backup] を宣言してください。"
+            "  定期バックアップは [backup.dsql] を宣言してください。"
             " 単発なら `pocket resource dsql backup` で取得できます。"
         )
 
@@ -173,9 +146,6 @@ class Dsql:
     def delete(self):
         if not self.identifier:
             return
-        # cluster より先に plan を消す (selection が消える cluster の ARN を
-        # 指したまま残ると、以後の backup job が失敗し続ける)
-        self.delete_backup_plan()
         echo.log("Deleting DSQL cluster: %s" % self.identifier)
         self._client.delete_cluster(identifier=self.identifier)
         echo.log("Waiting for DSQL cluster deletion...")
@@ -186,128 +156,13 @@ class Dsql:
     def ensure_post_deploy_state(self):
         # create の有無に関わらず毎 deploy で publish を冪等に確保する。cluster
         # 再作成や旧バージョンで deploy 済みの既存 cluster も常に実体を反映する
+        # (定期バックアップの plan / selection は Backup resource の責務)
         self.publish_endpoint()
-        # plan の selection は cluster ARN を指すため、cluster 作成後に ensure する
-        self.ensure_backup_plan()
 
     @property
-    def backup_plan_name(self) -> str:
-        return "%s-backup" % self.context.tag_name
-
-    def ensure_backup_plan(self) -> None:
-        """[dsql.backup] 宣言に沿って backup plan / selection を冪等に確保する。
-
-        DSQL は組み込みの自動バックアップを持たないため、宣言された stage では
-        pocket が plan まで provision する (native 属性で表現できる RDS の PITR
-        と違い、宣言だけでは何も起きないため)。未宣言なら何もしない。
-        """
-        backup = self.context.backup
-        if backup is None or not self.arn:
-            return
-        self._ensure_backup_vault(BACKUP_VAULT_NAME)
-        role_arn = self._ensure_backup_role()
-        plan_id = self._ensure_plan(backup)
-        self._ensure_selection(plan_id, role_arn)
-
-    def _plan_document(self, backup) -> dict:
-        lifecycle: dict = {"DeleteAfterDays": backup.delete_after_days}
-        if backup.cold_storage_after_days:
-            lifecycle["MoveToColdStorageAfterDays"] = backup.cold_storage_after_days
-        return {
-            "BackupPlanName": self.backup_plan_name,
-            "Rules": [
-                {
-                    "RuleName": "daily",
-                    "TargetBackupVaultName": BACKUP_VAULT_NAME,
-                    "ScheduleExpression": backup.schedule_expression,
-                    "ScheduleExpressionTimezone": backup.timezone,
-                    "Lifecycle": lifecycle,
-                }
-            ],
-        }
-
-    def _find_plan_id(self) -> str | None:
-        paginator = self._backup.get_paginator("list_backup_plans")
-        for page in paginator.paginate():
-            for plan in page["BackupPlansList"]:
-                if plan["BackupPlanName"] == self.backup_plan_name:
-                    return plan["BackupPlanId"]
-        return None
-
-    def _ensure_plan(self, backup) -> str:
-        document = self._plan_document(backup)
-        plan_id = self._find_plan_id()
-        if plan_id is None:
-            echo.log("Creating backup plan: %s" % self.backup_plan_name)
-            return self._backup.create_backup_plan(BackupPlan=document)["BackupPlanId"]
-        # 宣言が変わっていれば追従する (cron / lifecycle の drift 収束)
-        current = self._backup.get_backup_plan(BackupPlanId=plan_id)["BackupPlan"]
-        if not _plan_matches(current, document):
-            echo.log("Updating backup plan: %s" % self.backup_plan_name)
-            self._backup.update_backup_plan(BackupPlanId=plan_id, BackupPlan=document)
-        return plan_id
-
-    def _ensure_selection(self, plan_id: str, role_arn: str) -> None:
-        """cluster ARN を対象にした selection を確保する。
-
-        selection には更新 API が無いため、対象 ARN が変わっていたら
-        (cluster 再作成など) 作り直す。
-        """
-        if not self.arn:
-            return
-        selections = self._backup.list_backup_selections(BackupPlanId=plan_id)
-        for item in selections["BackupSelectionsList"]:
-            if item["SelectionName"] != self.backup_plan_name:
-                continue
-            detail = self._backup.get_backup_selection(
-                BackupPlanId=plan_id, SelectionId=item["SelectionId"]
-            )
-            if detail["BackupSelection"].get("Resources") == [self.arn]:
-                return
-            self._backup.delete_backup_selection(
-                BackupPlanId=plan_id, SelectionId=item["SelectionId"]
-            )
-        echo.log("Creating backup selection for %s" % self.context.tag_name)
-        self._backup.create_backup_selection(
-            BackupPlanId=plan_id,
-            BackupSelection={
-                "SelectionName": self.backup_plan_name,
-                "IamRoleArn": role_arn,
-                "Resources": [self.arn],
-            },
-        )
-
-    def delete_backup_plan(self) -> None:
-        """backup plan / selection を削除する (cluster 削除との対称操作)。
-
-        recovery point と vault は消さない。バックアップ「設定」は stack の
-        付属物だが、バックアップ「データ」は stack より長生きさせるべきで、
-        cluster を消した後こそ必要になりうるため。
-
-        宣言の有無に関わらず走査する ([dsql.backup] を外した後の destroy でも
-        plan を残さないため)。backup 権限を持たない古い deploy role でも
-        destroy 自体は完遂させたいので、権限エラーは警告に留める。
-        """
-        try:
-            plan_id = self._find_plan_id()
-        except ClientError as e:
-            if e.response["Error"]["Code"] != "AccessDeniedException":
-                raise
-            echo.warning(
-                "backup plan を確認する権限がないため、削除をスキップしました"
-                " (backup:ListBackupPlans)。plan が残っている場合は手動で"
-                " 削除してください。"
-            )
-            return
-        if plan_id is None:
-            return
-        selections = self._backup.list_backup_selections(BackupPlanId=plan_id)
-        for item in selections["BackupSelectionsList"]:
-            self._backup.delete_backup_selection(
-                BackupPlanId=plan_id, SelectionId=item["SelectionId"]
-            )
-        self._backup.delete_backup_plan(BackupPlanId=plan_id)
-        echo.log("Deleted backup plan: %s" % self.backup_plan_name)
+    def backup_target_arn(self) -> str | None:
+        """[backup] の selection 対象 ARN (Backup resource が参照する)。"""
+        return self.arn
 
     def publish_endpoint(self):
         """endpoint を stored user secret 正準パスへ publish する (作成記録)。
@@ -370,64 +225,43 @@ class Dsql:
             "ResourceArn": self.arn,
             "IamRoleArn": iam_role_arn,
         }
-        if retention_days is not None:
-            params["Lifecycle"] = {"DeleteAfterDays": retention_days}
+        resolved = self._resolve_retention_days(retention_days)
+        if resolved is not None:
+            params["Lifecycle"] = {"DeleteAfterDays": resolved}
         res = self._backup.start_backup_job(**params)
         return res["BackupJobId"]
 
-    def _ensure_backup_vault(self, name: str) -> None:
-        # describe → 無ければ create の順は不可。vault が 1 つも無いアカウントでは
-        # AWS Backup が存在しない vault への Describe に ResourceNotFoundException
-        # ではなく AccessDeniedException を返すため「未作成」を判定できない。
-        # CreateBackupVault は同名 vault があると AlreadyExistsException を返すので
-        # create を先に撃って握る (既存なら noop = 冪等)。
-        try:
-            self._backup.create_backup_vault(BackupVaultName=name)
-        except ClientError as e:
-            if e.response["Error"]["Code"] == "AlreadyExistsException":
-                return
-            raise
-        echo.log("Created backup vault: %s" % name)
-
-    def _ensure_backup_role(self) -> str:
-        """AWS Backup サービスロールを冪等に ensure して ARN を返す。
+    def _resolve_retention_days(self, retention_days: int | None) -> int | None:
+        """オンデマンドバックアップの保持日数を決める (None を返すと無期限)。
 
-        codebuild の _ensure_role と同型。boundary 必須のアカウントでも作成
-        できるよう context.permissions_boundary を付与する。
+        指定 > [backup.dsql] の最長階層 (monthly) > 既定 の順で解決する。
+        復元時の内部バックアップ (利用者が明示的に頼んでいない recovery point)
+        も start_backup を通るため同じ既定が効く。0 は「無期限」の明示指定。
         """
-        try:
-            return self._iam.get_role(RoleName=BACKUP_ROLE_NAME)["Role"]["Arn"]
-        except ClientError as e:
-            if e.response["Error"]["Code"] != "NoSuchEntity":
-                raise
-        echo.log("Creating AWS Backup service role: %s" % BACKUP_ROLE_NAME)
-        assume_role_policy = json.dumps(
-            {
-                "Version": "2012-10-17",
-                "Statement": [
-                    {
-                        "Effect": "Allow",
-                        "Principal": {"Service": "backup.amazonaws.com"},
-                        "Action": "sts:AssumeRole",
-                    }
-                ],
-            }
-        )
-        create_kwargs: dict = {
-            "RoleName": BACKUP_ROLE_NAME,
-            "AssumeRolePolicyDocument": assume_role_policy,
-        }
-        if self.context.permissions_boundary:
-            create_kwargs["PermissionsBoundary"] = self.context.permissions_boundary
-        role_arn: str = self._iam.create_role(**create_kwargs)["Role"]["Arn"]
-        for policy_arn in _BACKUP_ROLE_POLICIES:
-            self._iam.attach_role_policy(
-                RoleName=BACKUP_ROLE_NAME, PolicyArn=policy_arn
+        if retention_days == 0:
+            echo.warning(
+                "この recovery point は無期限保持です。"
+                "pocket からは削除できないため、消すには console 作業が必要です。"
             )
-        # IAM ロールの伝播待ち (作成直後の StartBackupJob 失敗を避ける)
-        echo.log("Waiting for IAM role propagation...")
-        time.sleep(10)
-        return role_arn
+            return None
+        if retention_days is not None:
+            echo.log("Retention: %d days (--retention-days)" % retention_days)
+            return retention_days
+        backup = self.context.backup
+        if backup is not None:
+            echo.log(
+                "Retention: %d days (from [backup.dsql] monthly)"
+                % backup.monthly_delete_after_days
+            )
+            return backup.monthly_delete_after_days
+        echo.log("Retention: %d days (default)" % DEFAULT_ON_DEMAND_RETENTION_DAYS)
+        return DEFAULT_ON_DEMAND_RETENTION_DAYS
+
+    def _ensure_backup_vault(self, name: str) -> None:
+        ensure_backup_vault(self._backup, name)
+
+    def _ensure_backup_role(self) -> str:
+        return ensure_backup_role(self._iam, self.context.permissions_boundary)
 
     def latest_recovery_point(self) -> dict | None:
         """現用クラスターの最新 recovery point (完了済み) を返す。"""

{magic_pocket_cli-0.26.0 → magic_pocket_cli-0.28.0}/pocket_cli/resources/rds.py

@@ -163,6 +163,19 @@ class Rds:
     def database_name(self) -> str:
         return self.context.database_name
 
+    @property
+    def backup_target_arn(self) -> str | None:
+        """[backup] の selection 対象 ARN (Backup resource が参照する)。
+
+        managed = false の既存クラスタは対象外 (他 stack の管理物にバックアップ
+        設定を足さない)。
+        """
+        if not self.context.managed:
+            return None
+        if self.cluster:
+            return self.cluster.get("DBClusterArn")
+        return None
+
     @property
     def status(self) -> ResourceStatus:
         if not self.context.managed:

{magic_pocket_cli-0.26.0 → magic_pocket_cli-0.28.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "magic-pocket-cli"
-version = "0.26.0"
+version = "0.28.0"
 description = "CLI and deploy tools for magic-pocket."
 requires-python = ">=3.10"
 dependencies = [
     # lib は同 minor に束縛する。0.x では minor が breaking の単位のため、
     # 上限なしだと cli を pin した消費者にも lib の破壊的変更が届いてしまう
-    "magic-pocket>=0.26.0,<0.27",
+    "magic-pocket>=0.28.0,<0.29",
     "click>=8.1.7",
     "jinja2>=3.1.3",
     "python-on-whales>=0.68.0",