repository·main·Indexed 20 days ago
https://github.com/platform-engineering-labs/formaeformae is an agentic Infrastructure-as-Code (IaC) tool that uses Pkl to manage infrastructure. It eliminates the need for state files by automatically synchronizing infrastructure code with real-world changes. The documentation covers the core tool, the experimental PKL Generator for creating schemas from resources, and the SDK for developing resource plugins, including the ResourcePlugin interface, plugin conformance testing, and manifest configuration.
The harness automatically selects the appropriate formae binary for each test run based on the following priority:
FORMAE_BINARY is set, that exact path is used.FORMAE_VERSION is set, the harness searches for that exact version in the stable channel, then the dev channel.minFormaeVersion from the plugin's formae-plugin.pkl and looks for the highest matching release in the stable channel.minFormaeVersion, the harness falls back to the dev channel.If no version can satisfy the minFormaeVersion floor, the test fails.
For long-running cloud operations, your CRUD methods should return a *resource.ProgressResult (embedded in the result type) with OperationStatus.InProgress and the cloud-side NativeID. The agent will then poll your plugin's Status method on a schedule until the operation reaches Success or Failure.
Automatic Retries: The SDK automatically retries operations if you return recoverable error codes. Non-recoverable error codes will terminate the operation immediately.
formae is designed to support various engineering roles and workflows:
When developing resource plugins, adhere to these constraints:
NativeID: Every ProgressResult must include a NativeID so the agent can re-find the resource during polling.json.RawMessage). Ensure they round-trip cleanly through your Pkl schema.resource.OperationErrorCode. Returning InternalFailure for a permanent error causes unnecessary retries, while using Throttling for auth failures masks the root cause.The conformance suite discovers Pkl test fixtures in a testdata/ directory located next to your test file. For every base resource file, the suite looks for specific optional suffixes to drive different lifecycle steps:
| File | Role |
|---|---|
<resource>.pkl | Required. Declares the resource to create and the expected post-create state. |
<resource>-update.pkl | Optional. Same resource with at least one mutable property changed; drives the update step. |
<resource>-replace.pkl | Optional. Same resource with a create-only field changed; drives the replace step (expects NativeID to change). |
Note: A unique identifier FORMAE_TEST_RUN_ID is provided as an environment variable to Pkl fixtures, allowing you to parameterize resource names to avoid collisions during concurrent runs.
You can extend your ResourcePlugin implementation by adding these optional interfaces to the same struct:
ObservablePlugin: Allows you to receive a Logger and MetricRegistry at startup. The SDK also injects these into the context.Context of every CRUD method. Use plugin.LoggerFromContext(ctx) and plugin.MetricsFromContext(ctx) to access them.Configurable: Allows you to receive plugin-specific configuration as json.RawMessage (sourced from the user's formae.conf.pkl) during startup, before the plugin announces itself to the agent.You can run the conformance tests using standard go test commands. Use environment variables to control which suite runs, filter specific tests, or enable parallel execution.
go test -v ./...Use FORMAE_TEST_TYPE=crud to skip discovery, and FORMAE_TEST_FILTER to specify resource types (comma-separated or regex).
FORMAE_TEST_TYPE=crud FORMAE_TEST_FILTER="s3-bucket,iam-group" go test -v ./...Use FORMAE_TEST_TYPE=discovery and FORMAE_TEST_PARALLEL=true.
FORMAE_TEST_TYPE=discovery FORMAE_TEST_PARALLEL=true go test -v ./...# Both suites
go test -v ./...
# CRUD only, on a subset of resource types
FORMAE_TEST_TYPE=crud FORMAE_TEST_FILTER="s3-bucket,iam-group" go test -v ./...
# Discovery only, in parallel
FORMAE_TEST_TYPE=discovery FORMAE_TEST_PARALLEL=true go test -v ./...To use the PKL Generator, follow this specific workflow.
formae using the following commands:make build build-debug build-pkl-localpkl project resolveformae extract command:formae extract --output-schema json --query="managed:false" --output-consumer machinesplit.py helper script to break the extracted JSON files into smaller, manageable pieces (recommended for large files).run_generator.py script to process the split JSON files and generate the PKL schema.File Locality: When running the generator, all files must reside in the same directory or in subdirectories. The PKL engine cannot access files located outside of the current working directory tree.
# 1. Build formae
make build build-debug build-pkl-local
# 2. Resolve PKL project
pkl project resolve
# 3. Extract resources
formae extract --output-schema json --query="managed:false" --output-consumer machine
# 4. Split (using split.py)
python3 split.py <input_file>
# 5. Run generator (using run_generator.py)
python3 run_generator.pyTo validate a formae resource plugin, add two conformance test functions to a _test.go file in your plugin repository. This uses the plugin-conformance-tests harness to exercise your plugin through the real formae CLI and agent lifecycle (CRUD and discovery).
Module path: github.com/platform-engineering-labs/formae/pkg/plugin-conformance-tests
package main
import (
"testing"
conformance "github.com/platform-engineering-labs/formae/pkg/plugin-conformance-tests"
)
func TestPluginConformance(t *testing.T) {
conformance.RunCRUDTests(t)
}
func TestPluginDiscovery(t *testing.T) {
conformance.RunDiscoveryTests(t)
}The recommended way to start a new resource plugin is to use the bundled scaffolding command. This clones the formae-plugin-template repository and configures it with the necessary SDK wiring, a manifest, a Pkl schema package, and a conformance test suite using pkg/plugin-conformance-tests to validate your plugin end-to-end.
formae plugin init