infra: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a multi-environment, multi-cloud infrastructure-as-code repository for a home lab environment using GitOps principles. It manages Terraform configurations for cloud resources, Kubernetes workloads via Flux CD, and on-premises virtualization.

Related Repositories:

• anthr76/snowflake - System-level configuration for nodes, routers, and infrastructure components

Additional Context:

• See .github/instructions/.instructions.md for comprehensive coding standards and guidelines

Development Environment

This repository uses Flox (Nix-based development environments) for consistent tooling. All required tools are automatically available:

# Enter the development environment (automatically via direnv, or manually)
flox activate

# All tools are now available: kubectl, flux, helm, sops, age, just, etc.

The environment is defined in .flox/env/manifest.toml. direnv auto-activates it on cd via .envrc (eval "$(flox activate)").

Never manually install tools - they are managed via the Flox manifest. To add a tool: flox install <package> (or edit .flox/env/manifest.toml).

kubectl-volsync is a custom Go build (not in the catalog) defined under .flox/pkgs/kubectl-volsync/. Build it once with flox build kubectl-volsync; the manifest's activation hook then adds ./result-kubectl-volsync/bin to PATH.

Common Commands

Task Automation

All automation tasks are defined in the Justfile. Use just instead of custom scripts:

# List all available tasks
just --list

# Reconcile all Flux GitRepositories and Kustomizations
just flux-reconcile

# Sync Flux GitRepos, Kustomizations, and HelmReleases
just flux-sync

# Suspend all Flux resources
just flux-suspend

# Resume all Flux resources
just flux-resume

# Install Fedora CoreOS for RPI4 (legacy - being phased out)
just burn-fcos-pi4