Skip to content

Juno Internet-Enabled On-Prem Installation Guide

Overview

This guide walks through the deployment of a Juno Internet-Enabled On-Prem installation using a 3-node Kubernetes cluster with mixed Linux distributions. This installation process is designed for customers who need to deploy Juno services in their own infrastructure with internet connectivity.

If you need to handle a big number of nodes or would like to automate the process, we maintain a set of Ansible Playbooks you can use to perform the deployments. We support both online&airgapped deployments within those.

The playbook repository contains instructions on how to get running with them. If you prefer to perform the installation without Ansible, continue with the guide below.

Kubernetes Basics

What is Kubernetes?

Kubernetes (K8s) is an open-source platform designed to automate deploying, scaling, and operating application containers. It groups containers that make up an application into logical units for easy management and discovery.

Key Concepts

  • Cluster: A set of nodes that run containerized applications
  • Node: A worker machine (VM or bare metal) that runs your applications
  • Control Plane: The container orchestration layer that exposes the API and interfaces to define, deploy, and manage the lifecycle of containers
  • Pod: The smallest deployable unit in Kubernetes consisting of one or more containers
  • Service: A way to access the pods services directly
  • Namespace: Logical collection of resources, isolated in a cluster

Cluster Architecture

The Juno deployment uses a lightweight Kubernetes distribution called K3s with the following components:

  • Control Node: Runs the Kubernetes API server, scheduler, and controller manager
  • Worker Nodes: Run your containerized applications and workloads
  • Container Runtime: The software responsible for running containers (containerd in K3s)
  • kubectl: Command-line tool for interacting with the cluster

In this installation, we create a 3-node cluster where: - One node serves as both control plane and can run services - Two nodes serve as workers for running various workloads - Node labels help determine what workloads run on which node

Deployment Architecture

For a standard Juno deployment, you'll need the following:

Role Operating System Minimum Requirements Purpose
Control Node Debian/Ubuntu or RHEL/Rocky 4 CPU cores, 8GB RAM, 100GB disk Kubernetes control plane, core services
Worker Node - Services Debian/Ubuntu or RHEL/Rocky 8 CPU cores, 16GB RAM, 250GB disk Support workloads and services
Worker Node - Workstation Debian/Ubuntu or RHEL/Rocky 8 CPU cores, 32GB RAM, 500GB disk, GPU (optional) High-performance workloads, GPU applications

Note: Your actual hostnames and IP addresses will differ from the examples used throughout this document. Replace them with your specific environment details.

Prerequisites

Before you begin the installation process, ensure you have reviewed the comprehensive preparation guide for Juno Deployment .

License Management

Activating Your License

Upon purchasing Juno, you will receive a license key via email from our team. This key is required during the Genesis deployment process to validate your subscription and activate all licensed services.

If you haven't received your license key or need assistance, please contact our support team at sales@juno-innovations.com. We aim to respond to all inquiries within one business day.

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 servicelb --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. Juno Installation

Clone the Juno Bootstrap repository:

git clone https://github.com/juno-fx/Juno-Bootstrap.git
cd Juno-Bootstrap

Before running any installation scripts, review the Auth Setup Guide as well as the Deployment Configurations

You must carefully configure the values.yaml file to match your specific environment requirements. Follow these steps:

  1. Review the sample configurations provided in the repository
  2. Modify the values.yaml file to reflect your environment specifics:
    • Auth
    • License
    • Ingress overrides
    • Nvidia overrides
  3. Search the Deployment Configurations documentation for detailed information about each configuration option

Install Juno

  1. If you are using the predefined Juno deployment configurations, run the following command (replace the <predefined deployment> with the path to the predefined Juno deployment configuration):
helm install juno ./chart/ \
  -f <predefined deployment> \
  -f <predefined deployment> \
  -f ./.values.yaml
  1. If you are using your own configuration, run the following command:
helm install juno ./chart/ \
  -f ./.values.yaml

Keep in mind that order matters here. We are adding our .values.yaml at the end of the command so we can override with our own settings.

The script will:
- Install necessary Kubernetes addons
- Deploy Juno core services

Post-Installation Configuration

Genesis Configuration

Genesis is the administration interface for Juno. For detailed setup instructions, visit our Genesis Documentation.

After installation completes:

  1. Access Genesis via your control node's hostname

(Note: It is not possible to access Genesis via an IP address. Juno uses a host based ingress which does not support IP connections.)

  1. Log in with the credentials created during installation
  2. Follow the setup wizard to configure:
  3. Projects and workspaces
  4. User accounts and permissions
  5. Storage backends
  6. Network access and policies
  7. License verification

Troubleshooting

Common Issues and Solutions

All troubleshooting commands involving k3s uninstallation or log checking must be executed on the specific node you're having issues with. In some cases, you may need to perform these actions on all nodes in the cluster.

Kubernetes Deployment Issues

Problem: Control node installation fails

  • Solution: SSH into the server and run k3s-uninstall.sh, then retry the installation

  • Verification: Check logs with journalctl -u k3s

Problem: Worker node fails to join cluster

  • Solution: SSH into the worker and run k3s-agent-uninstall.sh, then retry

  • Verification: Check logs with journalctl -u k3s-agent

Problem: Nodes show NotReady status

  • Solution: Check network connectivity between nodes

  • Verification: kubectl describe node <node-name>

Application Deployment Issues

Problem: Pods stuck in Pending state

  • Solution: Check if nodes have sufficient resources

  • Verification: kubectl describe pod <pod-name>

Problem: Pods fail to start with image pull errors

  • Solution: Verify internet connectivity or image registry access

  • Verification: kubectl describe pod <pod-name>

Problem: Services not accessible

  • Solution: Check network policies and service configurations

  • Verification: kubectl get svc and kubectl describe svc <service-name>

Diagnostic Commands

These commands can help diagnose issues in your cluster:

# List all pods across all namespaces and their status
kubectl get pods --all-namespaces

# Check Argo CD applications status
kubectl get applications -n argocd

# View detailed pod information
kubectl describe pod <pod-name> -n <namespace>

# Check container logs
kubectl logs <pod-name> -n <namespace>

# View events in the cluster
kubectl get events -A --sort-by='.lastTimestamp'

# Check node status and resources
kubectl describe node <node-name>

# Check deployment status
kubectl get deployments --all-namespaces

# Verify persistent volumes
kubectl get pv,pvc --all-namespaces

Access to Argo CD

Argo CD is used for managing applications in Juno. To access the Argo CD UI:

  1. To get your secret key: 

    kubectl get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo

  2. Forward the port to your local machine: 

    kubectl port-forward service/argocd-server 8080:80 -n argocd

  3. Access the UI at http://localhost:8080

  4. Run the port forward and login with the following: 

    username: admin
password: SECRETKEY

  5. Use the UI to inspect applications, check logs, and diagnose errors

Notes for Air-Gapped Environments

This guide assumes internet connectivity. For air-gapped deployments (environments without internet access):

  • Image Registry: Follow our Image Guide to set up a local container registry and pre-pull all required images
  • Package Repositories: Configure local mirrors for OS package repositories
  • K3s Installation: Use the airgap installation method for K3s
  • Juno Artifacts: Download all Juno components and transfer them to the environment

For detailed air-gapped installation instructions, refer to the dedicated Air-Gapped Documentation.

Maintenance and Updates

Upgrading Kubernetes

To upgrade your K3s installation, follow the standard K3s documentation for upgrades: K3s Upgrade Documentation

The general process involves:

  1. Upgrade the server (control) node first
  2. Verify the server node is functioning correctly
  3. Upgrade each agent (worker) node

Always ensure you have backups before performing upgrades.

For further assistance, contact Juno Support.