Document CRs ownership

[enxebre]

User Story

As a cluster operator/developer I would like comprehensive documentation for the CRs ownership relationship. This comes in particularly handy as the number of CRDs of the project keeps growing.

Detailed Description

In order to make it easier for devs to quickly understand CAPI internals, we could include a section with some CRs ownership diagram and implications in the developer guide https://cluster-api.sigs.k8s.io/developer/architecture/controllers.html

Anything else you would like to add:

[Miscellaneous information that will assist in solving the issue.]

/kind feature
/kind documentation
/help
/good-first-issue

[k8s-ci-robot]

@enxebre:
This request has been marked as suitable for new contributors.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-good-first-issue command.

In response to this:

User Story

As a cluster operator/developer I would like comprehensive documentation for the CRs ownership relationship. This comes in particularly handy as the number of CRDs of the project keeps growing.

Detailed Description

In order to make it easier for devs to quickly understand CAPI internals, we could include a section with some CRs ownership diagram and implications in the developer guide https://cluster-api.sigs.k8s.io/developer/architecture/controllers.html

Anything else you would like to add:

[Miscellaneous information that will assist in solving the issue.]

/kind feature
/kind documentation
/help
/good-first-issue

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[codablock]

Is there any generic k8s documentation available that documents when and who is recommended to take ownership of already existing objects? The only thing I can find is https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/ and it does not explicitly document this.

My understanding so far was that ownership is taken for objects that are created as a result of another object, for example when a controller creates PODs from a POD template in Deployment/ReplicaSet. This means, Deployments create and own ReplicaSets, ReplicaSets create and own PODs and so on. When I started integrating CAPI into the tooling that I use/develop, I assumed that ownership is handled in a comparable way with MachineDeployments, meaning that we get a chain of MachineDeployment -> MachineSet -> Machine -> AWSMachine (for AWS as an example).

I assumed that MachineDeployment would NOT get claimed by Cluster, as it was clearly not created by any CAPI controller as a result of of the cluster spec. It's a different story when it comes to cluster topologies, where it would be clear that MachineDeployments created from the machineDeployments templates found in the ClusterClass are owned by the cluster.

The reason why this is important for me to understand is, that I'm partly basing the pruning strategy in kluctl (a deployment tool that I work on) on object ownership. kluctl does not try to prune objects that have an owner, because it must assume that it did NOT create that object by itself (even if labels match, as some controllers copy labels from source->dependent objects). This result in MachineDeployments never being pruned even if I remove them from my deployment project. If my understanding of ownership is wrong, I need to reconsider how to handle pruning.

I also assume that other tools (e.g. ArgoCD) might run into the same issue.

[enxebre]

Related discussion #4014

[sbueringer]

@codablock I think the cluster deletion code could also be relevant for you:

cluster-api/controllers/cluster_controller.go

Line 214 in 42e61bd

func (r *ClusterReconciler) reconcileDelete(ctx context.Context, cluster *clusterv1.Cluster) (reconcile.Result, error) {

[codablock]

Thanks @enxebre. The linked discussion basically describes the same issue. I wonder why ownership has to be taken in the first place and if the underlying requirement can't be simply solved by labels and/or annotations that CAPI attaches to the objects? Thanks to server-side-apply and managed fields, this is something that all tools should understand in the future (mine already works with managed fields and would respect it.

@sbueringer Yeah I've noticed that cluster deletion also leads to MD deletion, so I already assumed that cleanup is one of the requirements that are solved via owner references. This however, could also be solved with the help of labels/annotations (in addition to owner reference based deletion, because the topology case would/should still set owner references)

[sbueringer]

MachineSet and Machine deletion is also triggered via ownerRefs.

[codablock]

@sbueringer Which is something that imho is expected and fine, because these objects are created by the controller, on behalf of the parent objects (MachineDeployment/MachineSet). The MachineDeployment is however not created on behalf of the Cluster object, so it should not become owned by the Cluster object. The only exception is when MachineDeployments are created via cluster topologies, where the cluster object defines MachineDeployments indirectly via topology.

[enxebre]

More relevant discussion #5483

[enxebre]

/milestone v1.1

[k8s-ci-robot]

@enxebre: You must be a member of the kubernetes-sigs/cluster-api-maintainers GitHub team to set the milestone. If you believe you should be able to issue the /milestone command, please contact your Cluster API Maintainers and have them propose you as an additional delegate for this responsibility.

In response to this:

/milestone v1.1

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[fabriziopandini]

/milestone v1.1

NOTE: this issue originally was about documenting current owner chain, which is something useful per se.

I would suggest to move discussion about changing current owner chain on another issue; mostly because CAPI relies heavily on it for deletion and move on top of my mind but most probably in other places as well, and this requires proper investigation.

[Jont828]

@enxebre Did you have any ideas in mind for how to document ownership of cluster resources? This is a bit off topic, but I've recently worked on a CAPI GUI app that visualizes resources. It currently does not show the ownership relations, but what do you think about using a graph or tree to document resource ownership?

[fabriziopandini]

FYI there is already a kubctl tree plugin showing document ownership

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[fabriziopandini]

/lifecycle frozen

[fabriziopandini]

/triage accepted

[ashutosh887]

@enxebre @codablock I would like to work on this Issue
/assign

[sbueringer]

cc @killianmuldoon
IIRC we have a way to automatically generate a dot file with a lot of the ownership information based on ownerRefs. This could probably be leveraged for this issue.

[killianmuldoon]

/assign

I'll take a go at this.

Linked to #4014