[release-1.5] 📖 Document changes to BYO certificates

docs/book/src/developer/providers/migrations/v1.4-to-v1.5.md

@@ -25,7 +25,7 @@ maintainers of providers and consumers of our Go API.
 ### Removals
 
 - API version `v1alpha3` is not served in v1.5 (users can enable it manually in case they are lagging behind with deprecation cycles). Important: `v1alpha3` will be completely removed in 1.6.
-- The lazy restmapper feature gate was removed in controller-runtime and lazy restmapper is now the default restmapper. Accordingly the `EXP_LAZY_RESTMAPPER` feature gate was removed in Cluster API. 
+- The lazy restmapper feature gate was removed in controller-runtime and lazy restmapper is now the default restmapper. Accordingly the `EXP_LAZY_RESTMAPPER` feature gate was removed in Cluster API.
 
 ### API Changes
 
@@ -34,32 +34,34 @@ maintainers of providers and consumers of our Go API.
 ### Other
 
 - clusterctl move is adding the new annotation `clusterctl.cluster.x-k8s.io/delete-for-move` before object deletion.
-- Providers running CAPI release-0.3 clusterctl upgrade tests should set `WorkloadKubernetesVersion` field to the maximum workload cluster kubernetes version supported by the old providers in `ClusterctlUpgradeSpecInput`. For more information, please see: https://github.com/kubernetes-sigs/cluster-api/pull/8518#issuecomment-1508064859 
+- Providers running CAPI release-0.3 clusterctl upgrade tests should set `WorkloadKubernetesVersion` field to the maximum workload cluster kubernetes version supported by the old providers in `ClusterctlUpgradeSpecInput`. For more information, please see: https://github.com/kubernetes-sigs/cluster-api/pull/8518#issuecomment-1508064859
 - Introduced function `CollectInfrastructureLogs` at the `ClusterLogCollector` interface in `test/framework/cluster_proxy.go` to allow collecting infrastructure related logs during tests.
 - A `GetTypedConfigOwner` function has been added to the `sigs.k8s.io./cluster-api/bootstrap/util` package. It is equivalent to `GetConfigOwner` except that it uses the cached typed client instead of the uncached unstructured client, so `GetTypedConfigOwner` is expected to be more performant.
 - `ClusterToObjectsMapper` in `sigs.k8s.io./cluster-api/util` has been deprecated, please use `ClusterToTypedObjectsMapper` instead.
 - The generated `kubeconfig` by the Control Plane providers must be labelled with the key-value pair `cluster.x-k8s.io/cluster-name=${CLUSTER_NAME}`.
-  This is required for the CAPI managers caches to store and retrieve them for the required operations.     
+  This is required for the CAPI managers caches to store and retrieve them for the required operations.
+- When using custom certificates, the certificates must be labeled with the key-value pair `cluster.x-k8s.io/cluster-name=${CLUSTER_NAME}`.
+  This is required for the CAPI managers caches to store and retrieve them for the required operations.
 
 ### Suggested changes for providers
 
-- 
+-
 
 ## Notes about the controller-runtime bump
 
 This section shares our learnings of bumping controller-runtime to v0.15 in core Cluster API. It highlights the most relevant changes and pitfalls
 for Cluster API providers. For the full list of changes please see the [controller-runtime release notes](https://github.com/kubernetes-sigs/controller-runtime/releases/tag/v0.15.0).
 
-* Webhooks can now also return warnings, this requires adding an additional `admission.Warnings` return parameter to all webhooks. 
+* Webhooks can now also return warnings, this requires adding an additional `admission.Warnings` return parameter to all webhooks.
 * Manager options have been refactored and old fields have been deprecated.
 * Manager now has a builtin profiler server which can be enabled via `Options.PprofBindAddress`, this allows us to remove our profiler server.
 * Controller builder has been refactored, this requires small changes to our controller setup code.
 * The EventHandler interface has been modified to also take a context, which affects our mapping functions (e.g. `ClusterToInfrastructureMapFunc`).
 * Controller-runtime now uses a lazy restmapper per default, i.e. API groups and resources are only fetched when they are actually used.
   This should drastically reduce the amount of API calls in clusters with a lot of CRDs.
-* Some wait utils in `k8s.io/apimachinery/pkg/util/wait` have been deprecated. The migration is relatively straightforward except that passing in `0` 
+* Some wait utils in `k8s.io/apimachinery/pkg/util/wait` have been deprecated. The migration is relatively straightforward except that passing in `0`
   as a timeout in `wait.PollUntilContextTimeout` is treated as a timeout with 0 seconds, in `wait.PollImmediateWithContext` it is interpreted as infinity.
 * The fake client has been improved to handle status properly. In tests that write the CRD status, the CRDs should be added to the fake client via `WithStatusSubresource`.
-* Ensure that the e2e test suite is setting a logger (e.g. via `ctrl.SetLogger(klog.Background())` in `TestE2E`. Otherwise logs are not visible and controller-runtime will print a warning. 
+* Ensure that the e2e test suite is setting a logger (e.g. via `ctrl.SetLogger(klog.Background())` in `TestE2E`. Otherwise logs are not visible and controller-runtime will print a warning.
 
 For reference, please see the [Bump to CR v0.15 PR](https://github.com/kubernetes-sigs/cluster-api/pull/8007) in core Cluster API.

docs/book/src/tasks/certs/using-custom-certificates.md

@@ -11,6 +11,7 @@ Each certificate must be stored in a single secret named one of:
 | *[cluster name]***-proxy** | CA       | openssl req -x509 -subj "/CN=Front-End Proxy" -new -newkey rsa:2048 -nodes -keyout tls.key -sha256 -days 3650 -out tls.crt                                                           |
 | *[cluster name]***-sa**  | Key Pair | openssl genrsa -out tls.key 2048 && openssl rsa -in tls.key -pubout -out tls.crt |
 
+The certificates *must* also be labeled with the key-value pair `cluster.x-k8s.io/cluster-name=[cluster name]` (where `[cluster name]` is the name of the cluster it should be used with).
 
 <aside class="note warning">
 
@@ -26,9 +27,10 @@ apiVersion: v1
 kind: Secret
 metadata:
   name: cluster1-ca
+  labels:
+    cluster.x-k8s.io/cluster-name: cluster1
 type: kubernetes.io/tls
 data:
   tls.crt: <base 64 encoded PEM>
   tls.key: <base 64 encoded PEM>
 ```
-