plumber

package module
v2.3.1 Latest Latest
Warning

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

Go to latest
Published: Jan 16, 2023 License: Apache-2.0 Imports: 15 Imported by: 0

README

Plumber

Plumber is a Go package that allows managing objects creation and patching, piping them from YAML to its concrete in-cluster representation. This package leverages Kustomize and its goal is to make object creation and management easier.

Example

To see the full example please see https://github.com/ricardomaraschini/plumber/tree/main/example

// start by embedding all YAML files we are going to render and create.
//go:embed kustomize
var resources embed.FS

func main() {
	cli, err := client.New(config.GetConfigOrDie(), client.Options{})
	if err != nil {
		panic(err)
	}

	// if we have objects that are not part of the objects supported by the
	// default controller runtime client we can register them here. below
	// we register the kurl types so we can create them in the cluster. if
	// no client can't be found to provide a concrete implementation of a
	// given type then we have to use Unstructured instead, see below.
	kurlkinds.AddToScheme(cli.Scheme())

	options := []plumber.Option{
		// when using WithUnstructured objects are kept as Unstructured,
		// no conversion to concrete objects are made by the library. be
		// aware that whenever you use this the Mutator will receive an
		// Unstructured object instead of a concrete type (Pod, Service,
		// Deployment, etc).
		// plumber.WithUnstructured(),
		plumber.WithObjectMutator(
			func(ctx context.Context, obj client.Object) error {
				// here we can edit the objects before they are
				// created in the cluster. if using Unstructured
				// the object is going to be of type Unstructured.
				deploy, ok := obj.(*appsv1.Deployment)
				if !ok {
					return nil
				}

				// as an example we append an annotation to the nginx
				// deployment we are creating.
				if deploy.Annotations == nil {
					deploy.Annotations = map[string]string{}
				}
				deploy.Annotations["this-is-a-mutation"] = "foo"
				return nil
			},
		),
		plumber.WithKustomizeMutator(
			func(ctx context.Context, k *types.Kustomization) error {
				// here we can edit the "kustomization.yaml"
				// before yaml files are rendered.
				return nil
			},
		),
		plumber.WithFSMutator(
			func(ctx context.Context, fs filesys.FileSystem) error {
				// here we can edit the filesystem before yaml files are
				// rendered with kustomize.
				return nil
			},
		),
	}

	// for sake of having a complete example, here we apply different overlays
	// on top of the base deployment.
	renderer := plumber.NewRenderer(cli, resources, options...)
	for _, overlay := range []string{"base", "scale-up", "scale-down"} {
		if err := renderer.Render(context.Background(), overlay); err != nil {
			panic(err)
		}
		fmt.Printf("overlay %q applied\n", overlay)
	}
}

Documentation

Index

Constants

View Source
const BaseKustomizationPath = "/kustomize/base/kustomization.yaml"

BaseKustomizationPath is the location for the base kustomization.yaml file. This controller expects to find this file among the read files from the embed reference. This is the file that, after parse, is send over to all registered KMutators for further transformations.

Variables

This section is empty.

Functions

func LoadFS

func LoadFS(content embed.FS) (filesys.FileSystem, error)

LoadFS loads an embed FS struct into an in memory kustomize file system representation. Reads all files from the embed and writes them to the FileSystem struct.

Types

type FSMutator

type FSMutator func(context.Context, filesys.FileSystem) error

FSMutator is a function that is intended to mutate a embed files prior to rendering them as a kustomize graph.

type KustomizeMutator

type KustomizeMutator func(context.Context, *types.Kustomization) error

KustomizeMutator is a function that is intended to mutate a Kustomization struct.

type ObjectMutator

type ObjectMutator func(context.Context, client.Object) error

ObjectMutator is a function that is intended to mutate a Kubernetes object.

type Option

type Option func(*Renderer)

Option is a function that sets an option in a Renderer.

func WithFSMutator

func WithFSMutator(mutator FSMutator) Option

WithFSMutator register a filesystem mutator into the controller. FS mutators are called before the Kustomize and Object mutators, allows for fine grained changes on the filesystem prior to rendering objects with kustomize.

func WithFieldOwner

func WithFieldOwner(owner string) Option

WithFieldOwner specifies the string to be used when patching objects. This sets the field manager on the patch request.

func WithForceOwnership

func WithForceOwnership() Option

WithForceOwnership sets the force ownership option during calls to Patch.

func WithKustomizeMutator

func WithKustomizeMutator(mutator KustomizeMutator) Option

WithKustomizeMutator register a Kustomization mutator into the controller.

func WithObjectMutator

func WithObjectMutator(mutator ObjectMutator) Option

WithObjectMutator register an Object mutator into the controller.

func WithPostApplyAction added in v2.3.1

func WithPostApplyAction(action PostApplyAction) Option

WithPostApplyAction register a post apply action into the controller. Post apply actions are called after the object is created in the API server. These actions are called sequentially and the creation of new objects is resumed once all actions return no error.

func WithUnstructured

func WithUnstructured() Option

WithUnstructured uses unstructured objects instead of typed ones.

type PostApplyAction added in v2.3.1

type PostApplyAction func(context.Context, client.Object) error

PostApplyAction is a function that is intended to be executed after the creation of an object. These functions are called after each object is created. The creation of new objects resumes once these functions returns no error.

type Renderer

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

Renderer is a base controller to provide some tooling around rendering and creating resources based in a kustomize directory struct. Files are expected to be injected into this controller by means of an embed.FS struct. The filesystem struct, inside the embed.FS struct, is expected to comply with the following layout:

/kustomize /kustomize/base/kustomization.yaml /kustomize/base/object_a.yaml /kustomize/base/object_a.yaml /kustomize/overlay0/kustomization.yaml /kustomize/overlay0/object_c.yaml /kustomize/overlay1/kustomization.yaml /kustomize/overlay1/object_d.yaml

In other words, we have a base kustomization under base/ directory and each other directory is treated as an overlay to be applied on top of base.

func NewRenderer

func NewRenderer(cli client.Client, emb embed.FS, opts ...Option) *Renderer

NewRenderer returns a kustomize renderer reading and applying files provided by the embed.FS reference. Files are read from 'emb' into a filesys.FileSystem representation and then used as argument to Kustomize when generating objects.

func (*Renderer) Apply added in v2.3.0

func (r *Renderer) Apply(ctx context.Context, overlay string) error

Apply applies provided overlay and creates objects in the kubernetes API using internal client. In case of failures there is no rollback so it is possible that this ends up partially creating the objects (returns at the first failure). Prior to object creation this function feeds all registered OMutators with the objects allowing for last time adjusts. Mutations in the default kustomization.yaml are also executed here.

func (*Renderer) Delete

func (r *Renderer) Delete(ctx context.Context, overlay string) error

Delete renders in memory the provided overlay and deletes all resulting objects from the kubernetes API. In case of failures there is no rollback so it is possible that this ends up partially deleting the objects (returns at the first failure).

Jump to

Keyboard shortcuts

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