K3s manual deployment - Internet-enabled¶

This guide walks you through a manual deployment of a K3s cluster you can use to install Juno onto.

It assumes your cluster has internet access. For air-gapped K3s deployments, we recommend the Ansible installation or following the official K3s air-gap guide

Prerequisites¶

Before you begin the installation process, ensure you have reviewed the pre-requisites

Required Local Tools¶

Install the following tools on your local machine before beginning the installation:

k3sup¶

A lightweight tool to bootstrap K3s Kubernetes clusters:
- Linux: curl -sLS https://get.k3sup.dev | sh
- macOS: brew install k3sup
- Windows: Download from K3Sup and add to PATH

kubectl¶

The Kubernetes command-line tool:
- Linux:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl && sudo mv kubectl /usr/local/bin/

- macOS: brew install kubectl
- Windows: choco install kubernetes-cli

Helm¶

The Kubernetes package manager: - Linux:

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

- macOS: brew install helm
- Windows: choco install kubernetes-helm

git¶

Version control system:
- Linux: sudo apt-get install git or sudo yum install git
- macOS: brew install git
- Windows: Download from https://git-scm.com/download/win

Verify all tools are correctly installed:

k3sup version
kubectl version --client
helm version
git --version

Environment Access¶

Verify you can connect to all your server nodes. Make sure to check and confirm that your servers are accessible before proceeding with the installation.

Deployment Process¶

1. Node Preparation¶

In this example, we have Debian and Rocky Linux nodes and we've followed the appropriate preparation steps for each. For detailed instructions on preparing different host nodes, refer to our guides:

Juno Deployment Documentation

2. K3sup Prerequisites¶

Before proceeding with Kubernetes cluster deployment, make sure you meet all the k3sup requirements for your login privileges. K3sup will use these privileges to sudo properly and install the necessary components.

Review the prerequisites here: K3sup Prerequisites

3. Kubernetes Cluster Deployment¶

The deployment uses k3sup (pronounced "ketchup"), a lightweight tool that simplifies the installation of K3s, a certified Kubernetes distribution designed for production workloads in unattended, resource-constrained, remote locations, or inside IoT appliances.

Deploy Control Node¶

From your local machine, run the following command to install Kubernetes on your control node:

# Replace with your control node's actual IP address and username
k3sup install \
  --ip <CONTROL_NODE_IP> \
  --user <USERNAME> \
  --context juno-cluster \
  --local-path ~/juno-kubeconfig \
  --k3s-extra-args "--disable traefik"

# Configure kubeconfig
export KUBECONFIG=~/juno-kubeconfig

# Verify deployment
kubectl get nodes

If successful, you should see your control node listed with the status Ready.

Troubleshooting: If the control node deployment fails, SSH into the server and run k3s-uninstall.sh to clean up before retrying.

Join Worker Nodes¶

Add each worker node to the cluster:

# Add service worker
k3sup join \
  --ip <SERVICE_WORKER_IP> \
  --user <USERNAME> \
  --server-ip <CONTROL_NODE_IP> \
  --server-user <USERNAME>

# Add workstation worker (with GPU)
k3sup join \
  --ip <WORKSTATION_WORKER_IP> \
  --user <USERNAME> \
  --server-ip <CONTROL_NODE_IP> \
  --server-user <USERNAME>

# Export the location of the generated kubeconfig file so we can access the cluster
export KUBECONFIG=~/juno-kubeconfig

# Verify all nodes joined successfully
kubectl get nodes

Troubleshooting: If a worker node join fails, SSH into the server and run k3s-agent-uninstall.sh to clean up before retrying.

Add Node Labels¶

Node labels help Kubernetes decide where to schedule particular workloads. Add labels to ALL your nodes:

# Replace these node names with your actual node names from 'kubectl get nodes'
kubectl label nodes <CONTROL_NODE_NAME> juno-innovations.com/service=true
kubectl label nodes <SERVICE_WORKER_NAME> juno-innovations.com/service=true
kubectl label nodes <WORKSTATION_NODE_NAME> juno-innovations.com/workstation=true

4. That's it!¶

You now have a working Kubernetes cluster, ready to install and run Juno. You can do that by following the Installing Juno guide.