io

package
v0.2.0-beta.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: Apache-2.0 Imports: 28 Imported by: 2

README

IO - YAML Serialization and Resource Printing

Go Reference

The io package provides utilities for parsing, serializing, and printing Kubernetes resources. It supports multiple output formats including YAML, JSON, and kubectl-compatible table views.

Overview

This package handles the I/O boundary of Kure: reading Kubernetes manifests from files, serializing resources to YAML/JSON, and printing resources in human-readable formats. It integrates with Kure's registered scheme for type-aware parsing.

Each Go block on this page is the body of an Example function in example_test.go, which go test runs: it imports this package as io, github.com/go-kure/kure/pkg/kubernetes for the objects it encodes, appsv1 "k8s.io/api/apps/v1", corev1 "k8s.io/api/core/v1", sigs.k8s.io/controller-runtime/pkg/client, bytes, os, path/filepath, strings, and fmt for the lines that print what the example read or wrote. testdata/manifests.yaml is a Deployment and a Service.

Parsing

Parse YAML Files
// Parse a multi-document YAML file into typed Kubernetes objects
objects, err := io.ParseFile("testdata/manifests.yaml")
if err != nil {
    panic(err)
}

// Parse YAML bytes directly
yamlData := []byte("apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: app-config\n")
more, err := io.ParseYAML(yamlData)
if err != nil {
    panic(err)
}

for _, obj := range append(objects, more...) {
    fmt.Printf("%T %s\n", obj, obj.GetName())
}
Parse Errors

A document that fails to decode into a Kubernetes object is an error in the ParseErrors value the parse returns, a type of the errors package. Such a failure does not end the parse: the documents before and after it are decoded all the same, and their objects are returned beside the error.

A place where the stream itself cannot be read is an error as well. Where the decoder can go on from it, the parse does: a YAML document that does not parse costs only itself, and the documents after it are read. Where the decoder cannot, the parse ends there. It returns one error for the place beside the objects decoded before it, and what follows in the stream is not read. A stream whose first character is { and whose first two documents are JSON objects, one after the other with no --- line between them, is read as JSON only from there on, and the first thing in it that is not JSON is such a place: malformed JSON, or a --- line. JSON documents with a --- line between them are read one by one, as the documents of a YAML stream are: one that does not parse costs only itself.

A registered kind is decoded into its upstream Go type, so that type's own UnmarshalJSON runs inside the parse. One that panics does not take the caller down. The document, or the list item, becomes a parse error that names the object and carries the panic's value, and the documents and items beside it are still returned:

parse error in Kubernetes object: failed to decode object: the decoder panicked on CiliumNetworkPolicy "default/p": runtime error: invalid memory address or nil pointer dereference

A panic whose value is an error keeps it in the chain, for errors.As. The panic's stack trace is not kept. A known case is a CiliumNetworkPolicy whose ICMP field has no type, or type: null: the upstream type dereferences a nil pointer.

Unstructured Fallback

By default, only GVKs registered in the kure scheme are accepted. To parse arbitrary Kubernetes YAML (CRDs, custom operators, etc.) use ParseYAMLWithOptions or ParseFileWithOptions with AllowUnstructured.

Which kinds are typed follows the scheme, so it widens when kure registers more. PriorityClass, EndpointSlice, Lease, RuntimeClass, the two webhook configurations and the four admission policy kinds are registered and come back as their k8s.io/api types in both modes; a caller that matched them as *unstructured.Unstructured must match the typed object instead. The same holds for APIService, typed as its k8s.io/kube-aggregator type, and for the Flux ImageRepository and ImagePolicy. The MetalLB BGPPeer at metallb.io/v1beta2 is registered beside metallb.io/v1beta1 and comes back as its typed object too; a caller that matched it as *unstructured.Unstructured must match the typed object instead. VerticalPodAutoscaler is not registered and still needs AllowUnstructured. The full list is the generated table.

A list document is flattened into its items; the list itself is never returned. The items come back in the list's order and take the list's place in a multi-document stream, and an empty list yields nothing.

  • A <Kind>List of a registered kind (DeploymentList, PriorityClassList) yields typed items in both modes. An item may leave apiVersion and kind out, as the API server's own list responses do; an item that states them must state the kind the list holds. A registered type is such a list when apimachinery reads its Items as a slice. One whose Items it cannot read (a nil field of interface type, or one behind a nil embedded pointer) is not flattened: it is decoded as one object of that type and refused with an error, never a panic, since it either fails to decode or is no client.Object.
  • A generic v1 List is read item by item, each as a document of its own: a registered kind comes back typed, an unregistered one follows AllowUnstructured, and a list inside the list is flattened where it stands.
  • A <Kind>List of a kind that is not registered is refused by a strict parse. With AllowUnstructured it is a list when it states items, and is read item by item like the v1 List: an item of a registered kind comes back typed, one of an unregistered kind unstructured, and a list among the items is flattened where it stands. An item that leaves apiVersion or kind out is given the list's: its apiVersion, and its kind without the List.

A kind that is not registered and does not end in List is one object, whatever fields it has: with AllowUnstructured, a field named items stays part of its content. A kind that ends in List and states no items is one object too, unless it states them under a key in another case (Items): that document is refused, see below.

Each item is decoded by itself, in every list shape. An item that cannot be decoded, a null among them, is reported with its position (item 1 of List, item 1 of DeploymentList), and the items beside it are still returned, as the documents of a stream are.

A list is refused as a whole, with no item returned, in three cases:

  • It is nested too deep. A list may sit inside eight lists whose items are documents of their own, the v1 List and the list of an unregistered kind; one nested deeper is refused, whatever its kind.
  • Its own metadata carries labels or annotations. The items are all a parse returns of a list, and they cannot keep what the list says about itself; a helm.sh/hook annotation on a list is the known case. The error names what the list carries. Metadata that cannot be read is refused as well, and a list that states metadata, labels or annotations more than once carries what any of them states. What describes the response a list came in (resourceVersion, continue, selfLink, remainingItemCount) is ignored, and so is a name on a list.
  • It states its items under a key in another case (Items); see below.
parse error in Kubernetes object: List has metadata of its own that its items cannot keep: annotations helm.sh/hook

A document has one reading. The Kubernetes decoder finds apiVersion and kind under those keys in any case, while a list is recognised, and its items are read, under the exact keys. A top-level key that equals apiVersion or kind only after case folding (Kind, APIVersion) is therefore refused, on every document and on every item of a list. One that equals items is refused on every list of a registered kind and, with AllowUnstructured, on every unregistered kind that ends in List, whether or not it states items as well. The error names the key:

parse error in Kubernetes object: the key "Kind" equals "kind" only after case folding; write it "kind" or remove it

On any other document, Items is a field like any other.

The fallback in use:

yamlData := []byte(`apiVersion: v1
kind: Pod
metadata:
  name: web
---
apiVersion: example.com/v1
kind: Widget
metadata:
  name: my-widget
`)

opts := io.ParseOptions{AllowUnstructured: true}
objects, err := io.ParseYAMLWithOptions(yamlData, opts)
if err != nil {
    panic(err)
}
// Known types are returned as typed objects (e.g. *corev1.Pod).
// Unknown types are returned as *unstructured.Unstructured.
for _, obj := range objects {
    fmt.Printf("%T\n", obj)
}
Load and Save

SaveFile writes one object as YAML; LoadFile reads YAML into an object you pass:

dir, err := os.MkdirTemp("", "kure-io-example")
if err != nil {
    panic(err)
}
defer func() { _ = os.RemoveAll(dir) }()
path := filepath.Join(dir, "service.yaml")

// Save an object to file
service := kubernetes.CreateService("web", "default")
if err := io.SaveFile(path, service); err != nil {
    panic(err)
}

// Load a single object from file
var loaded corev1.Service
if err := io.LoadFile(path, &loaded); err != nil {
    panic(err)
}
fmt.Println(loaded.Kind, loaded.Namespace+"/"+loaded.Name)

Serialization

Marshal and Unmarshal

Marshal writes YAML to an io.Writer, and Unmarshal reads it from an io.Reader:

deployment := kubernetes.CreateDeployment("web", "default")

// Serialize to YAML
var buf bytes.Buffer
if err := io.Marshal(&buf, deployment); err != nil {
    panic(err)
}

// Deserialize from YAML
var obj appsv1.Deployment
if err := io.Unmarshal(&buf, &obj); err != nil {
    panic(err)
}
fmt.Println(obj.Kind, obj.Namespace+"/"+obj.Name)
Encode Multiple Objects

The encoders take []*client.Object, where the parsers return []client.Object. The YAML encoder separates documents with ---. The JSON encoder writes one object per line and follows each, the last included, with a --- line, so its output is not a JSON array.

var configMap client.Object = kubernetes.CreateConfigMap("app-config", "default")
var service client.Object = kubernetes.CreateService("web", "default")
objects := []*client.Object{&configMap, &service}

// Encode as multi-document YAML
yamlData, err := io.EncodeObjectsToYAML(objects)
if err != nil {
    panic(err)
}

// Encode as JSON: one object per line, each followed by a --- separator
jsonData, err := io.EncodeObjectsToJSON(objects)
if err != nil {
    panic(err)
}

fmt.Print(string(yamlData))
fmt.Print(string(jsonData))
Numbers

The YAML encoders write an integer exactly when the object holds it as an integer: an integer field of a typed object, an int64 in an unstructured one. 9007199254740993 is written as 9007199254740993, in both field orders, and so is every integer up to the largest uint64.

A float64 is not an integer to the encoders, also when its value is one. A float64 that holds an integer between -2^63 and 2^64, both excluded, is written with the digits of its JSON form, the shortest that read back as the same float64, in both field orders. Above 2^53 those are not always its exact expansion: the float64 2^62 is written 4611686018427388000, not 4611686018427387904. Hold a large integer as an integer to have it written exactly.

Any other finite number, the float64 -2^63 among them, passes through a float64 and is written with that precision.

Strings

Every YAML writer of the package keeps every string as it is: EncodeObjectsToYAML and PrintObjectsAsYAML in both field orders, EncodeObjectsTo with YAML output, Marshal, Buffer.Marshal and SaveFile. A string holding NEL (U+0085), DEL (U+007F), another C1 control (U+0080 to U+009F), U+FFFE or U+FFFF is written double-quoted, with the character as an escape ("a\Nb", "a\x7Fb", "a\uFFFEb"), in a value and in a key alike. kure, kubectl and kustomize read it back unchanged. Before, every writer but the Kubernetes field order changed NEL into a space and refused the others (go-kure/kure#1129).

Marshal, Buffer.Marshal and EncodeObjectsTo also write a string that an object's own JSON spells with an escape YAML 1.1 lacks, such as \/ or a UTF-16 surrogate pair. They refused it before. Every other string is written as before, byte for byte.

Deterministic Field Ordering
configMap := kubernetes.CreateConfigMap("app-config", "default")
configMap.Data = map[string]string{"LOG_LEVEL": "info"}
var obj client.Object = configMap
objects := []*client.Object{&obj}

// Encode with Kubernetes-conventional field ordering:
// apiVersion, kind, metadata, spec, ... status (last)
opts := io.EncodeOptions{KubernetesFieldOrder: true}
yamlData, err := io.EncodeObjectsToYAMLWithOptions(objects, opts)
if err != nil {
    panic(err)
}
fmt.Print(string(yamlData))
Server-Set Field Stripping

By default, YAML encoding (EncodeObjectsToYAML, EncodeObjectsToYAMLWithOptions) strips server-managed metadata fields that should not appear in client-generated manifests: managedFields, resourceVersion, uid, generation, selfLink, the kubectl.kubernetes.io/last-applied-configuration annotation, null creationTimestamp, and empty status.

The example encodes one Service at each stripping level and reports whether its resourceVersion and its empty status survived:

// A Service as read back from a cluster: a resourceVersion, and an empty status
service := kubernetes.CreateService("web", "default")
service.ResourceVersion = "12345"
var obj client.Object = service
objects := []*client.Object{&obj}

for _, opts := range []io.EncodeOptions{
    // Default behavior — full stripping (the zero value, which EncodeObjectsToYAML uses)
    {},
    // Explicit full stripping with field ordering
    {KubernetesFieldOrder: true, ServerFieldStripping: io.StripServerFieldsFull},
    // Basic stripping (only null creationTimestamp and empty status)
    {ServerFieldStripping: io.StripServerFieldsBasic},
    // No stripping — preserve all fields as-is
    {ServerFieldStripping: io.StripServerFieldsNone},
} {
    yamlData, err := io.EncodeObjectsToYAMLWithOptions(objects, opts)
    if err != nil {
        panic(err)
    }
    out := string(yamlData)
    fmt.Println(strings.Contains(out, "resourceVersion:"), strings.Contains(out, "status:"))
}

Printing

Output Formats

The package supports these output formats, named as kubectl names them:

Format Constant Description
YAML OutputFormatYAML Full YAML output
JSON OutputFormatJSON Full JSON output
Table OutputFormatTable Columnar table view
Wide OutputFormatWide Extended table with extra columns
Name OutputFormatName kind[.group]/name, with (namespace: <ns>) appended for a namespaced object
Usage

The example prints one ConfigMap three ways: as YAML, as a table through a ResourcePrinter (ShowLabels adds the LABELS column), and in the format a user-supplied string names. ValidateOutputFormat turns that string into an OutputFormat, and fails on one it does not know. PrintObjectsAsTable prints a table directly, without a ResourcePrinter.

configMap := kubernetes.CreateConfigMap("app-config", "default")
configMap.Labels = map[string]string{"app": "web"}
var obj client.Object = configMap
objects := []*client.Object{&obj}

// Print as YAML to stdout
if err := io.PrintObjectsAsYAML(objects, os.Stdout); err != nil {
    panic(err)
}

// Use ResourcePrinter for configurable output
printer := io.NewResourcePrinter(io.PrintOptions{
    OutputFormat: io.OutputFormatTable,
    ShowLabels:   true,
})
if err := printer.Print(objects, os.Stdout); err != nil {
    panic(err)
}

// Validate a format string before use
format, err := io.ValidateOutputFormat("name")
if err != nil {
    panic(err)
}

// Format-agnostic printing (selects the printer by format)
if err := io.PrintObjects(objects, format, io.PrintOptions{}, os.Stdout); err != nil {
    panic(err)
}
  • errors - Error types for parse failures
  • kubernetes - Scheme registration for type-aware parsing

Documentation

Overview

Package io provides utilities for reading, writing and parsing YAML representations of Kubernetes resources. It acts as a thin wrapper around sigs.k8s.io/yaml and the Kubernetes runtime scheme from client-go.

YAML helpers

Basic marshalling and unmarshalling is performed through the Marshal and Unmarshal functions which operate on the standard io.Reader and io.Writer interfaces. When persisting data to disk the SaveFile and LoadFile helpers wrap file creation and reading so callers need only provide the destination path and the object to encode or decode.

For in-memory operations the Buffer type implements both io.Reader and io.Writer and exposes Marshal and Unmarshal methods. A Buffer can be reused for multiple round trips without allocating new byte slices:

buf := new(io.Buffer)
if err := buf.Marshal(obj); err != nil {
    log.Fatalf("marshal object: %v", err)
}
if err := buf.Unmarshal(&out); err != nil {
    log.Fatalf("unmarshal object: %v", err)
}

Parsing runtime objects

Kubernetes manifests frequently contain multiple YAML documents separated by `---`. ParseFile reads such a manifest and decodes each document into a runtime.Object using the client-go scheme. Several additional API schemes from projects like FluxCD, cert-manager and MetalLB are registered so their custom resources can be parsed without further setup.

Any decoding errors are aggregated in a ParseErrors value from github.com/go-kure/kure/pkg/errors, which implements the error interface. Successful objects are returned alongside the error so callers may continue processing valid resources while reporting individual failures.

objs, err := io.ParseFile("./manifests.yaml")
if err != nil {
    var pe *errors.ParseErrors // github.com/go-kure/kure/pkg/errors
    if stderrors.As(err, &pe) {
        for _, e := range pe.Errors {
            log.Printf("parse error: %v", e)
        }
    }
}

A place where the stream itself cannot be read is one of those errors too. A YAML document that does not parse costs only itself: the documents after it are read. Where the decoder cannot go on, the parse ends there with one error for the place, beside the objects decoded before it; what follows is not read. A stream whose first character is "{" and whose first two documents are JSON objects, one after the other with no "---" line between them, is read as JSON only from there on, and the first thing in it that is not JSON is such a place: malformed JSON, or a "---" line. JSON documents with a "---" line between them are read one by one, as the documents of a YAML stream are: one that does not parse costs only itself.

A registered kind is decoded into its upstream Go type, so that type's own UnmarshalJSON runs inside the parse. One that panics does not take the caller down: the document, or the list item, becomes one of those errors. It names the object and carries the panic's value, as in

the decoder panicked on CiliumNetworkPolicy "default/p": runtime error: invalid memory address or nil pointer dereference

and the documents and items beside it are still returned. A panic whose value is an error keeps it in the chain; the stack trace is not kept.

Unstructured fallback

By default the parser rejects objects whose GroupVersionKind is not registered in the kure scheme. ParseYAMLWithOptions and ParseFileWithOptions accept a ParseOptions value. When AllowUnstructured is true, unknown GVKs are decoded as *unstructured.Unstructured instead of returning an error, making it possible to process arbitrary Kubernetes YAML including CRDs that are not compiled into the binary:

opts := io.ParseOptions{AllowUnstructured: true}
objs, err := io.ParseYAMLWithOptions(data, opts)
for _, obj := range objs {
    if u, ok := obj.(*unstructured.Unstructured); ok {
        fmt.Println("unstructured:", u.GetKind(), u.GetName())
    }
}

List documents

A list document is flattened into its items and is never returned itself: a typed list of a registered kind (DeploymentList), the v1 List, and with AllowUnstructured the list of an unregistered kind, which is a kind that ends in List and states items. Each item is decoded by itself; one that fails is an error naming its position, beside the items that decoded.

A list is refused as a whole when its own metadata carries labels or annotations, which its items cannot keep, and when it is nested more than eight lists deep.

A document has one reading. A top-level key that equals apiVersion or kind only after case folding (Kind, APIVersion) is refused on every document and every item of a list. One that equals items is refused on every list of a registered kind and, with AllowUnstructured, on every unregistered kind that ends in List. The error names the key. The package README states these rules in full.

Resource printing

The io package includes comprehensive resource printing capabilities compatible with kubectl output formats. The ResourcePrinter provides unified formatting for YAML, JSON, table, wide, and name output modes:

printer := io.NewResourcePrinter(io.PrintOptions{
	OutputFormat: io.OutputFormatTable,
	NoHeaders:    false,
	ShowLabels:   true,
})
err := printer.Print(resources, os.Stdout)

Table output includes resource-specific column formatting for different Kubernetes kinds (Pod, Deployment, Service, ConfigMap) with appropriate status indicators, age formatting, and wide-mode additional details.

For simple table printing, use the SimpleTablePrinter which provides kubectl-style table output without external dependencies:

printer := io.NewSimpleTablePrinter(wide, noHeaders)
printer.Print(resources, os.Stdout)

Convenience functions are available for common operations:

io.PrintObjectsAsYAML(resources, os.Stdout)
io.PrintObjectsAsJSON(resources, os.Stdout)
io.PrintObjectsAsTable(resources, wide, noHeaders, os.Stdout)

Deterministic field ordering

EncodeObjectsToYAMLWithOptions accepts EncodeOptions to control YAML output. When KubernetesFieldOrder is true, top-level fields are emitted in the conventional order used by kubectl, Helm, and Kustomize: apiVersion, kind, metadata, spec, data, stringData, then remaining fields alphabetically, with status last.

Numbers

EncodeObjectsToYAML and EncodeObjectsToYAMLWithOptions write an integer exactly when the object holds it as an integer: an integer field of a typed object, an int64 in an unstructured one. That holds in both field orders and up to the largest uint64.

A float64 is not an integer to the encoders, also when its value is one. A float64 that holds an integer between -2^63 and 2^64, both excluded, is written with the digits of its JSON form, the shortest that read back as the same float64, in both field orders. Above 2^53 those are not always its exact expansion: the float64 2^62 is written 4611686018427388000, not 4611686018427387904. Hold a large integer as an integer to have it written exactly.

Any other finite number, the float64 -2^63 among them, passes through a float64 and is written with that precision.

Server-set field stripping

Resources exported from a cluster via `kubectl get -o yaml` include server-managed metadata fields (managedFields, resourceVersion, uid, generation, selfLink, and the kubectl.kubernetes.io/last-applied-configuration annotation) that should not appear in client-generated manifests.

The ServerFieldStripping option on EncodeOptions controls which of these fields are removed during encoding:

Because the zero value of ServerFieldStripping is StripServerFieldsFull, all existing callers of EncodeObjectsToYAML benefit from enhanced stripping without code changes.

The package forms the foundation for the other packages within this repository but can be imported directly by any program that requires lightweight YAML handling, runtime object parsing, and kubectl-compatible resource printing.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func EncodeObjectsTo

func EncodeObjectsTo(objects []*client.Object, yamlOutput bool) ([]byte, error)

EncodeObjectsTo encodes objects as JSON, or as YAML when yamlOutput is true, each followed by a "---" separator line. The objects are written as they are, without the cleanup EncodeObjectsToYAML does. In YAML every string reads back unchanged, as in Marshal.

func EncodeObjectsToJSON

func EncodeObjectsToJSON(objects []*client.Object) ([]byte, error)

func EncodeObjectsToYAML

func EncodeObjectsToYAML(objects []*client.Object) ([]byte, error)

EncodeObjectsToYAML encodes Kubernetes objects to clean YAML, stripping all known server-managed metadata fields by default (see StripServerFieldsFull). Every string reads back unchanged: one holding NEL, DEL, a C1 control, U+FFFE or U+FFFF is written double-quoted with escapes.

Example
package main

import (
	"fmt"

	"sigs.k8s.io/controller-runtime/pkg/client"

	"github.com/go-kure/kure/pkg/io"
	"github.com/go-kure/kure/pkg/kubernetes"
)

func main() {
	var configMap client.Object = kubernetes.CreateConfigMap("app-config", "default")
	var service client.Object = kubernetes.CreateService("web", "default")
	objects := []*client.Object{&configMap, &service}

	// Encode as multi-document YAML
	yamlData, err := io.EncodeObjectsToYAML(objects)
	if err != nil {
		panic(err)
	}

	// Encode as JSON: one object per line, each followed by a --- separator
	jsonData, err := io.EncodeObjectsToJSON(objects)
	if err != nil {
		panic(err)
	}

	fmt.Print(string(yamlData))
	fmt.Print(string(jsonData))
}
Output:
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: default
---
apiVersion: v1
kind: Service
metadata:
  name: web
  namespace: default
spec: {}
{"kind":"ConfigMap","apiVersion":"v1","metadata":{"name":"app-config","namespace":"default"}}
---
{"kind":"Service","apiVersion":"v1","metadata":{"name":"web","namespace":"default"},"spec":{},"status":{"loadBalancer":{}}}
---

func EncodeObjectsToYAMLWithOptions

func EncodeObjectsToYAMLWithOptions(objects []*client.Object, opts EncodeOptions) ([]byte, error)

EncodeObjectsToYAMLWithOptions encodes Kubernetes objects to clean YAML with configurable output options. When opts.KubernetesFieldOrder is true, top-level fields are emitted in the conventional order used by kubectl, Helm, and Kustomize (apiVersion, kind, metadata, spec, ..., status last). In either field order every string reads back unchanged, as in EncodeObjectsToYAML.

Example
package main

import (
	"fmt"

	"sigs.k8s.io/controller-runtime/pkg/client"

	"github.com/go-kure/kure/pkg/io"
	"github.com/go-kure/kure/pkg/kubernetes"
)

func main() {
	configMap := kubernetes.CreateConfigMap("app-config", "default")
	configMap.Data = map[string]string{"LOG_LEVEL": "info"}
	var obj client.Object = configMap
	objects := []*client.Object{&obj}

	// Encode with Kubernetes-conventional field ordering:
	// apiVersion, kind, metadata, spec, ... status (last)
	opts := io.EncodeOptions{KubernetesFieldOrder: true}
	yamlData, err := io.EncodeObjectsToYAMLWithOptions(objects, opts)
	if err != nil {
		panic(err)
	}
	fmt.Print(string(yamlData))
}
Output:
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: default
data:
  LOG_LEVEL: info

func FormatAge

func FormatAge(t *metav1.Time) string

FormatAge returns a human-readable age string for a resource

func GetDetailedStatus

func GetDetailedStatus(obj client.Object) string

GetDetailedStatus provides additional status information for wide output

func GetResourceAge

func GetResourceAge(obj client.Object) string

GetResourceAge returns the age of a resource based on its creation timestamp

func GetResourceStatus

func GetResourceStatus(obj client.Object) string

GetResourceStatus attempts to extract a status string from common status fields

func LoadFile

func LoadFile(path string, obj any) (retErr error)

LoadFile reads YAML from the given path and unmarshals it into obj.

func Marshal

func Marshal(w io.Writer, obj any) error

Marshal writes the YAML representation of obj to w. obj is read through its JSON form, so json struct tags and MarshalJSON apply. Every string reads back unchanged: one holding NEL, DEL, a C1 control, U+FFFE or U+FFFF is written double-quoted with escapes.

Example
package main

import (
	"bytes"
	"fmt"

	appsv1 "k8s.io/api/apps/v1"

	"github.com/go-kure/kure/pkg/io"
	"github.com/go-kure/kure/pkg/kubernetes"
)

func main() {
	deployment := kubernetes.CreateDeployment("web", "default")

	// Serialize to YAML
	var buf bytes.Buffer
	if err := io.Marshal(&buf, deployment); err != nil {
		panic(err)
	}

	// Deserialize from YAML
	var obj appsv1.Deployment
	if err := io.Unmarshal(&buf, &obj); err != nil {
		panic(err)
	}
	fmt.Println(obj.Kind, obj.Namespace+"/"+obj.Name)
}
Output:
Deployment default/web

func ParseFile

func ParseFile(path string) ([]client.Object, error)

ParseFile reads the YAML file at path and returns the runtime objects defined within. Each object is decoded using the k8s scheme. An error is returned if the file cannot be read or if decoding any document fails.

Example
package main

import (
	"fmt"

	"github.com/go-kure/kure/pkg/io"
)

func main() {
	// Parse a multi-document YAML file into typed Kubernetes objects
	objects, err := io.ParseFile("testdata/manifests.yaml")
	if err != nil {
		panic(err)
	}

	// Parse YAML bytes directly
	yamlData := []byte("apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: app-config\n")
	more, err := io.ParseYAML(yamlData)
	if err != nil {
		panic(err)
	}

	for _, obj := range append(objects, more...) {
		fmt.Printf("%T %s\n", obj, obj.GetName())
	}
}
Output:
*v1.Deployment web
*v1.Service web
*v1.ConfigMap app-config

func ParseFileWithOptions

func ParseFileWithOptions(path string, opts ParseOptions) ([]client.Object, error)

ParseFileWithOptions reads the YAML file at path and returns the runtime objects defined within. Behavior is controlled by opts; see ParseOptions.

func ParseYAML

func ParseYAML(data []byte) ([]client.Object, error)

ParseYAML parses YAML bytes and returns the runtime objects defined within. Each object is decoded using the k8s scheme. An error is returned if decoding any document fails.

func ParseYAMLWithOptions

func ParseYAMLWithOptions(data []byte, opts ParseOptions) ([]client.Object, error)

ParseYAMLWithOptions parses YAML bytes and returns the runtime objects defined within. Behavior is controlled by opts; see ParseOptions.

Example
package main

import (
	"fmt"

	"github.com/go-kure/kure/pkg/io"
)

func main() {
	yamlData := []byte(`apiVersion: v1
kind: Pod
metadata:
  name: web
---
apiVersion: example.com/v1
kind: Widget
metadata:
  name: my-widget
`)

	opts := io.ParseOptions{AllowUnstructured: true}
	objects, err := io.ParseYAMLWithOptions(yamlData, opts)
	if err != nil {
		panic(err)
	}
	// Known types are returned as typed objects (e.g. *corev1.Pod).
	// Unknown types are returned as *unstructured.Unstructured.
	for _, obj := range objects {
		fmt.Printf("%T\n", obj)
	}
}
Output:
*v1.Pod
*unstructured.Unstructured

func PrintObjects

func PrintObjects(objects []*client.Object, format OutputFormat, options PrintOptions, w io.Writer) error

PrintObjects prints objects using the specified output format and options

func PrintObjectsAsJSON

func PrintObjectsAsJSON(objects []*client.Object, w io.Writer) error

PrintObjectsAsJSON is a convenience function for JSON output

func PrintObjectsAsTable

func PrintObjectsAsTable(objects []*client.Object, wide, noHeaders bool, w io.Writer) error

PrintObjectsAsTable prints objects in table format using the simple table printer

func PrintObjectsAsYAML

func PrintObjectsAsYAML(objects []*client.Object, w io.Writer) error

PrintObjectsAsYAML is a convenience function for YAML output

func SaveFile

func SaveFile(path string, obj any) (retErr error)

SaveFile marshals obj as YAML and writes it to the given file path.

Example
package main

import (
	"fmt"
	"os"
	"path/filepath"

	corev1 "k8s.io/api/core/v1"

	"github.com/go-kure/kure/pkg/io"
	"github.com/go-kure/kure/pkg/kubernetes"
)

func main() {
	dir, err := os.MkdirTemp("", "kure-io-example")
	if err != nil {
		panic(err)
	}
	defer func() { _ = os.RemoveAll(dir) }()
	path := filepath.Join(dir, "service.yaml")

	// Save an object to file
	service := kubernetes.CreateService("web", "default")
	if err := io.SaveFile(path, service); err != nil {
		panic(err)
	}

	// Load a single object from file
	var loaded corev1.Service
	if err := io.LoadFile(path, &loaded); err != nil {
		panic(err)
	}
	fmt.Println(loaded.Kind, loaded.Namespace+"/"+loaded.Name)
}
Output:
Service default/web

func Unmarshal

func Unmarshal(r io.Reader, obj any) error

Unmarshal reads YAML from r into obj.

Types

type Buffer

type Buffer struct {
	bytes.Buffer
}

Buffer is a simple in-memory buffer that implements io.Reader and io.Writer and can marshal and unmarshal YAML representations of objects.

func (*Buffer) Marshal

func (b *Buffer) Marshal(obj any) error

Marshal writes the YAML representation of obj to the buffer. obj is read through its JSON form, as Marshal reads it, and every string reads back unchanged.

func (*Buffer) Unmarshal

func (b *Buffer) Unmarshal(obj any) error

Unmarshal parses the buffer contents as YAML into obj.

type EncodeOptions

type EncodeOptions struct {
	// KubernetesFieldOrder emits top-level resource keys in the
	// conventional order used by kubectl, Helm, and Kustomize:
	// apiVersion, kind, metadata, spec, data, stringData, type,
	// then remaining keys alphabetically, with status last.
	// Nested maps remain alphabetically sorted.
	KubernetesFieldOrder bool

	// ServerFieldStripping controls removal of server-managed metadata
	// fields during encoding. The zero value (StripServerFieldsFull)
	// strips all known server-set fields by default.
	ServerFieldStripping ServerFieldStripping
}

EncodeOptions controls how Kubernetes objects are serialized to YAML.

type OutputFormat

type OutputFormat string

OutputFormat represents the supported output formats for printing resources

const (
	OutputFormatYAML  OutputFormat = "yaml"
	OutputFormatJSON  OutputFormat = "json"
	OutputFormatTable OutputFormat = "table"
	OutputFormatWide  OutputFormat = "wide"
	OutputFormatName  OutputFormat = "name"
)

func ValidateOutputFormat

func ValidateOutputFormat(format string) (OutputFormat, error)

ValidateOutputFormat checks if the given format string is valid

type ParseOptions

type ParseOptions struct {
	// AllowUnstructured enables fallback decoding for GVKs not registered
	// in the kure scheme. When true, unknown objects are returned as
	// *unstructured.Unstructured instead of producing an error.
	AllowUnstructured bool
}

ParseOptions controls how Kubernetes YAML documents are decoded.

type PrintOptions

type PrintOptions struct {
	// OutputFormat specifies the desired output format
	OutputFormat OutputFormat
	// NoHeaders suppresses table headers when true
	NoHeaders bool
	// ShowLabels displays resource labels in table output
	ShowLabels bool
	// ColumnLabels is a list of label keys to display as columns
	ColumnLabels []string
	// SortBy specifies the column to sort by (for table output)
	SortBy string
}

PrintOptions contains configuration for resource printing

type ResourcePrinter

type ResourcePrinter struct {
	// contains filtered or unexported fields
}

ResourcePrinter provides a unified interface for printing Kubernetes resources in various formats, compatible with kubectl output styles

func NewResourcePrinter

func NewResourcePrinter(options PrintOptions) *ResourcePrinter

NewResourcePrinter creates a new ResourcePrinter with the given options

Example
package main

import (
	"os"

	"sigs.k8s.io/controller-runtime/pkg/client"

	"github.com/go-kure/kure/pkg/io"
	"github.com/go-kure/kure/pkg/kubernetes"
)

func main() {
	configMap := kubernetes.CreateConfigMap("app-config", "default")
	configMap.Labels = map[string]string{"app": "web"}
	var obj client.Object = configMap
	objects := []*client.Object{&obj}

	// Print as YAML to stdout
	if err := io.PrintObjectsAsYAML(objects, os.Stdout); err != nil {
		panic(err)
	}

	// Use ResourcePrinter for configurable output
	printer := io.NewResourcePrinter(io.PrintOptions{
		OutputFormat: io.OutputFormatTable,
		ShowLabels:   true,
	})
	if err := printer.Print(objects, os.Stdout); err != nil {
		panic(err)
	}

	// Validate a format string before use
	format, err := io.ValidateOutputFormat("name")
	if err != nil {
		panic(err)
	}

	// Format-agnostic printing (selects the printer by format)
	if err := io.PrintObjects(objects, format, io.PrintOptions{}, os.Stdout); err != nil {
		panic(err)
	}
}
Output:
apiVersion: v1
kind: ConfigMap
metadata:
  labels:
    app: web
  name: app-config
  namespace: default
NAMESPACE   NAME         AGE         LABELS
default     app-config   <unknown>   app=web
configmap/app-config (namespace: default)

func NewTablePrinter

func NewTablePrinter(options PrintOptions) *ResourcePrinter

NewTablePrinter creates a table printer configured for Kure resources

func (*ResourcePrinter) Print

func (rp *ResourcePrinter) Print(resources []*client.Object, w io.Writer) error

Print outputs the given resources to the writer using the configured format

func (*ResourcePrinter) PrintSingle

func (rp *ResourcePrinter) PrintSingle(resource client.Object, w io.Writer) error

PrintSingle is a convenience function for printing a single resource

func (*ResourcePrinter) PrintToString

func (rp *ResourcePrinter) PrintToString(resources []*client.Object) (string, error)

PrintToString returns the printed output as a string instead of writing to a writer

type ServerFieldStripping

type ServerFieldStripping int

ServerFieldStripping controls which server-managed metadata fields are removed during YAML encoding.

Example
package main

import (
	"fmt"
	"strings"

	"sigs.k8s.io/controller-runtime/pkg/client"

	"github.com/go-kure/kure/pkg/io"
	"github.com/go-kure/kure/pkg/kubernetes"
)

func main() {
	// A Service as read back from a cluster: a resourceVersion, and an empty status
	service := kubernetes.CreateService("web", "default")
	service.ResourceVersion = "12345"
	var obj client.Object = service
	objects := []*client.Object{&obj}

	for _, opts := range []io.EncodeOptions{
		// Default behavior — full stripping (the zero value, which EncodeObjectsToYAML uses)
		{},
		// Explicit full stripping with field ordering
		{KubernetesFieldOrder: true, ServerFieldStripping: io.StripServerFieldsFull},
		// Basic stripping (only null creationTimestamp and empty status)
		{ServerFieldStripping: io.StripServerFieldsBasic},
		// No stripping — preserve all fields as-is
		{ServerFieldStripping: io.StripServerFieldsNone},
	} {
		yamlData, err := io.EncodeObjectsToYAMLWithOptions(objects, opts)
		if err != nil {
			panic(err)
		}
		out := string(yamlData)
		fmt.Println(strings.Contains(out, "resourceVersion:"), strings.Contains(out, "status:"))
	}
}
Output:
false false
false false
true false
true true
const (
	// StripServerFieldsFull removes all known server-set metadata fields:
	// managedFields, resourceVersion, uid, generation, selfLink,
	// the kubectl.kubernetes.io/last-applied-configuration annotation,
	// null creationTimestamp, and empty status.
	StripServerFieldsFull ServerFieldStripping = iota

	// StripServerFieldsBasic removes only null creationTimestamp and
	// empty status (the pre-v0.1 behavior).
	StripServerFieldsBasic

	// StripServerFieldsNone disables all server-field stripping.
	StripServerFieldsNone
)

type SimpleTablePrinter

type SimpleTablePrinter struct {
	// contains filtered or unexported fields
}

SimpleTablePrinter provides a basic table printer implementation without k8s.io/cli-runtime dependency

func NewSimpleTablePrinter

func NewSimpleTablePrinter(wide, noHeaders bool) *SimpleTablePrinter

NewSimpleTablePrinter creates a simple table printer with default columns

func NewSimpleTablePrinterWithColumns

func NewSimpleTablePrinterWithColumns(columns []TableColumn, wide, noHeaders bool) *SimpleTablePrinter

NewSimpleTablePrinterWithColumns creates a simple table printer with custom columns

func (*SimpleTablePrinter) Print

func (stp *SimpleTablePrinter) Print(resources []*client.Object, w io.Writer) error

Print outputs resources in table format using the simple table printer

type TableColumn

type TableColumn struct {
	Header   string
	Width    int
	Accessor func(client.Object) string
	Priority int  // Lower values are shown first, higher values in wide mode
	WideOnly bool // Only shown in wide output
}

TableColumn represents a column in table output

func DefaultColumns

func DefaultColumns() []TableColumn

DefaultColumns returns the default column set for Kubernetes resources

func KindSpecificColumns

func KindSpecificColumns(gvk metav1.GroupVersionKind) []TableColumn

KindSpecificColumns returns columns tailored for specific Kubernetes resource kinds

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL