📖 Improve documentation for config (#176)

* changed: extend docs for config Signed-off-by: Danny Eiselt <eiselt@b1-systems.de> * changed: generate new config Signed-off-by: Danny Eiselt <eiselt@b1-systems.de> --------- Signed-off-by: Danny Eiselt <eiselt@b1-systems.de>
SovereignCloudStack · Sep 16, 2024 · f0f7ac2 · f0f7ac2
1 parent 44cd613
commit f0f7ac2
Show file tree

Hide file tree

Showing 3 changed files with 146 additions and 10 deletions.
diff --git a/docs/providers/openstack/configuration.md b/docs/providers/openstack/configuration.md
@@ -1,10 +1,68 @@
+# Configuration
+
+This page lists the custom configuration options available, including their default values and if they are optional. The following example shows how these variables can be used inside the `cluster.yaml` file under `spec.topology.variables`.
+
+## Example
+
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: Cluster
+metadata:
+  name:
+  namespace:
+  labels:
+    managed-secret: cloud-config
+spec:
+  clusterNetwork:
+    pods:
+      cidrBlocks:
+        - 192.168.0.0/16
+    serviceDomain: cluster.local
+    services:
+      cidrBlocks:
+        - 10.96.0.0/12
+  topology:
+    variables: // <-- variables from the table can be set here
+      - name: controller_flavor
+        value: "SCS-4V-8-20"
+      - name: worker_flavor
+        value: "SCS-4V-8-20"
+      - name: external_id
+        value: "ebfe5546-f09f-4f42-ab54-094e457d42ec"
+    class: openstack-alpha-1-29-v2
+    controlPlane:
+      replicas: 2
+    version: v1.29.3
+    workers:
+      machineDeployments:
+        - class: openstack-alpha-1-29-v2
+          failureDomain: nova
+          name: openstack-alpha-1-29-v2
+          replicas: 4
+```
+
+Variables from the table containing a `.` are to be used in an object with the part before the dot being the object name and the part behind the dot being the value names. The following example demonstrates this with `oidc_config`.
+
+```yaml
+...
+topology:
+  variables:
+    - name: oidc_config
+      value:
+        issuer_url: "https://dex.k8s.scs.community"
+        client_id: "kubectl"
+...
+```
+
+## Available variables
+
 |Name|Type|Default|Example|Description|Required|
 |----|----|-------|-------|-----------|--------|
 |`external_id`|string|""|"ebfe5546-f09f-4f42-ab54-094e457d42ec"|ExternalNetworkID is the ID of an external OpenStack Network. This is necessary to get public internet to the VMs.|False|
-|`controller_flavor`|string|"SCS-2V-4-20"|"SCS-2V-4-20"|OpenStack instance flavor for control-plane nodes.|False|
-|`worker_flavor`|string|"SCS-2V-4-20"|"SCS-2V-4-20"|OpenStack instance flavor for worker nodes.|False|
-|`controller_root_disk`|integer||20|Root disk size in GiB for control-plane nodes. OpenStack volume will be created and used instead of an ephemeral disk defined in flavor. Should be used also for the diskless flavors.|False|
-|`worker_root_disk`|integer||20|Root disk size in GiB for worker nodes. OpenStack volume will be created and used instead of an ephemeral disk defined in flavor. Should be used also for the diskless flavors.|False|
+|`controller_flavor`|string|"SCS-2V-4-20s"|"SCS-2V-4-20s"|OpenStack instance flavor for control-plane nodes.|False|
+|`worker_flavor`|string|"SCS-2V-4"|"SCS-2V-4"|OpenStack instance flavor for worker nodes.|False|
+|`controller_root_disk`|integer||25|Root disk size in GiB for control-plane nodes. OpenStack volume will be created and used instead of an ephemeral disk defined in flavor. Should only be used for the diskless flavors.|False|
+|`worker_root_disk`|integer|25|25|Root disk size in GiB for worker nodes. OpenStack volume will be created and used instead of an ephemeral disk defined in flavor. Should be used for the diskless flavors.|False|
 |`yawol_flavor_id`|string|""|"0a79590e-10d7-4c2c-8f69-ca0a2c6208d2"|ID of the existing flavor used as a default yawol flavor.|False|
 |`yawol_image_id`|string|""|"f0b2ef46-f0ff-43d2-9c08-f58a5a6e9060"|ID of the existing imaged used as a default yawol image.|False|
 |`kube_vip_network_id`|string|""|"40a51f6c-9e4b-4b24-9187-49851a410c97"|ID of the existing network. The network should have one subnet with one port reserved as virtual IP.|False|
@@ -29,4 +87,4 @@
 |`oidc_config.groups_prefix`|string|oidc:|oidc:|Prefix prepended to group claims to prevent clashes wit h existing names (such as system: groups). For example, the value oidc: will cre ate group names like oidc:engineering and oidc:infra.||
 |`network_mtu`|integer||1500|NetworkMTU sets the maximum transmission unit (MTU) value to address fragmentation for the private network ID.|False|
 |`controlPlaneAvailabilityZones`|array||['nova']|ControlPlaneAvailabilityZones is the set of availability zones which control plane machines may be deployed to.|False|
-|`controlPlaneOmitAvailabilityZone`|boolean||True|ControlPlaneOmitAvailabilityZone causes availability zone to be omitted when creating control plane nodes, allowing the Nova scheduler to make a decision on which availability zone to use based on other scheduling constraints.|False|
+|`controlPlaneOmitAvailabilityZone`|boolean||True|ControlPlaneOmitAvailabilityZone causes availability zone to be omitted when creating control plane nodes, allowing the Nova scheduler to make a decision on which availability zone to use based on other scheduling constraints.|False|
diff --git a/hack/config-template.md b/hack/config-template.md
@@ -0,0 +1,59 @@
+# Configuration
+
+This page lists the custom configuration options available, including their default values and if they are optional. The following example shows how these variables can be used inside the `cluster.yaml` file under `spec.topology.variables`.
+
+## Example
+
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: Cluster
+metadata:
+  name:
+  namespace:
+  labels:
+    managed-secret: cloud-config
+spec:
+  clusterNetwork:
+    pods:
+      cidrBlocks:
+        - 192.168.0.0/16
+    serviceDomain: cluster.local
+    services:
+      cidrBlocks:
+        - 10.96.0.0/12
+  topology:
+    variables: // <-- variables from the table can be set here
+      - name: controller_flavor
+        value: "SCS-4V-8-20"
+      - name: worker_flavor
+        value: "SCS-4V-8-20"
+      - name: external_id
+        value: "ebfe5546-f09f-4f42-ab54-094e457d42ec"
+    class: openstack-alpha-1-29-v2
+    controlPlane:
+      replicas: 2
+    version: v1.29.3
+    workers:
+      machineDeployments:
+        - class: openstack-alpha-1-29-v2
+          failureDomain: nova
+          name: openstack-alpha-1-29-v2
+          replicas: 4
+```
+
+Variables from the table containing a `.` are to be used in an object with the part before the dot being the object name and the part behind the dot being the value names. The following example demonstrates this with `oidc_config`.
+
+```yaml
+...
+topology:
+  variables:
+    - name: oidc_config
+      value:
+        issuer_url: "https://dex.k8s.scs.community"
+        client_id: "kubectl"
+...
+```
+
+## Available variables
+
+!!table!!
diff --git a/hack/docugen.py b/hack/docugen.py
@@ -8,16 +8,17 @@
 generates a markdown table for documentation purposes.
 """
 
-
+import argparse
 import subprocess
 from pathlib import Path
+import sys
 
 import yaml
 
 BASE_PATH = Path(__file__).parent.parent
-TEMPLATE_PATH = BASE_PATH.joinpath(
-    "providers", "openstack", "scs", "cluster-class"
-)
+TEMPLATE_PATH = BASE_PATH.joinpath("providers", "openstack", "scs", "cluster-class")
+DOCS_TMPL_PATH = BASE_PATH.joinpath("hack", "config-template.md")
+DOCS_OUT_PATH = BASE_PATH.joinpath("docs", "providers", "openstack", "configuration.md")
 
 
 def generate_row(content: list):
@@ -100,6 +101,13 @@ def parse_object(tmpl: dict) -> list:
 
 
 if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Only print result to stdout."
+    )
+
+    args = parser.parse_args()
+
     cmd = [
         "helm",
         "template",
@@ -109,6 +117,9 @@ def parse_object(tmpl: dict) -> list:
         "templates/cluster-class.yaml",
     ]
 
+    with open(DOCS_TMPL_PATH, "r") as f:
+        tmpl = f.read()
+
     cmdout = subprocess.run(cmd, capture_output=True, check=False)
     rendered_template = cmdout.stdout.decode("utf-8")
 
@@ -127,4 +138,12 @@ def parse_object(tmpl: dict) -> list:
             parsed = parse_variable(var)
             result_table.append(generate_row(parsed))
 
-    print("\n".join(result_table))
+    output = tmpl.replace("!!table!!", "\n".join(result_table))
+
+    if args.dry_run:
+        print(output)
+        sys.exit()
+
+    print(f"Writing output to file {DOCS_OUT_PATH}")
+    with open(DOCS_OUT_PATH, "w") as f:
+        f.write(output)