Apply Type

This document describes the design of the apply resource type for composing manifests from smaller reusable manifests.

Overview

The apply resource resolves and executes a child manifest within the parent manifest’s execution context. The child manifest shares the parent’s manager and session, allowing resource ordering and subscribe relationships across manifest boundaries.

Key behaviors:

• Noop strengthening: A parent in noop mode forces all children into noop mode, regardless of the child’s noop property
• Health check strengthening: Same semantics as noop; health check mode can only be strengthened, never weakened
• Recursion depth limiting: Nested apply resources are capped at a configurable maximum depth (default 10) to prevent infinite loops
• Transitive trust control: The allow_apply property prevents a child manifest from containing its own apply resources

Provider Interface

Apply providers must implement the ApplyProvider interface:

type ApplyProvider interface {
    model.Provider

    ApplyManifest(ctx context.Context, mgr model.Manager, properties *model.ApplyResourceProperties, currentDepth int, healthCheckOnly bool, log model.Logger) (*model.ApplyState, error)
}

Method Responsibilities

State Response

The ApplyManifest method returns an ApplyState containing:

type ApplyState struct {
    CommonResourceState
    ResourceCount int // Number of resources in the child manifest
}

Available Providers

Ensure States

Only present is valid. The ensure property defaults to present if not specified.

Properties

Apply Logic

┌─────────────────────────────────────────┐
│ Save parent state (noop, data, wd)      │
│ (restored via defer on all paths)       │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Strengthen noop and health_check_only   │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Resolve child manifest                  │
│ (applies data overrides, sets wd)       │
└─────────────────┬───────────────────────┘
                  │
                  ▼
    ┌─────────────┴─────────────┐
    │ Recursion depth within    │
    │ limit?                    │
    └─────────────┬─────────────┘
              Yes │         No
                  │         │
                  ▼         ▼
    ┌─────────────┴───┐ ┌───────┐
    │ allow_apply     │ │ Error │
    │ satisfied?      │ └───────┘
    └─────────────┬───┘
              Yes │         No
                  │         │
                  ▼         ▼
    ┌─────────────┴───┐ ┌───────┐
    │ Execute child   │ │ Error │
    │ resources       │ └───────┘
    └─────────┬───────┘
              │
              ▼
┌─────────────────────────────────────────┐
│ Report resource count, changed, failed  │
└─────────────────────────────────────────┘

Noop Strengthening

Noop mode follows a strict strengthening rule: a child manifest can run in noop mode when the parent does not, but a child can never weaken noop mode.

Health check mode follows the same strengthening pattern.

State Save and Restore

The provider saves three pieces of manager state before manifest resolution and restores them after execution:

State is saved before calling any resolve functions because ResolveManifestUrl mutates the manager’s working directory and data during resolution.

Recursion Depth Limiting

Nested apply resources increment a depth counter passed through Execute() options. The default maximum depth is 10.

parent.yaml (depth 0)
  +-- child.yaml (depth 1)
        +-- grandchild.yaml (depth 2)
              +-- ... (up to depth 10)

Exceeding the maximum depth returns an error before iterating any child resources.

Transitive Trust

The allow_apply property controls whether a child manifest may contain its own apply resources. When allow_apply is false, the child manifest is scanned for apply resources after resolution but before execution. If any are found, an error is returned.

This provides a mechanism to limit the trust boundary when including manifests authored by others.

Data Handling

The data property provides key-value data to the child manifest. This data is passed through the WithOverridingResolvedData option and merged into the resolved data after the child manifest’s own data resolution.

External data (CLI overrides) always persists through the merge. The parent’s original data is restored after child execution via the state save/restore mechanism.

Subscribe Behavior

Apply resources support the standard subscribe property. Subscribe targets use the apply#name format:

- apply:
    - child.yaml:

- exec:
    - post-apply:
        command: /usr/local/bin/notify.sh
        refresh_only: true
        subscribe:
          - apply#child.yaml

Child Manifest Failures

After child manifest execution, the provider inspects the result to determine the outcome: