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 ¶
- Variables
- func Equals(i, j schema.GroupKind) bool
- func FieldsToSet(f metav1.FieldsV1) (s fieldpath.Set, err error)
- func IsLessThan(i, j schema.GroupKind) bool
- func SanitizeUnstructuredData(old, new *unstructured.Unstructured) error
- func SetToFields(s fieldpath.Set) (f metav1.FieldsV1, err error)
- type Action
- type ApplyCleanupOptions
- type ApplyOptions
- type ChangeSet
- type ChangeSetEntry
- type DeleteOptions
- type DiffOptions
- type FieldManager
- type JSONPatch
- func NewPatchRemove(path string) JSONPatch
- func NewPatchReplace(path string, value []metav1.ManagedFieldsEntry) JSONPatch
- func PatchMigrateToVersion(object *unstructured.Unstructured, apiVersion string) ([]JSONPatch, error)
- func PatchRemoveAnnotations(object *unstructured.Unstructured, keys []string) []JSONPatch
- func PatchRemoveFieldsManagers(object *unstructured.Unstructured, managers []FieldManager) []JSONPatch
- func PatchRemoveLabels(object *unstructured.Unstructured, keys []string) []JSONPatch
- func PatchReplaceFieldsManagers(object *unstructured.Unstructured, managers []FieldManager, name string) ([]JSONPatch, error)
- type KindOrder
- type Owner
- type ResourceManager
- func (m *ResourceManager) Apply(ctx context.Context, object *unstructured.Unstructured, opts ApplyOptions) (*ChangeSetEntry, error)
- func (m *ResourceManager) ApplyAll(ctx context.Context, objects []*unstructured.Unstructured, opts ApplyOptions) (*ChangeSet, error)
- func (m *ResourceManager) ApplyAllStaged(ctx context.Context, objects []*unstructured.Unstructured, opts ApplyOptions) (*ChangeSet, error)
- func (m *ResourceManager) Client() client.Client
- func (m *ResourceManager) Delete(ctx context.Context, object *unstructured.Unstructured, opts DeleteOptions) (*ChangeSetEntry, error)
- func (m *ResourceManager) DeleteAll(ctx context.Context, objects []*unstructured.Unstructured, opts DeleteOptions) (*ChangeSet, error)
- func (m *ResourceManager) Diff(ctx context.Context, object *unstructured.Unstructured, opts DiffOptions) (*ChangeSetEntry, *unstructured.Unstructured, *unstructured.Unstructured, error)
- func (m *ResourceManager) GetOwnerLabels(name, namespace string) map[string]string
- func (m *ResourceManager) SetConcurrency(c int)
- func (m *ResourceManager) SetOwnerLabels(objects []*unstructured.Unstructured, name, namespace string)
- func (m *ResourceManager) Wait(objects []*unstructured.Unstructured, opts WaitOptions) error
- func (m *ResourceManager) WaitForSet(set object.ObjMetadataSet, opts WaitOptions) error
- func (m *ResourceManager) WaitForSetTermination(cs *ChangeSet, opts WaitOptions) error
- func (m *ResourceManager) WaitForSetWithContext(ctx context.Context, set object.ObjMetadataSet, opts WaitOptions) error
- func (m *ResourceManager) WaitForTermination(objects []*unstructured.Unstructured, opts WaitOptions) error
- type SortableMetas
- type SortableUnstructureds
- type WaitOptions
Constants ¶
This section is empty.
Variables ¶
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 FieldsToSet ¶ added in v0.13.0
FieldsToSet creates a set paths from an input trie of fields
func IsLessThan ¶
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.
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" )
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 ¶
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
ToGroupedMap converts ChangeSet entries into a map grouped by Action, where keys are actions and values are subject slices.
func (*ChangeSet) ToMap ¶
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
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 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 ¶
func (m *ResourceManager) Apply(ctx context.Context, object *unstructured.Unstructured, opts ApplyOptions) (*ChangeSetEntry, error)
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 ¶
func (m *ResourceManager) Delete(ctx context.Context, object *unstructured.Unstructured, opts DeleteOptions) (*ChangeSetEntry, error)
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 ¶
func (m *ResourceManager) Diff(ctx context.Context, object *unstructured.Unstructured, opts DiffOptions) ( *ChangeSetEntry, *unstructured.Unstructured, *unstructured.Unstructured, error, )
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.