apply

Documentation

Index

• Variables
• type Applier
  • func New(clusterConfig *rest.Config, fieldManager string) (*Applier, *runtime.Scheme, error)
  • func (ac *Applier) Apply(yamlResource YamlDocument, namespace string) error
  • func (ac *Applier) ApplyWithOwner(yamlResource YamlDocument, namespace string, owningResource metav1.Object) error
• type ApplyFilter
• type Builder
  • func NewBuilder(applier applier) *Builder
  • func (ab *Builder) ExecuteApply() error
  • func (ab *Builder) WithApplyFilter(filter ApplyFilter) *Builder
  • func (ab *Builder) WithCollector(collector PredicatedResourceCollector) *Builder
  • func (ab *Builder) WithNamespace(namespace string) *Builder
  • func (ab *Builder) WithOwner(owningResource metav1.Object) *Builder
  • func (ab *Builder) WithTemplate(filename string, templateObject interface{}) *Builder
  • func (ab *Builder) WithYamlResource(filename string, yamlResource []byte) *Builder
• type Logger
• type PredicatedResourceCollector
• type ResourceError
  • func NewResourceError(err error, wrapperErrMsg, kind, apiVersion, resourceName string) *ResourceError
  • func (e *ResourceError) Error() string
  • func (e *ResourceError) Unwrap() error
• type YamlDocument

Variables

var GetLogger = func() Logger { return logrus.StandardLogger() }

GetLogger is an alias function to provide a different logger for the core.

Types

type Applier

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

Applier provides a way to apply unstructured Kubernetes resources to the API without knowing their respective schemes beforehand.

func New

func New(clusterConfig *rest.Config, fieldManager string) (*Applier, *runtime.Scheme, error)

New returns a `kubectl`-like apply client which operates on the K8s API with YAML resources.

Both parameters clusterConfig and fieldManager are mandatory parameters. ClusterConfig contains values how to interact with the Kubernetes API. FieldManager contains a non-empty string to track value changes in the resources which are about to apply so that unexpected changes can be detected. A sensible value might be the name of the calling application. See also: https://kubernetes.io/docs/reference/using-api/server-side-apply/#field-management

This method also returns a runtime.Scheme which will be used to properly handle owner references (most important when working with your own CRD). Use it like this:

applier, scheme, err := apply.New(config, "your-field-manager-name")
yourCrdGroupVersion.AddToScheme(scheme)

func (*Applier) Apply

func (ac *Applier) Apply(yamlResource YamlDocument, namespace string) error

Apply sends a request to the K8s API with the provided YAML resource in order to apply them to the current cluster.

func (*Applier) ApplyWithOwner

func (ac *Applier) ApplyWithOwner(yamlResource YamlDocument, namespace string, owningResource metav1.Object) error

ApplyWithOwner sends a request to the K8s API with the provided YAML resource in order to apply them to the current cluster.

type ApplyFilter

type ApplyFilter interface {
	// Predicate returns true if the resource being effectively applied matches against a given predicate.
	Predicate(doc YamlDocument) (bool, error)
}

ApplyFilter help to filter specific Kubernetes resources that stream through the applier and applies them. It is the implementor's task to provide the predicate to match the resource that should not be applied. The filtered resources are still collected.

An example implementation to only apply namespace resources could look like this:

func (c *filter) Predicate(doc YamlDocument) (bool, error) {
  var namespace = &v1.Namespace{}
  if err := yaml.Unmarshal(doc, namespace); err != nil { return false, err }
  return namespace.Kind == "Namespace", nil
}

type Builder

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

Builder provides a convenience builder that simplifies the Applier usage and adds often-sought features, like doc splitting or templating.

Usage:

 applier, _, err := apply.New(restConfig)
 NewBuilder(applier).
   WithNamespace("my-namespace").
	  WithYamlResource(myfile, content).
	  WithTemplate(myfile, templateObject).
	  WithYamlResource(myfile2, content2).
	  WithTemplate(myfile2, templateObject2).
	  WithApplyFilter(myFilterImplementation).
   ExecuteApply()

func NewBuilder

func NewBuilder(applier applier) *Builder

NewBuilder creates a new builder.

func (*Builder) ExecuteApply

func (ab *Builder) ExecuteApply() error

ExecuteApply executes applies pending template renderings to the cumulated resources, collects resources for any configured collectors, and applies the result against the configured Kubernetes API.

func (*Builder) WithApplyFilter

func (ab *Builder) WithApplyFilter(filter ApplyFilter) *Builder

WithApplyFilter set the given ApplyFilter. This method is optional. When the applyFilter exists, only resources that match this filter will be applied.

func (*Builder) WithCollector

func (ab *Builder) WithCollector(collector PredicatedResourceCollector) *Builder

WithCollector adds the given PredicatedResourceCollector to list of collectors. This method is optional.

func (*Builder) WithNamespace

func (ab *Builder) WithNamespace(namespace string) *Builder

WithNamespace sets the target namespace to which the file's resources will apply. This method is mandatory.

func (*Builder) WithOwner

func (ab *Builder) WithOwner(owningResource metav1.Object) *Builder

WithOwner maintains an owner reference for the YAML resource that should be applied during ExecuteApply. If the owning resource is deleted then all associated resources will be deleted as well. This method is optional.

func (*Builder) WithTemplate

func (ab *Builder) WithTemplate(filename string, templateObject interface{}) *Builder

WithTemplate adds templating features to the YAML resource with the given filename. This method is optional.

func (*Builder) WithYamlResource

func (ab *Builder) WithYamlResource(filename string, yamlResource []byte) *Builder

WithYamlResource adds another YAML resource to the builder.

type Logger

type Logger interface {
	// Debug logs messages that generally should not be visible within a production environment but useful when trying
	// to pinpoint error situations during the development.
	Debug(args ...interface{})
	// Info logs messages that may be of general interest but do not state any danger.
	Info(args ...interface{})
	// Warning logs error messages that may require the attention of the user.
	Warning(args ...interface{})
	// Error logs error messages that may jeopardize the success during the run-time.
	Error(args ...interface{})

	// Debugf logs messages that generally should not be visible within a production environment but useful when trying
	// to pinpoint error situations during the development.
	Debugf(format string, args ...interface{})
	// Infof logs messages that may be of general interest but do not state any danger.
	Infof(format string, args ...interface{})
	// Warningf logs error messages that may require the attention of the user.
	Warningf(format string, args ...interface{})
	// Errorf logs error messages that may jeopardize the success during the run-time.
	Errorf(format string, args ...interface{})
}

Logger provides a simple definition of Logging methods that may be used within this project. Logger implementations can be set by getting the current logger referent with GetLogger and to replace it with one's own implementation.

type PredicatedResourceCollector

type PredicatedResourceCollector interface {
	// Predicate returns true if the resource being effectively applied matches against a given predicate.
	Predicate(doc YamlDocument) (bool, error)
	// Collect cumulates all YAML documents that match the predicate over the whole resource application against the
	// Kubernetes API.
	Collect(doc YamlDocument)
}

PredicatedResourceCollector help to identify and collect specific Kubernetes resources that stream through the applier. It is the implementor's task to provide both the predicate to match the resource and to handle the resource collection. The collected resources can be fetched after the Applier/Builder finished applying the resources to the Kubernetes API.

An example implementation to collect namespace resources might look like this:

func (c *collector) Predicate(doc YamlDocument) (bool, error) {
  var namespace = &v1.Namespace{}
  if err := yaml.Unmarshal(doc, namespace); err != nil { return false, err }
  return namespace.Kind == "Namespace", nil
}

func (c *collector) Collect(doc YamlDocument) {
  c.collected = append(c.collected, doc)
}

type ResourceError

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

ResourceError wraps an original, Kubernetes-centric error and takes additional arguments to identify a K8s resource by kind, version and name

func NewResourceError

func NewResourceError(err error, wrapperErrMsg, kind, apiVersion, resourceName string) *ResourceError

NewResourceError creates a custom K8s error that identifies the resource by kind, version and name.

func (*ResourceError) Error

func (e *ResourceError) Error() string

Error returns the string representation of this error.

func (*ResourceError) Unwrap

func (e *ResourceError) Unwrap() error

Unwrap returns the original error.

type YamlDocument

type YamlDocument []byte

YamlDocument is an alias type for exactly one single YAML document.