objectclient

package
v1.76.0 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package objectclient provides retrying, dynamic.Interface-based create-or-update ("Apply"), Get, and delete-if-present ("Uninstall") helpers for arbitrary Kubernetes objects. It is deliberately dynamic-client-based rather than controller-runtime client.Client-based: callers that already carry a dynamic.Interface (e.g. because their own reconciliation model is schema-unknown-at-compile-time) can use it without adopting a second client type.

Because objects are applied through the dynamic client, obj's GroupVersionKind must be set explicitly by the caller (TypeMeta) before calling Apply — a struct built via runtime.DefaultUnstructuredConverter or a bare unstructured.Unstructured literal often leaves TypeMeta empty, which makes the apply fail with "no kind is registered" or an equivalent low-level error.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Get

Get reads the object named name in namespace ns (cluster-scoped when ns is empty).

Types

type ApplyOp added in v1.55.0

type ApplyOp string

ApplyOp is the write Apply sent, and what the apiserver made of it.

const (
	// ApplyCreated: no object existed, and a Create was sent.
	ApplyCreated ApplyOp = "created"
	// ApplyUpdated: an Update was sent, and the apiserver persisted a change (resourceVersion moved).
	ApplyUpdated ApplyOp = "updated"
	// ApplyUnchanged: an Update was sent, and the apiserver persisted nothing (resourceVersion
	// unmoved). The apiserver short-circuits an Update whose result equals the stored object, so the
	// cluster keeps no trace of it: a caller recording changes records none here.
	ApplyUnchanged ApplyOp = "unchanged"
	// ApplyDryRun: the request was a dry run (ApplyOptions.DryRun). It was validated and NOT
	// persisted, whatever it would have changed, so it is not a write: a caller recording writes
	// records none, by construction. Returned for every dry-run request, created or updated, and on
	// a refused one too. Before and After are as for the write it stood in for.
	ApplyDryRun ApplyOp = "dryRun"
)

type ApplyOptions

type ApplyOptions struct {
	// DryRun causes the request to be validated but not persisted. The only valid value is "All".
	DryRun []string
	// FieldManager is the name of the user or component submitting this request. Required for
	// server-side apply; recommended for ordinary Create/Update so field ownership is attributable.
	FieldManager string
	// FieldValidation controls how the server reacts to unknown/duplicate fields ("Ignore" | "Warn" |
	// "Strict").
	FieldValidation string
	// FromCurrent, when set, is called on the UPDATE path of every attempt, after the existing object
	// is read and before it is replaced, with that object and a fresh copy of the desired one. It lets
	// a caller keep a field that another writer owns, copied from the very version being replaced: a
	// 409 from a concurrent write re-reads the object and calls FromCurrent again, so the copied value
	// can never be older than the object the Update replaces. Not called on create (there is nothing
	// to copy from). An error from it ends Apply without retrying: it is the caller's verdict, not a
	// transient failure.
	FromCurrent func(current, desired *unstructured.Unstructured) error
}

ApplyOptions mirrors metav1.CreateOptions/UpdateOptions, minus the fields Apply computes itself (Apply always uses the current resourceVersion for updates).

type ApplyResult added in v1.55.0

type ApplyResult struct {
	Op ApplyOp
	// Before is the object as read just before the write, the version the Update replaced. nil when
	// Op is ApplyCreated.
	Before *unstructured.Unstructured
	// After is the object the apiserver returned, the same content Apply writes back into obj.
	After *unstructured.Unstructured
}

ApplyResult is what Apply did (core-provider#423: a caller writing one audit record per real change must know which write happened, and what it changed).

func Apply

Apply creates obj if no object with its namespace/name exists yet, or updates it (carrying over the current resourceVersion) if one does, and reports which (ApplyResult). It retries on any transient error other than context cancellation, since the read-then-write is not atomic and can race a concurrent writer.

On success obj is REPLACED IN PLACE with the object the apiserver returned — i.e. the fully materialized resource, with server defaults, admission mutations and the new resourceVersion applied (this holds even under DryRun, where the response is the object as it WOULD be persisted). Callers that hash or compare the applied resource against a later live Get must have both sides reflect the same server-defaulted shape; without this write-back Apply would leave obj as the bare pre-apply render, so an apply-then-hash digest could never equal a get-then-hash digest of the same object (core-provider CompositionDefinition Observe deployed-digest gate never converged, so the CD never reached Available).

The result is the final attempt's. A dry-run request (ApplyOptions.DryRun) is reported ApplyDryRun, never created, updated or unchanged: nothing was persisted. The response is still the would-be object, written back into obj as described above.

On error the result names the write the final attempt SENT, so a caller recording writes can record a failed one (core-provider#423): Op is ApplyCreated for a Create the apiserver refused, ApplyUpdated for a refused Update (with Before, the version it tried to replace), and "" when no write was sent (the read failed, or FromCurrent refused). After is nil: nothing was persisted.

type UninstallOp added in v1.55.0

type UninstallOp string

UninstallOp is what Uninstall found and did.

const (
	// UninstallDeleted: the object existed and the apiserver accepted its Delete. An object with
	// finalizers is then terminating, not yet gone.
	UninstallDeleted UninstallOp = "deleted"
	// UninstallAbsent: there was nothing to delete, absent before the call or removed concurrently
	// (the Delete answered NotFound). Not a write of this caller's.
	UninstallAbsent UninstallOp = "absent"
	// UninstallDryRun: the Delete was a dry run (UninstallOptions.DryRun): validated, NOT persisted,
	// so not a write. Returned for an accepted and a refused dry-run Delete alike, with Before.
	UninstallDryRun UninstallOp = "dryRun"
)

type UninstallOptions

type UninstallOptions struct {
	GracePeriodSeconds *int64
	Preconditions      *metav1.Preconditions
	PropagationPolicy  *metav1.DeletionPropagation
	DryRun             []string
}

UninstallOptions mirrors metav1.DeleteOptions.

type UninstallResult added in v1.55.0

type UninstallResult struct {
	Op UninstallOp
	// Before is the object as read just before the Delete; nil when Op is UninstallAbsent.
	Before *unstructured.Unstructured
}

UninstallResult is what Uninstall did.

func Uninstall

Uninstall deletes the object named name in namespace ns (cluster-scoped when ns is empty), and reports whether it did. A missing object, whether absent before the call or removed concurrently, is treated as success (UninstallAbsent).

On error the result names the write the final attempt sent: Op is UninstallDeleted, with Before, for a Delete the apiserver refused, and "" when no Delete was sent (the read failed).

Jump to

Keyboard shortcuts

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