|
| 1 | +#!/usr/bin/env python3 |
| 2 | +"""Migration linter for backward-compatible CRD evolution (issue #1065). |
| 3 | +
|
| 4 | +Compares the CRD manifests in config/crd/ against a baseline git ref |
| 5 | +(default: origin/main) and reports changes that would break existing |
| 6 | +custom resources: |
| 7 | +
|
| 8 | + * a served API version was removed |
| 9 | + * a schema property was removed |
| 10 | + * a property changed its declared type |
| 11 | + * a previously optional field became required |
| 12 | +
|
| 13 | +Usage: |
| 14 | + scripts/crd_migration_lint.py [--against REF] [--crd-dir DIR] |
| 15 | +
|
| 16 | +Exit codes: 0 = no breaking changes, 1 = breaking changes found. |
| 17 | +""" |
| 18 | + |
| 19 | +from __future__ import annotations |
| 20 | + |
| 21 | +import argparse |
| 22 | +import subprocess |
| 23 | +import sys |
| 24 | +from pathlib import Path |
| 25 | + |
| 26 | +import yaml |
| 27 | + |
| 28 | + |
| 29 | +def _schema_of(version: dict) -> dict: |
| 30 | + return (version.get("schema") or {}).get("openAPIV3Schema") or {} |
| 31 | + |
| 32 | + |
| 33 | +def _walk_properties(schema: dict, prefix: str = "") -> dict: |
| 34 | + """Flatten an openAPIV3Schema into {dotted.path: type}.""" |
| 35 | + out = {} |
| 36 | + for name, prop in (schema.get("properties") or {}).items(): |
| 37 | + path = f"{prefix}.{name}" if prefix else name |
| 38 | + out[path] = prop.get("type", "object") |
| 39 | + if isinstance(prop, dict): |
| 40 | + out.update(_walk_properties(prop, path)) |
| 41 | + items = prop.get("items") |
| 42 | + if isinstance(items, dict): |
| 43 | + out.update(_walk_properties(items, f"{path}[]")) |
| 44 | + return out |
| 45 | + |
| 46 | + |
| 47 | +def _required_paths(schema: dict, prefix: str = "") -> set: |
| 48 | + out = set() |
| 49 | + for name in schema.get("required") or []: |
| 50 | + out.add(f"{prefix}.{name}" if prefix else name) |
| 51 | + for name, prop in (schema.get("properties") or {}).items(): |
| 52 | + if isinstance(prop, dict): |
| 53 | + path = f"{prefix}.{name}" if prefix else name |
| 54 | + out.update(_required_paths(prop, path)) |
| 55 | + return out |
| 56 | + |
| 57 | + |
| 58 | +def compare_crds(old: dict, new: dict) -> list: |
| 59 | + """Return a list of human-readable breaking changes between two CRDs.""" |
| 60 | + problems = [] |
| 61 | + name = new.get("metadata", {}).get("name", "<unknown>") |
| 62 | + old_versions = {v["name"]: v for v in old.get("spec", {}).get("versions", [])} |
| 63 | + new_versions = {v["name"]: v for v in new.get("spec", {}).get("versions", [])} |
| 64 | + |
| 65 | + for ver_name, old_ver in old_versions.items(): |
| 66 | + if old_ver.get("served") and ver_name not in new_versions: |
| 67 | + problems.append(f"{name}: served version '{ver_name}' was removed") |
| 68 | + continue |
| 69 | + if ver_name not in new_versions: |
| 70 | + continue |
| 71 | + |
| 72 | + old_schema = _schema_of(old_ver) |
| 73 | + new_schema = _schema_of(new_versions[ver_name]) |
| 74 | + old_props = _walk_properties(old_schema) |
| 75 | + new_props = _walk_properties(new_schema) |
| 76 | + |
| 77 | + for path, old_type in old_props.items(): |
| 78 | + if path not in new_props: |
| 79 | + problems.append( |
| 80 | + f"{name}/{ver_name}: property '{path}' was removed" |
| 81 | + ) |
| 82 | + elif new_props[path] != old_type: |
| 83 | + problems.append( |
| 84 | + f"{name}/{ver_name}: property '{path}' changed type " |
| 85 | + f"'{old_type}' -> '{new_props[path]}'" |
| 86 | + ) |
| 87 | + |
| 88 | + newly_required = _required_paths(new_schema) - _required_paths(old_schema) |
| 89 | + for path in sorted(newly_required): |
| 90 | + if path in old_props: |
| 91 | + problems.append( |
| 92 | + f"{name}/{ver_name}: existing field '{path}' became required" |
| 93 | + ) |
| 94 | + return problems |
| 95 | + |
| 96 | + |
| 97 | +def _first_crd_doc(text: str): |
| 98 | + """Return the first CustomResourceDefinition document in a YAML stream.""" |
| 99 | + for doc in yaml.safe_load_all(text): |
| 100 | + if isinstance(doc, dict) and doc.get("kind") == "CustomResourceDefinition": |
| 101 | + return doc |
| 102 | + return None |
| 103 | + |
| 104 | + |
| 105 | +def _load_at_ref(ref: str, rel_path: str, repo_root: Path): |
| 106 | + proc = subprocess.run( |
| 107 | + ["git", "show", f"{ref}:{rel_path}"], |
| 108 | + capture_output=True, |
| 109 | + text=True, |
| 110 | + cwd=repo_root, |
| 111 | + ) |
| 112 | + if proc.returncode != 0: |
| 113 | + return None # file did not exist at the baseline ref -> new CRD, skip |
| 114 | + return _first_crd_doc(proc.stdout) |
| 115 | + |
| 116 | + |
| 117 | +def main() -> int: |
| 118 | + parser = argparse.ArgumentParser(description=__doc__) |
| 119 | + parser.add_argument("--against", default="origin/main", help="baseline git ref") |
| 120 | + parser.add_argument("--crd-dir", default="config/crd", help="CRD manifest directory") |
| 121 | + args = parser.parse_args() |
| 122 | + |
| 123 | + repo_root = Path(__file__).resolve().parent.parent |
| 124 | + crd_dir = repo_root / args.crd_dir |
| 125 | + if not crd_dir.is_dir(): |
| 126 | + print(f"error: CRD directory not found: {crd_dir}", file=sys.stderr) |
| 127 | + return 1 |
| 128 | + |
| 129 | + all_problems = [] |
| 130 | + for crd_file in sorted(crd_dir.glob("*.yaml")): |
| 131 | + rel = crd_file.relative_to(repo_root).as_posix() |
| 132 | + old = _load_at_ref(args.against, rel, repo_root) |
| 133 | + if old is None: |
| 134 | + print(f"skip (new or non-CRD file at baseline): {rel}") |
| 135 | + continue |
| 136 | + new = _first_crd_doc(crd_file.read_text()) |
| 137 | + if new is None: |
| 138 | + all_problems.append(f"{rel}: CRD document was removed from the file") |
| 139 | + print(f"FAIL: {rel}") |
| 140 | + continue |
| 141 | + problems = compare_crds(old, new) |
| 142 | + all_problems.extend(problems) |
| 143 | + status = "FAIL" if problems else "ok" |
| 144 | + print(f"{status}: {rel}") |
| 145 | + |
| 146 | + if all_problems: |
| 147 | + print("\nBackward-incompatible CRD changes detected:", file=sys.stderr) |
| 148 | + for p in all_problems: |
| 149 | + print(f" - {p}", file=sys.stderr) |
| 150 | + return 1 |
| 151 | + print("\nAll CRDs are backward compatible with", args.against) |
| 152 | + return 0 |
| 153 | + |
| 154 | + |
| 155 | +if __name__ == "__main__": |
| 156 | + sys.exit(main()) |
0 commit comments