tree

package
Version: v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 6, 2021 License: Apache-2.0 Imports: 14 Imported by: 6

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

Variables

This section is empty.

Functions

func GetGroupItems

func GetGroupItems(obj client.Object) string

GetGroupItems return 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 IsGroupObject

func IsGroupObject(obj client.Object) bool

IsGroupObject return 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 return 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 VirtualObject

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

VirtualObject return 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

	// DisableNoEcho disable hiding MachineInfrastructure or BootstrapConfig objects if the object's ready condition is true
	// or it has the same Status, Severity and Reason of the parent's object ready condition (it is an echo)
	DisableNoEcho bool

	// DisableGrouping disable grouping machines objects in case the ready condition
	// has the same Status, Severity and Reason
	DisableGrouping 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

	// DisableNoEcho disables hiding 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)
	DisableNoEcho bool

	// DisableGrouping disables grouping sibling objects in case the ready condition
	// has the same Status, Severity and Reason
	DisableGrouping bool
}

ObjectTreeOptions defines the options for an ObjectTree.

Jump to

Keyboard shortcuts

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