# 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.)
