Patch Engine

Patch - Declarative Resource Patching

The patch package provides a JSONPath-based system for declaratively modifying Kubernetes resources. It supports both TOML and YAML patch file formats with structure-preserving modifications and variable substitution.

Scope and Status

pkg/patch is a supported, standalone library. It is not invoked by kurel build — that pipeline is closed through explicit registration (author-declared ${var} parameters plus registered component, trait, and lowering-rule handlers), not universally typed: a handler may declare a PropertySchema for an out-of-process validator to consume, but launcher’s own authored document path does not check property shape against it — see pkg/oam/validate.go and pkg/oam/property_validate.go’s scope note. No implicit patch step is planned. pkg/patch is the designated implementation for explicit, user-invoked patching (e.g. interactive patch mode), used directly by callers that want to modify Kubernetes resources outside the kurel build path.

Overview

Patches allow you to modify Kubernetes manifests without rewriting them. The system uses JSONPath expressions to target specific fields and applies changes while preserving the original YAML structure (comments, ordering, formatting).

Patch File Formats

TOML Format (.kpatch)

# Target a specific resource by kind and name
[deployment.myapp.spec]
replicas = 3

[deployment.myapp.spec.template.spec.containers.0]
image = "${app.image}:${app.tag}"
resources.requests.cpu = "200m"
resources.requests.memory = "256Mi"

# Append to a list with .-
[deployment.myapp.spec.template.spec.containers.-]
name = "sidecar"
image = "envoy:latest"

YAML Format

target:
  kind: Deployment
  name: myapp
patches:
  - path: spec.replicas
    value: 3
  - path: spec.template.spec.containers[0].image
    value: "nginx:latest"

Quick Start

import "github.com/go-kure/launcher/pkg/patch"

// Load patches from file
file, _ := os.Open("patches/customize.kpatch")
specs, err := patch.LoadPatchFile(file)

// Create patchable set with resources and patches
patchSet, err := patch.NewPatchableAppSet(resources, specs)

// Resolve targets and apply
resolved, err := patchSet.Resolve()
for _, r := range resolved {
    err := r.Apply()
}

// Write patched output
err = patchSet.WriteToFile("output.yaml")

Key Features

Variable Substitution

Patches support variable references that resolve against a parameter context:

[deployment.myapp.spec.template.spec.containers.0]
image = "${registry}/${image}:${tag}"
replicas = "${replicas}"

varCtx := &patch.VariableContext{
    Variables: map[string]interface{}{
        "registry": "docker.io",
        "image":    "myapp",
        "tag":      "v1.0.0",
        "replicas": 3,
    },
}
specs, err := patch.LoadPatchFileWithVariables(file, varCtx)

List Selectors

Target specific items in lists using selectors:

# By index
[deployment.myapp.spec.template.spec.containers.0]
image = "updated:latest"

# Append to list
[deployment.myapp.spec.template.spec.containers.-]
name = "new-container"

# By field value (name selector)
[deployment.myapp.spec.template.spec.containers.{name=myapp}]
image = "updated:latest"

Structure Preservation

When using NewPatchableAppSetWithStructure, the original YAML document structure is preserved through patching, maintaining comments, key ordering, and formatting.

Strategic Merge Patch

For broad document-level changes, strategic merge patch (SMP) deep-merges a partial YAML document into the target resource. Known Kubernetes kinds merge lists by key (e.g. containers by name); unknown kinds fall back to JSON merge patch (RFC 7386).

- target: deployment.my-app
  type: strategic
  patch:
    spec:
      template:
        spec:
          containers:
          - name: main
            resources:
              limits:
                cpu: "500m"
          - name: sidecar
            image: envoy:v1.28

// Enable kind-aware merging
lookup, _ := patch.DefaultKindLookup()
patchSet.KindLookup = lookup

// Detect conflicts before applying
resolved, reports, err := patchSet.ResolveWithConflictCheck()

SMP patches are applied before field-level patches. See DESIGN.md for full specification.

API Reference

Loading Patches

Applying Patches

Strategic Merge Patch

DetectSMPConflicts compares every patch pair exactly once (O(n²) in the number of patches targeting one resource) rather than sampling, so it stays accurate; a resource’s authored patch list is expected to stay small, which is what keeps the quadratic cost unnoticeable in practice.

Error Handling

Individual patch operation failures (op.go — replace, delete, insert, and the other per-line ops applied to a document) and patch-target resolution failures are returned as *errors.PatchError (github.com/go-kure/launcher/pkg/errors), carrying the failed operation, target path, resource name, and the underlying cause where one exists:

var pe *errors.PatchError
if errors.As(err, &pe) {
    // inspect pe.Operation, pe.Path, pe.ResourceName, pe.Reason
}

errors.As(err, &pe) also matches failures from PatchableAppSet.Resolve()’s target-lookup check and ResourceWithPatches.Apply() (both build on the same NewPatchError calls above) even where a caller in set.go wraps them again with fmt.Errorf("...: %w", err) — %w preserves the chain.

Two call paths never produce a *errors.PatchError, so errors.As(err, &pe) will not match them: direct use of ApplyStrategicMergePatch (and its applyJSONMergePatch/applyTypedSMP helpers in strategic.go), and the YAML-structure-preserving document mutation helpers (YAMLDocument.ApplyPatchesToDocument / ApplyStrategicPatchesToDocument in yaml_preserve.go, reached via PatchableAppSet.WriteToFile’s per-document apply loop, and UpdateDocumentFromResource). Those return plain wrapped errors (errors.Wrap/fmt.Errorf). Do not assume every error out of this package is a *errors.PatchError — check the call path.

Related Packages

• pkg/oam - the kurel build pipeline; independent of this package (see Scope and Status above)
• pkg/errors - structured error types, including PatchError
• kure pkg/io - YAML parsing for patch targets