provisioning/templates/workspaces/kubernetes/setup.md

Kubernetes Workspace Setup\n\nThis template provides a complete Kubernetes cluster configuration using the package-based provisioning system.\n\n## Prerequisites\n\n1. Core provisioning package installed:\n\n bash\n kcl-packager.nu install --version latest\n \n\n2. Module loader CLI available:\n\n bash\n module-loader --help\n \n\n## Setup Steps\n\n### 1. Initialize Workspace\n\n\n# Create workspace from template\ncp -r provisioning/templates/workspaces/kubernetes ./my-k8s-cluster\ncd my-k8s-cluster\n\n# Initialize directory structure\nworkspace-init.nu . init\n\n\n### 2. Load Required Taskservs\n\n\n# Load Kubernetes components\nmodule-loader load taskservs . [kubernetes, cilium, containerd]\n\n# Verify loading\nmodule-loader list taskservs .\n\n\n### 3. Load Cloud Provider\n\n\n# For UpCloud\nmodule-loader load providers . [upcloud]\n\n# For AWS\nmodule-loader load providers . [aws]\n\n# For local development\nmodule-loader load providers . [local]\n\n\n### 4. Configure Infrastructure\n\n1. Edit servers.k to uncomment the import statements and taskserv configurations\n2. Adjust server specifications, hostnames, and labels as needed\n3. Configure provider-specific settings in the generated provider files\n\n### 5. Validate Configuration\n\n\n# Validate KCL configuration\nkcl run servers.k\n\n# Validate workspace\nmodule-loader validate .\n\n\n### 6. Deploy Cluster\n\n\n# Create servers\nprovisioning server create --infra . --check\n\n# Install taskservs\nprovisioning taskserv create kubernetes --infra .\nprovisioning taskserv create cilium --infra .\nprovisioning taskserv create containerd --infra .\n\n# Verify cluster\nkubectl get nodes\n\n\n## Configuration Details\n\n### Server Roles\n\n- k8s-master-01: Control plane node running the Kubernetes API server, etcd, and scheduler\n- k8s-worker-01/02: Worker nodes running kubelet and container runtime\n\n### Taskservs\n\n- containerd: Container runtime for Kubernetes\n- kubernetes: Core Kubernetes components (kubelet, kubeadm, kubectl)\n- cilium: CNI (Container Network Interface) for pod networking\n\n### Network Configuration\n\n- All nodes have public IPv4 for initial setup\n- Cilium provides internal pod-to-pod networking\n- SSH access on port 22 for management\n\n## Customization\n\n### Adding More Workers\n\nCopy the worker node configuration in servers.k and modify:\n\n- hostname\n- title\n- Any provider-specific settings\n\n### Different Container Runtime\n\nReplace containerd taskserv with:\n\n- crio: CRI-O runtime\n- docker: Docker runtime (not recommended for production)\n\n### Different CNI\n\nReplace cilium taskserv with:\n\n- calico: Calico CNI\n- flannel: Flannel CNI\n- Built-in kubenet (remove CNI taskserv)\n\n### Storage\n\nAdd storage taskservs:\n\n\nmodule-loader load taskservs . [rook-ceph, mayastor]\n\n\nThen add to server taskserv configurations:\n\n\ntaskservs = [\n { name = "containerd", profile = "default" },\n { name = "kubernetes", profile = "worker" },\n { name = "cilium", profile = "worker" },\n { name = "rook-ceph", profile = "default" }\n]\n\n\n## Troubleshooting\n\n### Module Import Errors\n\nIf you see import errors like "module not found":\n\n1. Verify modules are loaded: module-loader list taskservs .\n2. Check generated import files: ls .taskservs/\n3. Reload modules if needed: module-loader load taskservs . [kubernetes, cilium, containerd]\n\n### Provider Configuration\n\nCheck provider-specific configuration in .providers/ directory after loading.\n\n### Kubernetes Setup Issues\n\n1. Check taskserv installation logs in ./tmp/k8s-deployment/\n2. Verify all nodes are reachable via SSH\n3. Check firewall rules for Kubernetes ports (6443, 10250, etc.)