From 8a81a985c443eadacba5d3e2243c2e96715264d9 Mon Sep 17 00:00:00 2001 From: Michael Morgen Date: Thu, 9 Jul 2026 12:04:04 +0200 Subject: [PATCH] docs(pi): document required CAPI provider label Every ProviderInterface must carry cluster.x-k8s.io/provider: - for k0rdent to discover it. Add the label to reference examples and note the flux helm-chart-name fallback for custom/out-of-tree objects. Refs: k0rdent/kcm#2894 --- .../cluster-identity-distribution.md | 28 +++++++++++------- docs/appendix/appendix-providers.md | 9 +++++- docs/reference/provider-interface.md | 29 +++++++++++++++++++ 3 files changed, 54 insertions(+), 12 deletions(-) diff --git a/docs/admin/access/credentials/cluster-identity-distribution.md b/docs/admin/access/credentials/cluster-identity-distribution.md index 842f655c2..0c0afa545 100644 --- a/docs/admin/access/credentials/cluster-identity-distribution.md +++ b/docs/admin/access/credentials/cluster-identity-distribution.md @@ -11,10 +11,10 @@ AccessManagement system (Credentials with `k0rdent.mirantis.com/managed: "true"` > WARNING: > To ensure proper Cluster Identity distribution, make sure the following requirements are met: -> -> 1. The ProviderInterface object is correctly configured. For details, see +> +> 1. The ProviderInterface object is correctly configured. For details, see > [ProviderInterface Configuration](#providerinterface-configuration). -> +> > 2. When distributing `ClusterIdentity` objects to regional clusters, the provider that defines the corresponding > `ClusterIdentity` CRDs must be enabled on the management and on the regional cluster. For example, to distribute > an `AWSClusterStaticIdentity` to a regional cluster, the AWS provider must be enabled on both the @@ -28,7 +28,7 @@ the process step-by-step: 1. User creates the following `Credential` and identity objects for the Azure provider in `region1` region: > NOTE: - > The name of the `Secret` must follow a specific pattern. See [credential secret](../../../appendix/appendix-providers.md#credential-secret) for details. + > The name of the `Secret` must follow a specific pattern. See [credential secret](../../../appendix/appendix-providers.md#credential-secret) for details. ```yaml apiVersion: k0rdent.mirantis.com/v1beta1 @@ -70,7 +70,7 @@ the process step-by-step: clientSecret: "${AZURE_CLIENT_SECRET}" type: Opaque ``` - + 2. The KCM controller retrieves all the `ProviderInterfaces` from the regional cluster registered with `region1` Region and looks for the `AzureClusterIdentity` object definition under `spec.clusterIdentities` of each `ProviderInterface` object. If nothing found, the cluster identity distribution will not work. @@ -78,7 +78,7 @@ object. If nothing found, the cluster identity distribution will not work. 3. The KCM controller copies the `test/azure-cluster-identity-secret` `Secret` and `test/azure-cluster-identity` `AzureClusterIdentity` objects from the management to the regional cluster. -## ProviderInterface Configuration +## `ProviderInterface` Configuration A `Credential` in k0rdent could reference more than one `ClusterIdentity` type and each of those identities might have its own transitive references. @@ -87,10 +87,17 @@ namespaces and multiple regions. The `ProviderInterface` object which is a part of the `ProviderTemplate` should define a set of identity kinds, each with its own reference-resolution instructions. Providers included with {{{ docsVersionInfo.k0rdentName }}} already -have a preconfigured ProviderInterface as part of the `ProviderTemplate`. If you are using a custom or Bring-Your-Own -provider, you must properly configure the ProviderInterface `spec.clusterIdentities` field to enable Cluster +have a preconfigured `ProviderInterface` as part of the `ProviderTemplate`. If you are using a custom or Bring-Your-Own +provider, you must properly configure the `ProviderInterface` `spec.clusterIdentities` field to enable Cluster Identity distribution. +> NOTE: +> Custom or out-of-tree `ProviderInterface` objects must also carry the +> standard Cluster API provider label `cluster.x-k8s.io/provider: -` +> (for example, `infrastructure-azure`) so {{{ docsVersionInfo.k0rdentName }}} +> can discover them. See [ProviderInterface Required Labels](../../../reference/provider-interface.md#required-labels) +> for details. + The example of the `ProviderInterface` object for the Azure provider: ```yaml @@ -98,6 +105,8 @@ apiVersion: k0rdent.mirantis.com/v1beta1 kind: ProviderInterface metadata: name: cluster-api-provider-azure + labels: + cluster.x-k8s.io/provider: infrastructure-azure annotations: helm.sh/resource-policy: keep spec: @@ -137,6 +146,3 @@ a `Secret` with the name defined under `spec.clientSecret.name` and the namespac > Cluster Identity distribution will not work if the ProviderInterface for a particular provider does not exist or > does not have `spec.clusterIdentities` field defined. The KCM controller will not fail, but it will not create any cluster > identity resources automatically. You will have to create it manually. - - - diff --git a/docs/appendix/appendix-providers.md b/docs/appendix/appendix-providers.md index f11c436e2..ad75c922f 100644 --- a/docs/appendix/appendix-providers.md +++ b/docs/appendix/appendix-providers.md @@ -8,11 +8,13 @@ Cloud provider credentials in Cluster API (CAPI) environments are managed throug The configuration follows two patterns: **ClusterIdentity Pattern** + - Uses a `ClusterIdentity` resource that defines provider identity configuration - References a `Secret` with credentials - Used by `Azure` and `vSphere` in-tree providers **Source Secret Pattern** + - Uses only a `Secret` without `ClusterIdentity` - `Secret` contains all cloud configuration data - Used by `OpenStack` in-tree provider @@ -72,7 +74,12 @@ Providers are registered through `ProviderInterface` CR, each [provider Helm cha Modifications to the `Management` Spec are needed to enable newly added provider. -For detailed information, refer to [Extended Management Configuration](./appendix-extend-mgmt.md) +For detailed information, refer to [Extended Management Configuration](./appendix-extend-mgmt.md). + +Every `ProviderInterface` must carry the standard Cluster API provider label +`cluster.x-k8s.io/provider: -` (for example, `infrastructure-aws`) +so {{{ docsVersionInfo.k0rdentName }}} can discover it. See +[ProviderInterface Required Labels](../reference/provider-interface.md#required-labels) for details. ### Configuration Examples diff --git a/docs/reference/provider-interface.md b/docs/reference/provider-interface.md index b535f5725..132fadf42 100644 --- a/docs/reference/provider-interface.md +++ b/docs/reference/provider-interface.md @@ -7,6 +7,30 @@ Each infrastructure provider Helm chart ships with a pre-configured `ProviderInt **Short name:** `pi` **Scope:** Cluster +## Required Labels + +Every `ProviderInterface` object **must** carry the standard Cluster API +provider label so {{{ docsVersionInfo.k0rdentName }}} can discover it: + +```yaml +metadata: + labels: + cluster.x-k8s.io/provider: +``` + +The label value follows the Cluster API convention `-` and must +match the corresponding value the provider's Helm chart sets in its +`Chart.yaml` `cluster.x-k8s.io/provider` annotation (for example, +`infrastructure-aws`, `infrastructure-azure`, `infrastructure-openstack`). + +> WARNING: +> If the label is missing, {{{ docsVersionInfo.k0rdentName }}} falls back to a +> legacy discovery method based on the flux `helm.toolkit.fluxcd.io/name` label. +> That fallback only matches `ProviderInterface` objects created by the +> provider's own Helm chart via a `HelmRelease`, so any custom or out-of-tree +> `ProviderInterface` installed differently will be invisible to the controller +> without the CAPI provider label. + ## Spec Fields ### `.spec.description` @@ -34,6 +58,7 @@ spec: ``` **Fields per entry:** + - `group` (string): API group - `version` (string): API version - `kind` (string): Resource kind @@ -60,12 +85,14 @@ spec: ``` **`ClusterIdentity` fields:** + - `group` (string): API group of the identity object - `version` (string): API version of the identity object - `kind` (string): Kind of the identity object - `references[]`: List of objects transitively referenced by this identity (see below) **`ClusterIdentityReference` fields:** + - `group` (string): API group of the referenced object - `version` (string): API version of the referenced object - `kind` (string): Kind of the referenced object @@ -91,6 +118,8 @@ apiVersion: k0rdent.mirantis.com/v1beta1 kind: ProviderInterface metadata: name: cluster-api-provider-azure + labels: + cluster.x-k8s.io/provider: infrastructure-azure annotations: helm.sh/resource-policy: keep spec: