ssa

package module
v0.61.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2025 License: Apache-2.0 Imports: 28 Imported by: 48

Documentation

Overview

Package ssa contains utilities for managing Kubernetes resources using sever-side apply. Adapted from https://github.com/stefanprodan/kustomizer/tree/v1.1.0/pkg/manager

Index

Constants

This section is empty.

Variables

View Source
var ReconcileOrder = KindOrder{
	First: []string{
		"CustomResourceDefinition",
		"Namespace",
		"ClusterRole",
		"ClusterClass",
		"RuntimeClass",
		"PriorityClass",
		"StorageClass",
		"VolumeSnapshotClass",
		"IngressClass",
		"GatewayClass",
		"ClusterRoleBinding",
		"ResourceQuota",
		"ServiceAccount",
		"Role",
		"RoleBinding",
		"ConfigMap",
		"Secret",
		"Service",
		"LimitRange",
		"Deployment",
		"StatefulSet",
		"CronJob",
		"PodDisruptionBudget",
	},
	Last: []string{
		"MutatingWebhookConfiguration",
		"ValidatingWebhookConfiguration",
	},
}

ReconcileOrder holds the list of the Kubernetes native kinds that describes in which order they are reconciled.

Functions

func Equals

func Equals(i, j schema.GroupKind) bool

func FieldsToSet added in v0.13.0

func FieldsToSet(f metav1.FieldsV1) (s fieldpath.Set, err error)

FieldsToSet creates a set paths from an input trie of fields

func IsLessThan

func IsLessThan(i, j schema.GroupKind) bool

func SanitizeUnstructuredData added in v0.33.0

func SanitizeUnstructuredData(old, new *unstructured.Unstructured) error

SanitizeUnstructuredData masks the "data" values of an Unstructured object, the objects are modified in place. If the data value is the same in both objects, the mask is replaced with a default mask. If the data value is different, the mask is replaced with a before and after mask.

func SetToFields added in v0.13.0

func SetToFields(s fieldpath.Set) (f metav1.FieldsV1, err error)

SetToFields creates a trie of fields from an input set of paths

Types

type Action

type Action string

Action represents the action type performed by the reconciliation process.

const (
	// CreatedAction represents the creation of a new object.
	CreatedAction Action = "created"
	// ConfiguredAction represents the update of an existing object.
	ConfiguredAction Action = "configured"
	// UnchangedAction represents the absence of any action to an object.
	UnchangedAction Action = "unchanged"
	// DeletedAction represents the deletion of an object.
	DeletedAction Action = "deleted"
	// SkippedAction represents the fact that no action was performed on an object
	// due to the object being excluded from the reconciliation.
	SkippedAction Action = "skipped"
	// UnknownAction represents an unknown action.
	UnknownAction Action = "unknown"
)

func (Action) String added in v0.24.0

func (a Action) String() string

String returns the string representation of the action.

type ApplyCleanupOptions added in v0.10.0

type ApplyCleanupOptions struct {
	// Annotations defines which 'metadata.annotations' keys should be removed from in-cluster objects.
	Annotations []string `json:"annotations,omitempty"`

	// Labels defines which 'metadata.labels' keys should be removed from in-cluster objects.
	Labels []string `json:"labels,omitempty"`

	// FieldManagers defines which `metadata.managedFields` managers should be removed from in-cluster objects.
	FieldManagers []FieldManager `json:"fieldManagers,omitempty"`

	// Exclusions determines which in-cluster objects are skipped from cleanup
	// based on the specified key-value pairs.
	Exclusions map[string]string `json:"exclusions"`
}

ApplyCleanupOptions defines which metadata entries are to be removed before applying objects.

type ApplyOptions added in v0.3.0

type ApplyOptions struct {
	// Force configures the engine to recreate objects that contain immutable field changes.
	Force bool `json:"force"`

	// ForceSelector determines which in-cluster objects are Force applied
	// based on the matching labels or annotations.
	ForceSelector map[string]string `json:"forceSelector"`

	// ExclusionSelector determines which in-cluster objects are skipped from apply
	// based on the matching labels or annotations.
	ExclusionSelector map[string]string `json:"exclusionSelector"`

	// IfNotPresentSelector determines which in-cluster objects are skipped from patching
	// based on the matching labels or annotations.
	IfNotPresentSelector map[string]string `json:"ifNotPresentSelector"`

	// WaitInterval defines the interval at which the engine polls for cluster
	// scoped resources to reach their final state.
	WaitInterval time.Duration `json:"waitInterval"`

	// WaitTimeout defines after which interval should the engine give up on waiting for
	// cluster scoped resources to reach their final state.
	WaitTimeout time.Duration `json:"waitTimeout"`

	// Cleanup defines which in-cluster metadata entries are to be removed before applying objects.
	Cleanup ApplyCleanupOptions `json:"cleanup"`
}

ApplyOptions contains options for server-side apply requests.

func DefaultApplyOptions added in v0.3.0

func DefaultApplyOptions() ApplyOptions

DefaultApplyOptions returns the default apply options where force apply is disabled.

type ChangeSet

type ChangeSet struct {
	Entries []ChangeSetEntry
}

ChangeSet holds the result of the reconciliation of an object collection.

func NewChangeSet

func NewChangeSet() *ChangeSet

NewChangeSet returns a ChangeSet with an empty slice of entries.

func (*ChangeSet) Add

func (c *ChangeSet) Add(e ChangeSetEntry)

Add appends the given ChangeSetEntry to the end of the slice.

func (*ChangeSet) Append

func (c *ChangeSet) Append(e []ChangeSetEntry)

Append adds the given ChangeSet entries to the end of the slice.

func (*ChangeSet) String

func (c *ChangeSet) String() string

String formats and returns the string representation of the ChangeSet by concatenating the string output of each entry.

func (*ChangeSet) ToGroupedMap added in v0.45.1

func (c *ChangeSet) ToGroupedMap() map[Action][]string

ToGroupedMap converts ChangeSet entries into a map grouped by Action, where keys are actions and values are subject slices.

func (*ChangeSet) ToMap

func (c *ChangeSet) ToMap() map[string]Action

ToMap converts the ChangeSet entries into a map where the keys are subjects and the values are the corresponding actions.

func (*ChangeSet) ToObjMetadataSet added in v0.2.0

func (c *ChangeSet) ToObjMetadataSet() object.ObjMetadataSet

ToObjMetadataSet converts the ChangeSet entries to an ObjMetadataSet by extracting the ObjMetadata from each entry.

type ChangeSetEntry

type ChangeSetEntry struct {
	// ObjMetadata holds the unique identifier of this entry.
	ObjMetadata object.ObjMetadata

	// GroupVersion holds the API group version of this entry.
	GroupVersion string

	// Subject represents the Object ID in the format 'kind/namespace/name'.
	Subject string

	// Action represents the action type taken by the reconciler for this object.
	Action Action
}

ChangeSetEntry defines the result of an action performed on an object.

func (ChangeSetEntry) String

func (e ChangeSetEntry) String() string

String returns a string representation of the ChangeSetEntry by combining its Subject and Action fields.

type DeleteOptions added in v0.3.0

type DeleteOptions struct {
	// PropagationPolicy determined whether and how garbage collection will be
	// performed.
	PropagationPolicy metav1.DeletionPropagation

	// Inclusions determines which in-cluster objects are subject to deletion
	// based on the specified key-value pairs.
	// A nil Inclusions map means all objects are subject to deletion
	// irregardless of their metadata labels.
	Inclusions map[string]string

	// Exclusions determines which in-cluster objects are skipped from deletion
	// based on the specified key-value pairs.
	// A nil Exclusions map means all objects are subject to deletion
	// irregardless of their metadata labels and annotations.
	Exclusions map[string]string
}

DeleteOptions contains options for delete requests.

func DefaultDeleteOptions added in v0.3.0

func DefaultDeleteOptions() DeleteOptions

DefaultDeleteOptions returns the default delete options where the propagation policy is set to background.

type DiffOptions added in v0.11.0

type DiffOptions struct {
	// Exclusions determines which in-cluster objects are skipped from dry-run apply
	// based on the matching labels or annotations.
	Exclusions map[string]string `json:"exclusions"`

	// IfNotPresentSelector determines which in-cluster objects are skipped from dry-run apply
	// based on the matching labels or annotations.
	IfNotPresentSelector map[string]string `json:"ifNotPresentSelector"`

	// Force configures the engine to recreate objects that contain immutable field changes.
	Force bool `json:"force"`

	// ForceSelector determines which in-cluster objects are Force applied
	// based on the matching labels or annotations.
	ForceSelector map[string]string `json:"forceSelector"`
}

DiffOptions contains options for server-side dry-run apply requests.

func DefaultDiffOptions added in v0.11.0

func DefaultDiffOptions() DiffOptions

DefaultDiffOptions returns the default dry-run apply options.

type FieldManager added in v0.12.0

type FieldManager struct {
	// Name is the name of the workflow managing fields.
	Name string `json:"name"`

	// ExactMatch controls the matching behavior for the manager name.
	// When true, requires an exact match. When false, it uses prefix matching.
	ExactMatch bool `json:"exactMatch"`

	// OperationType is the type of operation performed by this manager, can be 'update' or 'apply'.
	OperationType metav1.ManagedFieldsOperationType `json:"operationType"`
}

FieldManager identifies a workflow that's managing fields.

type JSONPatch added in v0.59.0

type JSONPatch struct {
	Operation string                      `json:"op"`
	Path      string                      `json:"path"`
	Value     []metav1.ManagedFieldsEntry `json:"value,omitempty"`
}

JSONPatch defines a patch as specified by RFC 6902 https://www.rfc-editor.org/rfc/rfc6902

func NewPatchRemove added in v0.59.0

func NewPatchRemove(path string) JSONPatch

NewPatchRemove returns a JSONPatch for removing the specified path.

func NewPatchReplace added in v0.59.0

func NewPatchReplace(path string, value []metav1.ManagedFieldsEntry) JSONPatch

NewPatchReplace returns a JSONPatch for replacing the specified path with the given value.

func PatchMigrateToVersion added in v0.59.0

func PatchMigrateToVersion(object *unstructured.Unstructured, apiVersion string) ([]JSONPatch, error)

PatchMigrateToVersion returns a JSONPatch array for replacing the existing apiVersion in the managed fields with the specified apiVersion.

func PatchRemoveAnnotations added in v0.23.0

func PatchRemoveAnnotations(object *unstructured.Unstructured, keys []string) []JSONPatch

PatchRemoveAnnotations returns a JSONPatch array for removing annotations with matching keys.

func PatchRemoveFieldsManagers added in v0.23.0

func PatchRemoveFieldsManagers(object *unstructured.Unstructured, managers []FieldManager) []JSONPatch

PatchRemoveFieldsManagers returns a JSONPatch array for removing managers with matching name or prefix.

func PatchRemoveLabels added in v0.23.0

func PatchRemoveLabels(object *unstructured.Unstructured, keys []string) []JSONPatch

PatchRemoveLabels returns a JSONPatch array for removing labels with matching keys.

func PatchReplaceFieldsManagers added in v0.23.0

func PatchReplaceFieldsManagers(object *unstructured.Unstructured, managers []FieldManager, name string) ([]JSONPatch, error)

PatchReplaceFieldsManagers returns a JSONPatch array for replacing the managers with matching name and operation type with the specified manager name and an apply operation.

type KindOrder added in v0.6.0

type KindOrder struct {
	First []string
	Last  []string
}

type Owner

type Owner struct {
	// Field sets the field manager name for the given server-side apply patch.
	Field string

	// Group sets the owner label key prefix.
	Group string
}

Owner contains options for setting the field manager and ownership labels group.

type ResourceManager

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

ResourceManager reconciles Kubernetes resources onto the target cluster using server-side apply.

func NewResourceManager

func NewResourceManager(client client.Client, poller *polling.StatusPoller, owner Owner) *ResourceManager

NewResourceManager creates a ResourceManager for the given Kubernetes client.

func (*ResourceManager) Apply

Apply performs a server-side apply of the given object if the matching in-cluster object is different or if it doesn't exist. Drift detection is performed by comparing the server-side dry-run result with the existing object. When immutable field changes are detected, the object is recreated if 'force' is set to 'true'.

func (*ResourceManager) ApplyAll

func (m *ResourceManager) ApplyAll(ctx context.Context, objects []*unstructured.Unstructured, opts ApplyOptions) (*ChangeSet, error)

ApplyAll performs a server-side dry-run of the given objects, and based on the diff result, it applies the objects that are new or modified.

func (*ResourceManager) ApplyAllStaged

func (m *ResourceManager) ApplyAllStaged(ctx context.Context, objects []*unstructured.Unstructured, opts ApplyOptions) (*ChangeSet, error)

ApplyAllStaged extracts the cluster and class definitions, applies them with ApplyAll, waits for them to become ready, then it applies all the other objects. This function should be used when the given objects have a mix of custom resource definition and custom resources, or a mix of namespace definitions with namespaced objects. If an error occurs during the apply of the cluster or class definitions, the change set is returned with the applied entries, up to that point, and the error is returned.

func (*ResourceManager) Client

func (m *ResourceManager) Client() client.Client

Client returns the underlying controller-runtime client.

func (*ResourceManager) Delete

Delete deletes the given object (not found errors are ignored).

func (*ResourceManager) DeleteAll

func (m *ResourceManager) DeleteAll(ctx context.Context, objects []*unstructured.Unstructured, opts DeleteOptions) (*ChangeSet, error)

DeleteAll deletes the given set of objects (not found errors are ignored).

func (*ResourceManager) Diff

Diff performs a server-side apply dry-un and returns the live and merged objects if drift is detected. If the diff contains Kubernetes Secrets, the data values are masked.

func (*ResourceManager) GetOwnerLabels

func (m *ResourceManager) GetOwnerLabels(name, namespace string) map[string]string

GetOwnerLabels returns a map of labels for the specified name and namespace.

func (*ResourceManager) SetConcurrency added in v0.31.0

func (m *ResourceManager) SetConcurrency(c int)

SetConcurrency sets how many goroutines execute concurrently to check for config drift when applying changes.

func (*ResourceManager) SetOwnerLabels

func (m *ResourceManager) SetOwnerLabels(objects []*unstructured.Unstructured, name, namespace string)

SetOwnerLabels adds the ownership labels to the given objects. The ownership labels are in the format:

<owner.group>/name: <name>
<owner.group>/namespace: <namespace>

func (*ResourceManager) Wait

func (m *ResourceManager) Wait(objects []*unstructured.Unstructured, opts WaitOptions) error

Wait checks if the given set of objects has been fully reconciled.

func (*ResourceManager) WaitForSet added in v0.2.0

func (m *ResourceManager) WaitForSet(set object.ObjMetadataSet, opts WaitOptions) error

WaitForSet checks if the given ObjMetadataSet has been fully reconciled.

func (*ResourceManager) WaitForSetTermination added in v0.47.0

func (m *ResourceManager) WaitForSetTermination(cs *ChangeSet, opts WaitOptions) error

WaitForSetTermination waits for the termination of resources specified in the given ChangeSet within the given options. Only resources marked for deletion are considered.

func (*ResourceManager) WaitForSetWithContext added in v0.58.0

func (m *ResourceManager) WaitForSetWithContext(ctx context.Context, set object.ObjMetadataSet, opts WaitOptions) error

WaitForSetWithContext checks if the given ObjMetadataSet has been fully reconciled. The provided context can be used to cancel the operation.

func (*ResourceManager) WaitForTermination

func (m *ResourceManager) WaitForTermination(objects []*unstructured.Unstructured, opts WaitOptions) error

WaitForTermination waits for the given objects to be deleted from the cluster.

type SortableMetas

type SortableMetas []object.ObjMetadata

func (SortableMetas) Len

func (a SortableMetas) Len() int

func (SortableMetas) Less

func (a SortableMetas) Less(i, j int) bool

func (SortableMetas) Swap

func (a SortableMetas) Swap(i, j int)

type SortableUnstructureds

type SortableUnstructureds []*unstructured.Unstructured

func (SortableUnstructureds) Len

func (a SortableUnstructureds) Len() int

func (SortableUnstructureds) Less

func (a SortableUnstructureds) Less(i, j int) bool

func (SortableUnstructureds) Swap

func (a SortableUnstructureds) Swap(i, j int)

type WaitOptions added in v0.3.0

type WaitOptions struct {
	// Interval defines how often to poll the cluster for the latest state of the resources.
	Interval time.Duration

	// Timeout defines after which interval should the engine give up on waiting for resources
	// to become ready.
	Timeout time.Duration

	// FailFast makes the Wait function return an error as soon as a resource reaches the failed state.
	FailFast bool
}

WaitOptions contains options for wait requests.

func DefaultWaitOptions added in v0.3.0

func DefaultWaitOptions() WaitOptions

DefaultWaitOptions returns the default wait options where the poll interval is set to five seconds and the timeout to one minute.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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