sigs.k8s.io/cluster-api@v1.7.1/cmd/clusterctl/client/tree/doc.go (about)

     1  /*
     2  Copyright 2020 The Kubernetes Authors.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  /*
    18  Package tree supports the generation of an "at glance" view of a Cluster API cluster designed to help the user in quickly
    19  understanding if there are problems and where.
    20  
    21  The "at glance" view is based on the idea that we should avoid to overload the user with information, but instead
    22  surface problems, if any; in practice:
    23  
    24    - The view assumes we are processing objects conforming with https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20200506-conditions.md.
    25      As a consequence each object should have a Ready condition summarizing the object state.
    26  
    27    - The view organizes objects in a hierarchical tree, however it is not required that the
    28      tree reflects the ownerReference tree so it is possible to skip objects not relevant for triaging the cluster status
    29      e.g. secrets or templates.
    30  
    31    - It is possible to add "meta names" to object, thus making hierarchical tree more consistent for the users,
    32      e.g. use MachineInfrastructure instead of using all the different infrastructure machine kinds (AWSMachine, VSphereMachine etc.).
    33  
    34    - It is possible to add "virtual nodes", thus allowing to make the hierarchical tree more meaningful for the users,
    35      e.g. adding a Workers object to group all the MachineDeployments.
    36  
    37    - It is possible to "group" siblings objects by ready condition e.g. group all the machines with Ready=true
    38      in a single node instead of listing each one of them.
    39  
    40    - Given that the ready condition of the child object bubbles up to the parents, it is possible to avoid the "echo"
    41      (reporting the same condition at the parent/child) e.g. if a machine's Ready condition is already
    42      surface an error from the infrastructure machine, let's avoid to show the InfrastructureMachine
    43      given that representing its state is redundant in this case.
    44  
    45    - In order to avoid long list of objects (think e.g. a cluster with 50 worker machines), sibling objects with the
    46      same value for the ready condition can be grouped together into a virtual node, e.g. 10 Machines ready
    47  
    48  The ObjectTree object defined implements all the above behaviors of the "at glance" visualization, by generating
    49  a tree of Kubernetes objects; each object gets a set of annotation, reflecting its own visualization specific attributes,
    50  e.g is virtual node, is group node, meta name etc.
    51  
    52  The Discovery object uses the ObjectTree to build the "at glance" view of a Cluster API.
    53  */
    54  package tree