Crossplane Validator

Crossplane Composition Validator

Quick Start

# From repository root — validates ALL compositions through all stages
./scripts/validate-kcl-compositions.sh

Four-Stage Validation Pipeline

Stage 1: KCL Formatting (CI Enforced)

cd infrastructure/base/crossplane/configuration/kcl/<module>
kcl fmt .
git diff --quiet . || echo "Files reformatted - review and commit"

Rules: Single-line list comprehensions only. No trailing blank lines.

Stage 2: KCL Syntax Validation

cd infrastructure/base/crossplane/configuration/kcl/<module>
kcl run . -Y settings-example.yaml

Catches syntax errors, logic errors, type mismatches, reference errors.

Stage 3: Composition Rendering

cd infrastructure/base/crossplane/configuration
crossplane render examples/<claim>.yaml <composition>.yaml functions.yaml \
  --extra-resources examples/environmentconfig.yaml > /tmp/rendered.yaml

Debug pipeline issues (v2.2):

crossplane render examples/<claim>.yaml <composition>.yaml functions.yaml \
  --include-function-results \
  --extra-resources examples/environmentconfig.yaml

Offline schema validation (v2.2):

crossplane render ... > /tmp/rendered.yaml
crossplane beta validate /tmp/rendered.yaml

Stage 4: Security & Policy Validation

Available Compositions

Critical KCL Rules

NEVER Mutate Resources (function-kcl Issue #285)

Mutating dicts after creation causes duplicate resources. function-kcl hashes resources at creation — mutation creates a second hash, producing two copies.

# WRONG - Mutation causes DUPLICATES
_deployment = {
    apiVersion = "apps/v1"
    kind = "Deployment"
    metadata.name = _name
    metadata.annotations = {}
}
if _ready:
    _deployment.metadata.annotations["krm.kcl.dev/ready"] = "True"  # MUTATION!
_items += [_deployment]

# CORRECT - Inline conditional
_deployment = {
    apiVersion = "apps/v1"
    kind = "Deployment"
    metadata = {
        name = _name
        annotations = {
            if _ready:
                "krm.kcl.dev/ready" = "True"
        }
    }
}
_items += [_deployment]

Safe: Inline conditionals, list comprehensions, ternary operators, compute-before-create. Unsafe: Post-creation field assignment (resource.field = value), nested mutation, loop mutation.

Single-Line List Comprehensions (CI Enforced)

# WRONG (CI fails)
_ready = any_true([
    c.get("type") == "Available"
    for c in conditions or []
])

# CORRECT
_ready = any_true([c.get("type") == "Available" and c.get("status") == "True" for c in conditions or []])

Rendered Output Analysis

# Count resources by kind
grep "^kind:" /tmp/rendered.yaml | sort | uniq -c

# Extract specific resource
yq 'select(.kind == "Deployment")' /tmp/rendered.yaml

# Check readiness annotations
grep -B 5 'krm.kcl.dev/ready: "True"' /tmp/rendered.yaml

# Detect duplicate resources
grep "name:" /tmp/rendered.yaml | sort | uniq -d

Native K8s Resource Readiness

Readiness checks use observed cluster state via option("params").ocds:

Static readiness (always ready): HPA, PDB, Gateway, CiliumNetworkPolicy, HelmRelease.

Troubleshooting

Success Criteria

1. kcl fmt makes no changes
2. kcl run executes without errors
3. crossplane render succeeds for all examples
4. Polaris score 85+ with no critical issues
5. kube-linter reports no errors
6. Datree passes (warnings acceptable if documented)
7. No duplicate resources in rendered output

For detailed KCL patterns and security tool recipes, see references/kcl-patterns.md.

Source: Smana/cloud-native-ref — distributed by TomeVault.