Kure patch
Module — Purpose and Design
Purpose
The patch
module provides the core abstraction layer for loading, representing, and mutating Kubernetes resources using structured patches — without templates, overlays, or DSLs.
It enables tools to declaratively define resource configurations and safe modifications using dual-format support (YAML and TOML) with Go-native data structures. Patches modify an existing base resource, with advanced structure preservation that maintains comments, formatting, and document order.
This forms the foundation for Kure’s deterministic, introspectable Kubernetes manifest generation pipeline with sophisticated intelligent path resolution and automatic type inference.
Design Principles
Dual-format declarative patching over templating:
- Support both YAML and TOML patch formats with automatic detection
- Use single-line syntax to express changes to Kubernetes objects
- Avoid logic or conditional expressions in patch files
One patch = one operation:
- Patches operate on individual fields or list items
- Operations include:
replace
,delete
,insertbefore
,insertafter
,append
Intelligent patch targeting with disambiguation:
- Automatically routes patches to matching resources using metadata and field validation
- Advanced resolution algorithms handle multiple resources with same names
- Supports
target:
override andkind.name
disambiguation - Smart target matching validates patch compatibility with resource schemas
Structure preservation and introspection:
- All paths are parsed and normalized into
PathPart
structs - YAML structure preservation maintains comments, formatting, and document order
- Path syntax is explicitly validated before application
- Comprehensive debug logging with
KURE_DEBUG=1
- All paths are parsed and normalized into
Automatic type inference and conversion:
- Intelligent conversion of string values to appropriate Go types (int, bool, etc.)
- Context-aware type inference based on Kubernetes field patterns
- Compatible with unstructured.Unstructured requirements
Graceful error handling:
- Missing patch targets generate warnings rather than failures
- Batch processing continues on individual patch failures
- Comprehensive error context for debugging
Base resource required:
- Each patch is applied on top of an existing object loaded from a file or provided programmatically
Core Types
PatchOp
: A single parsed patch line (path, value, operation, selector)PathPart
: A structured representation of a patch path segment with match typesPatchableAppSet
: Holds resources and their associated patch operations with structure preservationYAMLDocumentSet
: Advanced structure preservation for comments and formattingYAMLDocument
: Individual document with preserved structure and metadataTOMLHeader
: Parsed TOML-style header with intelligent Kubernetes path mappingVariableContext
: Context for variable substitution with values and features
Interfaces and Helpers
Resource Loading
LoadResourcesFromMultiYAML(io.Reader)
— Load 1..n Kubernetes resourcesLoadResourcesWithStructure(io.Reader)
— Load resources with structure preservation
Patch Loading
LoadPatchFile(io.Reader)
— Load patches with automatic format detectionLoadPatchFileWithVariables(io.Reader, *VariableContext)
— Load with variable substitutionLoadYAMLPatchFile(io.Reader, *VariableContext)
— Load YAML format patchesLoadTOMLPatchFile(io.Reader, *VariableContext)
— Load TOML format patches
PatchableAppSet Construction
NewPatchableAppSet([]*unstructured.Unstructured, []PatchSpec)
— Create from in-memory objectsNewPatchableAppSetWithStructure(*YAMLDocumentSet, []PatchSpec)
— Create with structure preservationLoadPatchableAppSet([]io.Reader, io.Reader)
— Create a complete working set
Path Processing and Validation
NormalizePath()
— Validate and parse patch paths before applicationParsePatchPath(string)
— Parse paths into structured PathPart componentsParseTOMLHeader(string)
— Parse TOML headers with intelligent path mapping
Type System and Variable Support
inferValueType(key, value string)
— Automatic type inference for Kubernetes compatibilitySubstituteVariables(string, *VariableContext)
— Variable substitution with ${values.key} syntax
Format Support
YAML Format
Supports expressive list modification syntax:
# Simple patch map
spec.containers[3].image: nginx:latest # replace by index
spec.containers[+name=web].image: sidecar:1 # insert after matching item
spec.containers[-]: { name: debug } # append to list
metadata.labels[delete=app]: "" # delete field
# Targeted patch list
- target: my-deployment
patch:
spec.replicas: 5
spec.template.metadata.labels.foo: bar
metadata.labels[delete=app]: ""
TOML Format (Preferred)
Intelligent header-based targeting with automatic path mapping:
# Basic resource targeting
[deployment.app]
spec.replicas: 3
metadata.labels.env: production
# Container-specific patches with semantic selectors
[deployment.app.containers.name=main]
resources.requests.cpu: 100m
resources.limits.memory: 512Mi
image.tag: "${values.version}"
# Service port configuration
[service.app.ports.name=https]
port: 443
nodePort: 30443
# Complex array operations
[deployment.app.containers.name=main.env[-]]
name: DEBUG_MODE
value: "true"
Advanced Features
Automatic Format Detection
The system automatically detects patch format based on content structure:
- TOML format: Detected by presence of
[header]
sections - YAML format: Detected by YAML structure patterns
Structure Preservation
- Maintains original YAML comments, formatting, and document order
- Preserves multi-document YAML structure with
---
separators - Updates only targeted fields while leaving surrounding structure intact
Intelligent Path Resolution
- Context-aware mapping of TOML sections to Kubernetes paths
- Different behavior based on resource type (Deployment vs Service vs Pod)
- Smart disambiguation for resources with identical names
Variable Substitution
[deployment.app.containers.name=main]
image.tag: "${values.version}"
resources.requests.cpu: "${values.cpu_request}"
debug.enabled: "${features.enable_debug}"
Automatic Type Inference
- Converts string values to appropriate Go types based on field context
- Recognizes port numbers, replica counts, timeout values automatically
- Kubernetes-compatible type conversion for unstructured objects