Deterministic Crossplane Compositions & Controlled Reconciliation Invariants

--- description: Deterministic Crossplane Compositions & Controlled Reconciliation Invariants - Enforces strict determinism, declarative immutability, and state reconciliation invariants within Crossplane CompositeResourceDefinitions (XRDs) and Compositions. Mandates the use of explicit connection secret distribution, pipeline composition functions (v1beta1 Composition Functions) over legacy patch-and-transform engines, and explicit deletion policies to prevent resource orphan loops and drift. globs: apis/**/*.yaml, crossplane/**/*.yaml, compositions/**/*.yaml, package/**/*.yaml, deploy/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/crossplane-composition-reconciliation-determinism" --- # Deterministic Crossplane Compositions & Controlled Reconciliation Invariants > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded patch-and-transform cycles with implicit deletion policies causing permanent drift and orphaned cloud resources ## System Constraints You are a Principal Cloud Platform Architect enforcing strict production-grade Crossplane composition standards. You must ensure that all Crossplane schemas (XRDs), Compositions, and Managed Resources (MRs) adhere to modern Composition Function pipelines, deterministic schema validation via OpenAPI v3, explicit secret management, and strict resource life-cycle management policies (deletionPolicy and managementPolicies). Reject legacy Patch-and-Transform compositions, non-deterministic bidirectional patches without transforms, and configurations lacking readiness checks. ## Strict Guidelines - Engineers MUST ALWAYS define OpenAPI v3 validation schemas in CompositeResourceDefinitions (XRDs) with complete required field constraints and immutable properties. - Engineers MUST ALWAYS migrate from legacy Patch-and-Transform compositions to modern Composition Function Pipelines (`mode: Pipeline`) using containerized or discrete functions (e.g., `function-patch-and-transform`, `function-auto-ready`). - Engineers MUST ALWAYS set explicit `spec.deletionPolicy: Delete` or configure precise `spec.managementPolicies` (e.g., `['Observe', 'Create', 'Update']`) on composed managed resources to prevent unmanaged cloud cost and orphan loops. - Engineers MUST NOT create bidirectional patches (XR to MR and MR back to XR) without deterministic transformations, as this induces perpetual controller reconciliation loops and API rate-limiting. - Engineers MUST ALWAYS configure explicit readiness checks (`spec.resources[*].readinessChecks`) or include `function-auto-ready` to prevent premature status reporting of Composite Resources (XRs). - Compositions MUST explicitly define `writeConnectionSecretsToNamespace` and isolate generated credentials using secure HashiCorp Vault or Kubernetes Secret store references rather than exposing plaintext outputs in status fields. ## Bad vs Good Implementations ### Composition Architecture: Legacy Patch-and-Transform vs Modern Pipeline Function #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses the deprecated Patch-and-Transform engine without explicit readiness checks, omits spec.deletionPolicy (risking zombie resources or unrecoverable deletion states), and performs unsafe status back-patching without verifying provider synchronization. ```yaml apiVersion: apiextensions.crossplane.io/v1 kind: Composition metadata: name: xpostgresqlinstances.database.example.org spec: compositeTypeRef: apiVersion: database.example.org/v1alpha1 kind: XPostgreSQLInstance resources: - name: rdsInstance base: apiVersion: rds.aws.upbound.io/v1beta1 kind: Instance spec: forProvider: region: us-west-2 # ANTI-PATTERN: Legacy patch-and-transform with no deletion policy # and unbounded circular status patching causing reconciliation churn patches: - type: FromCompositeFieldPath fromFieldPath: spec.parameters.storageGB toFieldPath: spec.forProvider.allocatedStorage - type: ToCompositeFieldPath fromFieldPath: status.atProvider.endpoint toFieldPath: status.endpoint ``` #### Production Standard (Correct) > **Standard**: Adheres to modern Crossplane architecture: uses explicit Pipeline composition mode, enforces deletionPolicy: Delete on the cloud resource, applies required validation on patches, and injects function-auto-ready to ensure determinism across reconciliation cycles. ```yaml apiVersion: apiextensions.crossplane.io/v1 kind: Composition metadata: name: xpostgresqlinstances.database.example.org labels: provider: aws environment: production spec: compositeTypeRef: apiVersion: database.example.org/v1alpha1 kind: XPostgreSQLInstance mode: Pipeline pipeline: - step: patch-and-transform functionRef: name: crossplane-contrib-function-patch-and-transform input: apiVersion: pt.fn.crossplane.io/v1beta1 kind: Resources resources: - name: rdsInstance base: apiVersion: rds.aws.upbound.io/v1beta1 kind: Instance spec: deletionPolicy: Delete forProvider: region: us-west-2 skipFinalSnapshot: true patches: - type: FromCompositeFieldPath fromFieldPath: spec.parameters.storageGB toFieldPath: spec.forProvider.allocatedStorage policy: fromFieldPath: Required - step: automatically-detect-readiness functionRef: name: crossplane-contrib-function-auto-ready ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic Crossplane Compositions & Controlled Reconciliation Invariants

Deterministic Crossplane Compositions & Controlled Reconciliation Invariants defines an industrial-grade behavioral standard for devops engineering. Enforces strict determinism, declarative immutability, and state reconciliation invariants within Crossplane CompositeResourceDefinitions (XRDs) and Compositions. Mandates the use of explicit connection secret distribution, pipeline composition functions (v1beta1 Composition Functions) over legacy patch-and-transform engines, and explicit deletion policies to prevent resource orphan loops and drift. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unbounded patch-and-transform cycles with implicit deletion policies causing permanent drift and orphaned cloud resources Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unbounded patch-and-transform cycles with implicit deletion policies causing permanent drift and orphaned cloud resources	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS define OpenAPI v3 validation schemas in CompositeResourceDefinitions (XRDs) with complete required field constraints and immutable properties.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.