tree

package
v1.4.0-rc.0 Latest Latest
Warning

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

 Go to latest Published: Mar 14, 2023 License: Apache-2.0 Imports: 16 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"

	// 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 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.
	ObjectZOrderAnnotation = "tree.cluster.x-k8s.io.io/z-order"
)

Variables

This section is empty.

Functions

func GetGroupItems 

func GetGroupItems(obj client.Object) string

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

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 GetOtherConditions 

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

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

func GetReadyCondition 

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

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

func ObjectReferenceObject added in v1.2.0 

func ObjectReferenceObject(objectRef *corev1.ObjectReference) *unstructured.Unstructured

ObjectReferenceObject returns a new object referenced by the objectRef.

func VirtualObject 

func VirtualObject(namespace, kind, name string) *unstructured.Unstructured

VirtualObject returns a new virtual object.

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
}

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

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.