From e136ebb4088ef281c33a3dc3e13deacdd0aa8df6 Mon Sep 17 00:00:00 2001 From: "Claude Sonnet 4.6 (1M context)" Date: Fri, 17 Apr 2026 10:30:10 +0000 Subject: [PATCH 1/2] docs: consolidate agent instructions into AGENTS.md Replace CLAUDE.md and .github/copilot-instructions.md with a single AGENTS.md as the canonical source of truth for AI coding agent instructions. CLAUDE.md becomes a symlink to AGENTS.md; copilot- instructions.md is removed since copilot reads AGENTS.md natively. Co-Authored-By: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-Authored-By: Vic Kerr --- .github/copilot-instructions.md | 165 -------------------------------- AGENTS.md | 105 ++++++++++++++++++++ CLAUDE.md | 1 + 3 files changed, 106 insertions(+), 165 deletions(-) delete mode 100644 .github/copilot-instructions.md create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 90e206af0..000000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,165 +0,0 @@ -# Copilot Instructions for CAPMOX - -This repository contains the Cluster API Provider for Proxmox Virtual Environment (CAPMOX). - -## Project Overview - -CAPMOX is a Kubernetes Cluster API provider that enables declarative management of Kubernetes clusters on Proxmox VE infrastructure. It follows the Kubernetes Operator pattern and uses controllers to reconcile resources. - -- **Language**: Go 1.25.0 -- **Framework**: Kubebuilder v4 -- **Key Dependencies**: - - Cluster API v1.11.4 - - controller-runtime v0.21.0 - - go-proxmox v0.4.0 (Proxmox API client) - -## Repository Structure - -- `api/v1alpha1/` - v1alpha1 (deprecated) Custom Resource Definitions with conversion support (ProxmoxCluster, ProxmoxMachine, ProxmoxMachineTemplate, ProxmoxClusterTemplate) -- `api/v1alpha2/` - v1alpha2 (current) Custom Resource Definitions (ProxmoxCluster, ProxmoxMachine, ProxmoxMachineTemplate, ProxmoxClusterTemplate) -- `cmd/main.go` - Controller manager entry point -- `internal/controller/` - Reconciliation logic for controllers -- `internal/webhook/` - Webhook handlers for validation and defaulting -- `pkg/` - Shared packages (ignition, cloudinit, proxmox client, scope, ipam) -- `config/` - Kustomize configuration for CRDs, RBAC, webhooks -- `docs/` - Documentation (Development.md, Usage.md, Troubleshooting.md) -- `test/e2e/` - End-to-end tests -- `hack/` - Helper scripts and tools - -## API Versions - -This branch contains both v1alpha1 and v1alpha2 API versions: - -- **v1alpha1**: Original API version with conversion support to v1alpha2 -- **v1alpha2**: Enhanced API version with improved network configuration and cluster class support - - Unified `NetworkDevices` array (replacing separate `Default` and `AdditionalDevices`) - - Array-based machine type configuration with `ProxmoxClusterClassSpec` - - Support for multiple IPv4/IPv6 addresses per device - - Webhook v2 for enhanced validation and defaulting - -The conversion layer (`api/v1alpha1/*_conversion.go`) automatically handles conversions between API versions. - -## Build and Development Workflow - -### Prerequisites -- Go 1.25.0 -- Docker (for building images and running kind) -- kubectl -- kind or minikube -- make - -### Key Commands - -**Building:** -```bash -make build # Build the manager binary -make docker-build # Build Docker image -``` - -**Testing:** -```bash -make test # Run unit tests (includes manifests, generate, fmt, vet) -make test WHAT=./pkg/... # Run tests for specific packages -``` - -**Code Generation and Validation:** -```bash -make manifests # Generate CRDs and RBAC manifests -make generate # Generate DeepCopy methods -make mockgen # Generate mocks for testing -make verify # Verify modules and generated files are up to date -make verify-modules # Check if go.mod and go.sum are up to date -make verify-gen # Check if generated files are up to date -``` - -**Linting:** -```bash -make lint # Run golangci-lint -make yamlfmt # Format YAML files -``` - -**Code Formatting:** -```bash -make fmt # Run go fmt -make vet # Run go vet -``` - -**Module Management:** -```bash -make tidy # Run go mod tidy -``` - -### Development Environment Setup - -**Tilt (Recommended):** -Use the helper script to set up a development environment with Tilt: -```bash -./hack/start-capi-tilt.sh -``` - -This will: -1. Clone cluster-api and cluster-api-ipam-provider-in-cluster if not present -2. Create tilt-settings.json -3. Start Tilt with hot-reload enabled - -**Manual Setup:** -See `docs/Development.md` for detailed manual setup instructions. - -### Important Development Notes - -1. **Always run `make verify` before committing** - This ensures generated files and modules are up to date -2. **After modifying API types**, run `make manifests generate` to update generated code and CRDs -3. **After adding new dependencies**, run `make tidy` to update go.mod and go.sum -4. **When adding mocks**, update `.mockery.yaml` and run `make mockgen` -5. **When modifying API types**, ensure conversion functions in `api/v1alpha1/*_conversion.go` are updated accordingly - -## CI/CD Pipeline - -The repository uses GitHub Actions with the following workflows: - -- **test.yml**: Runs `make verify` and `make test`, includes SonarQube scanning -- **lint.yml**: Runs golangci-lint, yamllint, and actionlint -- **e2e.yml**: End-to-end testing -- **codespell.yml**: Spell checking - -All PRs must pass these checks before merging. - -## Common Issues and Workarounds - -1. **Test Failures**: Run `make test` to see detailed error messages. Unit tests use envtest with Kubernetes 1.30.0. -2. **Build Failures**: Ensure Go version matches go.mod (1.25.0). Run `make tidy` to fix module issues. -3. **Generated Files Out of Date**: Run `make verify-gen` to check, then `make manifests generate mockgen` to fix. -4. **Module Issues**: Run `make verify-modules` to check, then `make tidy` to fix. -5. **Conversion Errors**: If you encounter conversion errors between v1alpha1 and v1alpha2, check the conversion functions in `api/v1alpha1/*_conversion.go`. - -## Testing Strategy - -- Unit tests are located alongside source files (e.g., `pkg/scope/machine_test.go`) -- Use testify for assertions and gomega for BDD-style tests -- Mock interfaces are generated using mockery (see `.mockery.yaml`) -- E2E tests are in `test/e2e/` and require a Proxmox VE instance -- Conversion tests ensure data integrity between API versions - -## Key Conventions - -- Controllers follow the Cluster API contract for infrastructure providers -- Use structured logging with klog/logr -- Error handling uses pkg/errors for wrapping -- Network configuration supports both cloud-init and Ignition -- Support for IPAM provider for IP address management -- API conversion maintains backward compatibility between v1alpha1 and v1alpha2 - -## Environment Variables - -Development environment variables are documented in `envfile.example`. Key variables: -- `PROXMOX_URL` - Proxmox API endpoint -- `PROXMOX_TOKEN` - API token ID -- `PROXMOX_SECRET` - API token secret -- `CAPMOX_LOGLEVEL` - Log level (default: 4) - -## Additional Resources - -- [Development Guide](docs/Development.md) -- [Usage Guide](docs/Usage.md) -- [Contributing Guide](CONTRIBUTING.md) -- [Troubleshooting](docs/Troubleshooting.md) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..141079384 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,105 @@ +# AGENTS.md + +CAPMOX (Cluster API Provider for Proxmox VE) enables declarative management of Kubernetes clusters on Proxmox VE using the Cluster API provider contract. See `go.mod` for dependency versions. + +The storage API version is **v1alpha2** (imported as `infrav1`). v1alpha1 exists only for backward compatibility with automatic conversion to/from v1alpha2. + +## Repository Structure + +- `api/v1alpha1/` — deprecated CRDs with conversion to v1alpha2 +- `api/v1alpha2/` — current storage version CRDs (ProxmoxCluster, ProxmoxMachine, ProxmoxMachineTemplate, ProxmoxClusterTemplate) +- `cmd/main.go` — controller manager entry point +- `internal/controller/` — reconciliation logic +- `internal/webhook/` — validation and defaulting webhooks +- `internal/service/` — VM, scheduler, and task services +- `pkg/` — shared packages (proxmox client, scope, cloudinit, ignition, ipam) +- `config/` — Kustomize configuration for CRDs, RBAC, webhooks +- `hack/` — helper scripts +- `test/e2e/` — end-to-end tests + +## Commands + +### Build & Test + +```bash +make build # Build manager binary +make test # Run unit tests +make test WHAT=./pkg/scope/... # Run tests for specific packages +make lint # Run golangci-lint + kube-api-linter +make lint-fix # Lint with auto-fix +make yamlfmt # Format YAML files +make tidy # go mod tidy +make tilt-up # Start Tilt dev environment in a kind cluster +``` + +### Code Generation + +```bash +make manifests # Regenerate CRDs, RBAC, webhook manifests +make generate # Regenerate DeepCopy methods and conversion functions +make mockgen # Regenerate mocks (configured in .mockery.yaml) +``` + +### Verification + +```bash +make verify # Verify modules and generated files are up to date +``` + +## Architecture + +### Reconciliation Flow + +Controllers (`internal/controller/`) reconcile two custom resources: + +- **ProxmoxCluster** — manages cluster-level infrastructure (control plane endpoint, allowed nodes) +- **ProxmoxMachine** — manages individual VM lifecycle on Proxmox VE + +Each controller creates a **Scope** (`pkg/scope/`) bundling the CAPI owner objects, infrastructure CR, Proxmox client, and IPAM helper into a single context object passed through the reconciliation pipeline. + +The ProxmoxMachine controller delegates VM operations to services under `internal/service/`: +- `vmservice/` — VM clone, configure, bootstrap (cloud-init or Ignition), IP assignment, power management, deletion +- `scheduler/` — selects which Proxmox node to place a new VM on +- `taskservice/` — tracks async Proxmox task completion and error handling + +### Proxmox Client Abstraction + +`pkg/proxmox/client.go` defines the `Client` interface for all Proxmox API operations. The production implementation lives in `pkg/proxmox/goproxmox/` (wrapping `go-proxmox`). Tests use a mock at `pkg/proxmox/proxmoxtest/`. + +### API Versions and Conversion + +- `api/v1alpha2/` — current storage version +- `api/v1alpha1/` — deprecated; conversion implemented in `*_conversion.go` and `zz_generated.conversion.go` + +Key v1alpha2 change: unified `NetworkDevices` array replacing v1alpha1's split of `Default` + `AdditionalDevices`. + +### Bootstrap & IPAM + +`pkg/cloudinit/` and `pkg/ignition/` handle cloud-init and Flatcar Ignition bootstrap data. IP management is via the Cluster API IPAM contract (`pkg/kubernetes/ipam/`). + +## Testing + +- Unit tests colocated with source files, using envtest; see `Makefile` for `ENVTEST_K8S_VERSION` +- First `make test` run builds envtest binaries — setup output is not a test failure +- `testify` for assertions, `gomega`/`ginkgo` for BDD-style tests +- Proxmox client mocks generated via `make mockgen` (`.mockery.yaml`) +- E2E tests in `test/e2e/` require a live Proxmox VE instance; controlled by PR labels + +## Rules + +✅ **Always:** +- Run `make manifests generate mockgen` after modifying API types +- If conversion behavior changes, update `api/v1alpha1/*_conversion.go` +- Run `make lint verify test` before committing + +⚠️ **Ask before:** +- Changing v1alpha1 conversion functions (affects backward compatibility) +- Removing or renaming fields in v1alpha2 API types + +🚫 **Never:** +- Edit files with a `Code generated … DO NOT EDIT` header +- Edit the unmarked outputs of `make manifests` (`config/crd/bases/*.yaml`, `config/rbac/role.yaml`, `config/webhook/manifests.yaml`) or `make crs-*` (`templates/crs/cni/*.yaml`) — regenerate instead + +## Environment + +See `envfile.example` for development config. Key vars: `PROXMOX_URL`, `PROXMOX_TOKEN`, `PROXMOX_SECRET`, `CAPMOX_LOGLEVEL`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 5b3a04df0898470fd662c477ba2e08b4bc5a26ed Mon Sep 17 00:00:00 2001 From: Vic Kerr Date: Fri, 17 Apr 2026 11:28:42 +0000 Subject: [PATCH 2/2] docs: add AI contribution policy and PR guidelines Add AI-Assisted Contributions section to CONTRIBUTING.md covering authorship, transparency, human oversight, and quality expectations. Add general PR scope guidelines (complete, self-contained, reasonable size, dependent PRs). Reference CONTRIBUTING.md from AGENTS.md. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- AGENTS.md | 4 ++++ CONTRIBUTING.md | 22 ++++++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 141079384..c3589d136 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -85,6 +85,10 @@ Key v1alpha2 change: unified `NetworkDevices` array replacing v1alpha1's split o - Proxmox client mocks generated via `make mockgen` (`.mockery.yaml`) - E2E tests in `test/e2e/` require a live Proxmox VE instance; controlled by PR labels +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines, paying particular attention to the [AI-Assisted Contributions](CONTRIBUTING.md#ai-assisted-contributions) section which covers authorship, transparency, and quality expectations for AI-assisted work. + ## Rules ✅ **Always:** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c37fee614..b14aeeb5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,6 +33,9 @@ git push origin feature-branch * Provide a clear and descriptive title for your changes. * Include details about the changes and the problem it solves. * Reference any relevant issues or pull requests. +* Keep changes complete and self-contained — partial implementations are not mergeable and stall review. +* Keep PRs focused and of reasonable size; smaller, focused changes are easier and faster to review and merge. +* A chain of dependent PRs is a good way to break up large contributions. The ionos-cloud/cluster-api-provider-proxmox repo requires approval to run actions on external PRs. This includes linters, unit (go) and e2e tests, scanners. @@ -67,6 +70,25 @@ Make sure that it's lint-free and that generated files are up to date. make lint test verify ``` +## AI-Assisted Contributions + +All guidelines in this document apply to AI-assisted contributions. The rules in this section are in addition to those. + +AI tools are welcome at any stage. + +**Authorship**: The git commit author must be the person responsible for the contribution. Any agent that produced code must be attributed with a `Co-Authored-By:` trailer. The only exception is a commit that solely modifies an agent instructions file (e.g. `AGENTS.md`) where the agent may be the author and the person a co-author. + +**Transparency**: AI agents must be clearly identified as such. We don't mind interacting with agents; we do mind agents masquerading as people. Do not have an agent interact on issues or pull requests while presenting as a human contributor. + +**Human oversight**: The human contributor is responsible for the entire contribution and must oversee it end to end — code, tests, and description. + +**Quality**: A non-draft pull request must represent completed work: +- Includes relevant tests covering the changes +- All tests and linters pass (`make lint test verify`) +- Correct attribution on all commits + +Pull requests that violate these standards will be closed. + ## Documentation Ensure that your changes are reflected in the documentation. If you are introducing new features, update the documentation accordingly.