Formae Plugin Proxmox

My attempt at writing a formae plugin to interact with proxmox.

Very much WIP.

Installation

# Install the plugin
make install

Supported Resources

TODO: Document your supported resource types

Resource Type	Description
PROXMOX::Service::LXC	LXC Container

Configuration

Configure a target in your Forma file:

new formae.Target {
    label = "proxmox"
    namespace = "PROXMOX"
    config = new Mapping {
      ["url"] = "https://your-url:8006"
      ["node"] = "nodename"
    }
  }

Examples

See the examples/ directory for usage examples.

# Evaluate an example
formae eval examples/basic/main.pkl

# Apply resources
formae apply --mode reconcile --watch examples/basic/main.pkl

Development

Prerequisites

• Go 1.25+
• Pkl CLI
• Cloud provider credentials (for conformance testing)

Building

make build      # Build plugin binary
make test       # Run unit tests
make lint       # Run linter
make install    # Build + install locally

Local Testing

# Install plugin locally
make install

# Start formae agent
formae agent start

# Apply example resources
formae apply --mode reconcile --watch examples/basic/main.pkl

Conformance Testing

Conformance tests validate your plugin's CRUD lifecycle using the test fixtures in testdata/:

File	Purpose
resource.pkl	Initial resource creation
resource-update.pkl	In-place update (mutable fields)
resource-replace.pkl	Replacement (createOnly fields)

The test harness sets FORMAE_TEST_RUN_ID for unique resource naming between runs.

make conformance-test                  # Latest formae version
make conformance-test VERSION=0.80.0   # Specific version

The scripts/ci/clean-environment.sh script cleans up test resources. It runs before and after conformance tests and should be idempotent.

Licensing

Plugins are independent works and may be licensed under any license of the author’s choosing.

See the formae plugin policy: <https://docs.formae.io/plugin-sdk/