fix(terraform)!: prevent unintended replacements during AIO upgrades

[Katrien De Graeve (katriendg)]

Description

Prevent deferred Arc cluster lookups from causing unintended replacement cascades during Azure IoT Operations (AIO) upgrades, and keep existing Linux VM bootstrap payloads unchanged during routine reconciliation. Also correct storage-account provider compatibility and update the Bicep schema-registry API version.

Bootstrap content becomes create-only: later script and template-input changes require explicitly reviewed maintenance instead of automatically updating deployed secrets or rerunning VM setup.

Related Issue

Closes #883.

This implements the source safeguards and bootstrap maintenance documentation.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Blueprint modification or addition
• Component modification or addition
• Documentation update
• CI/CD pipeline change
• Other (please describe):

Implementation Details

• Derive Arc cluster ID and name from configuration, retain live location and optional properties, and preserve lookup ordering. Explicit dependencies keep the four Arc RBAC assignments waiting for the cluster lookup.
• Ignore changes only to K3s script-secret value and content_type, and Linux VM extension protected_settings. Other attributes remain managed; deletion or identity changes can still destroy or replace resources.
• Document coordinated plaintext-to-compressed secret and loader migration before rerunning setup, rebuilding VMs, or adding nodes. The VM extension safeguard does not cover Arc-machine or SSH script delivery.
• Use public_network_access_enabled to preserve the Boolean input behavior with AzureRM 5.3.0 and 5.9.0. Provider constraints remain unchanged.
• Change the Bicep schema-registry API from 2024-09-01-preview to 2026-04-01 and regenerate its resource reference.

No cluster setup scripts, extension version pins, or deployment-specific dataflow graph inputs are changed by this commit.

Testing Performed

• Terraform plan/apply
• Blueprint deployment test
• Unit tests
• Integration tests
• Bug fix includes regression test (see Test Policy)
• Manual validation
• Other: Terraform validation, lint, formatting, documentation generation, and committed patch hygiene

Evidence collected during implementation:

• Terraform Build completed lint/format, validation, and documentation generation across 67 component and blueprint roots, including roots using AzureRM 5.3.0.
• The full-multi-node blueprint validated with AzureRM 5.9.0.
• Bicep documentation generation completed successfully.

The plan evidence is not a fresh-deployment or Kubernetes workload-health test. No regression tests were added. Hosted CI and first-deployment ordering verification remain pending.

Validation Steps

1. Run formatting, lint, and validation checks for the changed Terraform components, and compile the changed Bicep module.
2. Back up state for a representative existing VM-based deployment and review a full plan. Confirm no replacements arise solely from deferred cluster identity and no bootstrap secret or VM payload updates are scheduled.
3. Review genuine configuration changes separately. Refresh-only reconciliation does not guarantee a no-op normal plan, and Container Storage version changes require their own reviewed upgrade procedure.
4. Verify a fresh deployment preserves cluster lookup and RBAC ordering, and exercise the optional-cluster output path.
5. Review secret-format and loader compatibility before intentionally rerunning setup or adding/rebuilding nodes; require hosted CI before merging.

Checklist

• I have updated the documentation accordingly
• I have added tests to cover my changes
• All new and existing tests passed
• I have run terraform fmt on all Terraform code
• I have run terraform validate on all Terraform code
• I have run az bicep format on all Bicep code
• I have run az bicep build to validate all Bicep code
• I have checked for any sensitive data/tokens that should not be committed
• Lint checks pass (run applicable linters for changed file types)

Security Review

• No credentials, secrets, or tokens are hardcoded or logged
• RBAC and identity changes follow least-privilege principles
• No new network exposure or public endpoints introduced without justification
• Dependency additions or updates have been reviewed for known vulnerabilities
• Container image changes use pinned digests or SHA references

Additional Notes

The storage Boolean argument is deprecated toward AzureRM v6; this change retains compatibility within the existing v5 constraint rather than upgrading the provider.

Bootstrap fixes, including changes to in-cluster administrator bindings, will no longer propagate automatically through the ignored payload fields. Maintainers must plan explicit maintenance for existing deployments.

Screenshots (if applicable)

Not applicable: infrastructure and documentation changes only.

[github-actions]

📚 Documentation Health Report

Generated on: 2026-10-14 11:39:06 UTC

📈 Documentation Statistics

Category	File Count
Main Documentation	224
Infrastructure Components	238
Blueprints	40
GitHub Resources	26
AI Assistant Guides (Copilot)	17
Total	545

🏗️ Three-Tree Architecture Status

• ✅ Bicep Documentation Tree: Auto-generated navigation
• ✅ Terraform Documentation Tree: Auto-generated navigation
• ✅ README Documentation Tree: Manual README organization

🔍 Quality Metrics

• Frontmatter Validation:
  success
• Link Validation: success

---

This report is automatically generated by the Documentation Automation workflow.