docs: clarify k0sConfig as a ClusterConfig resource (#955)

Signed-off-by: Adrian Pedriza <[email protected]>

Author: apedriza

docs/configuration.md

@@ -31,17 +31,78 @@ The type of persistence used for this can be configurable via `spec.persistence`
 
 ## K0s configuration
 
-K0smotron allows you to configure k0s via `spec.k0sConfig` field. If empty, the default configuration will be used.
+K0smotron allows you to configure k0s via `spec.k0sConfig` field. This field expects a k0s **ClusterConfig** resource as value, which defines the configuration parameters for k0s. If `spec.k0sConfig` is left empty, the default k0s configuration will be applied.
 
-Refer to [k0s docs](https://docs.k0sproject.io/stable/configuration/) for a reference on k0s configuration.
+Refer to [k0s docs](https://docs.k0sproject.io/stable/configuration/) for a reference on configuring k0s via the ClusterConfig resource.
 
-**Note**: Some fields will be overwritten by k0smotron. K0smotron will set the following fields:
-
-- `spec.k0sConfig.spec.api.externalAddress` will be set to the value of `spec.externalAddress` if `spec.externalAddress` is set.
-   If not, k0smotron will use load balancer IP or try to detect `externalAddress` out of nodes IP addresses.
-- `spec.k0sConfig.spec.api.port` will be set to the value of `spec.service.apiPort`.
-- `spec.k0sConfig.spec.konnectivity.port` will be set to the value of `spec.service.konnectivityPort`.
-- `spec.k0sConfig.spec.storage.kine.dataSource` will be set to the value of `spec.kineDataSourceURL` if `spec.kineDataSourceURL` is set.
-  `spec.k0sConfig.spec.storage.type` will be set to `kine`.
+### ClusterConfig for K0smotron
 
+K0smotron can automatically generate `spec.k0sConfig` or override some fields (if provided) based on the values provided for the [Cluster](resource-reference.md/#clusterspec) resource, following specific configuration rules:
 
+<table>
+  <tr>
+    <th style="width: 30%;">ClusterConfig Field</th>
+    <th style="width: 30%;">Value</th>
+    <th>Condition</th>
+  </tr>
+  <tr>
+    <td><code>api.externalAddress</code></td>
+    <td>Value in <code>spec.externalAddress</code> if provided. Otherwise, depending of the service type, K0smotron attempts to detect an external address from the load balancer or available node IPs.</td>
+    <td>Only set if <code>nodeLocalLoadBalancing.enabled</code> is <code>false</code>.</td>
+  </tr>
+  <tr>
+    <td><code>api.port</code></td>
+    <td>Value in <code>spec.service.apiPort</code></td>
+    <td>Always.</td>
+  </tr>
+  <tr>
+    <td><code>api.sans</code></td>
+    <td><code>[&lt;spec.externalAddress&gt;, &lt;cluster-svc-ips&gt;, &lt;cluster-service-name&gt;, &lt;cluster-service-name-namespaced&gt;, &lt;cluster-service-name-DNS&gt;], &lt;cluster-service-name-FQDNS&gt;</code> plus the possible provided ones.</td>
+    <td>Always.</td>
+  </tr>
+  <tr>
+    <td><code>konnectivity.port</code></td>
+    <td>Value in <code>spec.service.konnectivityPort</code></td>
+    <td>Always.</td>
+  </tr>
+  <tr>
+    <td><code>storage.kine.dataSource</code></td>
+    <td>Value in <code>spec.kineDataSourceURL</code></td>
+    <td>Only set if <code>spec.kineDataSourceURL</code> is defined.</td>
+  </tr>
+  <tr>
+    <td><code>storage.type</code></td>
+    <td><code>kine</code></td>
+    <td>Only set if <code>spec.kineDataSourceURL</code> is defined.</td>
+  </tr>
+  <tr>
+    <td><code>storage.type</code></td>
+    <td><code>etcd</code></td>
+    <td>Only set if <code>spec.kineDataSourceURL</code> is not defined.</td>
+  </tr>
+  <tr>
+    <td><code>storage.etcd.externalCluster.endpoints</code></td>
+    <td><code>[https://kmc-&lt;cluster.name&gt;-etcd:2379]</code></td>
+    <td>Only set if <code>spec.kineDataSourceURL</code> is not defined.</td>
+  </tr>
+  <tr>
+    <td><code>storage.etcd.externalCluster.etcdPrefix</code></td>
+    <td>Value in <code>metadata.name</code></td>
+    <td>Only set if <code>spec.kineDataSourceURL</code> is not defined.</td>
+  </tr>
+  <tr>
+    <td><code>storage.etcd.externalCluster.caFile</code></td>
+    <td><code>/var/lib/k0s/pki/etcd-ca.crt</code></td>
+    <td>Only set if <code>spec.kineDataSourceURL</code> is not defined.</td>
+  </tr>
+  <tr>
+    <td><code>storage.etcd.externalCluster.clientCertFile</code></td>
+    <td><code>/var/lib/k0s/pki/apiserver-etcd-client.crt</code></td>
+    <td>Only set if <code>spec.kineDataSourceURL</code> is not defined.</td>
+  </tr>
+  <tr>
+    <td><code>storage.etcd.externalCluster.clientKeyFile</code></td>
+    <td><code>/var/lib/k0s/pki/apiserver-etcd-client.key</code></td>
+    <td>Only set if <code>spec.kineDataSourceURL</code> is not defined.</td>
+  </tr>
+</table>