ssa

Documentation

Overview

Package ssa contains utils related to Server-Side-Apply.

Index

• func CleanUpManagedFieldsForSSAAdoption(ctx context.Context, c client.Client, obj client.Object, ssaManager string) error
• func ComputeRequestIdentifier(scheme *runtime.Scheme, original, modified client.Object) (string, error)
• func DropManagedFields(ctx context.Context, c client.Client, obj client.Object, ssaManager string, ...) error
• func FilterIntent(ctx *FilterIntentInput) bool
• func FilterObject(obj *unstructured.Unstructured, input *FilterObjectInput)
• func IsPathAllowed(allowedPaths []contract.Path) func(path contract.Path) bool
• func IsPathIgnored(ignorePaths []contract.Path) func(path contract.Path) bool
• func IsPathNotAllowed(allowedPaths []contract.Path) func(path contract.Path) bool
• func MatchFieldOwnership(manager string, operation metav1.ManagedFieldsOperationType, ...) types.GomegaMatcher
• func MatchManagedFieldsEntry(manager string, operation metav1.ManagedFieldsOperationType) types.GomegaMatcher
• func Patch(ctx context.Context, c client.Client, fieldManager string, ...) error
• type Cache
  • func NewCache() Cache
• type FilterIntentInput
• type FilterObjectInput
• type Option
• type Options
• type WithCachingProxy
  • func (w WithCachingProxy) ApplyToOptions(in *Options)

Functions

func CleanUpManagedFieldsForSSAAdoption

func CleanUpManagedFieldsForSSAAdoption(ctx context.Context, c client.Client, obj client.Object, ssaManager string) error

CleanUpManagedFieldsForSSAAdoption deletes the managedFields entries on the object that belong to "manager" (Operation=Update) if there is no field yet that is managed by `ssaManager`. It adds an "empty" entry in managedFields of the object if no field is currently managed by `ssaManager`.

In previous versions of Cluster API (< v1.4.0) we were writing objects with Create and Patch which resulted in fields being owned by the "manager". After switching to Server-Side-Apply (SSA), fields will be owned by `ssaManager`.

If we want to be able to drop fields that were previously owned by the "manager" we have to ensure that fields are not co-owned by "manager" and `ssaManager`. Otherwise, when we drop the fields with SSA (i.e. `ssaManager`) the fields would remain as they are still owned by "manager". The following code will do a one-time update on the managed fields to drop all entries for "manager". We won't do this on subsequent reconciles. This case will be identified by checking if `ssaManager` owns any fields. Dropping all existing "manager" entries (which could also be from other controllers) is safe, as we assume that if other controllers are still writing fields on the object they will just do it again and thus gain ownership again.

func ComputeRequestIdentifier

func ComputeRequestIdentifier(scheme *runtime.Scheme, original, modified client.Object) (string, error)

ComputeRequestIdentifier computes a request identifier for the cache. The identifier is unique for a specific request to ensure we don't have to re-run the request once we found out that it would not produce a diff. The identifier consists of: gvk, namespace, name and resourceVersion of the original object and a hash of the modified object. This ensures that we re-run the request as soon as either original or modified changes.

func DropManagedFields

func DropManagedFields(ctx context.Context, c client.Client, obj client.Object, ssaManager string, paths []contract.Path) error

DropManagedFields modifies the managedFields entries on the object that belong to "manager" (Operation=Update) to drop ownership of the given paths if there is no field yet that is managed by `ssaManager`.

If we want to be able to drop fields that were previously owned by the "manager" we have to ensure that fields are not co-owned by "manager" and `ssaManager`. Otherwise, when we drop the fields with SSA (i.e. `ssaManager`) the fields would remain as they are still owned by "manager". The following code will do a one-time update on the managed fields. We won't do this on subsequent reconciles. This case will be identified by checking if `ssaManager` owns any fields. Dropping ownership in paths for existing "manager" entries (which could also be from other controllers) is safe, as we assume that if other controllers are still writing fields on the object they will just do it again and thus gain ownership again.

func FilterIntent

func FilterIntent(ctx *FilterIntentInput) bool

FilterIntent ensures that object only includes the fields and values for which the controller has an opinion, and filter out everything else by removing it from the Value. NOTE: This func is called recursively only for fields of type Map, but this is ok given the current use cases this func has to address. More specifically, we are using this func for filtering out not allowed paths and for ignore paths; all of them are defined in reconcile_state.go and are targeting well-known fields inside nested maps. Allowed paths / ignore paths which point to an array are not supported by the current implementation.

func FilterObject

func FilterObject(obj *unstructured.Unstructured, input *FilterObjectInput)

FilterObject filter out changes not relevant for the controller.

func IsPathAllowed

func IsPathAllowed(allowedPaths []contract.Path) func(path contract.Path) bool

IsPathAllowed returns true when the Path is one of the AllowedPaths.

func IsPathIgnored

func IsPathIgnored(ignorePaths []contract.Path) func(path contract.Path) bool

IsPathIgnored returns true when the Path is one of the IgnorePaths.

func IsPathNotAllowed

func IsPathNotAllowed(allowedPaths []contract.Path) func(path contract.Path) bool

IsPathNotAllowed returns true when the Path is NOT one of the AllowedPaths.

func MatchFieldOwnership

func MatchFieldOwnership(manager string, operation metav1.ManagedFieldsOperationType, path contract.Path) types.GomegaMatcher

MatchFieldOwnership is a gomega Matcher to check if path is owned by the given manager and operation. Note: The path has to be specified as is observed in managed fields. Example: to check if the labels are owned by the correct manager the correct way to pass the path is contract.Path{"f:metadata","f:labels"}.

func MatchManagedFieldsEntry

func MatchManagedFieldsEntry(manager string, operation metav1.ManagedFieldsOperationType) types.GomegaMatcher

MatchManagedFieldsEntry is a gomega Matcher to check if a ManagedFieldsEntry has the given name and operation.

func Patch

func Patch(ctx context.Context, c client.Client, fieldManager string, modified client.Object, opts ...Option) error

Patch executes an SSA patch. If WithCachingProxy is set and the request didn't change the object we will cache this result, so subsequent calls don't have to run SSA again.

Types

type Cache

type Cache interface {
	// Add adds the given key to the Cache.
	// Note: keys expire after the ttl.
	Add(key string)

	// Has checks if the given key (still) exists in the Cache.
	// Note: keys expire after the ttl.
	Has(key string) bool
}

Cache caches SSA request results. Specifically we only use it to cache that a certain request doesn't have to be repeated anymore because there was no diff.

func NewCache

func NewCache() Cache

NewCache creates a new cache.

type FilterIntentInput

type FilterIntentInput struct {
	// the Path of the field being processed.
	Path contract.Path

	// the Value for the current Path.
	Value interface{}

	// ShouldFilter handle the func that determine if the current Path should be dropped or not.
	ShouldFilter func(path contract.Path) bool
}

FilterIntentInput holds info required while filtering the intent for server side apply. NOTE: in server side apply an intent is a partial object that only includes the fields and values for which the user has an opinion.

type FilterObjectInput

type FilterObjectInput struct {
	// AllowedPaths instruct FilterObject to ignore everything except given paths.
	AllowedPaths []contract.Path

	// IgnorePaths instruct FilterObject to ignore given paths.
	// NOTE: IgnorePaths are used to filter out fields nested inside AllowedPaths, e.g.
	// spec.ControlPlaneEndpoint.
	// NOTE: ignore paths which point to an array are not supported by the current implementation.
	IgnorePaths []contract.Path
}

FilterObjectInput holds info required while filtering the object.

type Option

type Option interface {
	// ApplyToOptions applies this configuration to the given Options.
	ApplyToOptions(*Options)
}

Option is the interface for configuration that modifies Options for a patch request.

type Options

type Options struct {
	WithCachingProxy bool
	Cache            Cache
	Original         client.Object
}

Options contains the options for the Patch func.

type WithCachingProxy

type WithCachingProxy struct {
	Cache    Cache
	Original client.Object
}

WithCachingProxy enables caching for the patch request. The original and modified object will be used to generate an identifier for the request. The cache will be used to cache the result of the request.

func (WithCachingProxy) ApplyToOptions

func (w WithCachingProxy) ApplyToOptions(in *Options)

ApplyToOptions applies WithCachingProxy to the given Options.