63 lines
2.5 KiB
Markdown
63 lines
2.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Preview infrastructure changes
|
|
pulumi preview
|
|
|
|
# Sync Pulumi state with actual Proxmox state (run before up if resources were changed manually)
|
|
pulumi refresh --yes
|
|
|
|
# Deploy infrastructure
|
|
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.
|