diff --git a/docs/providers/openstack/configuration.md b/docs/providers/openstack/configuration.md index e6e533fe..330b1dc8 100644 --- 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| \ No newline at end of file diff --git a/hack/config-template.md b/hack/config-template.md new file mode 100644 index 00000000..8f05340b --- /dev/null +++ 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!! \ No newline at end of file diff --git a/hack/docugen.py b/hack/docugen.py index b7a7a72e..1f58fdd7 100755 --- 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)