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:
- StripServerFieldsFull (default, zero value): removes all known server-set fields, null creationTimestamp, and empty status.
- StripServerFieldsBasic: removes only null creationTimestamp and empty status.
- StripServerFieldsNone: disables all stripping.
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 ¶
- func EncodeObjectsTo(objects []*client.Object, yamlOutput bool) ([]byte, error)
- func EncodeObjectsToJSON(objects []*client.Object) ([]byte, error)
- func EncodeObjectsToYAML(objects []*client.Object) ([]byte, error)
- func EncodeObjectsToYAMLWithOptions(objects []*client.Object, opts EncodeOptions) ([]byte, error)
- func FormatAge(t *metav1.Time) string
- func GetDetailedStatus(obj client.Object) string
- func GetResourceAge(obj client.Object) string
- func GetResourceStatus(obj client.Object) string
- func LoadFile(path string, obj any) (retErr error)
- func Marshal(w io.Writer, obj any) error
- func ParseFile(path string) ([]client.Object, error)
- func ParseFileWithOptions(path string, opts ParseOptions) ([]client.Object, error)
- func ParseYAML(data []byte) ([]client.Object, error)
- func ParseYAMLWithOptions(data []byte, opts ParseOptions) ([]client.Object, error)
- func PrintObjects(objects []*client.Object, format OutputFormat, options PrintOptions, ...) error
- func PrintObjectsAsJSON(objects []*client.Object, w io.Writer) error
- func PrintObjectsAsTable(objects []*client.Object, wide, noHeaders bool, w io.Writer) error
- func PrintObjectsAsYAML(objects []*client.Object, w io.Writer) error
- func SaveFile(path string, obj any) (retErr error)
- func Unmarshal(r io.Reader, obj any) error
- type Buffer
- type EncodeOptions
- type OutputFormat
- type ParseOptions
- type PrintOptions
- type ResourcePrinter
- type ServerFieldStripping
- type SimpleTablePrinter
- type TableColumn
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EncodeObjectsTo ¶
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 EncodeObjectsToYAML ¶
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 GetDetailedStatus ¶
GetDetailedStatus provides additional status information for wide output
func GetResourceAge ¶
GetResourceAge returns the age of a resource based on its creation timestamp
func GetResourceStatus ¶
GetResourceStatus attempts to extract a status string from common status fields
func Marshal ¶
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 ¶
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 ¶
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 ¶
PrintObjectsAsJSON is a convenience function for JSON output
func PrintObjectsAsTable ¶
PrintObjectsAsTable prints objects in table format using the simple table printer
func PrintObjectsAsYAML ¶
PrintObjectsAsYAML is a convenience function for YAML output
func SaveFile ¶
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
Types ¶
type Buffer ¶
Buffer is a simple in-memory buffer that implements io.Reader and io.Writer and can marshal and unmarshal YAML representations of objects.
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 ¶
Print outputs the given resources to the writer using the configured format
func (*ResourcePrinter) PrintSingle ¶
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
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