engine

Documentation

Overview

Package engine provides the core YAML stream pipeline for k8q.

It wraps kustomize/kyaml's kio package to provide a simple Pipeline function that reads YAML from stdin, applies filter functions, and writes the result to stdout. Comments, formatting, and field ordering are preserved by using kyaml's AST-based representation throughout.

Index

• Variables
• func EnvMapFromBytes(data []byte) map[string]string
• func Match(meta yaml.ResourceMeta, opts MatchOptions) bool
• func ParseSelectorFlag(s string) (labels.Selector, error)
• func Pipeline(in io.Reader, out io.Writer, filters ...kio.Filter) error
• func ReadNodes(in io.Reader) ([]*yaml.RNode, error)
• func WriteJSONList(out io.Writer, nodes []*yaml.RNode) error
• func WriteNodes(out io.Writer, nodes []*yaml.RNode) error
• type AnnotateOptions
• type CountOptions
• type CountResult
  • func CountJSON(nodes []*yaml.RNode, opts CountOptions) (*CountResult, error)
• type DropOptions
  • func (o DropOptions) Validate() error
• type Filter
  • func AnnotateFilter(opts AnnotateOptions) (Filter, error)
  • func CountFilter(opts CountOptions) Filter
  • func DropFilter(opts DropOptions) Filter
  • func GetFilter(opts GetOptions) (Filter, error)
  • func LabelFilter(opts LabelOptions) (Filter, error)
  • func PatchFilter(opts PatchOptions) (Filter, error)
  • func RemoveFilter(opts RemoveOptions) Filter
  • func RenameFilter(opts RenameOptions) Filter
  • func ScaleFilter(opts ScaleOptions) Filter
  • func ScopedMutator(opts MatchOptions, mutateFn func(*yaml.RNode) error) Filter
  • func SelectorFilter(sel labels.Selector) Filter
  • func SetImageFilter(opts SetImageOptions) (Filter, error)
  • func SetNamespaceFilter(opts NamespaceOptions) Filter
  • func SumFilter(opts SumOptions) Filter
• type GetOptions
• type JSONListEnvelope
• type LabelOptions
• type MatchMode
• type MatchOptions
• type NamespaceOptions
• type PatchOptions
• type RemoveOptions
• type RenameOptions
• type ResourceTotals
• type ScaleOptions
• type SetImageOptions
• type SumAssertions
  • func (a *SumAssertions) HasAny() bool
• type SumOptions
• type SumResult
  • func SumJSON(nodes []*yaml.RNode, opts SumOptions) (*SumResult, error)

Variables

var CommonKinds = []string{
	"ConfigMap",
	"Secret",
	"Service",
	"Deployment",
	"StatefulSet",
	"DaemonSet",
	"Job",
	"CronJob",
	"Pod",
	"Namespace",
	"Ingress",
	"PersistentVolume",
	"PersistentVolumeClaim",
	"StorageClass",
	"CustomResourceDefinition",
	"Role",
	"RoleBinding",
	"ClusterRole",
	"ClusterRoleBinding",
	"ServiceAccount",
}

CommonKinds is a list of popular Kubernetes resource kinds for shell completion.

Functions

func EnvMapFromBytes

func EnvMapFromBytes(data []byte) map[string]string

EnvMapFromBytes parses KEY=VALUE lines from an env file. Empty lines and lines starting with '#' are skipped. Lines without '=' are also skipped.

func Match

func Match(meta yaml.ResourceMeta, opts MatchOptions) bool

Match returns true if the given resource metadata matches the criteria according to the specified Mode.

func ParseSelectorFlag

func ParseSelectorFlag(s string) (labels.Selector, error)

ParseSelectorFlag parses a selector string into a labels.Selector. Returns nil if the string is empty. Intended for CLI flag parsing.

func Pipeline

func Pipeline(in io.Reader, out io.Writer, filters ...kio.Filter) error

Pipeline reads a multi-document YAML stream from in, applies filters in order, and writes the resulting documents to out.

func ReadNodes

func ReadNodes(in io.Reader) ([]*yaml.RNode, error)

ReadNodes parses a multi-document YAML stream into a slice of RNodes. Convenience wrapper for tests that don't need the full pipeline.

func WriteJSONList

func WriteJSONList(out io.Writer, nodes []*yaml.RNode) error

WriteJSONList writes nodes as a Kubernetes List envelope JSON to out.

func WriteNodes

func WriteNodes(out io.Writer, nodes []*yaml.RNode) error

WriteNodes writes a slice of RNodes to out as a multi-document YAML stream. Convenience wrapper for tests that don't need the full pipeline.

Types

type AnnotateOptions

type AnnotateOptions struct {
	Annotation string
	Match      MatchOptions
}

AnnotateOptions configures the annotate filter.

type CountOptions

type CountOptions struct {
	GroupByKind bool
	Match       MatchOptions
}

CountOptions configures the count analyzer.

type CountResult

type CountResult struct {
	Count       int            `json:"count"`
	CountByKind map[string]int `json:"countByKind,omitempty"`
}

CountResult is the JSON representation of a count analysis.

func CountJSON

func CountJSON(nodes []*yaml.RNode, opts CountOptions) (*CountResult, error)

CountJSON counts matching manifests and returns a JSON-serializable result.

type DropOptions

type DropOptions struct {
	// Resource is a positional filter: "kind", "kind/name", or "api-group".
	Resource  string
	Kind      string
	Name      string
	Namespace string
	Group     string
	Selector  labels.Selector
}

DropOptions configures the drop filter.

func (DropOptions) Validate

func (o DropOptions) Validate() error

Validate checks that at least one drop criterion is set.

type Filter

type Filter = kio.FilterFunc

Filter is a pipeline stage that receives all parsed nodes and returns the transformed subset. Each k8q command implements one Filter.

func AnnotateFilter

func AnnotateFilter(opts AnnotateOptions) (Filter, error)

AnnotateFilter returns a Filter that injects an annotation into metadata.annotations only for manifests that match opts.

Annotation input format: key=value.

func CountFilter

func CountFilter(opts CountOptions) Filter

CountFilter returns a Filter that counts matching manifests. Instead of returning YAML, it prints the count to stdout and returns an empty slice to terminate the YAML pipeline.

func DropFilter

func DropFilter(opts DropOptions) Filter

DropFilter returns a Filter that removes manifests matching the given criteria. Manifests matching ANY provided criterion are dropped (OR semantics).

func GetFilter

func GetFilter(opts GetOptions) (Filter, error)

GetFilter returns a Filter that keeps only manifests matching the given criteria. Manifests must match ALL provided non-empty criteria (AND semantics).

func LabelFilter

func LabelFilter(opts LabelOptions) (Filter, error)

LabelFilter returns a Filter that injects a label into metadata.labels only for manifests that match opts. For workload kinds (Deployment, DaemonSet, StatefulSet, Job), the label is also injected into spec.template.metadata.labels.

Label input format: key=value (e.g. app.kubernetes.io/managed-by=k8q).

func PatchFilter

func PatchFilter(opts PatchOptions) (Filter, error)

PatchFilter returns a Filter that merges a YAML patch into matching manifests.

func RemoveFilter

func RemoveFilter(opts RemoveOptions) Filter

RemoveFilter returns a Filter that deletes a field from matching manifests. The field path is dot-separated (e.g. metadata.managedFields).

func RenameFilter

func RenameFilter(opts RenameOptions) Filter

RenameFilter returns a Filter that modifies metadata.name for matching manifests.

func ScaleFilter

func ScaleFilter(opts ScaleOptions) Filter

ScaleFilter returns a Filter that updates spec.replicas for matching manifests.

func ScopedMutator

func ScopedMutator(opts MatchOptions, mutateFn func(*yaml.RNode) error) Filter

ScopedMutator returns a Filter that applies mutateFn only to nodes that match opts, while passing all other nodes through untouched.

func SelectorFilter

func SelectorFilter(sel labels.Selector) Filter

SelectorFilter returns a Filter that keeps only manifests whose labels match the given Kubernetes label selector.

func SetImageFilter

func SetImageFilter(opts SetImageOptions) (Filter, error)

SetImageFilter returns a Filter that updates container images within matching manifests. It looks for container lists in spec.template.spec (for workloads) or top-level spec (for Pods).

Image input format: name=image:tag.

func SetNamespaceFilter

func SetNamespaceFilter(opts NamespaceOptions) Filter

SetNamespaceFilter returns a Filter that overwrites metadata.namespace on manifests that match MatchOptions. Non-matching manifests are passed through untouched.

func SumFilter

func SumFilter(opts SumOptions) Filter

SumFilter returns a Filter that sums CPU and Memory requests/limits from matching manifests.

type GetOptions

type GetOptions struct {
	// Resource is a positional filter: "kind", "kind/name", or "api-group".
	Resource string
	// Kind, Name, Namespace, Group, and Selector define the filter criteria.
	Kind      string
	Name      string
	Namespace string
	Group     string
	Selector  labels.Selector
}

GetOptions configures the get filter.

type JSONListEnvelope

type JSONListEnvelope struct {
	APIVersion string        `json:"apiVersion"`
	Kind       string        `json:"kind"`
	Items      []interface{} `json:"items"`
}

JSONListEnvelope is the Kubernetes "List" resource envelope used when outputting multiple objects as JSON.

type LabelOptions

type LabelOptions struct {
	Label string
	Match MatchOptions
}

LabelOptions configures the label filter.

type MatchMode

type MatchMode int

MatchMode defines how multiple criteria are combined.

const (
	// AndMode means ALL provided non-empty criteria must match.
	AndMode MatchMode = iota
	// OrMode means ANY provided non-empty criterion must match.
	OrMode
)

type MatchOptions

type MatchOptions struct {
	// Resource is a positional filter: "kind", "kind/name", or "api-group".
	Resource  string
	Kind      string
	Name      string
	Namespace string
	Group     string
	Selector  labels.Selector
	Mode      MatchMode
}

MatchOptions defines the criteria for matching a Kubernetes resource.

type NamespaceOptions

type NamespaceOptions struct {
	Namespace string
	Match     MatchOptions
}

NamespaceOptions configures the namespace filter.

type PatchOptions

type PatchOptions struct {
	Patch string
	Match MatchOptions
}

PatchOptions configures the patch filter.

type RemoveOptions

type RemoveOptions struct {
	Field string
	Match MatchOptions
}

RemoveOptions configures the remove filter.

type RenameOptions

type RenameOptions struct {
	Prefix string
	Suffix string
	Match  MatchOptions
}

RenameOptions configures the rename filter.

type ResourceTotals

type ResourceTotals struct {
	CPU    string `json:"cpu"`
	Memory string `json:"memory"`
}

ResourceTotals holds CPU and Memory totals using Kubernetes Quantity strings.

type ScaleOptions

type ScaleOptions struct {
	Replicas string
	Match    MatchOptions
}

ScaleOptions configures the scale filter.

type SetImageOptions

type SetImageOptions struct {
	Image string
	Match MatchOptions
}

SetImageOptions configures the set-image filter.

type SumAssertions

type SumAssertions struct {
	CPURequestsExceeded     bool   `json:"cpuRequestsExceeded"`
	MemoryRequestsExceeded  bool   `json:"memoryRequestsExceeded"`
	CPULimitsExceeded       bool   `json:"cpuLimitsExceeded"`
	MemoryLimitsExceeded    bool   `json:"memoryLimitsExceeded"`
	CPURequestsThreshold    string `json:"cpuRequestsThreshold,omitempty"`
	MemoryRequestsThreshold string `json:"memoryRequestsThreshold,omitempty"`
	CPULimitsThreshold      string `json:"cpuLimitsThreshold,omitempty"`
	MemoryLimitsThreshold   string `json:"memoryLimitsThreshold,omitempty"`
}

SumAssertions captures threshold assertion results.

func (*SumAssertions) HasAny

func (a *SumAssertions) HasAny() bool

type SumOptions

type SumOptions struct {
	Match           MatchOptions
	RequireRequests bool
	RequireLimits   bool

	// Thresholds for assertions.
	MaxCPURequests string
	MaxMemRequests string
	MaxCPULimits   string
	MaxMemLimits   string
}

SumOptions configures the sum analyzer.

type SumResult

type SumResult struct {
	Requests   ResourceTotals `json:"requests"`
	Limits     ResourceTotals `json:"limits"`
	Assertions *SumAssertions `json:"assertions,omitempty"`
}

SumResult is the JSON representation of a resource sum analysis.

func SumJSON

func SumJSON(nodes []*yaml.RNode, opts SumOptions) (*SumResult, error)

SumJSON computes resource totals and returns a JSON-serializable result together with any assertion errors.