objectclient

package
v1.56.0 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 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"
)

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. Under DryRun nothing is persisted and the resourceVersion says nothing, so a dry-run Update is reported ApplyUpdated, never ApplyUnchanged.

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"
)

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).

Jump to

Keyboard shortcuts

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