Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -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
123 changes: 123 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
15 changes: 15 additions & 0 deletions examples/standard_tags.yaml
Original file line number Diff line number Diff line change
@@ -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
29 changes: 29 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"]
3 changes: 3 additions & 0 deletions src/cloud_tagging_cli/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
"""Multi-cloud resource tagging standardization CLI."""

__version__ = "0.1.0"
100 changes: 100 additions & 0 deletions src/cloud_tagging_cli/cli.py
Original file line number Diff line number Diff line change
@@ -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()
72 changes: 72 additions & 0 deletions src/cloud_tagging_cli/config.py
Original file line number Diff line number Diff line change
@@ -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))
Loading
Loading