tree

package
v1.11.1 Latest Latest
Warning

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

 Go to latest Published: Sep 2, 2025 License: Apache-2.0 Imports: 19 Imported by: 5

Documentation

Overview

Package tree supports the generation of an "at glance" view of a Cluster API cluster designed to help the user in quickly understanding if there are problems and where.

The "at glance" view is based on the idea that we should avoid to overload the user with information, but instead surface problems, if any; in practice:

  • The view assumes we are processing objects conforming with https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20200506-conditions.md. As a consequence each object should have a Ready condition summarizing the object state.

  • The view organizes objects in a hierarchical tree, however it is not required that the tree reflects the ownerReference tree so it is possible to skip objects not relevant for triaging the cluster status e.g. secrets or templates.

  • It is possible to add "meta names" to object, thus making hierarchical tree more consistent for the users, e.g. use MachineInfrastructure instead of using all the different infrastructure machine kinds (AWSMachine, VSphereMachine etc.).

  • It is possible to add "virtual nodes", thus allowing to make the hierarchical tree more meaningful for the users, e.g. adding a Workers object to group all the MachineDeployments.

  • It is possible to "group" siblings objects by ready condition e.g. group all the machines with Ready=true in a single node instead of listing each one of them.

  • Given that the ready condition of the child object bubbles up to the parents, it is possible to avoid the "echo" (reporting the same condition at the parent/child) e.g. if a machine's Ready condition is already surface an error from the infrastructure machine, let's avoid to show the InfrastructureMachine given that representing its state is redundant in this case.

  • In order to avoid long list of objects (think e.g. a cluster with 50 worker machines), sibling objects with the same value for the ready condition can be grouped together into a virtual node, e.g. 10 Machines ready

The ObjectTree object defined implements all the above behaviors of the "at glance" visualization, by generating a tree of Kubernetes objects; each object gets a set of annotation, reflecting its own visualization specific attributes, e.g is virtual node, is group node, meta name etc.

The Discovery object uses the ObjectTree to build the "at glance" view of a Cluster API.

Index

Constants

View Source 
const (
	// ShowObjectConditionsAnnotation documents that the presentation layer should show all the conditions for the object.
	ShowObjectConditionsAnnotation = "tree.cluster.x-k8s.io.io/show-conditions"

	// ObjectMetaNameAnnotation contains the meta name that should be used for the object in the presentation layer,
	// e.g. control plane for KCP.
	ObjectMetaNameAnnotation = "tree.cluster.x-k8s.io.io/meta-name"

	// VirtualObjectAnnotation documents that the object does not correspond to any real object, but instead is
	// a virtual object introduced to provide a better representation of the cluster status, e.g. workers.
	VirtualObjectAnnotation = "tree.cluster.x-k8s.io.io/virtual-object"

	// GroupingObjectAnnotation is an annotation that should be applied to a node in order to trigger the grouping action
	// when adding the node's children. e.g. if you have a control-plane node, and you apply this annotation, then
	// the control-plane machines added as a children of this node will be grouped in case the ready condition
	// has the same Status, Severity and Reason.
	GroupingObjectAnnotation = "tree.cluster.x-k8s.io.io/grouping-object"

	// GroupObjectAnnotation is an annotation that documents that a node is the result of a grouping operation, and
	// thus the node is representing group of sibling nodes, e.g. a group of machines.
	GroupObjectAnnotation = "tree.cluster.x-k8s.io.io/group-object"

	// GroupItemsAnnotation contains the list of names for the objects included in a group object.
	GroupItemsAnnotation = "tree.cluster.x-k8s.io.io/group-items"

	// GroupItemsAvailableCounter contains the number of available objects in the group, e.g. available Machines.
	GroupItemsAvailableCounter = "tree.cluster.x-k8s.io.io/group-items-available-count"

	// GroupItemsReadyCounter contains the number of ready objects in the group, e.g. ready Machines.
	GroupItemsReadyCounter = "tree.cluster.x-k8s.io.io/group-items-ready-count"

	// GroupItemsUpToDateCounter contains the number of up-to-date objects in the group, e.g. up-to-date Machines.
	GroupItemsUpToDateCounter = "tree.cluster.x-k8s.io.io/group-items-up-to-date-count"

	// ObjectContractAnnotation is added to unstructured objects to track which Cluster API contract those objects abide to.
	// Note: Currently this annotation is applied only to control plane objects.
	ObjectContractAnnotation = "tree.cluster.x-k8s.io.io/object-contract"

	// ObjectContractVersionAnnotation is added to unstructured objects to track which Cluster API contract version those objects abide to.
	// Note: Currently this annotation is applied only to control plane objects.
	ObjectContractVersionAnnotation = "tree.cluster.x-k8s.io.io/object-contract-version"

	// GroupItemsSeparator is the separator used in the GroupItemsAnnotation.
	GroupItemsSeparator = ", "

	// ObjectZOrderAnnotation contains an integer that defines the sorting of child objects when the object tree is printed.
	// Objects are sorted by their z-order from highest to lowest, and then by their name in alphabetical order if the
	// z-order is the same. Objects with no z-order set are assumed to have a default z-order of 0.
	ObjectZOrderAnnotation = "tree.cluster.x-k8s.io.io/z-order"
)

Variables

View Source 
var GroupVersionVirtualObject = schema.GroupVersion{Group: "virtual.cluster.x-k8s.io", Version: clusterv1.GroupVersion.Version}

GroupVersionVirtualObject is the group version for VirtualObject.

Functions

func GetAvailableCondition added in v1.11.0 

func GetAvailableCondition(obj client.Object) *metav1.Condition

GetAvailableCondition returns the AvailableCondition for an object, if defined.

func GetConditions added in v1.11.0 

func GetConditions(obj client.Object) []metav1.Condition

GetConditions returns conditions for an object, if defined.

func GetGroupItems 

func GetGroupItems(obj client.Object) string

GetGroupItems returns the list of names for the objects included in a group object.

func GetGroupItemsAvailableCounter added in v1.9.0 

func GetGroupItemsAvailableCounter(obj client.Object) int

GetGroupItemsAvailableCounter returns the number of available objects in the group, e.g. available Machines.

func GetGroupItemsReadyCounter added in v1.9.0 

func GetGroupItemsReadyCounter(obj client.Object) int

GetGroupItemsReadyCounter returns the number of ready objects in the group, e.g. ready Machines.

func GetGroupItemsUpToDateCounter added in v1.9.0 

func GetGroupItemsUpToDateCounter(obj client.Object) int

GetGroupItemsUpToDateCounter returns the number of up-to-date objects in the group, e.g. up-to-date Machines.

func GetMachineUpToDateCondition added in v1.11.0 

func GetMachineUpToDateCondition(obj client.Object) *metav1.Condition

GetMachineUpToDateCondition returns machine's UpToDate condition, if defined. Note: The UpToDate condition only exist on machines, so no need to support reading from unstructured.

func GetMetaName 

func GetMetaName(obj client.Object) string

GetMetaName returns the object meta name that should be used for the object in the presentation layer, if defined.

func GetObjectContract added in v1.9.0 

func GetObjectContract(obj client.Object) string

GetObjectContract returns which Cluster API contract an unstructured object abides to. Note: Currently this annotation is applied only to control plane objects.

func GetObjectContractVersion added in v1.11.0 

func GetObjectContractVersion(obj client.Object) string

GetObjectContractVersion returns which Cluster API contract version an unstructured object abides to. Note: Currently this annotation is applied only to control plane objects.

func GetOtherV1Beta1Conditions added in v1.11.0 

func GetOtherV1Beta1Conditions(obj client.Object) []*clusterv1.Condition

GetOtherV1Beta1Conditions returns the other conditions (all the conditions except ready) for an object, if defined.

func GetReadyCondition 

func GetReadyCondition(obj client.Object) *metav1.Condition

GetReadyCondition returns the ReadyCondition for an object, if defined.

func GetV1Beta1ReadyCondition added in v1.11.0 

func GetV1Beta1ReadyCondition(obj client.Object) *clusterv1.Condition

GetV1Beta1ReadyCondition returns the ReadyCondition for an object, if defined.

func GetZOrder added in v1.2.0 

func GetZOrder(obj client.Object) int

GetZOrder return the zOrder of the object. Objects with no zOrder have a default zOrder of 0.

func IsGroupObject 

func IsGroupObject(obj client.Object) bool

IsGroupObject returns true if the object is the result of a grouping operation, and thus the object is representing group of sibling object, e.g. a group of machines.

func IsGroupingObject 

func IsGroupingObject(obj client.Object) bool

IsGroupingObject returns true in case the object is responsible to trigger the grouping action when adding the object's children. e.g. A control-plane object, could be responsible of grouping the control-plane machines while added as a children objects.

func IsShowConditionsObject 

func IsShowConditionsObject(obj client.Object) bool

IsShowConditionsObject returns true if the presentation layer should show all the conditions for the object.

func IsVirtualObject 

func IsVirtualObject(obj client.Object) bool

IsVirtualObject returns true if the object does not correspond to any real object, but instead it is a virtual object introduced to provide a better representation of the cluster status.

Types

type AddObjectOption 

type AddObjectOption interface {
	ApplyToAdd(*addObjectOptions)
}

AddObjectOption define an option for the ObjectTree Add operation.

type DiscoverOptions 

type DiscoverOptions struct {
	// ShowOtherConditions is a list of comma separated kind or kind/name for which we should add the ShowObjectConditionsAnnotation
	// to signal to the presentation layer to show all the conditions for the objects.
	ShowOtherConditions string

	// ShowMachineSets instructs the discovery process to include machine sets in the ObjectTree.
	ShowMachineSets bool

	// ShowClusterResourceSets instructs the discovery process to include cluster resource sets in the ObjectTree.
	ShowClusterResourceSets bool

	// ShowTemplates instructs the discovery process to include infrastructure and bootstrap config templates in the ObjectTree.
	ShowTemplates bool

	// AddTemplateVirtualNode instructs the discovery process to group template under a virtual node.
	AddTemplateVirtualNode bool

	// Echo displays MachineInfrastructure or BootstrapConfig objects if the object's ready condition is true
	Echo bool

	// Grouping groups machine objects in case the ready conditions
	// have the same Status, Severity and Reason.
	Grouping bool

	// V1Beta1 instructs tree to use V1Beta1 conditions.
	//
	// Deprecated: This field will be removed when v1beta1 will be dropped.
	V1Beta1 bool
}

DiscoverOptions define options for the discovery process.

type GroupingObject 

type GroupingObject bool

The GroupingObject option makes this node responsible of triggering the grouping action when adding the node's children.

func (GroupingObject) ApplyToAdd 

func (n GroupingObject) ApplyToAdd(options *addObjectOptions)

ApplyToAdd applies the given options.

type NoEcho 

type NoEcho bool

The NoEcho options defines if the object should be hidden if the object's ready condition has the same Status, Severity and Reason of the parent's object ready condition (it is an echo).

func (NoEcho) ApplyToAdd 

func (n NoEcho) ApplyToAdd(options *addObjectOptions)

ApplyToAdd applies the given options.

type NodeDeprecatedStatus added in v1.11.0 

type NodeDeprecatedStatus struct {
	V1Beta1 *NodeV1Beta1DeprecatedStatus
}

NodeDeprecatedStatus groups all the status fields that are deprecated and will be removed in a future version. See https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more context.

type NodeObject added in v1.9.0 

type NodeObject struct {
	metav1.TypeMeta
	metav1.ObjectMeta
	Status NodeStatus
}

NodeObject represent a node in the tree which doesn't correspond to Cluster, MachineDeployment, Machine etc. An example of NodeObject are GroupNodes, which are used e.g. to represent a set of Machines. Note: NodeObject implements condition getter and setter interfaces as well as the minimal set of methods usually existing on Kubernetes objects.

func ObjectReferenceObject added in v1.2.0 

func ObjectReferenceObject(objectRef *corev1.ObjectReference) *NodeObject

ObjectReferenceObject returns a new object referenced by the objectRef.

func VirtualObject 

func VirtualObject(namespace, kind, name string) *NodeObject

VirtualObject returns a new virtual object.

func (*NodeObject) DeepCopyObject added in v1.9.0 

func (o *NodeObject) DeepCopyObject() runtime.Object

DeepCopyObject returns a deep copy of the object.

func (*NodeObject) GetConditions added in v1.9.0 

func (o *NodeObject) GetConditions() []metav1.Condition

GetConditions returns the set of conditions for this object.

func (*NodeObject) GetCreationTimestamp added in v1.9.0 

func (o *NodeObject) GetCreationTimestamp() metav1.Time

GetCreationTimestamp returns object's CreationTimestamp.

func (*NodeObject) GetDeletionTimestamp added in v1.9.0 

func (o *NodeObject) GetDeletionTimestamp() *metav1.Time

GetDeletionTimestamp returns object's DeletionTimestamp.

func (*NodeObject) GetManagedFields added in v1.9.0 

func (o *NodeObject) GetManagedFields() []metav1.ManagedFieldsEntry

GetManagedFields returns object's ManagedFields.

func (*NodeObject) GetOwnerReferences added in v1.9.0 

func (o *NodeObject) GetOwnerReferences() []metav1.OwnerReference

GetOwnerReferences returns object's OwnerReferences.

func (*NodeObject) GetUID added in v1.9.0 

func (o *NodeObject) GetUID() types.UID

GetUID returns object's UID.

func (*NodeObject) GetV1Beta1Conditions added in v1.11.0 

func (o *NodeObject) GetV1Beta1Conditions() clusterv1.Conditions

GetV1Beta1Conditions returns the set of conditions for this object.

func (*NodeObject) SetConditions added in v1.9.0 

func (o *NodeObject) SetConditions(conditions []metav1.Condition)

SetConditions sets conditions for an API object.

func (*NodeObject) SetCreationTimestamp added in v1.9.0 

func (o *NodeObject) SetCreationTimestamp(timestamp metav1.Time)

SetCreationTimestamp sets object's CreationTimestamp.

func (*NodeObject) SetDeletionTimestamp added in v1.9.0 

func (o *NodeObject) SetDeletionTimestamp(timestamp *metav1.Time)

SetDeletionTimestamp sets object's DeletionTimestamp.

func (*NodeObject) SetManagedFields added in v1.9.0 

func (o *NodeObject) SetManagedFields(managedFields []metav1.ManagedFieldsEntry)

SetManagedFields sets object's ManagedFields.

func (*NodeObject) SetOwnerReferences added in v1.9.0 

func (o *NodeObject) SetOwnerReferences(references []metav1.OwnerReference)

SetOwnerReferences sets object's OwnerReferences.

func (*NodeObject) SetUID added in v1.9.0 

func (o *NodeObject) SetUID(uid types.UID)

SetUID sets object's UID.

func (*NodeObject) SetV1Beta1Conditions added in v1.11.0 

func (o *NodeObject) SetV1Beta1Conditions(conditions clusterv1.Conditions)

SetV1Beta1Conditions sets the conditions on this object.

type NodeStatus added in v1.9.0 

type NodeStatus struct {
	Deprecated *NodeDeprecatedStatus
	Conditions []metav1.Condition
}

NodeStatus is the status of a node object.

type NodeV1Beta1DeprecatedStatus added in v1.11.0 

type NodeV1Beta1DeprecatedStatus struct {
	Conditions clusterv1.Conditions
}

NodeV1Beta1DeprecatedStatus groups all the status fields that are deprecated and will be removed when support for v1beta1 will be dropped.

type ObjectMetaName 

type ObjectMetaName string

The ObjectMetaName option defines the meta name that should be used for the object in the presentation layer, e.g. control plane for KCP.

func (ObjectMetaName) ApplyToAdd 

func (n ObjectMetaName) ApplyToAdd(options *addObjectOptions)

ApplyToAdd applies the given options.

type ObjectTree 

type ObjectTree struct {
	// contains filtered or unexported fields
}

ObjectTree defines an object tree representing the status of a Cluster API cluster.

func Discovery 

func Discovery(ctx context.Context, c client.Client, namespace, name string, options DiscoverOptions) (*ObjectTree, error)

Discovery returns an object tree representing the status of a Cluster API cluster.

func NewObjectTree 

func NewObjectTree(root client.Object, options ObjectTreeOptions) *ObjectTree

NewObjectTree creates a new object tree with the given root and options.

func (ObjectTree) Add 

func (od ObjectTree) Add(parent, obj client.Object, opts ...AddObjectOption) (added bool, visible bool)

Add a object to the object tree.

func (ObjectTree) GetObject 

func (od ObjectTree) GetObject(id types.UID) client.Object

GetObject returns the object with the given uid.

func (ObjectTree) GetObjectsByParent 

func (od ObjectTree) GetObjectsByParent(id types.UID) []client.Object

GetObjectsByParent returns all the dependant objects for the given uid.

func (ObjectTree) GetParent added in v1.10.0 

func (od ObjectTree) GetParent(id types.UID) client.Object

GetParent returns parent of an object.

func (ObjectTree) GetRoot 

func (od ObjectTree) GetRoot() client.Object

GetRoot returns the root of the tree.

func (ObjectTree) IsObjectWithChild 

func (od ObjectTree) IsObjectWithChild(id types.UID) bool

IsObjectWithChild determines if an object has dependants.

type ObjectTreeOptions 

type ObjectTreeOptions struct {
	// ShowOtherConditions is a list of comma separated kind or kind/name for which we should add   the ShowObjectConditionsAnnotation
	// to signal to the presentation layer to show all the conditions for the objects.
	ShowOtherConditions string

	// ShowMachineSets instructs the discovery process to include machine sets in the ObjectTree.
	ShowMachineSets bool

	// ShowClusterResourceSets instructs the discovery process to include cluster resource sets in the ObjectTree.
	ShowClusterResourceSets bool

	// ShowTemplates instructs the discovery process to include infrastructure and bootstrap config templates in the ObjectTree.
	ShowTemplates bool

	// AddTemplateVirtualNode instructs the discovery process to group template under a virtual node.
	AddTemplateVirtualNode bool

	// Echo displays objects if the object's ready condition has the
	// same Status, Severity and Reason of the parent's object ready condition (it is an echo)
	Echo bool

	// Grouping groups sibling object in case the ready conditions
	// have the same Status, Severity and Reason
	Grouping bool

	// V1Beta1 instructs tree to use V1Beta1 conditions.
	//
	// Deprecated: This field will be removed when v1beta1 will be dropped.
	V1Beta1 bool
}

ObjectTreeOptions defines the options for an ObjectTree.

type ZOrder added in v1.2.0 

type ZOrder int

The ZOrder options defines the sorting of child objects when the tree is printed. Objects are sorted by their z-order from highest to lowest, and then by their name in alphaebetical order if the z-order is the same. Objects with no z-order set are assumed to have a default z-order of 0.

func (ZOrder) ApplyToAdd added in v1.2.0 

func (z ZOrder) ApplyToAdd(options *addObjectOptions)

ApplyToAdd applies the given options.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.