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
- func GetGroupItems(obj client.Object) string
- func GetMetaName(obj client.Object) string
- func GetOtherConditions(obj client.Object) []*clusterv1.Condition
- func GetReadyCondition(obj client.Object) *clusterv1.Condition
- func GetZOrder(obj client.Object) int
- func IsGroupObject(obj client.Object) bool
- func IsGroupingObject(obj client.Object) bool
- func IsShowConditionsObject(obj client.Object) bool
- func IsVirtualObject(obj client.Object) bool
- func ObjectReferenceObject(objectRef *corev1.ObjectReference) *unstructured.Unstructured
- func VirtualObject(namespace, kind, name string) *unstructured.Unstructured
- type AddObjectOption
- type DiscoverOptions
- type GroupingObject
- type NoEcho
- type ObjectMetaName
- type ObjectTree
- func (od ObjectTree) Add(parent, obj client.Object, opts ...AddObjectOption) (added bool, visible bool)
- func (od ObjectTree) GetObject(id types.UID) client.Object
- func (od ObjectTree) GetObjectsByParent(id types.UID) []client.Object
- func (od ObjectTree) GetRoot() client.Object
- func (od ObjectTree) IsObjectWithChild(id types.UID) bool
- type ObjectTreeOptions
- type ZOrder
Constants ¶
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 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 ¶
This section is empty.
Functions ¶
func GetGroupItems ¶
GetGroupItems returns the list of names for the objects included in a group object.
func GetMetaName ¶
GetMetaName returns the object meta name that should be used for the object in the presentation layer, if defined.
func GetOtherConditions ¶
GetOtherConditions returns the other conditions (all the conditions except ready) for an object, if defined.
func GetReadyCondition ¶
GetReadyCondition returns the ReadyCondition for an object, if defined.
func GetZOrder ¶ added in v1.2.0
GetZOrder return the zOrder of the object. Objects with no zOrder have a default zOrder of 0.
func IsGroupObject ¶
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 ¶
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 ¶
IsShowConditionsObject returns true if the presentation layer should show all the conditions for the object.
func IsVirtualObject ¶
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