Merge pull request #11194 from fabriziopandini/group-API-reference-docs

📖 Group API reference docs
kubernetes-sigs · Sep 19, 2024 · 649c34d · 649c34d
2 parents 8a634a7 + 9fb2545
commit 649c34d
Show file tree

Hide file tree

Showing 10 changed files with 98 additions and 102 deletions.
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -84,7 +84,6 @@
         - [MachinePool](./developer/architecture/controllers/machine-pool.md)
         - [ClusterTopology](./developer/architecture/controllers/cluster-topology.md)
         - [ClusterResourceSet](./developer/architecture/controllers/cluster-resource-set.md)
-        - [Metadata propagation](./developer/architecture/controllers/metadata-propagation.md)
         - [Multi-tenancy](./developer/architecture/controllers/multi-tenancy.md)
         - [Support multiple instances](./developer/architecture/controllers/support-multiple-instances.md)
         - [Tuning controllers](./developer/architecture/controllers/tuning.md)
@@ -106,10 +105,13 @@
           - [Webhooks](./developer/providers/webhooks.md)
           - [Controllers and Reconciliation](./developer/providers/implementers-guide/controllers_and_reconciliation.md)
           - [Building, Running, Testing](./developer/providers/implementers-guide/building_running_and_testing.md)
-    - [CustomResourceDefinitions relationships](./developer/crd-relationships.md)
 - [Troubleshooting](./user/troubleshooting.md)
 - [Reference](./reference/reference.md)
-    - [API Reference](./reference/api_reference.md)
+    - [API Reference](./reference/api/reference.md)
+      - [Labels and Annotations](reference/api/labels-and-annotations.md)
+      - [CRD relationships](reference/api/crd-relationships.md)
+      - [Metadata propagation](reference/api/metadata-propagation.md)
+      - [Owner References](reference/api/owner-references.md)
     - [Glossary](./reference/glossary.md)
     - [Provider List](./reference/providers.md)
     - [Ports](./reference/ports.md)
@@ -118,5 +120,3 @@
     - [Jobs](./reference/jobs.md)
     - [Code Review in Cluster API](./REVIEWING.md)
     - [Version Support](./reference/versions.md)
-    - [Supported Labels and Annotations](./reference/labels_and_annotations.md)
-    - [Owner References](./reference/owner_references.md)
diff --git a/docs/book/src/developer/crd-relationships.md → ...ok/src/reference/api/crd-relationships.md b/docs/book/src/developer/crd-relationships.md → ...ok/src/reference/api/crd-relationships.md
@@ -14,8 +14,8 @@ The direction of the arrows indicates the direction of "management" or "referenc
 
 ## Control plane machines relationships
 
-![]( ../images/kubeadm-control-plane-machines-resources.png)
+![]( ../../images/kubeadm-control-plane-machines-resources.png)
 
 ## Worker machines relationships
 
-![]( ../images/worker-machines-resources.png)
+![]( ../../images/worker-machines-resources.png)
diff --git a/docs/book/src/reference/api/labels-and-annotations.md b/docs/book/src/reference/api/labels-and-annotations.md
diff --git a/...cture/controllers/metadata-propagation.md → ...src/reference/api/metadata-propagation.md b/...cture/controllers/metadata-propagation.md → ...src/reference/api/metadata-propagation.md
@@ -3,7 +3,7 @@ Cluster API controllers implement consistent metadata (labels & annotations) pro
 This behaviour tries to be consistent with Kubernetes apps/v1 Deployment and ReplicaSet.
 New providers should behave accordingly fitting within the following pattern:
 
-![](../../../images/metadata-propagation.jpg)
+![](../../images/metadata-propagation.jpg)
 
 ## Cluster Topology
 ControlPlaneTopology labels are labels and annotations are continuously propagated to ControlPlane top-level labels and annotations
@@ -67,5 +67,3 @@ Label should meet one of the following criterias to propagate to Node:
 - Has `node-role.kubernetes.io` as prefix.
 - Belongs to `node-restriction.kubernetes.io` domain.
 - Belongs to `node.cluster.x-k8s.io` domain.  
-
-
diff --git a/docs/book/src/reference/owner_references.md → ...ook/src/reference/api/owner-references.md b/docs/book/src/reference/owner_references.md → ...ook/src/reference/api/owner-references.md
@@ -1,28 +1,29 @@
 # Owner References
 
-
-Cluster API uses [Kubernetes owner references](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/) to track relationships between objects. These references are used for Kubernetes garbage collection, which is the basis of Cluster deletion in CAPI. They are also used places where the ownership hierarchy is important, for example when using `clusterctl move`.
+Cluster API uses [Kubernetes owner references](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/) to track relationships between objects. These references are used
+for Kubernetes garbage collection, which is also used for Cluster deletion in CAPI. They are also used places where 
+the ownership hierarchy is important, for example when using `clusterctl move`.
 
 CAPI uses owner references in an opinionated way. The following guidelines should be considered:
-1. Objects should always be created with an owner reference to prevent leaking objects. Initial ownerReferences can be replaced later where another object is a more appropriate owner.
-2. Owner references should be re-reconciled if they are lost for an object. This is required as some tools - e.g. velero - may delete owner references on objects.
+1. Objects should always be created with an owner reference to prevent leaking objects. Initial ownerReferences can be  
+   replaced later where another object is a more appropriate owner.
+2. Owner references should be re-reconciled if they are lost for an object. This is required as some tools - e.g. velero -
+   may delete owner references on objects.
 3. Owner references should be kept to the most recent apiVersion.
    - This ensures garbage collection still works after an old apiVersion is no longer served.
 4. Owner references should not be added unless required.
    - Multiple owner references on a single object should be exceptional.
 
-
-
-
 ## Owner reference relationships in Cluster API
 
-The below tables map out the a reference for ownership relationships for the objects in a Cluster API cluster. The tables are identical for classy and non-classy clusters.
-
+The below tables map out the a reference for ownership relationships for the objects in a Cluster API cluster. The tables
+are identical for classy and non-classy clusters.
 
 Providers may implement their own ownership relationships which may or may not map directly to the below tables. 
-These owner references are almost all tested in an [end-to-end test](https://github.com/kubernetes-sigs/cluster-api/blob/caaa74482b51fae777334cd7a29595da1c06481e/test/e2e/quick_start_test.go#L31). Lack of testing is noted where this is not the case. CAPI Providers can take advantage of the e2e test framework to ensure their owner references are predictable, documented and stable.
+These owner references are almost all tested in an [end-to-end test](https://github.com/kubernetes-sigs/cluster-api/blob/caaa74482b51fae777334cd7a29595da1c06481e/test/e2e/quick_start_test.go#L31). Lack of testing is noted where this is not the case. 
+CAPI Providers can take advantage of the e2e test framework to ensure their owner references are predictable, documented and stable.
 
- Kubernetes core types
+## Kubernetes core types
 
 | type      | Owner               | Controller | Note                                       |
 |-----------|---------------------|------------|--------------------------------------------|
@@ -44,22 +45,18 @@ These owner references are almost all tested in an [end-to-end test](https://git
 | Machine             | KubeadmControlPlane | yes        | When created by KCP        |
 | MachineHealthChecks | Cluster             | no         |                            |
 
-
-
 ## Experimental types
 | type                       | Owner              | Controller | Note                     |
 |----------------------------|--------------------|------------|--------------------------|
 | ClusterResourcesSet        | None               |            |                          |
 | ClusterResourcesSetBinding | ClusterResourceSet | no         | May have many CRS owners |
 | MachinePool                | Cluster            | no         |                          |
 
-
 ## KubeadmControlPlane types
 | type                        | Owner        | Controller | Note |
 |-----------------------------|--------------|------------|------|
 | KubeadmControlPlane         | Cluster      | yes        |      |
 | KubeadmControlPlaneTemplate | ClusterClass | no         |      |
-
 
 ## Kubeadm bootstrap types
 | type                  | Owner        | Controller | Note                                            |
@@ -78,5 +75,3 @@ These owner references are almost all tested in an [end-to-end test](https://git
 | InfrastructureCluster         | Cluster      | yes        |                                             |
 | InfrastructureClusterTemplate | ClusterClass | no         |                                             | 
 | InfrastructureMachinePool     | MachinePool  | yes        |                                             |
-
-
diff --git a/docs/book/src/reference/api/reference.md b/docs/book/src/reference/api/reference.md
@@ -0,0 +1,17 @@
+# API Reference
+
+Cluster API currently exposes the following APIs:
+
+* the Cluster API Custom Resource Definitions (CRDs): [documentation](https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api)
+
+* Golang APIs: [godoc](https://pkg.go.dev/sigs.k8s.io/cluster-api)
+
+Following pages provide additional documentation to better understand and use Cluster API types. 
+
+* [Labels and Annotations](labels-and-annotations.md)
+
+* [CRD relationships](crd-relationships.md)
+
+* [Metadata propagation](metadata-propagation.md)
+
+* [Owner References](owner-references.md)
diff --git a/docs/book/src/reference/api_reference.md b/docs/book/src/reference/api_reference.md