K3s Orchestration

K3s orchestration lets you run your self-hosted apps on a lightweight Kubernetes cluster instead of Docker Compose. This gives you auto-scaling, rolling updates, health-based restarts, and namespace isolation — all managed automatically through the UnboundBytes portal.

K3s orchestration is available on the Business tier ($199/month).

Why K3s?

Capability	Docker Compose	K3s
Auto-restart on crash	Yes	Yes (with smarter health checks)
Rolling updates (zero downtime)	No (containers restart)	Yes (native)
Auto-scaling based on load	No	Yes (Horizontal Pod Autoscaler)
Resource quotas per tenant	No	Yes (namespace quotas)
Liveness and readiness probes	Basic	Full Kubernetes probes
Rollback to previous version	Manual	One command (kubectl rollout undo)
Secret management	.env files	Kubernetes Secrets (encrypted at rest)

K3s is a certified Kubernetes distribution designed for resource-constrained environments. It runs with approximately 512 MB of RAM overhead and includes everything you need: Traefik for ingress, local-path-provisioner for storage, and CoreDNS for service discovery.

Prerequisites

• Business tier subscription
• A paired device with at least 2 GB RAM and 2 CPU cores available
• Linux operating system (x86_64 or arm64)

Installation

Option 1: Automated (Recommended)

When you set up a new device with the zero-friction installer, k3s is installed automatically if your deployment uses the k3s runtime:

curl -fsSL https://get.unboundbytes.com/install/<YOUR_TOKEN> | bash

The installer detects the k3s runtime setting and installs k3s alongside the UnboundBytes agent.

Option 2: Manual

If you already have a paired device running Docker Compose and want to add k3s support:

1. Install k3s on your device:

curl -sfL https://get.k3s.io | sh -

2. Verify the installation:

# Check k3s is running
systemctl status k3s

# Verify kubectl works
kubectl version --client

# Confirm the node is ready
kubectl get nodes

You should see output like:

NAME     STATUS   ROLES                  AGE   VERSION
myhost   Ready    control-plane,master   1m    v1.31.4+k3s1

3. Ensure the agent can access the cluster:

sudo chmod 644 /etc/rancher/k3s/k3s.yaml

4. Restart the UnboundBytes agent so it detects k3s:

sudo systemctl restart unboundbytes-agent

The agent will report k3s capability in its next heartbeat, and the portal will show k3s as an available runtime.

Enabling K3s for a Deployment

1. Go to Deployments in the portal
2. Select your deployment (or create a new one)
3. Under Runtime, select K3s
4. Save changes

All apps deployed to this deployment will use Kubernetes instead of Docker Compose.

How It Works

When you deploy an app with k3s enabled:

1. The orchestrator converts the app’s catalog manifest into Kubernetes resources (Deployment, Service, PVC, IngressRoute)
2. The agent receives the manifests and applies them to the local k3s cluster
3. Your app runs in an isolated namespace (tenant-{your-tenant-id})
4. Traefik (included with k3s) handles HTTPS routing to your app
5. Persistent data is stored via PersistentVolumeClaims on the host filesystem

All 48 apps in the catalog work with both Docker Compose and k3s — no changes needed.

Checking App Status

In the portal, k3s-deployed apps show Kubernetes-native status:

• Running — Pods are healthy and serving traffic
• Deploying — Rolling update in progress
• Degraded — Some pods are unhealthy (app is still serving via healthy pods)
• Failed — All pods are failing

For detailed status, SSH into your device and run:

# List all your apps
kubectl get pods -n tenant-{your-tenant-id}

# Check a specific app
kubectl describe pod -l app.kubernetes.io/name={app-name} -n tenant-{your-tenant-id}

# View app logs
kubectl logs -l app.kubernetes.io/name={app-name} -n tenant-{your-tenant-id} --tail=50

Migrating from Docker Compose

To migrate an existing deployment from Docker Compose to k3s:

1. Create a backup of all apps in your deployment (Portal > Backups > Create Backup)
2. Install k3s on your device (see Installation above)
3. Switch the runtime in Portal > Deployments > your deployment > Runtime > K3s
4. Redeploy your apps — the orchestrator will generate Kubernetes manifests and deploy them
5. Verify your apps are running: Portal > Apps (status should show “Running”)

Your app data is preserved through the backup. Domain routing continues to work seamlessly since both Docker Compose and k3s use Traefik for ingress.

Note: Migration requires a brief maintenance window while apps are redeployed. Plan for 5-15 minutes of downtime depending on the number of apps.

FAQ

Can I use my own external Kubernetes cluster?

Not currently. UnboundBytes manages k3s on the device where the agent is installed. Support for connecting to external clusters is planned for a future release.

Can I run kubectl commands directly?

Yes. SSH into your device and use kubectl with the k3s kubeconfig:

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get pods -n tenant-{your-tenant-id}

The agent manages deployments in your tenant namespace. Avoid modifying resources that the agent manages (those labeled app.kubernetes.io/managed-by: unboundbytes) as changes will be overwritten on the next deployment.

What happens if k3s goes down?

K3s runs as a systemd service and automatically restarts. If the k3s service fails:

1. The agent detects the failure and reports it via heartbeat
2. The portal shows the device as degraded
3. Once k3s recovers, pods automatically restart

If k3s cannot recover, you can reinstall it:

# Uninstall
/usr/local/bin/k3s-uninstall.sh

# Reinstall
curl -sfL https://get.k3s.io | sh -

# Restart agent
sudo systemctl restart unboundbytes-agent

Your persistent data is stored on the host filesystem and survives k3s reinstallation.

Can I migrate back to Docker Compose?

Yes. Change the runtime back to “Docker Compose” in the portal and redeploy your apps. Create a backup first to preserve your data.

Does k3s support ARM devices?

Yes. K3s supports both x86_64 and arm64 architectures. The UnboundBytes agent is cross-compiled for both platforms.

What resources does k3s use?

K3s itself uses approximately:

• RAM: 512 MB baseline
• CPU: 0.5 cores baseline
• Disk: 500 MB

This is in addition to the resources your apps consume. We recommend devices with at least 2 GB of RAM available for k3s.

How are secrets handled?

App secrets (database passwords, API keys, etc.) are stored as Kubernetes Secrets in your tenant namespace. Secrets are encrypted at rest in k3s’s embedded etcd database. When you rotate secrets through the portal, the agent updates the Kubernetes Secrets and triggers a rolling restart of affected pods.