docs(pi): document required CAPI provider label

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,15 +70,15 @@ 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.
 
 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,17 +87,26 @@ 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: <role>-<name>`
+> (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
 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.
-
-
-

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: <role>-<name>` (for example, `infrastructure-aws`)
+so {{{ docsVersionInfo.k0rdentName }}} can discover it. See
+[ProviderInterface Required Labels](../reference/provider-interface.md#required-labels) for details.
 
 ### Configuration Examples
 

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: <provider-name>
+```
+
+The label value follows the Cluster API convention `<role>-<name>` 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: