atlas-init 0.1.1__py3-none-any.whl → 0.1.4__py3-none-any.whl

atlas_init/cli_cfn/{cfn.py → aws.py}

@@ -6,16 +6,22 @@ from collections.abc import Sequence
 from concurrent.futures import ThreadPoolExecutor, wait
 from datetime import UTC, datetime
 from functools import lru_cache, total_ordering
+from pathlib import Path
 
 import botocore.exceptions
+import humanize
+import typer
 from boto3.session import Session
 from model_lib import Event
 from mypy_boto3_cloudformation import CloudFormationClient
-from mypy_boto3_cloudformation.type_defs import ParameterTypeDef
+from mypy_boto3_cloudformation.type_defs import ListTypesOutputTypeDef, ParameterTypeDef
 from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_fixed
+from zero_3rdparty.datetime_utils import utc_now
 from zero_3rdparty.iter_utils import group_by_once
 
+from atlas_init.cli_helper.run import run_command_is_ok
 from atlas_init.cloud.aws import REGIONS, PascalAlias, region_continent
+from atlas_init.settings.interactive import confirm
 
 logger = logging.getLogger(__name__)
 EARLY_DATETIME = datetime(year=1990, month=1, day=1, tzinfo=UTC)
@@ -76,12 +82,12 @@ def deactivate_type(type_name: str, region: str):
     client.deactivate_type(TypeName=type_name, Type="RESOURCE")
 
 
-def delete_role_stack(type_name: str, region_name: str) -> None:
+def delete_role_stack(type_name: str, region_name: str, role_arn: str = "") -> None:
     stack_name = type_name.replace("::", "-").lower() + "-role-stack"
-    delete_stack(region_name, stack_name)
+    delete_stack(region_name, stack_name, role_arn)
 
 
-def delete_stack(region_name: str, stack_name: str):
+def delete_stack(region_name: str, stack_name: str, role_arn: str = ""):
     client = cloud_formation_client(region_name)
     logger.warning(f"deleting stack {stack_name} in region={region_name}")
     try:
@@ -91,7 +97,7 @@ def delete_stack(region_name: str, stack_name: str):
             logger.warning(f"stack {stack_name} not found")
             return
         raise
-    client.delete_stack(StackName=stack_name)
+    client.delete_stack(StackName=stack_name, RoleARN=role_arn)
     wait_on_stack_ok(stack_name, region_name, expect_not_found=True)
 
 
@@ -110,7 +116,9 @@ def create_stack(
         Parameters=parameters,
         RoleARN=role_arn,
     )
-    logger.info(f"stack with name: {stack_name} created in {region_name} has id: {stack_id['StackId']}")
+    logger.info(
+        f"stack with name: {stack_name} created in {region_name} has id: {stack_id['StackId']} role_arn:{role_arn}"
+    )
     wait_on_stack_ok(stack_name, region_name, timeout_seconds=timeout_seconds)
 
 
@@ -146,7 +154,9 @@ class StackInProgressError(StackBaseError):
 
 
 class StackError(StackBaseError):
-    pass
+    def __init__(self, status: str, timestamp: datetime, status_reason: str, reasons: str) -> None:
+        super().__init__(status, timestamp, status_reason)
+        self.reasons = reasons
 
 
 @total_ordering
@@ -184,10 +194,20 @@ class StackEvents(Event):
 
     def last_reason(self) -> str:
         for event in sorted(self.stack_events, reverse=True):
-            if reason := event.resource_status_reason:
+            if reason := event.resource_status_reason.strip():
                 return reason
         return ""
 
+    def multiple_reasons(self, max_reasons: int = 5) -> str:
+        reasons = []
+        for event in sorted(self.stack_events, reverse=True):
+            if reason := event.resource_status_reason.strip():
+                reason_number = len(reasons) + 1
+                reasons.append(f"{reason_number}. {reason}")
+                if reason_number >= max_reasons:
+                    break
+        return "\n".join(reasons)
+
 
 def wait_on_stack_ok(
     stack_name: str,
@@ -229,15 +249,21 @@ def wait_on_stack_ok(
                 current_event.resource_status,
                 current_event.timestamp,
                 current_event.resource_status_reason,
+                reasons=parsed.multiple_reasons(),
             )
         status = current_event.resource_status
         logger.info(f"stack is ready {stack_name} {status} ✅")
         if "ROLLBACK" in status:
-            last_reason = parsed.last_reason()
+            last_reason = parsed.multiple_reasons()
             logger.warning(f"stack did rollback, got: {current_event!r}\n{last_reason}")
+
         return None
 
-    return _wait_on_stack_ok()
+    try:
+        return _wait_on_stack_ok()
+    except StackError as e:
+        logger.warning(f"stack error {stack_name} {e.status} {e.status_reason}\n{e.reasons}")
+        raise typer.Exit(1) from None
 
 
 def print_version_regions(type_name: str) -> None:
@@ -257,7 +283,7 @@ def get_last_version_all_regions(type_name: str) -> dict[str | None, list[str]]:
     futures = {}
     with ThreadPoolExecutor(max_workers=10) as pool:
         for region in REGIONS:
-            future = pool.submit(get_last_cfn_type, type_name, region)
+            future = pool.submit(get_last_cfn_type, type_name, region, is_third_party=True)
             futures[future] = region
         done, not_done = wait(futures.keys(), timeout=300)
         for f in not_done:
@@ -287,8 +313,18 @@ class CfnTypeDetails(Event):
             raise TypeError
         return self.last_updated < other.last_updated
 
+    def seconds_since_update(self) -> float:
+        return (utc_now() - self.last_updated).total_seconds()
+
 
-def get_last_cfn_type(type_name: str, region: str, *, is_third_party: bool = False) -> None | CfnTypeDetails:
+def publish_cfn_type(region: str):
+    client: CloudFormationClient = cloud_formation_client(region)
+    client.publish_type()
+
+
+def get_last_cfn_type(
+    type_name: str, region: str, *, is_third_party: bool = False, force_version: str = ""
+) -> None | CfnTypeDetails:
     client: CloudFormationClient = cloud_formation_client(region)
     prefix = type_name
     logger.info(f"finding public 3rd party for '{prefix}' in {region}")
@@ -302,7 +338,7 @@ def get_last_cfn_type(type_name: str, region: str, *, is_third_party: bool = Fal
     }
     next_token = ""
     for _ in range(100):
-        types_response = client.list_types(**kwargs)  # type: ignore
+        types_response: ListTypesOutputTypeDef = client.list_types(**kwargs)  # type: ignore
         next_token = types_response.get("NextToken", "")
         kwargs["NextToken"] = next_token
         for t in types_response["TypeSummaries"]:
@@ -325,6 +361,12 @@ def get_last_cfn_type(type_name: str, region: str, *, is_third_party: bool = Fal
     if not type_details:
         logger.warning(f"no version for {type_name} in region {region}")
         return None
+    if force_version:
+        for detail in type_details:
+            if detail.version == force_version:
+                return detail
+        versions = [d.version for d in type_details]
+        raise ValueError(f"unable to find version {force_version} for {type_name}, got {versions}")
     return sorted(type_details)[-1]
 
 
@@ -335,4 +377,77 @@ def activate_resource_type(details: CfnTypeDetails, region: str, execution_role_
         PublicTypeArn=details.type_arn,
         ExecutionRoleArn=execution_role_arn,
     )
-    logger.info(f"activate response: {response}")
+    logger.info(f"activate response: {response} role={execution_role_arn}")
+
+
+def ensure_resource_type_activated(
+    type_name: str,
+    region: str,
+    force_deregister: bool,
+    is_interactive: bool,
+    resource_path: Path,
+    cfn_execution_role: str,
+    force_version: str = "",
+) -> None:
+    cfn_type_details = get_last_cfn_type(type_name, region, is_third_party=False)
+    logger.info(f"found cfn_type_details {cfn_type_details} for {type_name}")
+    is_third_party = False
+    if cfn_type_details is None:
+        cfn_type_details = get_last_cfn_type(type_name, region, is_third_party=True)
+        if cfn_type_details:
+            is_third_party = True
+            logger.warning(f"found 3rd party extension for cfn type {type_name} active")
+    if force_version:
+        if cfn_type_details and cfn_type_details.version == force_version:
+            logger.info(f"version {force_version} already active")
+            return
+        force_deregister = True
+    if cfn_type_details is not None and (cfn_type_details.seconds_since_update() > 3600 * 24 or force_deregister):
+        outdated_warning = f"more than {humanize.naturaldelta(cfn_type_details.seconds_since_update())} since last update to {type_name} {cfn_type_details.version}"
+        logger.warning(outdated_warning)
+        if force_deregister or confirm(
+            f"{outdated_warning}, should deregister?",
+            is_interactive=is_interactive,
+            default=True,
+        ):
+            if is_third_party:
+                deactivate_third_party_type(type_name, region)
+            else:
+                deregister_cfn_resource_type(type_name, deregister=True, region_filter=region)
+            cfn_type_details = None
+
+    # assert cfn_type_details, f"no cfn_type_details found for {type_name}"
+    # client = cloud_formation_client(region)
+    # response = client.activate_type(
+    #     Type="RESOURCE",
+    #     # PublicTypeArn=cfn_type_details.type_arn.replace(":type/", "::type/"),
+    #     PublicTypeArn="arn:aws:cloudformation:eu-south-2:358363220050::type/resource/MongoDB-Atlas-ResourcePolicy/00000001",
+    #     ExecutionRoleArn=cfn_execution_role,
+    #     LoggingConfig={"LogRoleArn": cfn_execution_role, "LogGroupName": "/apix/espen/cfn-test1"},
+    # )
+    # logger.info(f"activate response: {response}")
+    submit_cmd = f"cfn submit --verbose --set-default --region {region} --role-arn {cfn_execution_role}"
+    if (
+        not force_version
+        and cfn_type_details is None
+        and confirm(
+            f"No existing {type_name} found, ok to run:\n{submit_cmd}\nsubmit?",
+            is_interactive=is_interactive,
+            default=True,
+        )
+    ):
+        assert run_command_is_ok(cmd=submit_cmd.split(), env=None, cwd=resource_path, logger=logger)
+        cfn_type_details = get_last_cfn_type(type_name, region, is_third_party=False)
+    if cfn_type_details is None:
+        third_party = get_last_cfn_type(type_name, region, is_third_party=True, force_version=force_version)
+        assert third_party, f"unable to find 3rd party type for {type_name}"
+        last_updated = third_party.last_updated
+        if confirm(
+            f"No existing {type_name} found, ok to activate 3rd party: :\n'{third_party.version} ({humanize.naturalday(last_updated), {last_updated.isoformat()}})'\n?",
+            is_interactive=is_interactive,
+            default=True,
+        ):
+            activate_resource_type(third_party, region, cfn_execution_role)
+            cfn_type_details = third_party
+    assert cfn_type_details, f"no cfn_type_details found for {type_name}"
+    # TODO: validate the active type details uses the execution role

atlas_init/cli_cfn/cfn_parameter_finder.py

@@ -7,9 +7,11 @@ from mypy_boto3_cloudformation.type_defs import ParameterTypeDef
 from pydantic import ConfigDict, Field
 from rich import prompt
 from zero_3rdparty.dict_nested import read_nested
+from zero_3rdparty.file_utils import clean_dir
 
+from atlas_init.cli_cfn.files import create_sample_file, default_log_group_name
 from atlas_init.cloud.aws import PascalAlias
-from atlas_init.repos.cfn import cfn_examples_dir, cfn_type_normalized
+from atlas_init.repos.cfn import CfnType, cfn_examples_dir, cfn_type_normalized
 from atlas_init.settings.path import DEFAULT_TF_PATH
 
 logger = logging.getLogger(__name__)
@@ -46,13 +48,15 @@ class TemplatePathNotFoundError(Exception):
         self.examples_dir = examples_dir
 
 
-def infer_template_path(repo_path: Path, type_name: str, stack_name: str) -> Path:
+def infer_template_path(repo_path: Path, type_name: str, stack_name: str, example_name: str = "") -> Path:
     examples_dir = cfn_examples_dir(repo_path)
     template_paths: list[Path] = []
     type_setting = f'"Type": "{type_name}"'
     for p in examples_dir.rglob("*.json"):
+        if example_name and example_name != p.stem:
+            continue
         if type_setting in p.read_text():
-            logger.info(f"found template @ {p}")
+            logger.info(f"found template @ '{p.stem}': {p.parent}")
             template_paths.append(p)
     if not template_paths:
         raise TemplatePathNotFoundError(type_name, examples_dir)
@@ -78,6 +82,14 @@ parameters_exported_env_vars = {
     "KeyId": "MONGODB_ATLAS_ORG_API_KEY_ID",
     "TeamId": "MONGODB_ATLAS_TEAM_ID",
     "ProjectId": "MONGODB_ATLAS_PROJECT_ID",
+    "AWSVpcId": "AWS_VPC_ID",
+    "MongoDBAtlasProjectId": "MONGODB_ATLAS_PROJECT_ID",
+    "AWSSubnetId": "AWS_SUBNET_ID",
+    "AWSRegion": "AWS_REGION",
+    "AppId": "MONGODB_REALM_APP_ID",
+    "FunctionId": "MONGODB_REALM_FUNCTION_ID",
+    "FunctionName": "MONGODB_REALM_FUNCTION_NAME",
+    "ServiceId": "MONGODB_REALM_SERVICE_ID",
 }
 
 STACK_NAME_PARAM = "$STACK_NAME_PARAM$"
@@ -91,6 +103,13 @@ type_names_defaults: dict[str, dict[str, str]] = {
         STACK_NAME_PARAM: "ClusterName",
         "ProjectName": "Cluster-CFN-Example",
     },
+    "resourcepolicy": {
+        STACK_NAME_PARAM: "Name",
+        "Policies": 'forbid (principal, action == cloud::Action::"project.edit",resource) when {context.project.ipAccessList.contains(ip("0.0.0.0/0"))};',
+    },
+    "trigger": {
+        STACK_NAME_PARAM: "TriggerName",
+    },
 }
 
 
@@ -114,6 +133,11 @@ class CfnTemplate(Entity):
     parameters: dict[str, CfnParameter]
     resources: dict[str, CfnResource]
 
+    @classmethod
+    def read_template_types(cls, template_path: Path, prefix: str = CfnType.MONGODB_ATLAS_CFN_TYPE_PREFIX) -> set[str]:
+        cfn_template = parse_model(template_path, t=CfnTemplate)
+        return {r.type for r in cfn_template.resources.values() if r.type.startswith(prefix)}
+
     def find_resource(self, type_name: str) -> CfnResource:
         for r in self.resources.values():
             if r.type == type_name:
@@ -128,6 +152,31 @@ class CfnTemplate(Entity):
         resource = self.find_resource(type_name)
         resource.properties.update(resources)
 
+    def get_resource_properties(self, type_name: str, parameters: list[ParameterTypeDef]) -> dict:
+        resource = self.find_resource(type_name)
+        properties = resource.properties
+        for param in parameters:
+            key = param.get("ParameterKey")
+            assert key
+            if key not in properties:
+                key_found = next(
+                    (
+                        maybe_key
+                        for maybe_key, value in properties.items()
+                        if isinstance(value, dict) and value.get("Ref") == key
+                    ),
+                    None,
+                )
+                err_msg = f"unable to find parameter {key} in resource {type_name}, can happen if there are template parameters not used for {type_name}"
+                if key_found is None:
+                    logger.warning(err_msg)
+                    continue
+                key = key_found
+            param_value = param.get("ParameterValue", "")
+            assert param_value
+            properties[key] = param_value
+        return properties
+
 
 def updated_template_path(path: Path) -> Path:
     old_stem = path.stem
@@ -147,9 +196,11 @@ def decode_parameters(
     if resource_params:
         cfn_template.add_resource_params(type_name, resource_params)
         template_path = updated_template_path(template_path)
-        logger.info(f"updating template {template_path}")
+        logger.info(f"updating template {template_path} with {resource_params}")
         raw_dict = cfn_template.model_dump(by_alias=True, exclude_unset=True)
-        template_str = dump(raw_dict, format=template_path.suffix.lstrip(".") + "_pretty")
+        file_extension = template_path.suffix.lstrip(".")
+        dump_format = "pretty_json" if file_extension == "json" else file_extension
+        template_str = dump(raw_dict, format=dump_format)
         template_path.write_text(template_str)
     parameters_dict: dict[str, Any] = {}
     type_defaults = type_names_defaults.get(cfn_template.normalized_type_name(type_name), {})
@@ -178,9 +229,41 @@ def decode_parameters(
 
     if force_params:
         logger.warning(f"overiding params: {force_params} for {stack_name}")
-        parameters_dict.update(force_params)
+        parameters_dict |= force_params
     unknown_params = {key for key, value in parameters_dict.items() if value == "UNKNOWN"}
     parameters: list[ParameterTypeDef] = [
         {"ParameterKey": key, "ParameterValue": value} for key, value in parameters_dict.items()
     ]
     return template_path, parameters, unknown_params
+
+
+def dump_resource_to_file(
+    inputs_dir: Path,
+    template_path: Path,
+    type_name: str,
+    parameters: list[ParameterTypeDef],
+) -> Path:
+    cfn_template = parse_model(template_path, t=CfnTemplate)
+    properties = cfn_template.get_resource_properties(type_name, parameters)
+    clean_dir(inputs_dir, recreate=True)
+    dest_path = inputs_dir / "inputs_1_create.json"
+    dest_json = dump(properties, "pretty_json")
+    dest_path.write_text(dest_json)
+    return dest_path
+
+
+def dump_sample_file(
+    samples_dir: Path,
+    template_path: Path,
+    type_name: str,
+    parameters: list[ParameterTypeDef],
+):
+    cfn_template = parse_model(template_path, t=CfnTemplate)
+    samples_path = samples_dir / template_path.stem / "create.json"
+    create_sample_file(
+        samples_path,
+        default_log_group_name(CfnType.resource_name(type_name)),
+        cfn_template.get_resource_properties(type_name, parameters),
+        prev_resource_state={},
+    )
+    return samples_path

atlas_init/cli_cfn/example.py

@@ -0,0 +1,203 @@
+import logging
+from pathlib import Path
+from typing import Any
+
+import typer
+from pydantic import field_validator, model_validator
+from rich import prompt
+
+from atlas_init.cli_args import parse_key_values_any
+from atlas_init.cli_cfn.aws import (
+    create_stack,
+    ensure_resource_type_activated,
+    update_stack,
+)
+from atlas_init.cli_cfn.aws import delete_stack as delete_stack_aws
+from atlas_init.cli_cfn.cfn_parameter_finder import (
+    CfnTemplate,
+    check_execution_role,
+    decode_parameters,
+    dump_resource_to_file,
+    dump_sample_file,
+    infer_template_path,
+)
+from atlas_init.repos.cfn import CfnType, Operation, infer_cfn_type_name
+from atlas_init.repos.path import Repo, find_paths
+from atlas_init.settings.env_vars import AtlasInitSettings, init_settings
+
+logger = logging.getLogger(__name__)
+
+
+class CfnExampleInputs(CfnType):
+    stack_name: str
+    operation: Operation
+    example_name: str
+    resource_params: dict[str, Any] | None = None
+    stack_timeout_s: int
+    delete_stack_first: bool
+    reg_version: str = ""
+    force_deregister: bool
+    force_keep: bool
+    execution_role: str
+    export_example_to_inputs: bool
+    export_example_to_samples: bool
+    register_all_types_in_example: bool
+
+    @field_validator("resource_params", mode="before")
+    @classmethod
+    def validate_resource_params(cls, v):
+        return parse_key_values_any(v) if isinstance(v, list) else v
+
+    @model_validator(mode="after")
+    def check(self):
+        assert self.region_filter, "region is required"
+        assert self.execution_role.startswith("arn:aws:iam::"), f"invalid execution role: {self.execution_role}"
+        assert self.region
+        return self
+
+    @property
+    def is_export(self) -> bool:
+        return self.export_example_to_inputs or self.export_example_to_samples
+
+    @property
+    def region(self) -> str:
+        region = self.region_filter
+        assert isinstance(region, str), "region is required"
+        return region
+
+
+def example_cmd(
+    type_name: str = typer.Option("", "-n", "--type-name", help="inferred from your cwd if not provided"),
+    region: str = typer.Option("", help="inferred from your atlas_init cfn region if not provided"),
+    stack_name: str = typer.Option(
+        "",
+        help="inferred from your atlas_init cfn profile name and example if not provided",
+    ),
+    operation: str = typer.Argument(...),
+    example_name: str = typer.Option("", "-e", "--example-name", help="example filestem"),
+    resource_params: list[str] = typer.Option(
+        ..., "-r", "--resource-param", default_factory=list, help="key=value, can be set many times"
+    ),
+    stack_timeout_s: int = typer.Option(3600, "-t", "--stack-timeout-s"),
+    delete_first: bool = typer.Option(False, "-d", "--delete-first", help="Delete existing stack first"),
+    reg_version: str = typer.Option("", "--reg-version", help="Register a specific version"),
+    force_deregister: bool = typer.Option(False, "--dereg", help="Force deregister CFN Type"),
+    force_keep: bool = typer.Option(False, "--noreg", help="Force keep CFN Type (do not prompt)"),
+    execution_role: str = typer.Option("", "--execution-role", help="Execution role to use, otherwise inferred"),
+    export_example_to_inputs: bool = typer.Option(
+        False, "-o", "--export-example-to-inputs", help="Export example to inputs"
+    ),
+    export_example_to_samples: bool = typer.Option(
+        False, "-s", "--export-example-to-samples", help="Export example to samples"
+    ),
+    register_all_types_in_example: bool = typer.Option(False, "--reg-all", help="Check all types"),
+):
+    settings = init_settings()
+    assert settings.cfn_config, "no cfn config found, re-run atlas_init apply with CFN flags"
+    repo_path, resource_path, _ = find_paths(Repo.CFN)
+    env_vars_generated = settings.load_env_vars_generated()
+    inputs = CfnExampleInputs(
+        type_name=type_name or infer_cfn_type_name(),
+        example_name=example_name,
+        delete_stack_first=delete_first,
+        region_filter=region or settings.cfn_region,
+        stack_name=stack_name or f"{settings.cfn_profile}-{example_name or 'atlas-init'}",
+        operation=operation,  # type: ignore
+        resource_params=resource_params,  # type: ignore
+        stack_timeout_s=stack_timeout_s,
+        force_deregister=force_deregister,
+        reg_version=reg_version,
+        force_keep=force_keep,
+        execution_role=execution_role or check_execution_role(repo_path, env_vars_generated),
+        export_example_to_inputs=export_example_to_inputs,
+        export_example_to_samples=export_example_to_samples,
+        register_all_types_in_example=register_all_types_in_example,
+    )
+    example_handler(inputs, repo_path, resource_path, settings)
+
+
+def example_handler(inputs: CfnExampleInputs, repo_path: Path, resource_path: Path, settings: AtlasInitSettings):
+    logger.info(
+        f"about to {inputs.operation} stack {inputs.stack_name} for {inputs.type_name} in {inputs.region_filter} params: {inputs.resource_params}"
+    )
+    type_name = inputs.type_name
+    stack_name = inputs.stack_name
+    env_vars_generated = settings.load_env_vars_generated()
+    region = inputs.region
+    operation = inputs.operation
+    stack_timeout_s = inputs.stack_timeout_s
+    delete_first = inputs.delete_stack_first
+    force_deregister = inputs.force_deregister
+    execution_role = inputs.execution_role
+    logger.info(f"using execution role: {execution_role}")
+    if not inputs.is_export and not inputs.force_keep:
+        ensure_resource_type_activated(
+            type_name,
+            region,
+            force_deregister,
+            settings.is_interactive,
+            resource_path,
+            execution_role,
+            force_version=inputs.reg_version,
+        )
+    if not inputs.is_export and (operation == Operation.DELETE or delete_first):
+        delete_stack_aws(region, stack_name, execution_role)
+        if not delete_first:
+            return
+    template_path = infer_template_path(repo_path, type_name, stack_name, inputs.example_name)
+    template_path, parameters, not_found = decode_parameters(
+        exported_env_vars=env_vars_generated,
+        template_path=template_path,
+        stack_name=stack_name,
+        force_params=inputs.resource_params,
+        resource_params=inputs.resource_params,
+        type_name=type_name,
+    )
+    if inputs.register_all_types_in_example:
+        extra_example_types = [t for t in CfnTemplate.read_template_types(template_path) if t != type_name]
+        for extra_type in extra_example_types:
+            logger.info(f"extra type {extra_type} in example {template_path}")
+            ensure_resource_type_activated(
+                extra_type,
+                region,
+                force_deregister,
+                settings.is_interactive,
+                resource_path,
+                execution_role,
+            )
+    logger.info(f"parameters: {parameters}")
+    if not_found:
+        # TODO: support specifying these extra
+        logger.critical(f"need to fill out parameters manually: {not_found} for {type_name}")
+        raise typer.Exit(1)
+    if not prompt.Confirm("parameters 👆looks good?")():
+        raise typer.Abort
+    if inputs.export_example_to_inputs:
+        out_inputs = dump_resource_to_file(resource_path / "inputs", template_path, type_name, parameters)
+        logger.info(f"dumped to {out_inputs} ✅")
+        return
+    if inputs.export_example_to_samples:
+        samples_dir = resource_path / "samples"
+        samples_path = dump_sample_file(samples_dir, template_path, type_name, parameters)
+        logger.info(f"dumped to {samples_path} ✅")
+        return
+    if operation == Operation.CREATE:
+        create_stack(
+            stack_name,
+            template_str=template_path.read_text(),
+            region_name=region,
+            role_arn=execution_role,
+            parameters=parameters,
+            timeout_seconds=stack_timeout_s,
+        )
+    elif operation == Operation.UPDATE:
+        update_stack(
+            stack_name,
+            template_str=template_path.read_text(),
+            region_name=region,
+            parameters=parameters,
+            role_arn=execution_role,
+            timeout_seconds=stack_timeout_s,
+        )
+    else:
+        raise NotImplementedError

atlas_init/cli_cfn/files.py

@@ -0,0 +1,63 @@
+import contextlib
+import logging
+import re
+from collections.abc import Iterable
+from pathlib import Path
+
+import stringcase
+from model_lib import Entity, dump, parse_model
+from pydantic import ConfigDict, Field, ValidationError
+from zero_3rdparty import file_utils
+
+logger = logging.getLogger(__name__)
+
+
+def create_sample_file(
+    samples_file: Path,
+    log_group_name: str,
+    resource_state: dict,
+    prev_resource_state: dict | None = None,
+):
+    logger.info(f"adding sample @ {samples_file}")
+    assert isinstance(resource_state, dict)
+    new_json = dump(
+        {
+            "providerLogGroupName": log_group_name,
+            "previousResourceState": prev_resource_state or {},
+            "desiredResourceState": resource_state,
+        },
+        "pretty_json",
+    )
+    file_utils.ensure_parents_write_text(samples_file, new_json)
+
+
+CamelAlias = ConfigDict(alias_generator=stringcase.camelcase, populate_by_name=True)
+
+
+class CfnSchema(Entity):
+    model_config = CamelAlias
+
+    description: str
+    type_name: str = Field(pattern=r"^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$")
+
+
+def iterate_schemas(resource_root: Path) -> Iterable[tuple[Path, CfnSchema]]:
+    for path in resource_root.rglob("*.json"):
+        if path.parent.parent != resource_root:
+            continue
+        with contextlib.suppress(ValidationError):
+            yield path, parse_model(path, t=CfnSchema)
+
+
+_md_patterns = [
+    re.compile(r"\[[^\]]+\]\([^\)]+\)"),
+    re.compile(r"`\S+`"),
+]
+
+
+def has_md_link(text: str) -> bool:
+    return any(bool(pattern.findall(text)) for pattern in _md_patterns)
+
+
+def default_log_group_name(resource_name: str) -> str:
+    return f"mongodb-atlas-{resource_name}-logs"