docs: add config documentation

Update documentation.

Signed-off-by: Serge Logvinov <[email protected]>

docs/config.md

@@ -0,0 +1,174 @@
+# Talos CCM Configuration
+
+## Overview
+
+The Talos CCM is a Kubernetes controller that manages the lifecycle of Talos nodes in a Kubernetes cluster.
+
+In scope of the Talos CCM, the following features are implemented:
+* Initialize nodes in a Kubernetes cluster, set [well-known labels and annotations](https://kubernetes.io/docs/reference/labels-annotations-taints/).
+* Label and annotate nodes based on the transformation rules.
+* Approve and sign the [kubelet certificate signing request](https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/#kubernetes-signers) for Talos nodes.
+
+Result of kubernetes node object after Talos CCM initialization:
+
+```yaml
+apiVersion: v1
+kind: Node
+metadata:
+  annotations:
+    ...
+    # Annotations based on transformation rules, see the configuration section
+    custom-annotation/instance-id: "id-e8e8c388-5812-4db0-87e2-ad1fee51a1c1"
+    ...
+  labels:
+    ...
+    # Set well-known labels, sets by Talos CCM
+    node.cloudprovider.kubernetes.io/platform: metal
+    node.kubernetes.io/instance-type: t2.micro
+    topology.kubernetes.io/region: us-west-1-on-metal
+    topology.kubernetes.io/zone: us-west-1f
+    ...
+    # Label based on transformation rules, see the configuration section
+    node-role.kubernetes.io/web: ""
+    ...
+  name: web-1
+spec:
+  ...
+  # Define the provider ID of the node, it depends on the cloud platform
+  providerID: someproviderID:///e8e8c388-5812-4db0-87e2-ad1fee51a1c1
+status:
+  # Define the addresses of the node
+  addresses:
+  - address: 172.16.0.11
+    type: InternalIP
+  - address: 1.2.3.4
+    type: ExternalIP
+  - address: 2001:123:123:123::1
+    type: ExternalIP
+  - address: web-1
+    type: Hostname
+```
+
+## Configuration
+
+Talos CCM configuration file:
+
+```yaml
+# Global parameters
+global:
+  # Check and approve node client certificate signing requests
+  # In case when you use `rotate-server-certificates` flag in kubelet
+  # Parameter is optional, by default is "false"
+  approveNodeCSR: true
+
+  # Skip non-Talos nodes after initialisation
+  # Parameter is optional, by default is "false"
+  skipForeignNode: false
+
+  # The list of endpoints to connect to the Talos API (control-plane)
+  # Parameter is optional, by default the controller will discover the control-plane endpoint
+  endpoints:
+    - 1.2.3.4
+    - 4.3.2.1
+
+# Transformations rules for nodes
+transformations:
+  # All rules are applied in order, all matched rules are applied to the node
+
+  - name: nocloud-nodes
+    # Match nodes by nodeSelector
+    nodeSelector:
+      - matchExpressions:
+          - key: platform           <- talos platfrom metadata variable case insensitive
+            operator: In            <- In, NotIn, Exists, DoesNotExist, Gt, Lt, Regexp
+            values:                 <- array of string values
+              - nocloud
+    # Set labels for matched nodes
+    labels:
+      pvc-storage-class/name: "my-storage-class"
+
+  - name: web-nodes                 <- transformation name, optional
+    nodeSelector:
+      # Or condition for nodeSelector
+      - matchExpressions:
+          # And condition for matchExpressions
+          - key: platform           <- talos platfrom metadata variable case insensitive
+            operator: In            <- In, NotIn, Exists, DoesNotExist, Gt, Lt, Regexp
+            values:                 <- array of string values
+              - metal
+          - key: hostname
+            operator: Regexp
+            values:
+              - ^web-[\w]+$         <- go regexp pattern
+      - matchExpressions:
+          - key: hostname
+            operator: Regexp
+            values:
+              - ^web-cloud-.+$
+
+    # Add/replace annotations and labels for nodes that match the transformation
+    annotations:
+      # You can use the Go template to get the value of the platform metadata variable
+      custom-annotation/instance-id: "id-{{ .InstanceID }}"
+    labels:
+      # Add label to the node, in this case, we add well-known node role label
+      node-role.kubernetes.io/web: ""
+
+    # Replace platform metadata variables for nodes that match the transformation
+    platformMetadata:
+      Region: "{{ .Region }}-on-metal"
+      Zone: "us-west-1f"
+```
+
+### Transformations parameters:
+
+* `nodeSelector` - a list of node selector requirements by platfrom metadata variable.
+  * `matchExpressions` - a list of node selector requirements by platfrom metadata variable.
+    * `key` - the key that the selector applies to, case `insensitive`.
+    * `operator` - represents a key's relationship to a set of values. Supported operators are `In`, `NotIn`, `Exists`, `DoesNotExist`, `Gt`, `Lt`, `Regexp`.
+    * `values` - an array of string values.
+
+* `annotations` - a map of key-value pairs to add to each node that matches the transformation.
+  * `key` - the key of the annotation.
+  * `value` - the value of the annotation. You can use the [Go template](https://golang.org/pkg/text/template/) to get the value of the platform metadata variable. Variables are case `sensitive`.
+
+* `labels` - a map of key-value pairs to add to each node that matches the transformation.
+  * `key` - the key of the label.
+  * `value` - the value of the label. You can use the [Go template](https://golang.org/pkg/text/template/) to get the value of the platform metadata variable. Variables are case `sensitive`.
+
+* `platformMetadata` - a map of key-value pairs to add to each node that matches the transformation.
+  * `key` - the key of the platform metadata variable to replace.
+  * `value` - the value of the platform metadata variable. You can use the [Go template](https://golang.org/pkg/text/template/) to get the value of the platform metadata variable. Variables are case `sensitive`.
+
+### Platform metadata variables:
+
+Go struct for platform metadata,
+original code: [platform_metadata.go](https://github.com/siderolabs/talos/blob/main/pkg/machinery/resources/runtime/platform_metadata.go)
+
+```go
+type PlatformMetadataSpec struct {
+	Platform     string `yaml:"platform,omitempty" protobuf:"1"`
+	Hostname     string `yaml:"hostname,omitempty" protobuf:"2"`
+	Region       string `yaml:"region,omitempty" protobuf:"3"`
+	Zone         string `yaml:"zone,omitempty" protobuf:"4"`
+	InstanceType string `yaml:"instanceType,omitempty" protobuf:"5"`
+	InstanceID   string `yaml:"instanceId,omitempty" protobuf:"6"`
+	ProviderID   string `yaml:"providerId,omitempty" protobuf:"7"`
+	Spot         bool   `yaml:"spot,omitempty" protobuf:"8"`
+}
+```
+
+* `Platform` - the Talos platform, for example, `aws`, `gcp`, `azure`, `openstack`, `metal`. Supported platforms are defined in the [platform.go](https://github.com/siderolabs/talos/blob/main/internal/app/machined/pkg/runtime/v1alpha1/platform/platform.go)
+* `Hostname` - the hostname of the node.
+* `Region` - the region of the node, for example, `us-east-1`.
+* `Zone` - the zone of the node, for example, `us-west-1f`.
+* `InstanceType` - the instance type of the node, for example, `t2.micro`.
+* `InstanceID` - the instance ID of the node, for example, `i-1234567890abcdef0`.
+* `ProviderID` - the provider ID of the node, for example, `aws:///us-east-1f/i-1234567890abcdef0`.
+* `Spot` - the spot instance, for example, `true` or `false`.
+
+You can use the following command to get the platform metadata:
+
+```bash
+talosctl get PlatformMetadatas.talos.dev -oyaml
+```