Document CustomResources ownership

[gianlucam76]

User Story

As a developer I would like comprehensive documentation for the CRs ownership relationship. For instance, when a cluster matches a ClusterProfile, a ClusterSummary is created and it is owned by the ClusterProfile instance. 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 sveltos internals, in the documentation (https://projectsveltos.github.io/sveltos/) create a section with some CRs ownership diagram. Add information on when CRs are created/update/deleted and which other CR owns it.

/kind documentation /help /good-first-issue

[hanshal101]

Hey @gianlucam76 I would like to work on this issue. I had a doubt where should I write the documentation for the CRs?

[gianlucam76]

@hanshal101 thank you so much. The repository used for documentation is sveltos

We use mkdocs behind the scene. So once you fork/clone repo locally, if you have mkdocs installed, "mkdocs serve" will allow you see change locally

[hanshal101]

Gotcha Should I make a separate section in the /docs/CRs Ownership.

[gianlucam76]

New section sounds good. Thank you

[hanshal101]

Ok Thanks for the swift response

[hanshal101]

Heyy @gianlucam76 I have made this diagram according to my understanding related to this issue. Please guide me for all the changes that is to be made for this diagram. Also I made this according to the ClusterProfile and ClusterSummary, while when the Profile makes the add-ons on the cluster the metadata is created (here you can see the table). This is just a template the designing part will be done after your approval.

Thank You.

[gianlucam76]

Thank you @hanshal101 !!!

You are correct, ClusterProfile owns ClusterSummary.

ClusterProfile.Spec.ClusterSelector contains a Kubernetes label selector used by Sveltos to decide on which clusters to deploy add-ons (helm charts, raw YAML, etc) listed in the ClusterProfile instance.

For every cluster matching a ClusterProfile, a ClusterSummary is created:

• ClusterSummary owner is the ClusterProfile creating it (ClusterSummary ownerReferences contains that information)
• ClusterSummary also contains labels indicating which cluster (in the example below the labels projectsveltos.io/cluster-type and projectsveltos.io/cluster-name indicates that the cluster is a ClusterAPI powered cluster named clusterapi-workload)
• ClusterSummary is created in the managed cluster namespace (while ClusterProfile is a cluster wide resource)

apiVersion: config.projectsveltos.io/v1alpha1
kind: ClusterSummary
metadata:
  ...
  labels:
    projectsveltos.io/cluster-name: clusterapi-workload
    projectsveltos.io/cluster-profile-name: kyverno
    projectsveltos.io/cluster-type: Capi
  name: kyverno-capi-clusterapi-workload
  namespace: default
  ownerReferences:
  - apiVersion: config.projectsveltos.io/v1alpha1
    kind: ClusterProfile
    name: kyverno
    uid: ae1812f8-f36d-4006-b8fc-da3c3deb380b

ClusterSummary.Spec.ClusterProfileSpec contains all the add-ons to be deployed

  clusterProfileSpec:
    helmCharts:
    - chartName: kyverno/kyverno
      chartVersion: v3.0.1
      helmChartAction: Install
      releaseName: kyverno-latest
      releaseNamespace: kyverno
      repositoryName: kyverno
      repositoryURL: https://kyverno.github.io/kyverno/
      values: |
        admissionController:
          replicas: 1

ClusterSummary.Status.FeatureSummaries contains the status (whether add-ons are deployed or being deployed or any error occurred)

status:
  dependencies: no dependencies
  featureSummaries:
  - featureID: Helm
    hash: VFvzbvlAg91J3Fp7q2hD1yHPwGaSuyD7JPEC6AuKT3E=
    lastAppliedTime: "2023-12-27T13:00:44Z"
    status: Provisioned

Also Sveltos has another CustomResourceDefinition, called ClusterConfiguration.

There is one ClusterConfiguration for each managed Cluster. One or more ClusterProfile can match a managed cluster. All ClusterProfile instances matching a cluster, are listed as Owners for the ClusterConfiguration.

apiVersion: config.projectsveltos.io/v1alpha1
kind: ClusterConfiguration
metadata:
  labels:
    projectsveltos.io/cluster-name: clusterapi-workload
    projectsveltos.io/cluster-type: Capi
  name: capi--clusterapi-workload
  namespace: default
  ownerReferences:
  - apiVersion: config.projectsveltos.io/v1alpha1
    kind: ClusterProfile
    name: kyverno
    uid: ae1812f8-f36d-4006-b8fc-da3c3deb380b
  - apiVersion: config.projectsveltos.io/v1alpha1
    kind: ClusterProfile
    name: nginx
    uid: 904412bd-92a8-4a66-bf98-581ad32dcb61

ClusterConfiguration.Status.ClusterProfileResources contains all resources deployed by Sveltos on that cluster (considering all matching ClusterProfile instances)

status:
  clusterProfileResources:
  - Features:
    - charts:
      - appVersion: v1.10.0
        chartVersion: 3.0.1
        lastAppliedTime: "2023-12-27T13:00:16Z"
        namespace: kyverno
        releaseName: kyverno-latest
        repoURL: https://kyverno.github.io/kyverno/
      featureID: Helm
    profileName: kyverno
  - Features:
    - charts:
      - appVersion: 2.3.0
        chartVersion: 0.14.0
        lastAppliedTime: "2023-12-27T13:11:16Z"
        namespace: nginx
        releaseName: nginx-latest
        repoURL: https://helm.nginx.com/stable/
      featureID: Helm
    profileName: nginx

[hanshal101]

Oh ok I guess I made the diagram a little incomplete I need to add another box named ClusterConfiguration, which will be connected to ClusterProfile with label isValid, which represents as the authorization to get Configuration details of the cluster.

[gianlucam76]

Thank you @hanshal101

I think your diagram is good. I would:

• add that one ClusterSummary is created for each managed cluster matching a ClusterProfile (and it is owned by ClusterProfile as you already have in your diagram);
• add information that can be found in a ClusterSummary, resources to be deployed (Spec section) and the status (Status section)

Then create one similar for ClusterConfiguration. But that's just my 2 cents. Your call.

[hanshal101]

Sorry for the late response, @gianlucam76 Can you please elaborate on or explain both points in detail?

[gianlucam76]

Hi @hanshal101, thank you.

In your diagram, you already have that a ClusterProfile owns a ClusterSummary. I am suggesting to add two managed clusters matching the ClusterProfile. Inside the ClusterProfile block, add

clusterSelector: env= production

Then add two Clusters, each with

labels:
  env: production

Then show the ClusterProfile owns two ClusterSummary (one per matching managed cluster).

Also, instead of listing properties of the ClusterProfile, I suggest we list properties of the ClusterSummary and specifically the addons and applications to be deployed and their status. So essentially ClusterSummary.Spec.ClusterProfileSpec and the ClusterSummary.Status.

Then (it can also be done separately) we do same for ClusterConfiguration. Essentially since we have two managed clusters, there will be two ClusterConfigurations. And we add that any ClusterProfile matching a managed cluster is added as OwnerReference of the corresponding ClusterConfiguration.

So if again there are two clusters with labels

labels:
  env: production

we can have two ClusterProfiles both with

clusterSelector: env=production

and then have two ClusterConfigurations (one for each cluster). The two ClusterProfiles both own both the ClusterConfigurations.

[hanshal101]

Oh, ok I will make all the necessary changes soon. Thanks for such a detailed response

[hanshal101]

Do we have any Slack channels or any other community messaging servers to interact with other developers and contributers?

[gianlucam76]

Thank you so much @hanshal101

Yes we do have a slack channel

[hanshal101]

Thank you @gianlucam76 I'm getting an error in signing in on the workspace. I tried with different accounts too but still the error exists. Can you help me with this issue.

[gianlucam76]

sent you an invitation to join. thank you

[hanshal101]

ok Thanks