Skip to content

Environment Setup

This guide walks you through setting up your local development environment for working with the fzymgc-house cluster.

Prerequisites

  • macOS or Linux workstation
  • Git installed and configured
  • Terminal access
  • Homebrew (macOS) or equivalent package manager
  • Network access to 192.168.20.0/24 (cluster network)

Required Tools

Install the following tools:

Tool Purpose Installation
kubectl Kubernetes CLI brew install kubectl
kubelogin OIDC authentication brew install kubelogin
vault HashiCorp Vault CLI brew install vault
terraform Infrastructure as Code brew install terraform
ansible Configuration management pip install ansible
gh GitHub CLI brew install gh
pre-commit Git hooks pip install pre-commit
uvx Python tool runner pip install uv

Quick install (macOS): 

brew install kubectl kubelogin vault terraform gh
pip install ansible pre-commit uv

Cross-platform: Linux users can use their package manager. See tool-specific installation docs for Windows.

Repository Setup

Clone the Repository

git clone git@github.com:fzymgc-house/selfhosted-cluster.git
cd selfhosted-cluster

Install Pre-commit Hooks

pre-commit install

This installs git hooks that run linting and validation before commits.

Python Environment

The repository includes a virtual environment setup for Ansible:

# Create virtual environment (one-time)
./setup-venv.sh

# Activate before Ansible work
source .venv/bin/activate

Environment Variables

Vault Configuration

export VAULT_ADDR=https://vault.fzymgc.house

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

Kubeconfig

Create a directory for cluster configs:

mkdir -p ~/.kube/configs

Set KUBECONFIG to include cluster configs:

export KUBECONFIG=~/.kube/configs/fzymgc-house-oidc.yml

Note: You need to create this kubeconfig file first. See Cluster Access for instructions.

Authentication Setup

Vault Login

vault login

This opens a browser for OIDC authentication via Authentik.

GitHub CLI

gh auth login

Follow prompts to authenticate with GitHub.

Verification

Run these commands to verify your setup:

# Check Vault connectivity
./scripts/vault-helper.sh status

# Verify kubectl can reach cluster
kubectl --context fzymgc-house get nodes

# Verify Terraform
terraform version

# Verify Ansible
ansible --version

# Verify GitHub CLI
gh auth status

Expected output includes: - Vault showing "connected" status - 8 cluster nodes listed (3 control plane, 5 workers) - Terraform version 1.x - Ansible version 2.x - GitHub CLI showing authenticated status

Directory Structure

Key directories you'll work with:

Directory Purpose
ansible/ Cluster deployment playbooks
tf/ Terraform modules for infrastructure
argocd/ Kubernetes manifests (GitOps)
docs/ Documentation (MkDocs)
scripts/ Utility scripts

Next Steps