homelab-infrastructure-as-code/01-proxmox-infra/CLAUDE.md

CLAUDE.md

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

Project Overview

This is a Pulumi TypeScript project (proxmox-infra) for provisioning VMs and LXC containers in Proxmox using the @muhlba91/pulumi-proxmoxve provider. The stack name is dev.

Common Commands

# Install dependencies
npm install

# Preview infrastructure changes
pulumi preview

# Sync Pulumi state with actual Proxmox state (run before up if resources were changed manually)
# Note: shut down all k3s VMs in Proxmox first — refresh is slow against running VMs
pulumi refresh --yes

# Deploy infrastructure
# Note: shut down all k3s VMs in Proxmox first, then run:
pulumi refresh --yes && pulumi up --yes

# Destroy infrastructure
pulumi destroy

# View current stack outputs
pulumi stack output

# View stack config
pulumi config

Architecture

• Entry point: index.ts — all Pulumi resources are declared here
• Provider: @muhlba91/pulumi-proxmoxve v8.x — community Proxmox provider (not an official Pulumi provider)
• Stack: dev — configured in Pulumi.dev.yaml
• Runtime: Node.js with npm, TypeScript compiled to bin/ (excluded from git)

CI/CD (Gitea Actions)

Workflow file: ../.gitea/workflows/deploy-proxmox-infra.yaml

Triggers: push to main and pull requests targeting main, scoped to changes under proxmox-infra/** or .gitea/workflows/**.

• Pull request → pulumi preview (no changes deployed)
• Push to main → pulumi refresh then pulumi up

Secrets required in Gitea (Settings → Actions → Secrets):

• PULUMI_BACKEND_URL — PostgreSQL connection string for the self-hosted state backend
• PULUMI_CONFIG_PASSPHRASE — passphrase used to decrypt secrets in Pulumi.dev.yaml
• PULUMI_DEV_YAML — base64-encoded content of Pulumi.dev.yaml; update manually whenever the file changes: base64 -w 0 Pulumi.dev.yaml

Key Notes

• Credentials for both Proxmox nodes are stored as encrypted secrets in Pulumi.dev.yaml and decrypted at runtime using PULUMI_CONFIG_PASSPHRASE. Do not pass Proxmox credentials via environment variables — the code uses config.requireSecret().
• There are two Proxmox providers: pveProvider (main node pve) and pveBckpProvider (backup node pve-bckp). Always pass the correct provider when adding resources.
• Pulumi.dev.yaml contains the encryption salt — never delete it or secrets become unrecoverable.
• TypeScript is compiled with strict mode, nodenext module resolution, and noImplicitReturns — all functions must have explicit return types when TypeScript cannot infer them.
• Don't add a co-author when committing to git.