diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..a4d62df --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,19 @@ +name: ci + +on: + push: + branches: [main] + pull_request: + +jobs: + lint-and-test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0 + with: + python-version: "3.12" + - run: python -m pip install --upgrade pip + - run: pip install -e . ruff pytest + - run: ruff check . + - run: pytest -q diff --git a/README.md b/README.md new file mode 100644 index 0000000..39b7cab --- /dev/null +++ b/README.md @@ -0,0 +1,123 @@ +# cloud-tagging-cli + +A CLI that checks cloud resources against a standard tagging policy and +bulk-fixes the violations it can fix safely. + +## Problem + +Teams accumulate resources tagged inconsistently across clouds and over +time: `Environment: Prod` next to `environment: production` next to nothing +at all. This tool defines one standard-tags policy, reports who's out of +line (`check`), and brings them into line (`apply`), without ever guessing +a value it can't justify. + +## Scope, honestly + +Only **AWS** has a real adapter, built on the +[Resource Groups Tagging API](https://docs.aws.amazon.com/resourcegroupstaggingapi/latest/APIReference/) +(`GetResources` / `TagResources`), which is why one adapter covers every +taggable AWS resource type instead of needing a client per service. + +**Azure and GCP are interface-only.** `AzureProvider` and `GcpProvider` +implement the same `TaggingProvider` protocol but every method raises +`NotImplementedError` immediately — they exist to show the interface is +multi-cloud by design, not to claim working support. Wiring in a real +adapter means implementing `list_resources` / `set_tags` against that +cloud's SDK; the CLI and the check/apply logic do not change. + +## How it works + +```mermaid +flowchart LR + cfg[standard_tags.yaml] --> rules[rule engine] + provider[TaggingProvider\naws / azure stub / gcp stub] -->|list_resources| rules + rules -->|violations + desired tags| check[check command] + rules -->|desired tags, dry-run by default| apply[apply command] + apply -->|--apply only| provider +``` + +For every resource, the rule engine compares its current tags against the +policy and classifies each mismatch: + +| Violation | Fixable automatically? | +|---|---| +| Required tag missing, policy has a `default` | yes — default is applied | +| Required tag missing, no `default` | no — reported, left alone | +| Tag value has wrong case (`PROD` vs `prod`) | yes — value is normalized | +| Tag value not in `allowed_values` | no — reported, left alone | + +`check` only reports. `apply` reports and, with `--apply`, writes the +fixable changes. A resource that's already correct produces no API call at +all, in either command — that's what makes repeated runs idempotent. + +## Usage + +```bash +pip install -e . + +# report non-conforming resources, exit 1 if any exist +cloud-tag check --config examples/standard_tags.yaml + +# show what would change, writes nothing +cloud-tag apply --config examples/standard_tags.yaml + +# actually write the fixable tags +cloud-tag apply --apply --config examples/standard_tags.yaml + +# azure/gcp are stubs: this raises NotImplementedError on purpose +cloud-tag check --provider azure --config examples/standard_tags.yaml +``` + +Config format (`examples/standard_tags.yaml`): + +```yaml +tags: + - key: Environment + required: true + case: lower # lower | upper | kebab | none + allowed_values: [prod, staging, dev] + - key: Owner + required: true + case: lower + default: unassigned # auto-filled when missing + - key: CostCenter + required: false + case: upper +``` + +## Limits + +- Only AWS has working code against a real API shape; Azure/GCP are stubs. +- `apply` never guesses a disallowed or missing-with-no-default value — it + reports it and exits non-zero, so a human decides. +- No batching/rate-limit backoff beyond what `TagResources` itself does in + one call per resource; fine for the scale this was built for, not for + thousands of resources per run. + +## Security + +No credentials are read, stored, or required to run or test this project. +The AWS adapter takes an already-constructed `boto3` client — real +credential handling is the caller's problem, not this tool's. If wired to +a real AWS account, the IAM principal needs at minimum: +`tag:GetResources` and `tag:TagResources` on the resources being managed. +This project has never been run against a real AWS account. + +## Idempotency + +`apply` computes a diff (`desired_tags`) between current and policy-correct +tags. When the diff is empty, no `set_tags`/`TagResources` call is made. +Running `apply --apply` twice in a row produces zero additional API calls +on the second run — covered by `test_apply_is_idempotent_on_second_run`. + +## Testing status + +Tested: rule engine (all four violation kinds, including negative cases), +config loading (valid + four malformed-config negative cases), the AWS +adapter against a hand-written fake of the boto3 client (pagination, +tagging failure handling), and the CLI end-to-end via Click's `CliRunner` +with that same fake client injected. 29 tests, all passing. + +Not tested: real AWS (no network calls anywhere in the suite), Azure/GCP +(interface-only, verified only to raise `NotImplementedError`), and +large-scale pagination/throttling behavior beyond what the fake simulates. diff --git a/examples/standard_tags.yaml b/examples/standard_tags.yaml new file mode 100644 index 0000000..f99d551 --- /dev/null +++ b/examples/standard_tags.yaml @@ -0,0 +1,15 @@ +# Standard tagging policy applied by `cloud-tag check` and `cloud-tag apply`. +tags: + - key: Environment + required: true + case: lower + allowed_values: [prod, staging, dev] + + - key: Owner + required: true + case: lower + default: unassigned + + - key: CostCenter + required: false + case: upper diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..5722d59 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,29 @@ +[project] +name = "cloud-tagging-cli" +version = "0.1.0" +description = "Multi-cloud resource tagging standardization CLI" +requires-python = ">=3.10" +dependencies = [ + "click>=8.1", + "pyyaml>=6.0", +] + +[project.scripts] +cloud-tag = "cloud_tagging_cli.cli:main" + +[build-system] +requires = ["setuptools>=68"] +build-backend = "setuptools.build_meta" + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.ruff] +line-length = 100 +target-version = "py310" + +[tool.ruff.lint] +select = ["E", "F", "I", "UP", "B"] + +[tool.pytest.ini_options] +testpaths = ["tests"] diff --git a/src/cloud_tagging_cli/__init__.py b/src/cloud_tagging_cli/__init__.py new file mode 100644 index 0000000..49250ec --- /dev/null +++ b/src/cloud_tagging_cli/__init__.py @@ -0,0 +1,3 @@ +"""Multi-cloud resource tagging standardization CLI.""" + +__version__ = "0.1.0" diff --git a/src/cloud_tagging_cli/cli.py b/src/cloud_tagging_cli/cli.py new file mode 100644 index 0000000..d505db9 --- /dev/null +++ b/src/cloud_tagging_cli/cli.py @@ -0,0 +1,100 @@ +"""Click entry point: `cloud-tag check` and `cloud-tag apply`.""" + +from __future__ import annotations + +import sys + +import click + +from cloud_tagging_cli.config import ConfigError, load_config +from cloud_tagging_cli.core import apply_resources, check_resources +from cloud_tagging_cli.provider import TaggingProvider +from cloud_tagging_cli.providers.aws import AwsTaggingProvider, build_client +from cloud_tagging_cli.providers.unsupported import AzureProvider, GcpProvider + +PROVIDER_CHOICES = ("aws", "azure", "gcp") + + +def _build_provider(name: str, region: str) -> TaggingProvider: + if name == "aws": + return AwsTaggingProvider(build_client(region)) + if name == "azure": + return AzureProvider() + if name == "gcp": + return GcpProvider() + raise click.UsageError(f"unknown provider: {name}") + + +@click.group() +def main() -> None: + """Standardize and bulk-update resource tags across clouds.""" + + +@main.command() +@click.option("--provider", "provider_name", type=click.Choice(PROVIDER_CHOICES), default="aws") +@click.option("--region", default="us-east-1", show_default=True) +@click.option("--config", "config_path", required=True, type=click.Path(exists=True)) +def check(provider_name: str, region: str, config_path: str) -> None: + """Report resources that do not conform to the standard-tags config.""" + try: + config = load_config(config_path) + except ConfigError as exc: + raise click.ClickException(str(exc)) from exc + + provider = _build_provider(provider_name, region) + reports = check_resources(provider, config) + + if not reports: + click.echo("all resources conform to the standard-tags config") + return + + for report in reports: + click.echo(f"{report.resource_id}:") + for violation in report.violations: + click.echo(f" [{violation.kind}] {violation.key}: {violation.detail}") + + click.echo(f"\n{len(reports)} non-conforming resource(s)") + sys.exit(1) + + +@main.command() +@click.option("--provider", "provider_name", type=click.Choice(PROVIDER_CHOICES), default="aws") +@click.option("--region", default="us-east-1", show_default=True) +@click.option("--config", "config_path", required=True, type=click.Path(exists=True)) +@click.option("--apply", "do_apply", is_flag=True, default=False, help="Actually write tags.") +def apply(provider_name: str, region: str, config_path: str, do_apply: bool) -> None: + """Bring resources into compliance. Dry-run unless --apply is given.""" + try: + config = load_config(config_path) + except ConfigError as exc: + raise click.ClickException(str(exc)) from exc + + provider = _build_provider(provider_name, region) + results = apply_resources(provider, config, apply=do_apply) + + mode = "applying" if do_apply else "dry-run (pass --apply to write changes)" + click.echo(f"mode: {mode}") + + changed = [r for r in results if not r.is_noop] + unfixable_total = 0 + for result in changed: + verb = "applied" if do_apply else "would apply" + click.echo(f"{result.resource_id}: {verb} {result.applied_tags}") + + for result in results: + for violation in result.unfixable: + unfixable_total += 1 + click.echo( + f"{result.resource_id}: [{violation.kind}] {violation.key}: {violation.detail}" + ) + + compliant = len(results) - len(changed) + click.echo(f"\n{len(changed)} resource(s) changed, {compliant} already compliant") + + if unfixable_total: + click.echo(f"{unfixable_total} violation(s) require manual fixing (no default configured)") + sys.exit(1) + + +if __name__ == "__main__": + main() diff --git a/src/cloud_tagging_cli/config.py b/src/cloud_tagging_cli/config.py new file mode 100644 index 0000000..f7ebb33 --- /dev/null +++ b/src/cloud_tagging_cli/config.py @@ -0,0 +1,72 @@ +"""Loading and representing the standard-tags configuration file.""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from pathlib import Path + +import yaml + +VALID_CASES = {"lower", "upper", "kebab", "none"} + + +class ConfigError(Exception): + """Raised when the standard-tags config file is malformed.""" + + +@dataclass(frozen=True) +class TagRule: + key: str + required: bool = True + case: str = "none" + allowed_values: tuple[str, ...] | None = None + default: str | None = None + + +@dataclass(frozen=True) +class StandardTagsConfig: + rules: tuple[TagRule, ...] = field(default_factory=tuple) + + def rule_for(self, key: str) -> TagRule | None: + for rule in self.rules: + if rule.key == key: + return rule + return None + + +def load_config(path: str | Path) -> StandardTagsConfig: + raw_path = Path(path) + if not raw_path.is_file(): + raise ConfigError(f"standard-tags config not found: {raw_path}") + + with raw_path.open("r", encoding="utf-8") as handle: + data = yaml.safe_load(handle) or {} + + rules_data = data.get("tags") + if not isinstance(rules_data, list) or not rules_data: + raise ConfigError("config must define a non-empty 'tags' list") + + rules: list[TagRule] = [] + for index, entry in enumerate(rules_data): + if not isinstance(entry, dict) or "key" not in entry: + raise ConfigError(f"tags[{index}] must be a mapping with a 'key'") + + case = entry.get("case", "none") + if case not in VALID_CASES: + raise ConfigError(f"tags[{index}].case '{case}' must be one of {sorted(VALID_CASES)}") + + allowed_values = entry.get("allowed_values") + if allowed_values is not None: + allowed_values = tuple(str(v) for v in allowed_values) + + rules.append( + TagRule( + key=str(entry["key"]), + required=bool(entry.get("required", True)), + case=case, + allowed_values=allowed_values, + default=entry.get("default"), + ) + ) + + return StandardTagsConfig(rules=tuple(rules)) diff --git a/src/cloud_tagging_cli/core.py b/src/cloud_tagging_cli/core.py new file mode 100644 index 0000000..9098a38 --- /dev/null +++ b/src/cloud_tagging_cli/core.py @@ -0,0 +1,65 @@ +"""Provider-agnostic check/apply logic, shared by the CLI and its tests.""" + +from __future__ import annotations + +from dataclasses import dataclass, field + +from cloud_tagging_cli.config import StandardTagsConfig +from cloud_tagging_cli.provider import TaggingProvider +from cloud_tagging_cli.rules import Violation, evaluate + + +@dataclass(frozen=True) +class ResourceReport: + resource_id: str + violations: tuple[Violation, ...] + + +def check_resources( + provider: TaggingProvider, config: StandardTagsConfig +) -> list[ResourceReport]: + """Return a report for every resource that is out of compliance.""" + reports = [] + for resource in provider.list_resources(): + plan = evaluate(resource.tags, config) + if plan.violations: + reports.append(ResourceReport(resource_id=resource.id, violations=plan.violations)) + return reports + + +@dataclass(frozen=True) +class ApplyResult: + resource_id: str + applied_tags: dict[str, str] = field(default_factory=dict) + unfixable: tuple[Violation, ...] = () + + @property + def is_noop(self) -> bool: + return not self.applied_tags + + +def apply_resources( + provider: TaggingProvider, config: StandardTagsConfig, apply: bool +) -> list[ApplyResult]: + """Compute (and optionally perform) the tag changes needed on every resource. + + When apply is False, nothing is written and applied_tags describes what + *would* be written. Resources already compliant produce a no-op result, + which is what keeps repeated runs idempotent. + """ + results = [] + for resource in provider.list_resources(): + plan = evaluate(resource.tags, config) + unfixable = tuple(v for v in plan.violations if not v.fixable) + + if plan.desired_tags and apply: + provider.set_tags(resource.id, plan.desired_tags) + + results.append( + ApplyResult( + resource_id=resource.id, + applied_tags=plan.desired_tags, + unfixable=unfixable, + ) + ) + return results diff --git a/src/cloud_tagging_cli/provider.py b/src/cloud_tagging_cli/provider.py new file mode 100644 index 0000000..31da4ee --- /dev/null +++ b/src/cloud_tagging_cli/provider.py @@ -0,0 +1,25 @@ +"""Provider-agnostic interface that every cloud adapter implements.""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Protocol + + +@dataclass(frozen=True) +class Resource: + id: str + kind: str + tags: dict[str, str] + + +class TaggingProvider(Protocol): + """Minimal contract the CLI needs from any cloud's tagging API.""" + + def list_resources(self) -> list[Resource]: + """Return every taggable resource with its current tags.""" + ... + + def set_tags(self, resource_id: str, tags: dict[str, str]) -> None: + """Merge the given key/value pairs into the resource's existing tags.""" + ... diff --git a/src/cloud_tagging_cli/providers/__init__.py b/src/cloud_tagging_cli/providers/__init__.py new file mode 100644 index 0000000..75bf900 --- /dev/null +++ b/src/cloud_tagging_cli/providers/__init__.py @@ -0,0 +1 @@ +"""Cloud provider adapters.""" diff --git a/src/cloud_tagging_cli/providers/aws.py b/src/cloud_tagging_cli/providers/aws.py new file mode 100644 index 0000000..0bf8155 --- /dev/null +++ b/src/cloud_tagging_cli/providers/aws.py @@ -0,0 +1,73 @@ +"""AWS adapter, backed by the Resource Groups Tagging API. + +This is the one real adapter in the project. It only depends on a boto3 +client object passed in by the caller (see ``build_client``), so it can be +exercised in tests against a hand-written fake with no network access and +no real AWS account. +""" + +from __future__ import annotations + +from typing import Any, Protocol + +from cloud_tagging_cli.provider import Resource + + +class TaggingApiError(Exception): + """Raised when the Resource Groups Tagging API reports a failure.""" + + +class BotoTaggingClient(Protocol): + """The subset of the boto3 resourcegroupstaggingapi client we use.""" + + def get_resources(self, **kwargs: Any) -> dict: ... + + def tag_resources(self, **kwargs: Any) -> dict: ... + + +def build_client(region: str = "us-east-1"): + """Create a real boto3 client. Only called outside of tests.""" + import boto3 + + return boto3.client("resourcegroupstaggingapi", region_name=region) + + +class AwsTaggingProvider: + """Real adapter: AWS via the Resource Groups Tagging API.""" + + def __init__(self, client: BotoTaggingClient) -> None: + self._client = client + + def list_resources(self) -> list[Resource]: + resources: list[Resource] = [] + token = None + while True: + kwargs = {"PaginationToken": token} if token else {} + page = self._client.get_resources(**kwargs) + for mapping in page.get("ResourceTagMappingList", []): + arn = mapping["ResourceARN"] + tags = {t["Key"]: t["Value"] for t in mapping.get("Tags", [])} + resources.append(Resource(id=arn, kind=_kind_from_arn(arn), tags=tags)) + token = page.get("PaginationToken") or None + if not token: + break + return resources + + def set_tags(self, resource_id: str, tags: dict[str, str]) -> None: + if not tags: + return + response = self._client.tag_resources(ResourceARNList=[resource_id], Tags=tags) + failures = response.get("FailedResourcesMap", {}) + if resource_id in failures: + error = failures[resource_id] + raise TaggingApiError( + f"failed to tag {resource_id}: " + f"{error.get('ErrorCode')} {error.get('ErrorMessage')}" + ) + + +def _kind_from_arn(arn: str) -> str: + parts = arn.split(":") + if len(parts) >= 3: + return parts[2] + return "unknown" diff --git a/src/cloud_tagging_cli/providers/unsupported.py b/src/cloud_tagging_cli/providers/unsupported.py new file mode 100644 index 0000000..845f1eb --- /dev/null +++ b/src/cloud_tagging_cli/providers/unsupported.py @@ -0,0 +1,27 @@ +"""Interface-only stubs for clouds without a real adapter yet. + +These exist to show the provider interface is multi-cloud by design, not +to claim working support. Every method raises immediately. +""" + +from __future__ import annotations + +from cloud_tagging_cli.provider import Resource + + +class UnsupportedProvider: + name = "unsupported" + + def list_resources(self) -> list[Resource]: + raise NotImplementedError(f"{self.name} provider is interface-only, not implemented") + + def set_tags(self, resource_id: str, tags: dict[str, str]) -> None: + raise NotImplementedError(f"{self.name} provider is interface-only, not implemented") + + +class AzureProvider(UnsupportedProvider): + name = "azure" + + +class GcpProvider(UnsupportedProvider): + name = "gcp" diff --git a/src/cloud_tagging_cli/rules.py b/src/cloud_tagging_cli/rules.py new file mode 100644 index 0000000..edaa3c2 --- /dev/null +++ b/src/cloud_tagging_cli/rules.py @@ -0,0 +1,104 @@ +"""Tag validation and standardization logic, independent of any provider.""" + +from __future__ import annotations + +from dataclasses import dataclass + +from cloud_tagging_cli.config import StandardTagsConfig + + +def normalize_value(value: str, case: str) -> str: + if case == "lower": + return value.lower() + if case == "upper": + return value.upper() + if case == "kebab": + return value.strip().lower().replace("_", "-").replace(" ", "-") + return value + + +@dataclass(frozen=True) +class Violation: + key: str + kind: str # "missing_required", "wrong_case", "disallowed_value" + detail: str + fixable: bool + + +@dataclass(frozen=True) +class Plan: + """Result of checking one resource's tags against the standard-tags config.""" + + violations: tuple[Violation, ...] + desired_tags: dict[str, str] # only the keys that should change + + @property + def has_unfixable_violations(self) -> bool: + return any(not v.fixable for v in self.violations) + + @property + def is_compliant(self) -> bool: + return not self.violations + + +def evaluate(current_tags: dict[str, str], config: StandardTagsConfig) -> Plan: + """Compare current_tags against every rule and compute what should change. + + Returns the violations found plus a minimal set of tag keys/values that + need to be written to bring the resource into compliance. Keys already + correct are left out of desired_tags so callers can skip no-op updates. + """ + violations: list[Violation] = [] + desired: dict[str, str] = {} + + for rule in config.rules: + current_value = current_tags.get(rule.key) + + if current_value is None: + if rule.required: + if rule.default is not None: + desired[rule.key] = normalize_value(rule.default, rule.case) + violations.append( + Violation( + key=rule.key, + kind="missing_required", + detail=f"missing, will set default '{rule.default}'", + fixable=True, + ) + ) + else: + violations.append( + Violation( + key=rule.key, + kind="missing_required", + detail="missing and no default configured", + fixable=False, + ) + ) + continue + + normalized = normalize_value(current_value, rule.case) + + if rule.allowed_values is not None and normalized not in rule.allowed_values: + violations.append( + Violation( + key=rule.key, + kind="disallowed_value", + detail=f"'{current_value}' not in {list(rule.allowed_values)}", + fixable=False, + ) + ) + continue + + if normalized != current_value: + desired[rule.key] = normalized + violations.append( + Violation( + key=rule.key, + kind="wrong_case", + detail=f"'{current_value}' should be '{normalized}'", + fixable=True, + ) + ) + + return Plan(violations=tuple(violations), desired_tags=desired) diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/fakes.py b/tests/fakes.py new file mode 100644 index 0000000..452159a --- /dev/null +++ b/tests/fakes.py @@ -0,0 +1,72 @@ +"""Hand-written fakes used across the test suite. No moto, no real SDKs.""" + +from __future__ import annotations + +from dataclasses import dataclass, field + +from cloud_tagging_cli.provider import Resource + + +@dataclass +class InMemoryProvider: + """In-memory stand-in for the TaggingProvider interface.""" + + resources: dict[str, Resource] + set_tags_calls: list[tuple[str, dict[str, str]]] = field(default_factory=list) + + def list_resources(self) -> list[Resource]: + return list(self.resources.values()) + + def set_tags(self, resource_id: str, tags: dict[str, str]) -> None: + self.set_tags_calls.append((resource_id, dict(tags))) + current = self.resources[resource_id] + merged = {**current.tags, **tags} + self.resources[resource_id] = Resource(id=current.id, kind=current.kind, tags=merged) + + +class FakeBotoTaggingClient: + """Hand-written fake of the boto3 resourcegroupstaggingapi client. + + Mirrors the shapes GetResources / TagResources return, including + pagination and a configurable per-resource failure. + """ + + def __init__( + self, + resources: dict[str, dict[str, str]], + page_size: int = 50, + fail_resource_id: str | None = None, + ) -> None: + self._resources = dict(resources) + self._page_size = page_size + self._fail_resource_id = fail_resource_id + self.tag_resources_calls: list[dict] = [] + + def get_resources(self, PaginationToken: str = "", **_: object) -> dict: + arns = sorted(self._resources) + start = int(PaginationToken) if PaginationToken else 0 + page = arns[start : start + self._page_size] + next_start = start + self._page_size + + mapping_list = [ + { + "ResourceARN": arn, + "Tags": [{"Key": k, "Value": v} for k, v in self._resources[arn].items()], + } + for arn in page + ] + + result = {"ResourceTagMappingList": mapping_list} + if next_start < len(arns): + result["PaginationToken"] = str(next_start) + return result + + def tag_resources(self, ResourceARNList: list[str], Tags: dict[str, str]) -> dict: + self.tag_resources_calls.append({"ResourceARNList": ResourceARNList, "Tags": Tags}) + failed = {} + for arn in ResourceARNList: + if arn == self._fail_resource_id: + failed[arn] = {"ErrorCode": "ThrottlingException", "ErrorMessage": "rate exceeded"} + else: + self._resources[arn] = {**self._resources.get(arn, {}), **Tags} + return {"FailedResourcesMap": failed} if failed else {} diff --git a/tests/test_aws_provider.py b/tests/test_aws_provider.py new file mode 100644 index 0000000..7ac50b7 --- /dev/null +++ b/tests/test_aws_provider.py @@ -0,0 +1,58 @@ +import pytest + +from cloud_tagging_cli.providers.aws import AwsTaggingProvider, TaggingApiError +from tests.fakes import FakeBotoTaggingClient + +ARN_1 = "arn:aws:ec2:us-east-1:123456789012:instance/i-1" +ARN_2 = "arn:aws:ec2:us-east-1:123456789012:instance/i-2" + + +def test_list_resources_parses_tags_and_kind(): + client = FakeBotoTaggingClient({ARN_1: {"Environment": "prod"}}) + provider = AwsTaggingProvider(client) + + resources = provider.list_resources() + + assert len(resources) == 1 + assert resources[0].id == ARN_1 + assert resources[0].kind == "ec2" + assert resources[0].tags == {"Environment": "prod"} + + +def test_list_resources_follows_pagination(): + client = FakeBotoTaggingClient( + {ARN_1: {"Environment": "prod"}, ARN_2: {"Environment": "dev"}}, page_size=1 + ) + provider = AwsTaggingProvider(client) + + resources = provider.list_resources() + + assert {r.id for r in resources} == {ARN_1, ARN_2} + + +def test_set_tags_calls_tag_resources_with_given_tags(): + client = FakeBotoTaggingClient({ARN_1: {}}) + provider = AwsTaggingProvider(client) + + provider.set_tags(ARN_1, {"Environment": "prod"}) + + assert client.tag_resources_calls == [ + {"ResourceARNList": [ARN_1], "Tags": {"Environment": "prod"}} + ] + + +def test_set_tags_with_no_changes_does_not_call_api(): + client = FakeBotoTaggingClient({ARN_1: {}}) + provider = AwsTaggingProvider(client) + + provider.set_tags(ARN_1, {}) + + assert client.tag_resources_calls == [] + + +def test_set_tags_raises_on_api_failure(): + client = FakeBotoTaggingClient({ARN_1: {}}, fail_resource_id=ARN_1) + provider = AwsTaggingProvider(client) + + with pytest.raises(TaggingApiError): + provider.set_tags(ARN_1, {"Environment": "prod"}) diff --git a/tests/test_cli.py b/tests/test_cli.py new file mode 100644 index 0000000..827905c --- /dev/null +++ b/tests/test_cli.py @@ -0,0 +1,92 @@ +from click.testing import CliRunner + +from cloud_tagging_cli import cli +from tests.fakes import FakeBotoTaggingClient + +ARN = "arn:aws:ec2:us-east-1:123456789012:instance/i-1" + +CONFIG_YAML = ( + "tags:\n" + " - key: Environment\n" + " required: true\n" + " case: lower\n" + " allowed_values: [prod, dev]\n" + " - key: Owner\n" + " required: true\n" + " case: lower\n" + " default: unassigned\n" +) + + +def write_config(tmp_path): + path = tmp_path / "standard_tags.yaml" + path.write_text(CONFIG_YAML) + return str(path) + + +def test_check_command_exits_nonzero_on_violations(tmp_path, monkeypatch): + client = FakeBotoTaggingClient({ARN: {"Environment": "PROD"}}) + monkeypatch.setattr(cli, "build_client", lambda region: client) + + runner = CliRunner() + result = runner.invoke(cli.main, ["check", "--config", write_config(tmp_path)]) + + assert result.exit_code == 1 + assert "wrong_case" in result.output + + +def test_check_command_exits_zero_when_compliant(tmp_path, monkeypatch): + client = FakeBotoTaggingClient({ARN: {"Environment": "prod", "Owner": "jane"}}) + monkeypatch.setattr(cli, "build_client", lambda region: client) + + runner = CliRunner() + result = runner.invoke(cli.main, ["check", "--config", write_config(tmp_path)]) + + assert result.exit_code == 0 + assert "conform" in result.output + + +def test_apply_without_flag_is_dry_run(tmp_path, monkeypatch): + client = FakeBotoTaggingClient({ARN: {"Environment": "PROD"}}) + monkeypatch.setattr(cli, "build_client", lambda region: client) + + runner = CliRunner() + result = runner.invoke(cli.main, ["apply", "--config", write_config(tmp_path)]) + + assert result.exit_code == 0 + assert "dry-run" in result.output + assert client.tag_resources_calls == [] + + +def test_apply_with_flag_writes_tags(tmp_path, monkeypatch): + client = FakeBotoTaggingClient({ARN: {"Environment": "PROD"}}) + monkeypatch.setattr(cli, "build_client", lambda region: client) + + runner = CliRunner() + result = runner.invoke(cli.main, ["apply", "--apply", "--config", write_config(tmp_path)]) + + assert result.exit_code == 0 + assert client.tag_resources_calls == [ + {"ResourceARNList": [ARN], "Tags": {"Environment": "prod", "Owner": "unassigned"}} + ] + + +def test_apply_reports_unfixable_violation_as_failure(tmp_path, monkeypatch): + client = FakeBotoTaggingClient({ARN: {"Environment": "qa", "Owner": "jane"}}) + monkeypatch.setattr(cli, "build_client", lambda region: client) + + runner = CliRunner() + result = runner.invoke(cli.main, ["apply", "--apply", "--config", write_config(tmp_path)]) + + assert result.exit_code == 1 + assert "disallowed_value" in result.output + + +def test_azure_provider_is_rejected_as_unimplemented(tmp_path, monkeypatch): + runner = CliRunner() + result = runner.invoke( + cli.main, ["check", "--provider", "azure", "--config", write_config(tmp_path)] + ) + + assert result.exit_code != 0 + assert "not implemented" in str(result.exception) or "not implemented" in result.output diff --git a/tests/test_config.py b/tests/test_config.py new file mode 100644 index 0000000..a2a015a --- /dev/null +++ b/tests/test_config.py @@ -0,0 +1,43 @@ +import pytest + +from cloud_tagging_cli.config import ConfigError, load_config + + +def test_load_valid_config(tmp_path): + path = tmp_path / "tags.yaml" + path.write_text( + "tags:\n" + " - key: Environment\n" + " required: true\n" + " case: lower\n" + " allowed_values: [prod, dev]\n" + ) + config = load_config(path) + assert len(config.rules) == 1 + assert config.rules[0].allowed_values == ("prod", "dev") + + +def test_missing_file_raises_config_error(tmp_path): + with pytest.raises(ConfigError): + load_config(tmp_path / "missing.yaml") + + +def test_missing_tags_key_raises_config_error(tmp_path): + path = tmp_path / "tags.yaml" + path.write_text("other: true\n") + with pytest.raises(ConfigError): + load_config(path) + + +def test_invalid_case_value_raises_config_error(tmp_path): + path = tmp_path / "tags.yaml" + path.write_text("tags:\n - key: Environment\n case: screaming\n") + with pytest.raises(ConfigError): + load_config(path) + + +def test_entry_without_key_raises_config_error(tmp_path): + path = tmp_path / "tags.yaml" + path.write_text("tags:\n - required: true\n") + with pytest.raises(ConfigError): + load_config(path) diff --git a/tests/test_core.py b/tests/test_core.py new file mode 100644 index 0000000..40c432f --- /dev/null +++ b/tests/test_core.py @@ -0,0 +1,70 @@ +from cloud_tagging_cli.config import StandardTagsConfig, TagRule +from cloud_tagging_cli.core import apply_resources, check_resources +from cloud_tagging_cli.provider import Resource +from tests.fakes import InMemoryProvider + +CONFIG = StandardTagsConfig( + rules=( + TagRule(key="Environment", required=True, case="lower", allowed_values=("prod", "dev")), + TagRule(key="Owner", required=True, case="lower", default="unassigned"), + ) +) + + +def make_provider(**resources: dict[str, str]) -> InMemoryProvider: + return InMemoryProvider( + resources={ + rid: Resource(id=rid, kind="instance", tags=tags) for rid, tags in resources.items() + } + ) + + +def test_check_resources_only_reports_non_conforming(): + provider = make_provider( + good={"Environment": "prod", "Owner": "jane"}, + bad={"Environment": "PROD"}, + ) + + reports = check_resources(provider, CONFIG) + + assert len(reports) == 1 + assert reports[0].resource_id == "bad" + + +def test_apply_dry_run_does_not_call_set_tags(): + provider = make_provider(bad={"Environment": "PROD"}) + + results = apply_resources(provider, CONFIG, apply=False) + + assert provider.set_tags_calls == [] + changed = [r for r in results if not r.is_noop] + assert changed[0].applied_tags == {"Environment": "prod", "Owner": "unassigned"} + + +def test_apply_writes_tags_when_apply_true(): + provider = make_provider(bad={"Environment": "PROD"}) + + apply_resources(provider, CONFIG, apply=True) + + assert provider.set_tags_calls == [("bad", {"Environment": "prod", "Owner": "unassigned"})] + assert provider.resources["bad"].tags["Environment"] == "prod" + + +def test_apply_is_idempotent_on_second_run(): + provider = make_provider(bad={"Environment": "PROD"}) + + apply_resources(provider, CONFIG, apply=True) + provider.set_tags_calls.clear() + second_results = apply_resources(provider, CONFIG, apply=True) + + assert provider.set_tags_calls == [] + assert all(r.is_noop for r in second_results) + + +def test_apply_reports_unfixable_violations_without_crashing(): + provider = make_provider(bad={"Owner": "jane"}) + + results = apply_resources(provider, CONFIG, apply=True) + + assert results[0].unfixable[0].key == "Environment" + assert provider.set_tags_calls == [] diff --git a/tests/test_rules.py b/tests/test_rules.py new file mode 100644 index 0000000..72e4f9a --- /dev/null +++ b/tests/test_rules.py @@ -0,0 +1,53 @@ +from cloud_tagging_cli.config import StandardTagsConfig, TagRule +from cloud_tagging_cli.rules import evaluate + +CONFIG = StandardTagsConfig( + rules=( + TagRule(key="Environment", required=True, case="lower", allowed_values=("prod", "dev")), + TagRule(key="Owner", required=True, case="lower", default="unassigned"), + TagRule(key="CostCenter", required=False, case="upper"), + ) +) + + +def test_fully_compliant_resource_has_no_violations(): + plan = evaluate({"Environment": "prod", "Owner": "jane"}, CONFIG) + assert plan.is_compliant + assert plan.desired_tags == {} + + +def test_missing_required_with_default_is_fixable(): + plan = evaluate({"Environment": "prod"}, CONFIG) + assert plan.desired_tags == {"Owner": "unassigned"} + violation = next(v for v in plan.violations if v.key == "Owner") + assert violation.kind == "missing_required" + assert violation.fixable + + +def test_missing_required_without_default_is_unfixable(): + plan = evaluate({"Owner": "jane"}, CONFIG) + violation = next(v for v in plan.violations if v.key == "Environment") + assert violation.kind == "missing_required" + assert not violation.fixable + assert "Environment" not in plan.desired_tags + + +def test_wrong_case_is_fixed_in_desired_tags(): + plan = evaluate({"Environment": "PROD", "Owner": "jane"}, CONFIG) + assert plan.desired_tags == {"Environment": "prod"} + violation = next(v for v in plan.violations if v.key == "Environment") + assert violation.kind == "wrong_case" + assert violation.fixable + + +def test_disallowed_value_is_unfixable_and_not_overwritten(): + plan = evaluate({"Environment": "qa", "Owner": "jane"}, CONFIG) + violation = next(v for v in plan.violations if v.key == "Environment") + assert violation.kind == "disallowed_value" + assert not violation.fixable + assert "Environment" not in plan.desired_tags + + +def test_optional_missing_tag_is_not_a_violation(): + plan = evaluate({"Environment": "prod", "Owner": "jane"}, CONFIG) + assert all(v.key != "CostCenter" for v in plan.violations) diff --git a/tests/test_unsupported_providers.py b/tests/test_unsupported_providers.py new file mode 100644 index 0000000..06128f2 --- /dev/null +++ b/tests/test_unsupported_providers.py @@ -0,0 +1,12 @@ +import pytest + +from cloud_tagging_cli.providers.unsupported import AzureProvider, GcpProvider + + +@pytest.mark.parametrize("provider_cls", [AzureProvider, GcpProvider]) +def test_stub_providers_raise_not_implemented(provider_cls): + provider = provider_cls() + with pytest.raises(NotImplementedError): + provider.list_resources() + with pytest.raises(NotImplementedError): + provider.set_tags("anything", {"k": "v"})