Add a configuration section

Signed-off-by: Danil Grigorev <danil.grigorev@suse.com>

docs/book/src/reference/providers.md

@@ -81,3 +81,26 @@ type IPAMProvider struct {
 ```
 
 The following sections provide details about `ProviderSpec` and `ProviderStatus`, which are shared among all the provider types.
+
+## Provider Status
+
+`ProviderStatus`: observed state of the Provider, consisting of:
+
+- Contract (optional string): core provider contract being adhered to (e.g., "v1beta1")
+- Conditions (optional clusterv1.Conditions): current service state of the provider
+- ObservedGeneration (optional int64): latest generation observed by the controller
+- InstalledVersion (optional string): version of the provider that is installed
+
+   YAML example:
+
+   ```yaml
+   status:
+     contract: "v1beta1"
+     conditions:
+       - type: "Ready"
+         status: "True"
+         reason: "ProviderAvailable"
+         message: "Provider is available and ready"
+     observedGeneration: 1
+     installedVersion: "v0.1.0"
+   ```

docs/book/src/topics/air-gapped-environtment.md → docs/book/src/topics/configuration/air-gapped-environtment.md

@@ -84,35 +84,3 @@ yq eval -i '.metadata.labels += {"my-label": "label-value"}' configmap.yaml
 ```sh
 kubectl create -f configmap.yaml
 ```
-
-## Patching provider manifests
-
-Provider manifests can be patched using JSON merge patches. This can be useful when you need to modify the provider manifests that are fetched from the repository. In order to provider
-manifests `spec.ResourcePatches` has to be used where an array of patches can be specified:
-
-```yaml
----
-apiVersion: operator.cluster.x-k8s.io/v1alpha2
-kind: CoreProvider
-metadata:
-  name: cluster-api
-  namespace: capi-system
-spec:
-  resourcePatches:
-    - |
-apiVersion: v1
-kind: Service
-metadata:
-labels:
-    test-label: test-value
-```
-
-More information about JSON merge patches can be found here <https://datatracker.ietf.org/doc/html/rfc7396>
-
-There are couple of rules for the patch to match a manifest:
-
-- The `kind` field must match the target object.
-- If `apiVersion` is specified it will only be applied to matching objects.
-- If `metadata.name` and `metadata.namespace` not specified, the patch will be applied to all objects of the specified kind.
-- If `metadata.name` is specified, the patch will be applied to the object with the specified name. This is for cluster scoped objects.
-- If both `metadata.name` and `metadata.namespace` are specified, the patch will be applied to the object with the specified name and namespace.

docs/book/src/topics/configuration/configuration.md

@@ -0,0 +1,153 @@
+# Configuration
+
+## Provider Spec
+
+1. `ProviderSpec`: desired state of the Provider, consisting of:
+   - Version (string): provider version (e.g., "v0.1.0")
+   - Manager (optional ManagerSpec): controller manager properties for the provider
+   - Deployment (optional DeploymentSpec): deployment properties for the provider
+   - ConfigSecret (optional SecretReference): reference to the config secret
+   - FetchConfig (optional FetchConfiguration): how the operator will fetch components and metadata
+
+   YAML example:
+
+   ```yaml
+   ...
+   spec:
+    version: "v0.1.0"
+    manager:
+      maxConcurrentReconciles: 5
+    deployment:
+      replicas: 1
+    configSecret:
+      name: "provider-secret"
+    fetchConfig:
+      url: "https://github.com/owner/repo/releases"
+   ...
+   ```
+
+2. `ManagerSpec`: controller manager properties for the provider, consisting of:
+   - ProfilerAddress (optional string): pprof profiler bind address (e.g., "localhost:6060")
+   - MaxConcurrentReconciles (optional int): maximum number of concurrent reconciles
+   - Verbosity (optional int): logs verbosity
+   - FeatureGates (optional map[string]bool): provider specific feature flags
+
+   YAML example:
+
+   ```yaml
+   ...
+   spec:
+    manager:
+      profilerAddress: "localhost:6060"
+      maxConcurrentReconciles: 5
+      verbosity: 1
+      featureGates:
+        FeatureA: true
+        FeatureB: false
+   ...
+   ```
+
+3. `DeploymentSpec`: deployment properties for the provider, consisting of:
+   - Replicas (optional int): number of desired pods
+   - NodeSelector (optional map[string]string): node label selector
+   - Tolerations (optional []corev1.Toleration): pod tolerations
+   - Affinity (optional corev1.Affinity): pod scheduling constraints
+   - Containers (optional []ContainerSpec): list of deployment containers
+   - ServiceAccountName (optional string): pod service account
+   - ImagePullSecrets (optional []corev1.LocalObjectReference): list of image pull secrets specified in the Deployment
+
+   YAML example:
+
+   ```yaml
+   ...
+   spec:
+     deployment:
+       replicas: 2
+       nodeSelector:
+         disktype: ssd
+       tolerations:
+       - key: "example"
+         operator: "Exists"
+         effect: "NoSchedule"
+       affinity:
+         nodeAffinity:
+           requiredDuringSchedulingIgnoredDuringExecution:
+             nodeSelectorTerms:
+             - matchExpressions:
+               - key: "example"
+                 operator: "In"
+                 values:
+                 - "true"
+       containers:
+         - name: "containerA"
+           imageUrl: "example.com/repo/image-name:v1.0.0"
+           args:
+             exampleArg: "value"
+    ...
+   ```
+
+4. `ContainerSpec`: container properties for the provider, consisting of:
+   - Name (string): container name
+   - ImageURL (optional string): container image URL
+   - Args (optional map[string]string): extra provider specific flags
+   - Env (optional []corev1.EnvVar): environment variables
+   - Resources (optional corev1.ResourceRequirements): compute resources
+   - Command (optional []string): override container's entrypoint array
+
+   YAML example:
+
+   ```yaml
+   ...
+   spec:
+     deployment:
+       containers:
+         - name: "example-container"
+           imageUrl: "example.com/repo/image-name:v1.0.0"
+           args:
+             exampleArg: "value"
+           env:
+             - name: "EXAMPLE_ENV"
+               value: "example-value"
+           resources:
+             limits:
+               cpu: "1"
+               memory: "1Gi"
+             requests:
+               cpu: "500m"
+               memory: "500Mi"
+           command:
+             - "/bin/bash"
+   ...
+   ```
+
+5. `FetchConfiguration`: components and metadata fetch options, consisting of:
+   - URL (optional string): URL for remote Github repository releases (e.g., "<https://github.com/owner/repo/releases>")
+   - Selector (optional metav1.LabelSelector): label selector to use for fetching provider components and metadata from ConfigMaps stored in the cluster
+
+   YAML example:
+
+   ```yaml
+   ...
+   spec:
+     fetchConfig:
+       url: "https://github.com/owner/repo/releases"
+       selector:
+         matchLabels:
+   ...
+   ```
+
+6. `SecretReference`: pointer to a secret object, consisting of:
+
+- Name (string): name of the secret
+- Namespace (optional string): namespace of the secret, defaults to the provider object namespace
+
+  YAML example:
+
+  ```yaml
+  ...
+  spec:
+    configSecret:
+      name: capa-secret
+      namespace: capa-system
+  ...
+  ```

docs/book/src/topics/configuration/examples-of-api-usage.md

@@ -0,0 +1,122 @@
+# Examples of API Usage
+
+In this section we provide some concrete examples of CAPI Operator API usage for various use-cases.
+
+1. As an admin, I want to install the aws infrastructure provider with specific controller flags.
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+ name: aws-variables
+ namespace: capa-system
+type: Opaque
+data:
+ AWS_B64ENCODED_CREDENTIALS: ...
+---
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: InfrastructureProvider
+metadata:
+ name: aws
+ namespace: capa-system
+spec:
+ version: v2.1.4
+ configSecret:
+   name: aws-variables
+ manager:
+   # These top level controller manager flags, supported by all the providers.
+   # These flags come with sensible defaults, thus requiring no or minimal
+   # changes for the most common scenarios.
+   metrics:
+    bindAddress: ":8181"
+   syncPeriod: "500s"
+ fetchConfig:
+   url: https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases
+ deployment:
+   containers:
+   - name: manager
+     args:
+      # These are controller flags that are specific to a provider; usage
+      # is reserved for advanced scenarios only.
+      "--awscluster-concurrency": "12"
+      "--awsmachine-concurrency": "11"
+```
+
+2. As an admin, I want to install aws infrastructure provider but override the container image of the CAPA deployment.
+
+```yaml
+---
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: InfrastructureProvider
+metadata:
+ name: aws
+ namespace: capa-system
+spec:
+ version: v2.1.4
+ configSecret:
+   name: aws-variables
+ deployment:
+   containers:
+   - name: manager
+     imageUrl: "gcr.io/myregistry/capa-controller:v2.1.4-foo"
+```
+
+3. As an admin, I want to change the resource limits for the manager pod in my control plane provider deployment.
+
+```yaml
+---
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: ControlPlaneProvider
+metadata:
+ name: kubeadm
+ namespace: capi-kubeadm-control-plane-system
+spec:
+ version: v1.4.3
+ configSecret: 
+   name: capi-variables
+ deployment:
+   containers:
+   - name: manager
+     resources:
+       limits:
+         cpu: 100m
+         memory: 30Mi
+       requests:
+         cpu: 100m
+         memory: 20Mi
+```
+
+4. As an admin, I would like to fetch my azure provider components from a specific repository which is not the default.
+
+```yaml
+---
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: InfrastructureProvider
+metadata:
+ name: myazure
+ namespace: capz-system
+spec:
+ version: v1.9.3
+ configSecret:
+   name: azure-variables
+ fetchConfig:
+   url: https://github.com/myorg/awesome-azure-provider/releases
+
+```
+
+5. As an admin, I would like to use the default fetch configurations by simply specifying the expected Cluster API provider names such as `aws`, `vsphere`, `azure`, `kubeadm`, `talos`, or `cluster-api` instead of having to explicitly specify the fetch configuration. In the example below, since we are using 'vsphere' as the name of the InfrastructureProvider the operator will fetch it's configuration from `url: https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/releases` by default.
+
+See more examples in the [air-gapped environment section](#air-gapped-environment)
+
+```yaml
+---
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: InfrastructureProvider
+metadata:
+ name: vsphere
+ namespace: capv-system
+spec:
+ version: v1.6.1
+ configSecret:
+   name: vsphere-variables
+```

docs/book/src/topics/configuration/patching-provider-manifests.md

@@ -0,0 +1,31 @@
+# Patching provider manifests
+
+Provider manifests can be patched using JSON merge patches. This can be useful when you need to modify the provider manifests that are fetched from the repository. In order to provider
+manifests `spec.ResourcePatches` has to be used where an array of patches can be specified:
+
+```yaml
+---
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: CoreProvider
+metadata:
+  name: cluster-api
+  namespace: capi-system
+spec:
+  resourcePatches:
+    - |
+apiVersion: v1
+kind: Service
+metadata:
+labels:
+    test-label: test-value
+```
+
+More information about JSON merge patches can be found here <https://datatracker.ietf.org/doc/html/rfc7396>
+
+There are couple of rules for the patch to match a manifest:
+
+- The `kind` field must match the target object.
+- If `apiVersion` is specified it will only be applied to matching objects.
+- If `metadata.name` and `metadata.namespace` not specified, the patch will be applied to all objects of the specified kind.
+- If `metadata.name` is specified, the patch will be applied to the object with the specified name. This is for cluster scoped objects.
+- If both `metadata.name` and `metadata.namespace` are specified, the patch will be applied to the object with the specified name and namespace.