Documentation
¶
Overview ¶
Package ssa provides helpers for Server-Side Apply (SSA) workflows, including TypeConverter initialisation, diff-before-apply, and structured-merge-diff-based object merging.
Index ¶
- Constants
- func ApplyIfChanged(ctx context.Context, logger logr.Logger, cl client.Client, ...) (op.Result, error)
- func ApplyStatusIfChanged(ctx context.Context, logger logr.Logger, cl client.Client, ...) (op.Result, error)
- func FieldsWithRawBytes(raw []byte) *metav1.FieldsV1
- func FindManagedFieldsEntry(obj metav1.Object, fieldManager, subresource string) (metav1.ManagedFieldsEntry, bool)
- func MergeObjects(tc managedfields.TypeConverter, base, userOverlay runtime.Object) (*unstructured.Unstructured, error)
- type TypeConverterProvider
- func (p *TypeConverterProvider) CRDGroups() map[string]struct{}
- func (p *TypeConverterProvider) IsCRDGroupRelevant(group string) bool
- func (p *TypeConverterProvider) ObjectToTyped(obj runtime.Object, opts ...typed.ValidationOptions) (*typed.TypedValue, error)
- func (p *TypeConverterProvider) Ready(_ *http.Request) error
- func (p *TypeConverterProvider) Rebuild(ctx context.Context, logger logr.Logger, ...) error
- func (p *TypeConverterProvider) TypedToObject(v *typed.TypedValue) (runtime.Object, error)
Constants ¶
const FieldManager = "gateway-operator"
FieldManager is the field manager name used by the operator for Server-Side Apply operations.
Variables ¶
This section is empty.
Functions ¶
func ApplyIfChanged ¶
func ApplyIfChanged( ctx context.Context, logger logr.Logger, cl client.Client, tc managedfields.TypeConverter, desired client.Object, fieldManager string, ) (op.Result, error)
ApplyIfChanged performs a diff-before-apply using structured-merge-diff:
- Fetch the existing object from the API server.
- Convert both existing and desired to typed.TypedValue via TypeConverter.
- Compare using TypedValue.Compare().
- Issue a Server-Side Apply only when a difference is detected.
This prevents infinite reconcile loops on API server versions that incorrectly bump resourceVersion on no-op SSA patches.
func ApplyStatusIfChanged ¶
func ApplyStatusIfChanged( ctx context.Context, logger logr.Logger, cl client.Client, tc managedfields.TypeConverter, desired client.Object, fieldManager string, ) (op.Result, error)
ApplyStatusIfChanged is like ApplyIfChanged but operates on the status subresource. It compares fields owned by fieldManager under the "status" subresource via SMD and issues a Status().Apply only when a difference is detected, preventing spurious status patches on every reconcile.
func FieldsWithRawBytes ¶ added in v2.3.0
FieldsWithRawBytes returns a new FieldsV1 object with the given raw bytes.
func FindManagedFieldsEntry ¶ added in v2.3.0
func FindManagedFieldsEntry(obj metav1.Object, fieldManager, subresource string) (metav1.ManagedFieldsEntry, bool)
FindManagedFieldsEntry returns the ManagedFieldsEntry for the given field manager and subresource (pass "" for the main resource). Only entries with Operation=Apply are considered, matching the Server-Side Apply ownership model. Returns false if no matching entry exists.
func MergeObjects ¶
func MergeObjects(tc managedfields.TypeConverter, base, userOverlay runtime.Object) (*unstructured.Unstructured, error)
MergeObjects merges userOverlay into base using structured-merge-diff. User-provided values in userOverlay win on conflicts; the base supplies default values for fields the user has not specified. Returns an *unstructured.Unstructured so the caller can use the result directly with ApplyIfChanged or convert it to a typed struct.
Types ¶
type TypeConverterProvider ¶ added in v2.3.0
type TypeConverterProvider struct {
// contains filtered or unexported fields
}
TypeConverterProvider is a shared, always-current managedfields.TypeConverter. It implements the managedfields.TypeConverter interface directly, so it can be passed anywhere a managedfields.TypeConverter is expected (e.g. ApplyIfChanged, ApplyStatusIfChanged, MergeObjects).
CRD schemas are built in-process from the live CRD objects (apiserver-style, zero debounce latency); built-in schemas (core/v1, apps/v1) are fetched once from /openapi/v3. A dedicated CRD controller calls Rebuild whenever a relevant CRD changes, atomically swapping the live converter.
func NewTypeConverterProvider ¶ added in v2.3.0
func NewTypeConverterProvider(ctx context.Context, logger logr.Logger, mgr ctrl.Manager, crdGroups map[string]struct{}) (*TypeConverterProvider, error)
NewTypeConverterProvider builds a TypeConverterProvider scoped to crdGroups: it fetches the built-in schemas and lists the matching CRDs concurrently (via mgr's uncached API reader, safe to call before mgr.Start), then builds the initial converter. The returned provider is immediately usable.
func (*TypeConverterProvider) CRDGroups ¶ added in v2.3.0
func (p *TypeConverterProvider) CRDGroups() map[string]struct{}
CRDGroups returns the set of API groups managed by this provider.
func (*TypeConverterProvider) IsCRDGroupRelevant ¶ added in v2.3.0
func (p *TypeConverterProvider) IsCRDGroupRelevant(group string) bool
IsCRDGroupRelevant reports whether the given group is managed by this provider.
func (*TypeConverterProvider) ObjectToTyped ¶ added in v2.3.0
func (p *TypeConverterProvider) ObjectToTyped(obj runtime.Object, opts ...typed.ValidationOptions) (*typed.TypedValue, error)
ObjectToTyped implements managedfields.TypeConverter. Lock-free read.
func (*TypeConverterProvider) Ready ¶ added in v2.3.0
func (p *TypeConverterProvider) Ready(_ *http.Request) error
Ready implements the healthz.Checker interface. Returns nil once the first build has completed so the manager's readyz check passes only after the converter is ready.
func (*TypeConverterProvider) Rebuild ¶ added in v2.3.0
func (p *TypeConverterProvider) Rebuild(ctx context.Context, logger logr.Logger, crds []*apiextensionsv1.CustomResourceDefinition) error
Rebuild rebuilds the TypeConverter in-process from the provided CRD list and the cached built-in schemas, then atomically swaps the live converter. Concurrent callers (rare) coalesce: the last one to store wins, which is correct since each holds its own current CRD snapshot.
BuildOpenAPIV3 is only called for CRD versions whose resourceVersion has changed since the last build; unchanged versions reuse their cached spec.
func (*TypeConverterProvider) TypedToObject ¶ added in v2.3.0
func (p *TypeConverterProvider) TypedToObject(v *typed.TypedValue) (runtime.Object, error)
TypedToObject implements managedfields.TypeConverter.
Source Files