Perplexity Reasoning R1

Setting up a multi-node k3s cluster on Alpine Linux for a home lab requires careful planning for networking, storage, and application deployment. Below is a structured guide based on your requirements:

Cluster Architecture Overview

Physical Machine 1
- VM1 (Master Node): Runs k3s server + control-plane components
- VM2 (Worker Node): Joins the cluster
- Existing NFS Server: Used for persistent storage
Physical Machine 2
- VM3 (Worker Node): Joins the cluster

1. Cluster Setup with Alpine Linux and k3s

Prerequisites

Ensure all Alpine VMs have:
- Static IPs assigned for stable networking.
- OpenSSH server for remote access.
- Required packages: curl, sudo, nfs-utils (for NFS clients).

Install k3s on the Master Node (VM1)

Disable IPv6 system-wide (required for all nodes):

echo "net.ipv6.conf.all.disable_ipv6 = 1" >> /etc/sysctl.conf
echo "net.ipv6.conf.default.disable_ipv6 = 1" >> /etc/sysctl.conf
sysctl -p

Modify GRUB to disable IPv6 at boot (see[7]).

Install k3s with --disable servicelb to avoid conflicts and --node-ip to enforce IPv4:

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable servicelb --node-ip " sh -

Retrieve the join token:

cat /var/lib/rancher/k3s/server/node-token

Join Worker Nodes (VM2 and VM3)

Disable IPv6 on each worker (repeat steps from master).

Join the cluster using the master token:

curl -sfL https://get.k3s.io | K3S_URL=https://:6443 K3S_TOKEN= sh -

Verify Cluster Status

kubectl get nodes  # Should show VM1, VM2, VM3

2. Persistent Storage with NFS

Configure NFS Server (Physical Machine 1)

Export the NFS directory to worker nodes:

echo "/nfs/share *(rw,sync,no_subtree_check)" >> /etc/exports
exportfs -a

Deploy NFS Provisioner in Kubernetes

Install the NFS subdir external provisioner via Helm:

helm repo add nfs-subdir-external-provisioner https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner
helm install nfs-provisioner nfs-subdir-external-provisioner/nfs-subdir-external-provisioner \
  --set nfs.server= \
  --set nfs.path=/nfs/share

This creates a StorageClass named nfs-client for dynamic PVCs.

3. Application Deployment

Example: Nextcloud via Helm

Create a values.yaml for Nextcloud:

persistence:
  enabled: true
  storageClass: "nfs-client"
service:
  type: ClusterIP

Deploy:

helm install nextcloud nextcloud/nextcloud -f values.yaml

Example: Vaultwarden

Deploy via a manifest with NFS-backed storage:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vaultwarden
spec:
  template:
    spec:
      containers:
        - name: vaultwarden
          image: vaultwarden/server
          volumeMounts:
            - mountPath: /data
              name: vaultwarden-data
      volumes:
        - name: vaultwarden-data
          persistentVolumeClaim:
            claimName: vaultwarden-pvc

General Recommendations

Paperless-ngx: Requires PostgreSQL (deploy as a StatefulSet with PVCs).
BookStack: Use an existing MySQL database or deploy a dedicated instance.
Use kubectl apply -f .yaml for custom apps.

4. Security and Maintenance

Firewall Rules: Allow traffic on ports 6443 (k3s API), 111/2049 (NFS), and app-specific ports.
Backups: Schedule CronJobs to backup NFS data to external storage.
Updates: Regularly upgrade Alpine (apk update && apk upgrade) and k3s (k3s-upgrade.sh).

Troubleshooting Tips

If nodes fail to join, verify the token, network connectivity, and IPv6 status.
Check PVC status with kubectl get pvc to ensure NFS provisioning works.

By following this guide, you’ll have a lightweight, IPv4-only k3s cluster with persistent storage and self-hosted apps[1][3][4][7].

Answer from Perplexity: pplx.ai/share

Diagram