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
- func LoadFS(content embed.FS) (filesys.FileSystem, error)
- type FSMutator
- type KustomizeMutator
- type ObjectMutator
- type Option
- func WithFSMutator(mutator FSMutator) Option
- func WithFieldOwner(owner string) Option
- func WithForceOwnership() Option
- func WithKustomizeMutator(mutator KustomizeMutator) Option
- func WithObjectMutator(mutator ObjectMutator) Option
- func WithPostApplyAction(action PostApplyAction) Option
- func WithUnstructured() Option
- type PostApplyAction
- type Renderer
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 ¶
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 ¶
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 ¶
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
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 ¶
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
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.
Source Files