Deploying a Lightweight K3s

Configuration

After K3s installation, the cluster is ready for use, but additional configuration will be required to publish applications to the outside world and ensure their security (HTTPS). We will deploy an Ingress controller and configure automatic TLS certificate acquisition using Caddy.

1. Deploying Ingress Controller (Nginx Ingress Controller)

Although K3s includes Traefik by default, we disabled it to have more control. Instead, we will install the popular Nginx Ingress Controller, which has proven to be reliable.

# Install Nginx Ingress Controller via Helm
# First, add the Helm repository
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

# Install Ingress Controller in ingress-nginx namespace
# Assuming version 4.10.x for 2026
helm install ingress-nginx ingress-nginx/ingress-nginx \
    --namespace ingress-nginx --create-namespace \
    --set controller.service.type=NodePort \
    --set controller.service.nodePorts.http=30080 \
    --set controller.service.nodePorts.https=30443 \
    --version 4.10.1

We use NodePort to expose the Ingress controller on ports 30080 (HTTP) and 30443 (HTTPS) on the VPS. This will allow us to proxy traffic through Caddy.

Check that the Ingress controller pods are running:

# Check Ingress controller pods
kubectl get pods -n ingress-nginx

Ensure that all pods are in Running status.

2. Installing Caddy as a Reverse Proxy and ACME Client

Caddy is a powerful web server with automatic HTTPS. We will use it as an external reverse proxy that will accept traffic from ports 80/443, automatically obtain and renew TLS certificates, and then proxy requests to the K3s Ingress controller.

Create the Caddy configuration file at /etc/caddy/Caddyfile:

# Create directory for Caddy config
sudo mkdir -p /etc/caddy

# Open Caddyfile for editing
sudo nano /etc/caddy/Caddyfile

Insert the following content, replacing your-domain.com with your domain:

# /etc/caddy/Caddyfile
{
    email [email protected]
    # Enable logging for debugging
    log {
        output file /var/log/caddy/caddy.log
        level INFO
    }
}

your-domain.com {
    # Automatic HTTPS
    reverse_proxy localhost:30080 {
        # Required for correct Ingress controller operation
        header_up Host {http.request.host}
        header_up X-Real-IP {http.request.remote}
        header_up X-Forwarded-For {http.request.remote}
        header_up X-Forwarded-Proto {http.request.scheme}
    }
}

Save the file (Ctrl+X, Y, Enter).

Create a directory for Caddy logs:

# Create directory for Caddy logs and set permissions
sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy

Install Caddy. We will use the official repository for Ubuntu:

# Install dependencies
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https

# Add Caddy GPG key
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# Add Caddy repository
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# Update package list and install Caddy
sudo apt update
sudo apt install -y caddy

Enable and start the Caddy service:

# Start Caddy
sudo systemctl enable caddy
sudo systemctl start caddy
sudo systemctl status caddy

Ensure that Caddy is running and not showing any errors. If there are issues, check Caddy logs: sudo journalctl -u caddy --no-pager.

Important: ensure that your domain (your-domain.com) points to your VPS's IP address in DNS records (A-record).

3. Deploying the First Application (Nginx)

Let's deploy a simple Nginx web application to test the cluster and Ingress controller.

Create the nginx-app.yaml file:

# Create Nginx manifest file
nano nginx-app.yaml

Insert the following content:

# nginx-app.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25.4-alpine # Current version for 2026
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx # Specify that this is an Ingress for Nginx Ingress Controller
  rules:
  - host: your-domain.com # Replace with your domain
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nginx-service
            port:
              number: 80

Save the file and apply it to the cluster:

# Apply Nginx manifest
kubectl apply -f nginx-app.yaml

Check the deployment status:

# Check Nginx pods
kubectl get pods -l app=nginx

# Check Nginx service
kubectl get service nginx-service

# Check Nginx Ingress
kubectl get ingress nginx-ingress

Ensure that the Nginx pod is running, and the service and Ingress exist.

4. Checking Functionality

Now that everything is configured, open your domain (https://your-domain.com) in a browser. You should see the standard Nginx welcome page. If you see it, then K3s, Nginx Ingress Controller, and Caddy are working correctly, and the HTTPS certificate has been automatically issued and installed.

If you encounter problems, check:

• Nginx Ingress Controller pod logs: kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx
• Caddy logs: sudo journalctl -u caddy --no-pager
• Your domain's DNS records.
• K3s status: sudo systemctl status k3s

You can also use curl to check accessibility:

# Check HTTP access
curl http://your-domain.com

# Check HTTPS access
curl -k https://your-domain.com # -k ignores certificate verification if there are issues

Troubleshooting + FAQ

In this section, we will cover common issues you might encounter when working with K3s and provide answers to frequently asked questions.

Cannot connect to the cluster using kubectl

What to check: Ensure that the KUBECONFIG environment variable is set correctly (echo $KUBECONFIG should return /home/your_user/.kube/config). Check permissions on the ~/.kube/config file (should be 600). Make sure the K3s service is running (sudo systemctl status k3s) and the firewall (UFW) allows port 6443/tcp.

How to fix: Restart K3s: sudo systemctl restart k3s. Check K3s logs: sudo journalctl -u k3s --no-pager. Ensure that the server's IP address in the ~/.kube/config file is correct.

My application is not accessible via domain, Caddy shows an error

What to check: Check the DNS record for your domain (the A-record should point to your VPS's IP). Ensure Caddy is running (sudo systemctl status caddy) and its Caddyfile is configured correctly, pointing to localhost:30080. Check Caddy logs (sudo journalctl -u caddy --no-pager) for Let's Encrypt or proxying errors. Make sure the Ingress controller is running and its pods are in Running status (kubectl get pods -n ingress-nginx).

How to fix: Correct DNS records. Validate the Caddyfile syntax with the command sudo caddy validate --config /etc/caddy/Caddyfile. Restart Caddy: sudo systemctl reload caddy. Ensure your Ingress resource in Kubernetes (kubectl get ingress) has the correct host and references an existing service and port.

Application pods are in Pending or CrashLoopBackOff status

What to check: If a pod is in Pending status, it often indicates a lack of resources (CPU/RAM) or Persistent Volume issues. If CrashLoopBackOff, it means the application inside the container is constantly crashing. Check the pod logs: kubectl logs <pod_name> and the pod description: kubectl describe pod <pod_name>.

How to fix: For Pending: increase VPS resources or reduce resource requests in the pod manifest. For CrashLoopBackOff: examine application logs; the problem might be in its configuration, environment variables, or missing dependencies.

What is the minimum suitable VPS configuration?

For K3s without heavy applications, 1 CPU core, 1 GB RAM, and 20-30 GB SSD are sufficient. This will be enough to run K3s itself and several very lightweight services. However, if you plan to run real web applications or databases, a minimum of 2 CPU cores, 4 GB RAM, and 50 GB SSD is recommended for comfortable operation and scalability.

What to choose — VPS or dedicated for this task?

For deploying K3s on a single node for most personal projects, startups, or test environments, a VPS is the optimal choice in terms of price/performance ratio. Dedicated servers are justified when maximum performance, guaranteed resources, very large disk space are required, or if you plan to run many resource-intensive clusters/applications where a VPS can no longer handle the load or CPU/RAM/IOPS limitations.

K3s does not start after server reboot

What to check: Ensure that the K3s service is enabled for autostart: sudo systemctl is-enabled k3s. If it's not enabled, run sudo systemctl enable k3s. Check service logs: sudo journalctl -u k3s --no-pager.

How to fix: If there are errors in the logs related to the firewall or network, ensure that UFW allows all necessary ports and network interfaces are up. If it's a database error, the file /var/lib/rancher/k3s/server/db/state.db might be corrupted. In such a case, recovery from a backup may be required.

How to update K3s to a new version?

What to check: Before updating, be sure to back up the cluster. Check the official K3s documentation for changes in the new version that might affect your applications or configuration.

How to fix: Updating K3s on a single node is done by re-running the installation script with the new version specified: curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="vX.Y.Z+k3s1" sh -. This will automatically download the new version, update the binaries, and restart K3s. Your applications will be temporarily unavailable during the K3s update.

Conclusion and Next Steps

Congratulations! You have successfully deployed a lightweight Kubernetes K3s cluster on your VPS, configured an Ingress controller with automatic HTTPS, and published your first application. You now have a powerful and flexible platform for hosting your containerized applications, managed declaratively and with minimal overhead.

Where to go next?

1. Monitoring and Logging: Install monitoring systems such as Prometheus and Grafana, as well as centralized logging (e.g., Loki or ELK stack) to track the status of the cluster and applications.
2. Secret Management: Explore tools for securely storing and managing secrets in Kubernetes (e.g., HashiCorp Vault, Sealed Secrets) instead of using environment variables or files.
3. Scaling and High Availability: If your project grows, consider adding additional K3s worker nodes or migrating to a full-fledged multi-node Kubernetes cluster to improve fault tolerance and performance.