document clusterctl pinning version

Author: fabriziopandini

docs/book/src/clusterctl/commands/init.md

@@ -62,6 +62,10 @@ for each selected provider.
 
 You can specify the provider version by appending a version tag to the provider name, e.g. `aws:v0.4.1`.
 
+Pinning the version provides better control over what clusterctl chooses to install
+(usually required in an enterprise environment). Version pinning should always be used when using [image overrides](../configuration.md#image-overrides), or when relying on internal repositories with a separated
+software supply chain, or a custom versioning schema.
+
 </aside>
 
 <aside class="note">

docs/book/src/clusterctl/configuration.md

@@ -170,6 +170,9 @@ overridesFolder: /Users/foobar/workspace/dev-releases
 Image override is an advanced feature and wrong configuration can easily lead to non-functional clusters.
 It's strongly recommended to test configurations on dev/test environments before using this functionality in production.
 
+This feature must always be used in conjunction with 
+[version tag](commands/init.md#provider-version) when executing clusterctl commands.
+
 </aside>
 
 When working in air-gapped environments, it's necessary to alter the manifests to be installed in order to pull

docs/book/src/user/troubleshooting.md

@@ -101,3 +101,26 @@ Alternatively a Cert Manager yaml file can be placed in the [clusterctl override
 
 More information on the clusterctl config file can be found at [its page in the book](../clusterctl/configuration.md#clusterctl-configuration-file)
 
+## Clusterctl failing to start providers due to outdated image overrides
+
+clusterctl allows users to configure [image overrides](../clusterctl/configuration.md#image-overrides) via the clusterctl config file.
+However, when the image override is pinning a provider image to a specific version, it could happen that this
+conflicts with clusterctl behavior of picking the latest version of a provider.
+
+E.g., if you are pinning KCP images to version v1.0.2 but then clusterctl init fetches yamls for version v1.1.0 or greater KCP will 
+fail to start with the following error: 
+
+```
+invalid argument "ClusterTopology=false,KubeadmBootstrapFormatIgnition=false" for "--feature-gates" flag: unrecognized feature gate: KubeadmBootstrapFormatIgnition
+```
+
+In order to solve this problem you should specify the version of the provider you are installing by appending a
+version tag to the provider name:
+
+```shell
+clusterctl init -b kubeadm:v1.0.2 -c kubeadm:v1.0.2 --core cluster-api:v1.0.2 -i docker:v1.0.2
+```
+
+Even if slightly verbose, pinning the version provides a better control over what is installed, as usually
+required in an enterprise environment, especially if you rely on an internal repository with a separated
+software supply chain or a custom versioning schema.