docs: dependencies vs dependents

guettli commented 1 year ago

Thank your very much for this great tool.

Could you please explain in the README (and/or in -h) the difference between dependencies and dependents?

Are you sure "dependencies" is the correct term?

❯ k lineage cluster host-cluster -o=wide
NAME                                                             READY   STATUS   AGE   RELATIONSHIPS
Cluster/host-cluster                                             True             69d   []
├── HCloudMachineTemplate/host-cluster-control-plane             -                69d   [OwnerReference]
├── HCloudMachineTemplate/host-cluster-md-0                      -                69d   [OwnerReference]
├── HetznerCluster/host-cluster                                  -                69d   [ControllerReference OwnerReference]
│   ├── Secret/hetzner                                           -                69d   [OwnerReference]
│   └── Secret/host-cluster-kubeconfig                           -                69d   [OwnerReference]

With option -D

❯ k lineage -D Secret/host-cluster-kubeconfig
NAME                                                 READY   STATUS   AGE
Secret/host-cluster-kubeconfig                       -                69d
├── HetznerCluster/host-cluster                      -                69d
│   └── Cluster/host-cluster                         True             69d
└── KubeadmControlPlane/host-cluster-control-plane   True             69d
    └── Cluster/host-cluster                         True             69d

For me -D looks like reverse-dependencies to me.

tohjustin commented 1 year ago

Hi @guettli, really appreciate your feedback on this 🙏 Here's my initial idea for these two operations:

Default command (e.g. kubectl lineage <RESOURCE>)
1. Recursively list all dependents — "dependents" are k8s resources that have the specified <RESOURCE> in its metadata.ownerReferences field, consistent with the terminology used in Kubernetes official documentation
  1. Deployment — ReplicaSet — Pod
2. Recursively list all dependents — "dependents" here means k8s resources referencing/using the specified <RESOURCE>
  1. Pod — Service — Ingress
  2. Pod — Service — APIService
  3. PersistentVolume — PersistentVolumeClaim — Pod
  4. ConfigMap — Pod
  5. ClusterRole — ClusterRoleBinding — ServiceAccount — Pod
Inverse of the default command (e.g. kubectl lineage --<BOOLEAN_FLAG_FOR_INVERSE_OPERATION> <RESOURCE>)
1. Recursively list all owners — "owners" are k8s resource(s) that are found in the specified <RESOURCE> metadata.ownerReferences field, consistent with the terminology used in Kubernetes official documentation
  1. Pod — ReplicaSet — Deployment
2. Recursively list all dependencies — "dependencies" are k8s resources referenced/used by the specified <RESOURCE>
  1. Ingress — Service — Pod
  2. APIService — Service — Pod
  3. Pod — PersistentVolumeClaim — PersistentVolume
  4. Pod — ConfigMap
  5. Pod — ServiceAccount — ClusterRoleBinding — ClusterRole

For

1.ii. Recursively list all dependents — "dependents" here means k8s resources referencing/using the specified <RESOURCE>

I think it still makes sense to call them dependents (eg. Service references/depends on the Pod to work, Ingress references/depends on Service to work)

As for

2.ii. Recursively list all dependencies — "dependencies" are k8s resources referenced/used by the specified <RESOURCE>

I guess the word "dependencies" is a little ambiguous/awkward, perhaps a better way is to just describe this as "printing the dependents in reverse order" & I should use the --reverse/-r flags instead 🤔

What's your thoughts on this?

guettli commented 1 year ago

I like the list owners, since this is easy to understand. But -r for "reverse" is good, too.

mattcockrell commented 1 year ago

Since the plugin is named lineage, would using "children" and "parents" be appropriate?

tohjustin / kube-lineage

docs: dependencies vs dependents #6