[johnsca]

ENG-8760

what

Raises the declared Terraform floor to a version the module can actually plan on, moves the CI pin to the current release, adds a job that validates at whatever floor is declared, and adds a docs job to keep the generated README tables honest. The lint job also gains a token for zizmor. The docs job reads .terraform-docs.yml, which the action ignores by default, and the config file is renamed from .terraform-docs.yaml so all five repos spell it the same way.

why

The ticket is about a sibling that declared a floor it could not run on. This module turned out to have the same problem, which the ticket did not predict.

The declared 1.9 was defensible on paper, since two variable validations reach outside their own variable and that needs 1.9. What nobody had checked is whether the module plans there. It does not. The blank-topic guards added in ENG-8756 read x == null || trimspace(x) != "", and Terraform did not short-circuit || until 1.12, so below that it evaluated trimspace(null) and failed the plan outright. Both topic arguments default to null, so this hit every consumer on 1.9 through 1.11 who did not attach an existing topic.

Rewriting the guards as conditionals would have fixed it in place. Raising the floor is the better trade, because 1.13 and below no longer receive security fixes and there is no reason to keep supporting them. The floor lands at 1.14, the CI pin moves to 1.16.5, and the guards stay as written.

That bug is also worth knowing about when reading the new job. terraform validate against a module directory treats every variable as unknown, so it never evaluates a validation block, and it reported this module as fine on 1.9. Only a plan from a root module, with the defaults actually applied, exposed it. The job therefore covers syntax and provider schema at the floor, not variable validation. Closing that gap with terraform test and mock_provider is worth a follow-up.

The docs job is unrelated to floors but adjacent. This repo generates its README tables and had nothing checking they stayed current, which is precisely the state a sibling was already in, with its tables claiming the module had no requirements at all.

The job itself lives in stacklet/github-tooling, because five module repositories need the same check and it carries enough shell to be worth one copy rather than five. This PR references that action by commit SHA, naming the commit on github-tooling's main.

testing

• Sandbox deploy. Planned from a root module against the sandbox Azure subscription with a service principal, at the declared floor of 1.14.0 and again at 1.16.4. Both produce the same 34 resources, and no resource, variable or output changed. The plan running at all is the thing to watch, since this is the change that decides whether the module evaluates on a given CLI.
• The old floor disproved rather than assumed. The module fails on 1.9.0, 1.10.5, 1.11.0 and 1.11.4, and passes from 1.12.0 up, which matches where Terraform started short-circuiting ||.
• The README confirmed already identical to freshly generated output, so the new docs job passes on arrival rather than going red.
• The extraction checked against a module carrying three constraints at once, one of them in a .tf.json and one split across lines. It returns all three, and Terraform's own init agrees on which one binds. The action it replaces returns an empty string for that module.
• The docs job confirmed to load .terraform-docs.yml, which it was silently ignoring.
• just lint clean at the new pin, and zizmor re-run with a token to confirm its five online audits schedule rather than skip. The prek release that job installs now comes from .tool-versions rather than being resolved at run time, so CI and a local run agree on it.
• Repointed the uses: pin at 3865043, the commit github-tooling's main carries now that feat: add the validate-min-terraform action (ENG-8760) github-tooling#1 merged. The action resolves there, so this job runs for the first time on this PR.
• Refreshed the pinned tools and re-ran just lint at them: terraform 1.16.5, tflint 0.64.0, just 1.58.0, uv 0.12.23. terraform-docs stays at 0.20.0, the version terraform-docs/gh-actions v1.4.1 bundles, so the docs job and just docs keep rendering with the same binary. The plans above ran at 1.16.4, the pin at the time.

docs

No documentation change beyond the generated Requirements table. The new job enforces the existing generated output rather than altering it.

[johnsca]

@cubic-dev-ai please review this PR.

Filed by Claude on Cory's behalf.

[cubic-dev-ai]

@cubic-dev-ai please review this PR.

Filed by Claude on Cory's behalf.

@johnsca I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

All reported issues were addressed across 4 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[johnsca]

@cubic-dev-ai please review this PR.

Filed by Claude on Cory's behalf.

[cubic-dev-ai]

@cubic-dev-ai please review this PR.

Filed by Claude on Cory's behalf.

@johnsca I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 6 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant GH as GitHub Actions CI
    participant Lint as Lint Job (pre-commit)
    participant LintDocs as Lint Docs Job
    participant MinTF as Validate Min Terraform Job
    participant TD as terraform-docs container
    participant TF as Terraform CLI
    participant Module as Terraform Module
    participant Zizmor as zizmor

    Note over GH,Module: CI pipeline with new validation jobs

    GH->>Lint: Run pre-commit checks
    Lint->>Lint: Run pre-commit hooks
    
    alt With GH_TOKEN set
        Lint->>Zizmor: Run zizmor audits
        Note over Zizmor: Online audits now schedule with token
        Zizmor-->>Lint: Audit results
    end

    GH->>LintDocs: Check documentation freshness
    LintDocs->>LintDocs: Checkout repo (persist-credentials: false)
    LintDocs->>TD: Run terraform-docs with config-file: .terraform-docs.yml
    Note over TD: Action fails without this - defaults differ from just docs
    TD->>Module: Parse module config
    Module-->>TD: Extract requirements
    TD-->>LintDocs: Generated README
    LintDocs->>LintDocs: Compare generated vs committed README
    alt Diff found
        LintDocs-->>GH: Fail - README out of date
    end

    GH->>MinTF: Validate at declared floor
    MinTF->>MinTF: Checkout repo (persist-credentials: false)
    MinTF->>TD: docker run terraform-docs json . --output-file ''
    TD-->>MinTF: JSON with requirements
    MinTF->>MinTF: Extract required_version constraints
    alt No constraints found
        MinTF-->>GH: Fail - no required_version declared
    else Multiple constraints
        MinTF->>MinTF: Find highest lower bound >= or ~>
        Note over MinTF: Effective floor = max of all bounds
    end
    
    MinTF->>TF: Setup Terraform at floor version
    TF->>Module: terraform init -backend=false
    Module-->>TF: Init complete
    TF->>Module: terraform validate
    Module-->>TF: Validation result
    TF-->>MinTF: Result (syntax + provider schema)
    MinTF-->>GH: Job result

    Note over Module: Validation at CLI version
    alt Below 1.12
        Module-->>TF: Fail - no short-circuit || for null checks
    else 1.12 - 1.13 (unsupported)
        Module-->>TF: Pass but no security fixes
    else >= 1.14 (declared floor)
        Module-->>TF: Pass with supported version
    end

Loading

_{Re-trigger cubic}

[johnsca]

@cubic-dev-ai please review this PR.

Filed by Claude on Cory's behalf.

[cubic-dev-ai]

@cubic-dev-ai please review this PR.

Filed by Claude on Cory's behalf.

@johnsca I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 6 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant DV as Terraform Module<br/>(required_version: >= 1.14.0, < 2.0.0)
    participant TFCore as Terraform Core<br/>(CLI: 1.16.4 CI pin)
    participant Vars as Variables<br/>(cross-variable validation)
    participant Guard as Validation Guards<br/>(null || trimspace check)
    participant Plan as Terraform Plan<br/>(root module with defaults)
    participant CI as GitHub Actions CI
    participant TFDocs as terraform-docs<br/>(.terraform-docs.yml)
    participant Config as .terraform-docs.yml<br/>(config file)
    participant GH as GitHub<br/>(token for zizmor)

    Note over DV,TFCore: Terraform Floor Enforcement

    CI->>TFCore: CHANGED: Validate at pinned 1.16.4 (lint job)
    CI->>TFCore: NEW: Validate at declared floor 1.14.0<br/>(validate-min-terraform action)
    TFCore->>DV: Load module (required_version check)
    DV-->>TFCore: Constraint >= 1.14.0, < 2.0.0

    alt CLI version >= 1.14.0
        TFCore->>Vars: Evaluate variable defaults<br/>(null topic args)
        Vars->>Guard: Check x == null || trimspace(x) != ""
        Note over Guard: NEW: Requires Terraform >= 1.12<br/>(short-circuits || to avoid trimspace(null))
        alt Guard passes
            Guard-->>TFCore: Valid conditions
            TFCore->>Plan: Generate plan (34 resources)
            Plan-->>CI: Plan output
        else Guard fails (old Terraform < 1.12)
            Guard-->>TFCore: CHANGED: trimspace(null) error<br/>(previously unfixed below 1.12)
            TFCore-->>CI: Plan failure (older versions)
        end
    else CLI version < 1.14.0 (unsupported)
        TFCore-->>CI: CHANGED: Module rejects CLI<br/>(raised floor from 1.9 to 1.14)
    end

    Note over TFDocs,Config: Documentation Validation

    CI->>Config: CHANGED: Read config file explicitly
    Config-->>TFDocs: Configuration (.terraform-docs.yml)
    CI->>TFDocs: NEW: Check docs match (fail-on-diff)
    TFDocs->>DV: Generate README requirement tables
    DV-->>TFDocs: Generated output
    alt Docs current
        TFDocs-->>CI: Pass (no diff)
    else Docs stale
        TFDocs-->>CI: FAIL (tables out of date)
    end

    Note over CI,GH: Lint Token

    CI->>GH: CHANGED: Supply GH_TOKEN (zizmor online audits)
    GH-->>CI: Token accepted (5 online audits run)

Loading

_{Re-trigger cubic}

[cubic-dev-ai]

No issues found across 6 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant CI as GitHub Actions CI
    participant Lint as Lint Job
    participant Docs as Docs Job
    participant Valid as Validate-min-Terraform Job
    participant Tooling as stacklet/github-tooling Action
    participant Terraform as Terraform CLI
    participant Module as Terraform Module
    participant README as README.md

    Note over Dev,README: CI Pipeline for Terraform Module

    Dev->>CI: Push to repo
    CI->>CI: Trigger workflow

    CI->>Lint: Run lint job
    Lint->>Lint: Run pre-commit checks
    Note over Lint: Includes zizmor with GH_TOKEN<br/>for supply-chain audits

    CI->>Docs: Run docs job (new)
    Docs->>README: Check documentation
    Note over Docs: Uses .terraform-docs.yml config
    Docs->>Docs: fail-on-diff: true
    alt README out of date
        Docs-->>CI: Fail CI
    else README matches
        Docs-->>CI: Pass
    end

    CI->>Valid: Run validate-min-terraform job (new)
    Valid->>Tooling: Invoke validate-min-terraform action
    Tooling->>Tooling: Extract required_version from provider.tf
    Tooling->>Terraform: Install Terraform at floor version (>= 1.14.0)
    Terraform->>Module: terraform validate
    Note over Terraform,Module: Validates syntax and provider schema<br/>at declared floor, not variable validation
    Module-->>Terraform: Validation result
    Terraform-->>Tooling: Exit code
    Tooling-->>Valid: Pass/fail

    Note over Terraform,Module: Floor version 1.14.0 -<br/>1.13 and earlier no security fixes

Loading

_{Re-trigger cubic}

[jtroup]

Comments aren't blocking. Thanks @johnsca