How-To Guide

Set Up Your Local Environment

Type: How-To (Task-oriented)

Related: Setup Workspace | Tutorial: First Deployment

Goal: Configure your local machine with credentials and tools to manage the KUP6S cluster.

Time: ~15 minutes

Prerequisites

  • Hetzner Cloud account with API access

  • Hetzner Object Storage credentials

  • Hetzner Storage Box credentials (optional, for backups)

  • Text editor

Step 1: Install OpenTofu

On Debian/Ubuntu

curl --proto '=https' --tlsv1.2 -fsSL \
  https://get.opentofu.org/install-opentofu.sh -o install-opentofu.sh
chmod +x install-opentofu.sh
./install-opentofu.sh --install-method deb
rm -f install-opentofu.sh

On macOS

brew install opentofu

Verify installation

tofu version
# Should show: OpenTofu v1.8.x or higher

Step 2: Install kubectl

On Debian/Ubuntu

sudo apt-get update
sudo apt-get install -y kubectl

On macOS

brew install kubectl

Verify installation

kubectl version --client

Step 3: Clone the repository

git clone git@your-git-server:your-org/kup6s.git
cd kup6s

Step 4: Create .env file

Copy example template

cd kube-hetzner
cp ../.env.example .env

Edit .env file

Open .env in your editor:

nano .env
# or: vim .env
# or: code .env

Step 5: Configure Hetzner Cloud credentials

Get API token

  1. Log in to Hetzner Cloud Console

  2. Select your project

  3. Go to Security → API Tokens

  4. Click Generate API Token

  5. Name: kup6s-management

  6. Permissions: Read & Write

  7. Copy the token

Add to .env

export TF_VAR_hcloud_token="YOUR_HETZNER_API_TOKEN_HERE"

Step 6: Configure S3 Object Storage

Shared S3 Credentials

All S3 services use shared Hetzner Object Storage credentials:

export TF_VAR_hetzner_s3_access_key="YOUR_HETZNER_S3_ACCESS_KEY"
export TF_VAR_hetzner_s3_secret_key="YOUR_HETZNER_S3_SECRET_KEY"

Note

Regional Strategy: We use two regions for geographic redundancy:

  • hel1 (Helsinki) - For disaster recovery backups (etcd)

  • fsn1 (Falkenstein) - For production data (Crossplane, Loki)

etcd Backup Configuration (DR region)

export TF_VAR_etcdbackup_s3_endpoint="https://hel1.your-objectstorage.com"
export TF_VAR_etcdbackup_s3_bucket="kup6s-etcd-backups"

Production S3 Configuration (Crossplane + Loki)

export TF_VAR_production_s3_endpoint="https://fsn1.your-objectstorage.com"
export TF_VAR_loki_s3_bucket="kup6s-loki-logs"

Tip

Why separate endpoints? Keeping backups in a different region (hel1) from production data (fsn1) provides geographic redundancy for disaster recovery.

Step 7: Configure Storage Box (CIFS/SMB)

For Longhorn backups

export TF_VAR_longhorn_cifs_username="uXXXXXX"
export TF_VAR_longhorn_cifs_password="YOUR_STORAGE_BOX_PASSWORD"
export TF_VAR_longhorn_cifs_url="//uXXXXXX.your-storagebox.de/backup"

For SMB CSI driver

export TF_VAR_storagebox_csi_username="uXXXXXX"
export TF_VAR_storagebox_csi_password="YOUR_STORAGE_BOX_PASSWORD"
export TF_VAR_storagebox_csi_smbpath="//uXXXXXX.your-storagebox.de/data"

Note

Storage Box credentials typically start with u followed by numbers (e.g., u123456).

Step 8: Configure SMTP (optional)

For alert notifications:

export TF_VAR_smtp_host="smtp.example.com"
export TF_VAR_smtp_port=587
export TF_VAR_smtp_username="alerts@example.com"
export TF_VAR_smtp_password="YOUR_SMTP_PASSWORD"

Step 9: Verify configuration

Source the environment

source .env

Check variables are set

env | grep TF_VAR_ | wc -l

Should show 20+ variables.

Verify Hetzner token works

tofu init
tofu validate

Should show no errors.

Step 10: Set up SSH keys (if needed)

If you don’t have SSH keys:

ssh-keygen -t ed25519 -f ~/.ssh/kup6s -C "kup6s-cluster"

Update kube.tf to reference your keys:

ssh_public_key  = file("~/.ssh/kup6s.pub")
ssh_private_key = file("~/.ssh/kup6s")

Step 11: Configure kubeconfig path

Add to your shell profile (~/.bashrc or ~/.zshrc):

# KUP6S cluster access
export KUBECONFIG=~/kup6s/kube-hetzner/kup6s_kubeconfig.yaml

Reload shell:

source ~/.bashrc  # or source ~/.zshrc

Verification checklist

✅ OpenTofu installed and working (tofu version) ✅ kubectl installed (kubectl version --client) ✅ Repository cloned ✅ .env file created and populated ✅ All TF_VAR_* variables set (check with env | grep TF_VAR_) ✅ source .env runs without errors ✅ tofu init succeeds ✅ SSH keys configured ✅ KUBECONFIG environment variable set

Security best practices

Protect your .env file

chmod 600 .env

Verify .env is git-ignored

git status
# Should NOT show .env file

Never commit credentials

# Double-check .gitignore
cat .gitignore | grep -E '\.env|tfvars'

Should show:

.env
.env.local
.env.*.local
*.tfvars

Use separate credentials per environment

For production vs staging:

cp .env .env.prod
cp .env .env.staging
# Edit each with different credentials

Load the appropriate one:

source .env.prod    # or
source .env.staging

Troubleshooting

“tofu: command not found”

OpenTofu not in PATH. Reinstall or add to PATH:

export PATH="/usr/local/bin:$PATH"

“Environment variables not set”

Forgot to source .env:

source .env

“Invalid credentials”

Check your API token is correct:

echo $TF_VAR_hcloud_token
# Should show your token (partially masked)

“Permission denied” on .env

Fix permissions:

chmod 600 .env

Next steps