kubernetes

Kubernetes manifests in Go

• What is this?
• But why?
• Getting started
• Best practices
• CRDs
• Testing manifests
• CLI Utilities
  • Explode
  • Kygo
• Packages
  • Kube
  • Kubeconfig
  • KubeUtil
  • Testutils

What is this?

This is a collection of libraries and helpers functions that helps to work with kubernetes manifests.

With this library you can:

• Import kubernetes manifests to Go structs ( YAML to Go )
  • see Import Options for more information
• Export Go structs to kubernetes manifests ( Go to YAML )
  • see Export Options for more information
• Explode kubernetes manifests to a single resource per file organized by namespaces (YAML to YAML)

But why?

Rationale.md

Getting started

1. Get a kubernetes manifest
   • example:

wget https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.45.0/release.yaml

2. Convert it to Go structs. Choose either: A) Most manifests don't include extensions CRD object, use the kygo CLI:

   go run cmd/kygo/ -in=./install.yaml -out=output -app=myapp -group`

   B) for CRDs, look at the CRD example C) for more options, see Import Options

3. Modify the structs to your liking

   • see best practices for more information
   • example: tekton

4. Export:

package crd_test

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

	team "github.com/golingon/docskubernetes/crd/out"
	"github.com/golingon/lingon/pkg/kube"
)

var defaultOut = "out"

// Example_export to shows how to export to kubernetes manifests files in YAML.
func Example_export() {
	out := filepath.Join(defaultOut, "manifests")

	// Remove previously generated output directory
	_ = os.RemoveAll(out)

	tm := team.New()
	err := kube.Export(
		tm,
		// directory where to export the manifests
		kube.WithExportOutputDirectory(out),

		// // Write the manifests to a bytes.Buffer.
		// // Note that it will be written as txtar format.
		// kube.WithExportWriter(buf),
		// // Add a kustomization.yaml file next to the manifests.
		// kube.WithExportKustomize(true),

		// // Write the manifest as a single file.
		// kube.WithExportAsSingleFile("manifest.yaml"),

		// // Write the manifests as JSON instead of YAML.
		// // Written as an JSON array if written as a single file.
		// kube.WithExportOutputJSON(true),

		// // Write to standard output instead of a file.
		// kube.WithExportStdOut(),

		// // Write the manifests as it would appear on the cluster.
		// // 1 resource per file and one folder per namespace.
		// kube.WithExportExplodeManifests(true),

		// // Define a hook to be called before exporting a secret.
		// // Note that this will remove the secret from the output.
		// kube.WithExportSecretHook(
		// 	func(s *corev1.Secret) error {
		// 		// do something with the secret
		// 		return nil
		// 	}),
	)
	if err != nil {
		fmt.Printf("%s\n", err)
	}
	fmt.Println("successfully exported CRDs to manifests")

	// Output:
	// successfully exported CRDs to manifests
}

5. Apply:

kubectl apply -f out/manifests/

done ✅.

Have a look at the tests and the example for a full example.

What does the Go code looks like, see tekton example

Best practices

PLEASE READ best practices before using this library.

This project has been heavily inspired by :

• Mimic (you should definitely check it out, we copied the best practices from there)
• NAML (we found out about valast from there)

Honorable mentions:

• valast convert Go structs to its Go code representation
• jennifer generate Go code

CRDs

How to convert CRDs from YAML to Go. By setting a kubernetes runtime scheme:

"k8s.io/apimachinery/pkg/runtime"
"k8s.io/client-go/kubernetes/scheme"

Short example:

func defaultSerializer() runtime.Decoder {
// Add CRDs to scheme
// This is needed to be able to import CRDs from kubernetes manifests files.
_ = apiextensions.AddToScheme(scheme.Scheme)
_ = apiextensionsv1.AddToScheme(scheme.Scheme)
_ = secretsstorev1.AddToScheme(scheme.Scheme)
_ = istionetworkingv1beta1.AddToScheme(scheme.Scheme)
return scheme.Codecs.UniversalDeserializer()
}

_ = kube.Import(
    kube.WithImportSerializer(defaultSerializer()),
    ...
)

Full example in the crd folder

Testing manifests

see testing manifests

CLI Utilities

Explode

Converts multi-kubernetes-object manifest into multiple files, organized by namespace. A CLI was written to make it easier to use in the terminal instead of just a library.

Kygo

Converts kubernetes manifests to Go structs.

A CLI was written to make it easier to use in the terminal instead of just a library. It does support CustomResourceDefinitions but not the custom resources themselves, although it is easy to add them manually. An example of how to convert custom resource from YAML to Go can be found in the CRD example.

Packages

Have a look at the godoc for more information.

Kube

• App struct that is embedded to mark kubernetes applications
• Export kubernetes objects defined as Go struct to kubernetes manifests in YAML.
• Explode kubernetes manifests in YAML to multiple files, organized by namespace.
• Import kubernetes manifests in YAML to Go structs.

Kubeconfig

Manipulate kubeconfig files without any dependencies on go-client.

KubeUtil

Reusable functions used to create kubernetes objects in Go.

Testutils

Reusable test functions.