The highest tagged major version is
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 ¶
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 ¶
Types ¶
type FSMutator ¶ added in v1.13.0
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 ¶
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 ¶ added in v1.13.0
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 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 WithUnstructured ¶ added in v1.12.0
func WithUnstructured() Option
WithUnstructured uses unstructured objects instead of typed ones.
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 ¶
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) Render ¶
Render 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.
Source Files