Kubespray Setup

Complete control over your Akash provider setup with production-grade Kubernetes.

Kubespray provides a manual, step-by-step approach to deploying an Akash provider, giving you full control and customization over every component. Ideal for advanced users who need specific configurations or want to deeply understand the infrastructure.

Setup Time: 1-2 hours

What is Kubespray?

Kubespray is a composition of Ansible playbooks, inventory, provisioning tools, and domain knowledge for deploying production-ready Kubernetes clusters. For Akash providers, we use:

• Kubespray 2.31.0 - Pinned release used by Provider Playbook
• Kubernetes 1.35.4 - Officially supported version
• etcd 3.6.10 - Distributed key-value store
• containerd 2.2.3 - Container runtime
• Calico 3.31.5 - Container Network Interface (CNI)

Why Choose Kubespray?

Advantages

• Full control - Customize every aspect of your setup
• Production-grade - Battle-tested for large deployments
• Deep understanding - Learn exactly how components work together
• Maximum flexibility - Adapt to your specific infrastructure needs
• Custom configurations - Fine-tune network, storage, and security
• Reproducible - Infrastructure as Code approach

Considerations

• Requires Kubernetes knowledge - Must understand K8s concepts
• More manual steps - Less automated than Provider Playbook
• Command-line focused - Terminal-based setup
• Ongoing maintenance - Manual updates and configuration changes

Prerequisites

Required Knowledge

• Linux administration - Comfortable with command line and SSH
• Kubernetes fundamentals - Understand pods, deployments, services, namespaces
• Networking basics - IP addressing, DNS, firewalls, routing
• Ansible basics - Understand playbook concepts (helpful but not required)

Hardware & System Requirements

See Hardware Requirements for complete specifications including CPU, RAM, storage, network, and GPU requirements.

Setup Process Overview

The Kubespray setup is divided into distinct steps:

Phase 1: Kubernetes foundation (Required)

1. Kubernetes Cluster Setup

• Clone Kubespray repository
• Configure inventory and variables
• Deploy Kubernetes cluster with Ansible
• Verify cluster health

Phase 2: Provider capabilities (Optional)

Add advanced capabilities based on your hardware and business needs:

2. GPU Support

• Deploy NVIDIA GPU Operator
• Configure CDI and the container runtime
• Configure GPU attributes
• Test GPU workloads

3. Persistent Storage

• Deploy Rook-Ceph operator
• Configure OSD devices
• Create storage classes (beta1/beta2/beta3)
• Test persistent volumes

Install GPU and storage before rendering the provider configuration so its advertised attributes match the available cluster capabilities.

Phase 3: Provider installation (Required)

4. Provider installation (two parts)

• Provider installation (prep) — wallet, provider.yaml, DNS, NGF, and Let’s Encrypt (steps 1–9)
• Provider installation (install) — akash-gateway, operators, and helm install for the Akash provider
• Verify the provider is running

Phase 4: Additional features (Optional)

5. IP Leases

• Configure an IP address pool
• Deploy the MetalLB load balancer
• Enable the IP lease operator
• Test static IP assignment

Recommended Setup Approach

Start Simple, Add Complexity

Step 1: Install the provider stack

1. Deploy Kubernetes cluster (Kubespray)
2. Enable GPU support if the provider has NVIDIA GPUs
3. Configure persistent storage if the provider will advertise it
4. Install the provider software with the resulting attributes
5. Test with a simple deployment
6. Verify the provider shows up on network

Goal: Prove your infrastructure works

Step 2: Add more capabilities

1. Set up IP leases if you have extra public IPs

Goal: Maximize earning potential

Step 3: Optimize & Scale

1. Fine-tune pricing based on market
2. Monitor metrics and performance
3. Add capacity as needed
4. Automate maintenance tasks

Goal: Maximize profitability and uptime

Time Estimates

First-Time Setup

• Kubernetes cluster: 30-45 minutes
• Provider installation: 30-45 minutes
• Configuration & testing: 15-30 minutes
• Total: ~1-2 hours

Optional Features

• GPU support: 30-60 minutes
• Persistent storage: 45-90 minutes (depending on complexity)
• IP leases: 30-45 minutes

Experienced Operators

• Full setup: 45-60 minutes
• With automation: 20-30 minutes

Note: Times assume you have hardware ready, DNS configured, and have done this before. First-time setup may take longer due to learning curve.

Kubespray vs Provider Playbook

The manual path always uses Kubespray. Provider Playbook can build with Kubespray or K3s, or install onto an existing Kubernetes cluster:

Use Kubespray when you:

• Need specific Kubernetes configurations
• Want to understand every component
• Have custom networking requirements
• Are integrating with existing infrastructure
• Need fine-grained control over resources

Use Provider Playbook when you:

• Want the fastest setup
• Prefer guided configuration
• Are setting up a standard provider
• Don’t need custom Kubernetes settings

What Makes This “Advanced”?

Unlike Provider Playbook’s automated script, the Kubespray method requires you to:

1. Manually configure inventory files - Define your nodes and variables
2. Understand Ansible concepts - Know what playbooks are doing
3. Manually run each step - Execute commands in the right order
4. Troubleshoot issues - Debug problems without a script
5. Customize configurations - Edit YAML files for specific needs
6. Manage updates - Manually apply upgrades and patches

However, you gain:

• Deep understanding of the infrastructure
• Ability to customize anything
• Fine-grained control over security
• Flexibility for unique requirements
• Transferable Kubernetes knowledge

Alternative Setup Methods

Not sure Kubespray is right for you?

Provider Playbook →

• Interactive wizard for Kubespray, K3s, or an existing cluster
• Automated detection and validated configuration
• Recommended for most users
• Time: ~1 hour

Provider Console →

• Web-based setup with no K8s knowledge required
• Fully managed Kubernetes
• Best for beginners
• Time: 15-30 minutes

Getting Help

Before You Start

• Review Hardware Requirements
• Read Should I Run a Provider?
• Calculate earnings with Provider Calculator

During Setup

• Discord: discord.akash.network - #providers channel
• Kubespray Docs: kubespray.io

After Setup

• Operations Guide → - Managing your provider
• Provider Verification → - Verify your setup

Ready to Begin?

Start with the Kubernetes cluster setup:

→ Kubernetes Setup Guide

This will walk you through deploying a production-grade Kubernetes cluster using Kubespray 2.31.0.