docs: Add k3s module documentation

deployment-examples/openstack-kubernetes/k3s-cluster/main.tf

@@ -1,5 +1,7 @@
 module "openstack_cogstack_infra" {
-  source = "../../../terraform-modules/openstack-kubernetes-k3s"
+  source  = "CogStack/kubernetes-k3s/openstack"
+  version = "0.1.0"
+
   host_instances = [
     {
       name          = "cogstack-k3s",

docs/docs/platform/deployment/reference/terraform/terraform-openstack-kubernetes-k3s.md

@@ -0,0 +1,21 @@
+# Terraform OpenStack Kubernetes K3s
+
+<div class="tech-stack-banner" markdown="block">
+
+{{ cogstack_banner_logo() }}
+
+:simple-openstack:{ .tech-icon-openstack } :simple-kubernetes:{ .tech-icon-kubernetes } :simple-terraform:{ .tech-icon-terraform }
+
+</div>
+
+This Terraform module provisions a Kubernetes cluster on OpenStack using [K3s](https://k3s.io/). It creates the VMs, installs K3s on them, sets up networking, and returns a kubeconfig so you can use the cluster with `kubectl`, Helm, and other Terraform Kubernetes providers.
+
+The module is published to the Terraform Registry:
+
+- [CogStack/kubernetes-k3s/openstack](https://registry.terraform.io/modules/CogStack/kubernetes-k3s/openstack/latest)
+
+Source code lives in this repository:
+
+- [terraform-modules/openstack-kubernetes-k3s](https://github.com/CogStack/cogstack-platform/tree/main/terraform-modules/openstack-kubernetes-k3s)
+
+For a full CogStack platform deployment that uses this module, see the [OpenStack Kubernetes K3s example](../../examples/openstack-kubernetes-k3s.md).

docs/mkdocs.yml

@@ -83,7 +83,10 @@ nav:
           - Azure Kubernetes AKS: platform/deployment/examples/azure-kubernetes-aks.md
           - OpenStack Kubernetes K3s: platform/deployment/examples/openstack-kubernetes-k3s.md
           - OpenStack Docker: platform/deployment/examples/openstack-docker.md
-      - Docker Compose: platform/deployment/reference/docker-compose/_index.md
+      - Reference:
+          - Docker Compose: platform/deployment/reference/docker-compose/_index.md
+          - Terraform:
+              - OpenStack Kubernetes K3s: platform/deployment/reference/terraform/terraform-openstack-kubernetes-k3s.md
 
   - Observability:
       - Overview: platform/observability/index.md

terraform-modules/README.md

@@ -1,4 +1,16 @@
-Reusable terraform modules for CogStack deployments. 
+Reusable terraform modules for CogStack deployments.
 
 These modules should not be limited to a specific deployment or contain secrets.
 
+## Generating module docs
+
+Modules that use [terraform-docs](https://github.com/terraform-docs/terraform-docs) keep a `.terraform-docs.yml` and inject generated Requirements, Providers, Resources, Inputs, and Outputs between `<!-- BEGIN_TF_DOCS -->` and `<!-- END_TF_DOCS -->` in the module README.
+
+From the module directory:
+
+```bash
+docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.24.0 markdown /terraform-docs
+```
+
+If that tag is missing for your architecture, use `quay.io/terraform-docs/terraform-docs:0.24.0-amd64` (or `-arm64`) instead.
+

terraform-modules/openstack-kubernetes-k3s/.terraform-docs.yml

@@ -0,0 +1,61 @@
+formatter: markdown table
+
+output:
+  file: README.md
+  mode: inject
+
+sort:
+  enabled: true
+  by: required
+
+settings:
+  anchor: true
+  color: true
+  default: true
+  description: true
+  escape: true
+  hide-empty: true
+  html: true
+  indent: 2
+  lockfile: true
+  read-comments: true
+  required: true
+  sensitive: true
+  type: true
+
+content: |-
+  ## Example
+
+  This example deploys a two node kubernetes cluster in Openstack with K3s.
+
+  ```hcl
+  {{ include "examples/minimal/main.tf" }}
+  ```
+
+  {{ .Requirements }}
+
+  {{ .Providers }}
+
+  {{ .Modules }}
+
+  {{ .Resources }}
+
+  {{ .Inputs }}
+
+  {{ .Outputs }}
+
+  ## Existing Network and Floating IPs
+
+  You can use this module with a custom OpenStack network by specifying the `network` variable with your own network name or network ID.
+
+  Using a custom OpenStack network with your own subnet allows you to improve security by keeping most nodes private. This ensures worker nodes and other internal resources are not directly exposed, reducing security risks. Only the controller node needs a floating IP to be accessible in order to use the k8s api server (eg for kubectl to work from outside the network). Using floating ips will also have the advantage of being stable, so you can destroy/create VMs without having to update anywhere the IP address is referenced by reassigning the floating ip.
+
+  To use this configuration, you will probably need to assign a floating IP to the controller node so that it is accessible. You can configure floating IP assignment per node using the `floating_ip` block within each entry in the `host_instances` variable.
+
+  Please see this example for using this module with a custom network and floating IPs.
+
+  ```hcl
+  {{ include "examples/floating-ips/main.tf" }}
+  ```
+
+  When using a non-default network, ensure the controller host has a floating IP so Terraform can access it for provisioning.