Documentation
¶
Overview ¶
Package built reads a resource as kustomize builds it once it is written: the object itself, or the objects a List holds. The layout writers' pre-write checks and the Flux integration read a resource through it, so they cannot disagree on which objects a resource holds.
Index ¶
- func AddAnnotations(obj client.Object, want map[string]string) func()
- func Annotations(obj client.Object) map[string]any
- func Labels(obj client.Object) map[string]any
- func LocalConfig(obj runtime.Object) (bool, error)
- func Text(obj client.Object) (objLabels, objAnnotations map[string]string, err error)
- func WrittenType(obj runtime.Object) (kind, apiVersion string, err error)
- type Object
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddAnnotations ¶
AddAnnotations gives obj each annotation of want whose key it does not carry, and keeps every annotation it carries as written (Annotations). It returns how to put obj back exactly as it was, or nil when it changed nothing: when obj already carries every key of want, or when obj is unstructured and its metadata is present but no map, which holds no annotations and takes none.
func Annotations ¶
Annotations returns obj's annotations as written. For an unstructured object that is its metadata.annotations map as it is: decoded from YAML, it may hold a boolean, a number or null, and then Unstructured.GetAnnotations returns none at all, so that setting annotations from it drops every one. For a typed object it is GetAnnotations. The map returned is a copy. Text reads its values as a kustomize build does.
func Labels ¶
Labels returns obj's labels as written, as Annotations returns its annotations: for an unstructured object its metadata.labels map as it is, for which Unstructured.GetLabels returns none at all once it holds a value that is no string, and for a typed object GetLabels. The map returned is a copy. Text reads its values as a kustomize build does.
func LocalConfig ¶
LocalConfig reports whether obj is written with kustomize's local-config annotation (konfig.IgnoredByKustomizeAnnotation) at any value but false: the string "false" or the boolean false. kustomize reads the value as the text of the YAML node it is written as (kyaml v0.21.2 RNode.GetMeta and GetValue, yaml/rnode.go:322-326 and :54-58), keeps the object where that text is exactly "false" (Factory.DropLocalNodes, resource/factory.go:149-150) and drops it at any other: "true", "False", "", a number, null (read as ""), a map or a list (no text, read as ""). The writers marshal an object to JSON first, so the value is judged by its JSON, whatever its Go type: an unstructured object decoded from YAML holds a boolean or a number as one. A kustomize build drops such an object once it has run its transformers, and does not require an apiVersion: by kustomize api v0.21.2 it reads the kind of every object it takes in, and the name of every one whose kind does not end in "List", and refuses one without (Factory.dropBadNodes, resource/factory.go:253-268), and then drops the object (KustTarget.IgnoreLocal, internal/target/kusttarget.go:255-265; Factory.DropLocalNodes, resource/factory.go:134-155). Like WrittenType it reads what is written, not the Go value.
func Text ¶
Text returns obj's labels and annotations as written (Labels, Annotations) as a kustomize build reads them from what the writers write. kustomize takes such a value as the text of its YAML node (kyaml v0.21.2 RNode.GetLabels and GetAnnotations through getMapFromMeta, yaml/rnode.go:519-570), and selects a patch's targets by those texts (RNode.MatchesLabelSelector and MatchesAnnotationSelector, yaml/rnode.go:1191-1206). So a boolean reads as "true" or "false", a number as the writers write it ("3", "1.5", and a whole float64 as an integer, "2"), null as "null", and a map or a list, which is no scalar, as "". A string reads as itself, unless it is no valid UTF-8: the writers' JSON replaces each invalid byte with U+FFFD. And what the writers leave out is not read at all: they drop the kubectl.kubernetes.io/last-applied-configuration annotation.
The writers marshal an object to JSON and clean its metadata before they write it as YAML (kio.EncodeObjectsToYAML), so Text does not restate their rules: it writes both maps through them, as the metadata of an object of their own, and reads them back as kustomize does.
func WrittenType ¶
WrittenType returns the kind and the apiVersion obj is written with: the two top-level fields of the JSON the writers marshal it to, which is what a kustomize build reads them from. Each is empty where the field is absent, null, empty or no string. A typed object is read from its written form and not from its Go value, so one whose TypeMeta is unset has neither, whatever its Go type is.
Types ¶
type Object ¶
type Object struct {
// Object is the resource itself, or an item of a List it is or holds. An
// item of a typed List can be any runtime.Object, so it need not carry
// object metadata.
runtime.Object
// Read is set when the object is not a Go value the resource holds but
// was read from what the resource writes in its place: an item a typed
// List holds as raw JSON, an item of a typed object that writes an items
// field its Go value gives no access to, and whatever such an item holds.
// It has the content that is written, and a change to it is not a change
// to the resource.
Read bool
}
Object is one object kustomize builds from a resource.
func Objects ¶
Objects returns the objects kustomize builds from r once it is written: r itself, or the objects a List holds, a List among them opened the same way.
A List is what kustomize takes for one (its resource factory's inlineAnyEmbeddedLists): an object whose kind ends in "List" and that has an items field. Any other kind is one object, whatever fields it has, and so is a kind ending in "List" without items. A List whose items are null holds nothing; one whose items are not an array fails the kustomize build and is returned as the one object it is, since there is nothing in it to read.
For a typed object the kind and the items field are read from its written form, the JSON the writers marshal it to, not from its Go value: one whose written kind does not end in "List" is no List, whatever kind its Go value reports (one whose TypeMeta is left out of that JSON writes no kind, unless another field writes one), and one that writes a kind ending in "List" is opened as one. Of the items field, a field left out when empty counts as absent, and one written as null or as something that is no array is read as that, whatever the Go value holds beside it. The items are the ones its Go value gives access to, read as the writers serialize them (rawItems): an item held as raw JSON is the object that JSON encodes, and an empty item holds nothing, as does one that is a nil pointer, which is written as null. A List among them need not carry object metadata (metav1.List has none) to be opened. A typed object that writes its items from a field apimachinery does not take for a list's items, so that its Go value gives no access to them or gives other ones, has them read from the written form (writtenAs).
The items of an unstructured List are the List's own: a change to one is a change to the List. They are read from its map and not from a written form, so one that holds itself, directly or through the Lists it holds, would be opened without end: it is refused. So is a typed List that holds itself as the object of an item, where apimachinery takes it and the Lists between for lists (refuseItemCycle): where each of them writes its Items it cannot be marshalled, and where one does not it is refused by the same rule. No other value that reaches itself is looked for.