fogies 0.0.0.dev10__tar.gz → 0.0.0.dev11__tar.gz

{fogies-0.0.0.dev10 → fogies-0.0.0.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fogies
-Version: 0.0.0.dev10
+Version: 0.0.0.dev11
 Summary: 
 Author: James Fogarty
 Author-email: jayfo@users.noreply.github.com

{fogies-0.0.0.dev10 → fogies-0.0.0.dev11}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "fogies"
 # Version follows semantic versioning <https://semver.org/>.
-version = "0.0.0-dev.10"
+version = "0.0.0-dev.11"
 description = ""
 authors = [
     {name = "James Fogarty",email = "jayfo@users.noreply.github.com"}

{fogies-0.0.0.dev10 → fogies-0.0.0.dev11}/src/fogies/tasks/terraform.py

@@ -26,7 +26,7 @@ def get_task_apply(
     binary_cache_path: pathlib.Path,
     module_path: pathlib.Path,
     aws_environ_factory: AwsEnvironFactory | None = None,
-    backend: BackendConfig | None = None,
+    backend_config: BackendConfig | None = None,
     backend_status_path: pathlib.Path | None = None,
     tfbackend_factory: TfbackendFactory | None = None,
     tfvars_factory: TfvarsFactory | None = None,
@@ -35,10 +35,18 @@ def get_task_apply(
     default_init_reconfigure: bool = False,
     default_apply_auto_approve: bool = False,
 ) -> Task[Callable[[Context, bool, bool, bool, bool], None]]:
-    if backend is not None and tfbackend_factory is None:
-        raise ValueError("tfbackend_factory is required when backend is set")
-    if (backend_status_path is None) != (backend is None):
-        raise ValueError("backend_status_path and backend must be provided together")
+    if backend_config is not None and tfbackend_factory is None:
+        raise ValueError("tfbackend_factory is required when backend_config is set")
+    if (backend_config is not None or tfbackend_factory is not None) and (
+        aws_environ_factory is None
+    ):
+        raise ValueError(
+            "aws_environ_factory is required when backend_config or tfbackend_factory is set"
+        )
+    if (backend_status_path is None) != (backend_config is None):
+        raise ValueError(
+            "backend_status_path and backend_config must be provided together"
+        )
 
     @task(
         name="apply",
@@ -72,11 +80,16 @@ def get_task_apply(
         )
 
         with ExitStack() as stack:
-            if aws_environ_factory is not None:
-                _ = stack.enter_context(aws_environ_factory())
+            aws_environ = (
+                stack.enter_context(aws_environ_factory())
+                if aws_environ_factory
+                else None
+            )
 
             tfbackend_path = (
-                stack.enter_context(tfbackend_factory()) if tfbackend_factory else None
+                stack.enter_context(tfbackend_factory(aws_environ))
+                if tfbackend_factory and aws_environ
+                else None
             )
             tfvars_path = (
                 stack.enter_context(tfvars_factory()) if tfvars_factory else None
@@ -87,7 +100,8 @@ def get_task_apply(
                     binary_cache_path=binary_cache_path,
                     command_params=command_params,
                     module_path=module_path,
-                    backend=backend,
+                    backend_config=backend_config,
+                    aws_environ=aws_environ,
                     backend_status_path=backend_status_path,
                     tfbackend_path=tfbackend_path,
                     tfvars_path=tfvars_path,
@@ -107,7 +121,7 @@ def get_task_destroy(
     binary_cache_path: pathlib.Path,
     module_path: pathlib.Path,
     aws_environ_factory: AwsEnvironFactory | None = None,
-    backend: BackendConfig | None = None,
+    backend_config: BackendConfig | None = None,
     backend_status_path: pathlib.Path | None = None,
     tfbackend_factory: TfbackendFactory | None = None,
     tfvars_factory: TfvarsFactory | None = None,
@@ -116,10 +130,18 @@ def get_task_destroy(
     default_init_reconfigure: bool = False,
     default_destroy_auto_approve: bool = False,
 ) -> Task[Callable[[Context, bool, bool, bool, bool], None]]:
-    if backend is not None and tfbackend_factory is None:
-        raise ValueError("tfbackend_factory is required when backend is set")
-    if (backend_status_path is None) != (backend is None):
-        raise ValueError("backend_status_path and backend must be provided together")
+    if backend_config is not None and tfbackend_factory is None:
+        raise ValueError("tfbackend_factory is required when backend_config is set")
+    if (backend_config is not None or tfbackend_factory is not None) and (
+        aws_environ_factory is None
+    ):
+        raise ValueError(
+            "aws_environ_factory is required when backend_config or tfbackend_factory is set"
+        )
+    if (backend_status_path is None) != (backend_config is None):
+        raise ValueError(
+            "backend_status_path and backend_config must be provided together"
+        )
 
     @task(
         name="destroy",
@@ -153,11 +175,16 @@ def get_task_destroy(
         )
 
         with ExitStack() as stack:
-            if aws_environ_factory is not None:
-                _ = stack.enter_context(aws_environ_factory())
+            aws_environ = (
+                stack.enter_context(aws_environ_factory())
+                if aws_environ_factory
+                else None
+            )
 
             tfbackend_path = (
-                stack.enter_context(tfbackend_factory()) if tfbackend_factory else None
+                stack.enter_context(tfbackend_factory(aws_environ))
+                if tfbackend_factory and aws_environ
+                else None
             )
             tfvars_path = (
                 stack.enter_context(tfvars_factory()) if tfvars_factory else None
@@ -168,7 +195,8 @@ def get_task_destroy(
                     binary_cache_path=binary_cache_path,
                     command_params=command_params,
                     module_path=module_path,
-                    backend=backend,
+                    backend_config=backend_config,
+                    aws_environ=aws_environ,
                     backend_status_path=backend_status_path,
                     tfbackend_path=tfbackend_path,
                     tfvars_path=tfvars_path,
@@ -188,7 +216,7 @@ def get_collection(
     binary_cache_path: pathlib.Path,
     module_path: pathlib.Path,
     aws_environ_factory: AwsEnvironFactory | None = None,
-    backend: BackendConfig | None = None,
+    backend_config: BackendConfig | None = None,
     backend_status_path: pathlib.Path | None = None,
     tfbackend_factory: TfbackendFactory | None = None,
     tfvars_factory: TfvarsFactory | None = None,
@@ -200,7 +228,7 @@ def get_collection(
             binary_cache_path=binary_cache_path,
             module_path=module_path,
             aws_environ_factory=aws_environ_factory,
-            backend=backend,
+            backend_config=backend_config,
             backend_status_path=backend_status_path,
             tfbackend_factory=tfbackend_factory,
             tfvars_factory=tfvars_factory,
@@ -211,7 +239,7 @@ def get_collection(
             binary_cache_path=binary_cache_path,
             module_path=module_path,
             aws_environ_factory=aws_environ_factory,
-            backend=backend,
+            backend_config=backend_config,
             backend_status_path=backend_status_path,
             tfbackend_factory=tfbackend_factory,
             tfvars_factory=tfvars_factory,

{fogies-0.0.0.dev10 → fogies-0.0.0.dev11}/src/fogies/terraform/backend.py

@@ -14,68 +14,94 @@ from fogies.tools.boto import s3_delete_keys
 
 
 class BackendVars(BaseModel):
-    name: str
+    backend_name: str
     region: str
-    states: list[str]
+    state_names: list[str]
     tags: dict[str, str] = {}
 
 
+# S3 limits the length of a bucket name.
+_BUCKET_NAME_MAX_LENGTH = 63
+
+
 class BackendConfig(BaseModel):
-    """Connection info for a single state within an S3 Terraform backend.
+    """Connection config for a single state within an S3 Terraform backend.
 
-    Unlike a Terraform backend module's output, this does not describe every
-    state sharing a backend bucket. It describes only the one state a
-    consumer wants to connect to.
+    The bucket name includes the AWS account ID, which is not stored in code.
+    A config is safe to create at import time; bucket_name() is given the
+    account ID (e.g. from AwsEnviron) when the bucket is actually needed. This
+    lets a tenant point at an already-applied backend without knowing about
+    any other state sharing its bucket.
     """
 
-    state: str
-    bucket_name: str
+    state_name: str
+    backend_name: str
     region: str
     key: str
 
     @staticmethod
-    def for_state(*, name: str, region: str, state: str) -> "BackendConfig":
-        """Return connection config for a state, without applying the backend module.
+    def for_state(
+        *, backend_name: str, region: str, state_name: str
+    ) -> "BackendConfig":
+        """Return config for a state, without applying the backend module.
 
-        Mirrors the bucket and key naming the backend Terraform module derives
+        Mirrors the key naming the backend Terraform module derives
         internally, so a tenant can point at an already-applied backend without
         knowing about any other state sharing its bucket.
         """
         return BackendConfig(
-            state=state,
-            bucket_name="{}-bucket-{}".format(name, region),
+            state_name=state_name,
+            backend_name=backend_name,
             region=region,
-            key="{}/terraform.tfstate".format(state),
+            key="{}/terraform.tfstate".format(state_name),
         )
 
+    def bucket_name(self, *, account_id: str) -> str:
+        """Return the name of the backend bucket in the given account.
+
+        Mirrors the bucket naming of the backend Terraform module. Raises
+        ValueError if the backend name leaves no room for the account and
+        region suffix.
+        """
+        bucket_name = "{}-{}-{}-an".format(self.backend_name, account_id, self.region)
+        if len(bucket_name) > _BUCKET_NAME_MAX_LENGTH:
+            raise ValueError(
+                "Backend name '{}' makes a bucket name longer than {} characters".format(
+                    self.backend_name,
+                    _BUCKET_NAME_MAX_LENGTH,
+                )
+            )
+        return bucket_name
+
 
 class BackendOutput(BaseModel):
+    backend_name: str
     bucket_name: str
     region: str
     state_keys: dict[str, str]
 
-    def config(self, *, state: str) -> BackendConfig:
+    def config(self, *, state_name: str) -> BackendConfig:
         """Return connection config for one of this backend's declared states.
 
-        Raises ValueError if state is not declared as part of the backend.
+        Raises ValueError if state_name is not declared as part of the backend.
         """
-        if state not in self.state_keys:
+        if state_name not in self.state_keys:
             raise ValueError(
                 "State '{}' is not declared as part of backend. Declared states: {}.".format(
-                    state,
+                    state_name,
                     ", ".join(sorted(self.state_keys)),
                 )
             )
 
         return BackendConfig(
-            state=state,
-            bucket_name=self.bucket_name,
+            state_name=state_name,
+            backend_name=self.backend_name,
             region=self.region,
-            key=self.state_keys[state],
+            key=self.state_keys[state_name],
         )
 
-    def __getitem__(self, state: str) -> BackendConfig:
-        return self.config(state=state)
+    def __getitem__(self, state_name: str) -> BackendConfig:
+        return self.config(state_name=state_name)
 
 
 def backend_delete_state_objects(*, output: BackendOutput) -> None:
@@ -111,15 +137,23 @@ def backend_delete_state_objects(*, output: BackendOutput) -> None:
     )
 
 
-def backend_state_resources(*, config: BackendConfig) -> list[object]:
+def backend_state_resources(*, config: BackendConfig, account_id: str) -> list[object]:
     """Return config's resources from the backend bucket.
 
     Returns an empty list if the state's object is absent (never applied) or
     has no resources.
     """
-    client = boto_client_s3(region=config.region)
+    return _state_resources(
+        bucket_name=config.bucket_name(account_id=account_id),
+        region=config.region,
+        key=config.key,
+    )
+
+
+def _state_resources(*, bucket_name: str, region: str, key: str) -> list[object]:
+    client = boto_client_s3(region=region)
     try:
-        response = client.get_object(Bucket=config.bucket_name, Key=config.key)
+        response = client.get_object(Bucket=bucket_name, Key=key)
     except client.exceptions.NoSuchKey:
         return []
 
@@ -134,10 +168,14 @@ def backend_states_with_resources(*, output: BackendOutput) -> dict[str, list[ob
     Empty if every declared state is empty.
     """
     states_with_resources: dict[str, list[object]] = {}
-    for state in output.state_keys:
-        resources = backend_state_resources(config=output.config(state=state))
+    for state_name in output.state_keys:
+        resources = _state_resources(
+            bucket_name=output.bucket_name,
+            region=output.region,
+            key=output.state_keys[state_name],
+        )
         if resources:
-            states_with_resources[state] = resources
+            states_with_resources[state_name] = resources
     return states_with_resources
 
 
@@ -167,8 +205,8 @@ class BackendStatus(BaseModel):
 
         status = BackendStatus.load(path=path)
         status.backend.applied = True
-        applied = status.states.get(name, BackendStatusEntry()).applied
-        status.states[name] = BackendStatusEntry(applied=True)
+        applied = status.states.get(state_name, BackendStatusEntry()).applied
+        status.states[state_name] = BackendStatusEntry(applied=True)
         status.save(path=path)
     """
 
@@ -212,10 +250,10 @@ class BackendStatus(BaseModel):
             if "states" not in doc:
                 doc["states"] = tomlkit.table(is_super_table=True)
             states_table = cast(Table, doc["states"])
-            for name, entry in self.states.items():
-                if name not in states_table:
-                    states_table[name] = tomlkit.table()
-                state_table = cast(Table, states_table[name])
+            for state_name, entry in self.states.items():
+                if state_name not in states_table:
+                    states_table[state_name] = tomlkit.table()
+                state_table = cast(Table, states_table[state_name])
                 state_table["applied"] = entry.applied
 
         with path.open("w", encoding="utf-8", newline="\n") as f:

{fogies-0.0.0.dev10 → fogies-0.0.0.dev11}/src/fogies/tools/aws_environ.py

@@ -26,6 +26,7 @@ class AwsProfile(BaseModel):
 
 class AwsEnviron(BaseModel):
     profile: str
+    account_id: str
     username: str
     aws_access_key_id: str
 
@@ -127,11 +128,11 @@ def aws_environ_from_profile(
     yielding, raising ValueError immediately rather than letting some later,
     unrelated AWS call fail confusingly. The extra round trip is minor next
     to the time lost misdiagnosing an unclear downstream error. That same
-    call's identity ARN also supplies the yielded username, so callers never
-    need a second STS call just to learn it.
+    call's identity also supplies the yielded account ID and username, so
+    callers never need a second STS call just to learn them.
 
-    Yields an :class:`AwsEnviron` describing which profile, IAM username,
-    and key ID are active.
+    Yields an :class:`AwsEnviron` describing which profile, account ID, IAM
+    username, and key ID are active.
     """
     variables: dict[str, str] = {
         "AWS_ACCESS_KEY_ID": profile.aws_access_key_id,
@@ -151,6 +152,7 @@ def aws_environ_from_profile(
         username = _username_from_iam_arn(identity["Arn"])
         yield AwsEnviron(
             profile=profile.name,
+            account_id=identity["Account"],
             username=username,
             aws_access_key_id=profile.aws_access_key_id,
         )
@@ -172,7 +174,8 @@ def aws_environ_from_config(
     config file. See aws_environ_from_profile() for credential validation
     and for raise_if_env_exists/raise_if_env_changed defaults.
 
-    Yields an :class:`AwsEnviron` describing which profile and key ID are active.
+    Yields an :class:`AwsEnviron` describing which profile, account ID, IAM
+    username, and key ID are active.
     """
     aws_profile = load_aws_profile_from_config(
         config_path=config_path, profile_name=profile_name

{fogies-0.0.0.dev10 → fogies-0.0.0.dev11}/src/fogies/tools/terraform.py

@@ -18,6 +18,7 @@ from fogies.terraform.backend import (
     BackendStatusEntry,
     backend_state_resources,
 )
+from fogies.tools.aws_environ import AwsEnviron
 from fogies.tools.command import CommandParams, command_run
 
 
@@ -93,8 +94,9 @@ TfvarsContextManager = AbstractContextManager[TfvarsPath]
 # by @contextlib.contextmanager can only be entered once, so anything that
 # might run more than once per process (e.g. an invoke task) must build its
 # own fresh instance each time instead of reusing one captured at definition
-# time.
-TfbackendFactory = Callable[[], TfbackendContextManager]
+# time. A tfbackend factory is given the AWS environment the task runs in,
+# whose account a backend's bucket name depends on.
+TfbackendFactory = Callable[[AwsEnviron], TfbackendContextManager]
 TfvarsFactory = Callable[[], TfvarsContextManager]
 
 
@@ -102,7 +104,8 @@ TfvarsFactory = Callable[[], TfvarsContextManager]
 def terraform_tfbackend(
     *,
     path: pathlib.Path,
-    backend: BackendConfig,
+    backend_config: BackendConfig,
+    aws_environ: AwsEnviron,
     delete_on_exit: bool = True,
 ) -> Generator[TfbackendPath]:
     """Write S3 backend configuration to a file and yield the path.
@@ -110,7 +113,7 @@ def terraform_tfbackend(
     The file is written as flat key/value entries, one per line, e.g.:
 
     region = "us-west-2"
-    bucket = "pyfogies-test-backend-session-bucket-us-west-2"
+    bucket = "pyfogies-test-backend-session-111122223333-us-west-2-an"
     key = "test-state-a/terraform.tfstate"
     use_lockfile = true
     """
@@ -118,9 +121,13 @@ def terraform_tfbackend(
         raise ValueError("Path '{}' must end with '.tfbackend'".format(path))
     path.parent.mkdir(parents=True, exist_ok=True)
     with path.open("w", encoding="utf-8", newline="\n") as f:
-        _ = f.write('region = "{}"\n'.format(backend.region))
-        _ = f.write('bucket = "{}"\n'.format(backend.bucket_name))
-        _ = f.write('key = "{}"\n'.format(backend.key))
+        _ = f.write('region = "{}"\n'.format(backend_config.region))
+        _ = f.write(
+            'bucket = "{}"\n'.format(
+                backend_config.bucket_name(account_id=aws_environ.account_id)
+            )
+        )
+        _ = f.write('key = "{}"\n'.format(backend_config.key))
         _ = f.write("use_lockfile = true\n")
     try:
         yield TfbackendPath(path)
@@ -358,7 +365,8 @@ def terraform(
     binary_cache_path: pathlib.Path,
     command_params: CommandParams | None = None,
     module_path: pathlib.Path | None = None,
-    backend: BackendConfig | None = None,
+    backend_config: BackendConfig | None = None,
+    aws_environ: AwsEnviron | None = None,
     backend_status_path: pathlib.Path | None = None,
     tfbackend_path: pathlib.Path | None = None,
     tfvars_path: pathlib.Path | None = None,
@@ -377,11 +385,12 @@ def terraform(
     *tfbackend_path* is optional for init and, when set, is passed as
     -backend-config=<path>.
 
-    *backend_status_path* and *backend*, when provided together, check
-    whether backend.state has any resources in the backend bucket after a
+    *backend_status_path* and *backend_config*, when provided together, check
+    whether backend_config.state_name has any resources in the backend bucket after a
     successful apply_on_entry, and again after a successful destroy_on_exit,
     recording the result in backend_status_path's backend status file. See
-    fogies.terraform.backend.
+    fogies.terraform.backend. *aws_environ* is the AWS environment of the
+    backend bucket's account, and is required when *backend_config* is set.
 
     *tfvars_path* is optional for apply. If *destroy_on_exit* is true, run
     destroy when exiting the context; requires *command_params* and
@@ -409,8 +418,12 @@ def terraform(
         raise ValueError("apply_on_entry requires command_params and module_path")
     if destroy_on_exit and (command_params is None or module_path is None):
         raise ValueError("destroy_on_exit requires command_params and module_path")
-    if (backend_status_path is None) != (backend is None):
-        raise ValueError("backend_status_path and backend must be provided together")
+    if (backend_status_path is None) != (backend_config is None):
+        raise ValueError(
+            "backend_status_path and backend_config must be provided together"
+        )
+    if backend_config is not None and aws_environ is None:
+        raise ValueError("aws_environ is required when backend_config is set")
 
     exe_name = "terraform_{}.exe".format(version.replace(".", "_"))
     exe_path = binary_cache_path / exe_name
@@ -458,10 +471,15 @@ def terraform(
                 apply_params=apply_params,
             )
             if backend_status_path is not None:
-                assert backend is not None
+                assert backend_config is not None
+                assert aws_environ is not None
                 backend_status = BackendStatus.load(path=backend_status_path)
-                backend_status.states[backend.state] = BackendStatusEntry(
-                    applied=bool(backend_state_resources(config=backend))
+                backend_status.states[backend_config.state_name] = BackendStatusEntry(
+                    applied=bool(
+                        backend_state_resources(
+                            config=backend_config, account_id=aws_environ.account_id
+                        )
+                    )
                 )
                 backend_status.save(path=backend_status_path)
 
@@ -477,10 +495,15 @@ def terraform(
                 destroy_params=destroy_params,
             )
             if backend_status_path is not None:
-                assert backend is not None
+                assert backend_config is not None
+                assert aws_environ is not None
                 backend_status = BackendStatus.load(path=backend_status_path)
-                backend_status.states[backend.state] = BackendStatusEntry(
-                    applied=bool(backend_state_resources(config=backend))
+                backend_status.states[backend_config.state_name] = BackendStatusEntry(
+                    applied=bool(
+                        backend_state_resources(
+                            config=backend_config, account_id=aws_environ.account_id
+                        )
+                    )
                 )
                 backend_status.save(path=backend_status_path)
 
@@ -493,7 +516,8 @@ def terraform_output(
     binary_cache_path: pathlib.Path,
     command_params: CommandParams,
     module_path: pathlib.Path,
-    backend: BackendConfig | None = None,
+    backend_config: BackendConfig | None = None,
+    aws_environ: AwsEnviron | None = None,
     backend_status_path: pathlib.Path | None = None,
     tfbackend_path: pathlib.Path | None = None,
     tfvars_path: pathlib.Path | None = None,
@@ -515,7 +539,8 @@ def terraform_output(
     binary_cache_path: pathlib.Path,
     command_params: CommandParams,
     module_path: pathlib.Path,
-    backend: BackendConfig | None = None,
+    backend_config: BackendConfig | None = None,
+    aws_environ: AwsEnviron | None = None,
     backend_status_path: pathlib.Path | None = None,
     tfbackend_path: pathlib.Path | None = None,
     tfvars_path: pathlib.Path | None = None,
@@ -536,7 +561,8 @@ def terraform_output(
     binary_cache_path: pathlib.Path,
     command_params: CommandParams,
     module_path: pathlib.Path,
-    backend: BackendConfig | None = None,
+    backend_config: BackendConfig | None = None,
+    aws_environ: AwsEnviron | None = None,
     backend_status_path: pathlib.Path | None = None,
     tfbackend_path: pathlib.Path | None = None,
     tfvars_path: pathlib.Path | None = None,
@@ -560,7 +586,7 @@ def terraform_output(
     None then, as the Literal[True] overload above tells callers; the assert
     below is what actually enforces that assumption at runtime.
 
-    *backend_status_path* and *backend* are passed through to terraform();
+    *backend_status_path*, *backend_config* and *aws_environ* are passed through to terraform();
     see its docstring.
     """
     with terraform(
@@ -568,7 +594,8 @@ def terraform_output(
         binary_cache_path=binary_cache_path,
         command_params=command_params,
         module_path=module_path,
-        backend=backend,
+        backend_config=backend_config,
+        aws_environ=aws_environ,
         backend_status_path=backend_status_path,
         tfbackend_path=tfbackend_path,
         tfvars_path=tfvars_path,