Skip to main content

Frequently Asked Questions

General​

What is sloth-kubernetes?​

sloth-kubernetes is a unified tool for deploying production-grade Kubernetes clusters across multiple cloud providers. It embeds infrastructure provisioning (Pulumi), configuration management (SaltStack), and Kubernetes tooling (kubectl, Helm, Kustomize) into a single binary.

Why use sloth-kubernetes instead of Terraform + Ansible?​

Single Binary: No need to install and manage multiple tools. Everything is embedded in one executable.

Simplified Workflow: Declarative LISP configuration covers infrastructure, networking, security, and Kubernetes setup.

Built-in Multi-Cloud VPN: Automatic WireGuard mesh networking between clouds - no manual setup required.

Integrated Management: SaltStack for remote operations, kubectl embedded, Helm wrapper - all in one tool.

Do I need to install Pulumi CLI?​

No. sloth-kubernetes uses the Pulumi Automation API, which embeds the entire Pulumi engine in the binary. No external Pulumi CLI installation required.

Which cloud providers are supported?​

Currently supported:

  • DigitalOcean - Droplets, VPCs, Floating IPs, Cloud Firewalls
  • Linode - Instances, VLANs, NodeBalancers
  • AWS - EC2, VPC, Security Groups, Route53
  • Azure - VMs, VNets, Load Balancers
  • GCP - Compute Engine, VPC, Cloud DNS

Is sloth-kubernetes production-ready?​

Yes. sloth-kubernetes deploys:

  • RKE2 - CNCF-certified Kubernetes distribution
  • Security hardening - CIS Benchmark compliance
  • High availability - Multi-master etcd clusters
  • Automatic backups - etcd snapshots
  • GitOps - ArgoCD integration

Installation​

How do I install sloth-kubernetes?​

Download the latest binary from GitHub Releases:

curl -sSL https://github.com/chalkan3/sloth-kubernetes/releases/latest/download/sloth-kubernetes-linux-amd64 -o sloth-kubernetes
chmod +x sloth-kubernetes
sudo mv sloth-kubernetes /usr/local/bin/

See Installation Guide for details.

Can I build from source?​

Yes:

git clone https://github.com/chalkan3/sloth-kubernetes.git
cd sloth-kubernetes
go build -o sloth-kubernetes .

Requires Go 1.21+.

Does it work on Windows?​

Currently, only Linux binaries (amd64 and arm64) are available in releases. For Windows users, we recommend using WSL2 (Windows Subsystem for Linux).

Configuration​

How do I configure multiple cloud providers?​

Enable multiple providers in your cluster.lisp:

(cluster
  (providers
    (digitalocean
      (enabled true)
      (token "${DIGITALOCEAN_TOKEN}"))
    (linode
      (enabled true)
      (token "${LINODE_TOKEN}")))

  (node-pools
    (pool
      (name "do-masters")
      (provider "digitalocean")
      (roles master etcd)
      (count 1))
    (pool
      (name "linode-masters")
      (provider "linode")
      (roles master etcd)
      (count 2))))

Can I use different instance sizes per node pool?​

Yes:

(node-pools
  (pool
    (name "masters")
    (size "s-2vcpu-4gb")
    (count 3))
  (pool
    (name "workers-small")
    (size "s-2vcpu-4gb")
    (count 5))
  (pool
    (name "workers-large")
    (size "s-8vcpu-16gb")
    (count 2)))

How do I specify SSH keys?​

Either:

  1. Let sloth-kubernetes generate them (automatic)
  2. Provide existing keys:
(providers
  (digitalocean
    (ssh-keys
      "ssh-ed25519 AAAA... user@host")))

Deployment​

How long does deployment take?​

Typical times:

  • Single node: ~3 minutes
  • 3 masters + 5 workers: ~5-7 minutes
  • Multi-cloud cluster: ~8-10 minutes

Can I deploy to multiple regions?​

Yes, specify region per node pool:

(node-pools
  (pool
    (name "nyc-masters")
    (provider "digitalocean")
    (region "nyc3")
    (count 1))
  (pool
    (name "sfo-masters")
    (provider "digitalocean")
    (region "sfo3")
    (count 1))
  (pool
    (name "lon-masters")
    (provider "linode")
    (region "eu-west")
    (count 1)))

What if deployment fails?​

sloth-kubernetes preserves state and allows resume:

# Check status
sloth-kubernetes status

# Retry deployment
sloth-kubernetes deploy --config cluster.lisp

Pulumi handles idempotency - only missing resources are created.

Can I update a running cluster?​

Yes. Modify cluster.yaml and re-run:

sloth-kubernetes deploy --config cluster.yaml

Changes are applied incrementally.

Security​

Is traffic between clouds encrypted?​

Yes. WireGuard VPN automatically encrypts all traffic between nodes across clouds.

Do nodes have public IPs?​

By default, only the bastion host has a public IP. All cluster nodes use private IPs and are accessed via the bastion.

How does bastion authentication work?​

  • SSH keys - Automatic key distribution
  • MFA - Optional Google Authenticator
  • Audit logging - Complete session recording

Can I use my own VPN?​

Yes, disable WireGuard and configure your own:

(network
  (wireguard
    (enabled false)))

Operations​

How do I access nodes?​

Via bastion jump host:

# List nodes
sloth-kubernetes nodes list

# SSH to node (automatically via bastion)
sloth-kubernetes nodes ssh master-0

How do I run commands on all nodes?​

Use SaltStack:

# Test connectivity
sloth-kubernetes salt ping

# Run command
sloth-kubernetes salt cmd.run "uptime"

# Install package
sloth-kubernetes salt pkg.install htop

How do I scale workers?​

# Add 3 workers
sloth-kubernetes nodes add --pool workers --count 3

# Or update cluster.yaml and redeploy

Can I manage multiple clusters?​

Yes, using stacks:

# List stacks
sloth-kubernetes stacks list

# Switch stack
sloth-kubernetes stacks select production

# Each stack is an independent cluster

Kubernetes​

Which Kubernetes version is installed?​

RKE2 with the version specified in your config:

(kubernetes
  (version "v1.28.2+rke2r1")
  (distribution "rke2"))

Can I use kubectl directly?​

Yes:

# Export kubeconfig
sloth-kubernetes kubeconfig > ~/.kube/config

# Use kubectl normally
kubectl get nodes

Or use embedded kubectl:

sloth-kubernetes kubectl get nodes

Is Helm supported?​

Yes, via wrapper:

sloth-kubernetes helm install nginx bitnami/nginx

Or use Helm directly with exported kubeconfig.

How do I deploy applications?​

Multiple ways:

  1. kubectl:
sloth-kubernetes kubectl apply -f app.yaml
  1. Helm:
sloth-kubernetes helm install myapp ./chart
  1. GitOps (ArgoCD):
(addons
  (argocd
    (enabled true)
    (repository "https://github.com/org/k8s-apps")))

Troubleshooting​

Deployment fails with "insufficient quota"​

Your cloud provider account has quota limits. Either:

  • Increase quota in provider dashboard
  • Use smaller instances
  • Reduce node count

Nodes not joining cluster​

Check RKE2 status:

sloth-kubernetes nodes ssh master-0
sudo systemctl status rke2-server
sudo journalctl -u rke2-server -f

Common causes:

  • Network connectivity issues
  • Insufficient resources
  • Firewall blocking ports

SaltStack commands timeout​

# Check minion connectivity
sloth-kubernetes salt ping

# Check keys
sloth-kubernetes salt keys list

# Accept pending keys
sloth-kubernetes salt keys accept-all

How do I get logs?​

# Cluster logs
sloth-kubernetes status

# Node logs
sloth-kubernetes nodes ssh master-0
sudo journalctl -u rke2-server

# Kubernetes logs
sloth-kubernetes kubectl logs <pod-name>

Cost​

How much does it cost?​

Costs depend on cloud provider and instance sizes. Example DigitalOcean cluster:

  • 3 masters (s-2vcpu-4gb): $54/month
  • 5 workers (s-4vcpu-8gb): $240/month
  • Bastion (s-1vcpu-1gb): $6/month
  • Total: ~$300/month

Can I use spot/preemptible instances?​

Yes, for supported providers:

(node-pools
  (pool
    (name "workers")
    (provider "aws")
    (spot-instances true)
    (count 5)))

Support varies by provider - check your provider's configuration options.

How do I minimize costs?​

  • Start with smaller instances
  • Use fewer nodes
  • Enable cluster autoscaler
  • Shut down dev/test clusters when not in use

Advanced​

Can I customize cloud-init?​

Yes, provide custom user data:

(node-pools
  (pool
    (name "workers")
    (cloud-init "
#cloud-config
packages:
  - docker
runcmd:
  - systemctl enable docker
")))

How do I backup etcd?​

Automatic backups enabled by default:

(kubernetes
  (rke2
    (server
      (etcd-snapshot-schedule-cron "0 */6 * * *")
      (etcd-snapshot-retention 10))))

Manual backup:

sloth-kubernetes nodes ssh master-0
sudo rke2 etcd-snapshot save --name manual-backup

Can I use a custom Kubernetes distribution?​

Currently only RKE2 is supported. Support for k3s and kubeadm is planned.

How do I contribute?​

See Contributing Guide.

Getting Help​

Where can I get support?​

How do I report a bug?​

Open an issue with:

  • sloth-kubernetes version
  • Cloud provider(s)
  • Configuration (sanitized)
  • Error messages
  • Steps to reproduce