135 lines
3.6 KiB
Markdown
135 lines
3.6 KiB
Markdown
> **⚠️ Do not clone this repository directly!**
|
||
>
|
||
> Use `formae plugin init` to create your plugin. This command scaffolds a new
|
||
> plugin from this template with proper naming and configuration.
|
||
>
|
||
> ```bash
|
||
> formae plugin init my-plugin
|
||
> ```
|
||
|
||
---
|
||
|
||
## Setup Checklist
|
||
|
||
*Remove this section and the warning above after completing setup.*
|
||
|
||
After creating your plugin with `formae plugin init`, complete these steps:
|
||
|
||
- [X] Update `formae-plugin.pkl` with your plugin metadata (name, namespace, description)
|
||
- [X] Define your resource types in `schema/pkl/*.pkl`
|
||
- [ ] Implement CRUD operations in `plugin.go`
|
||
- [ ] Update test fixtures in `testdata/*.pkl` to use your resources
|
||
- [ ] Update this README (replace title, description, resources table, etc.)
|
||
- [ ] Set up local credentials for testing
|
||
- [ ] Run conformance tests locally: `make conformance-test`
|
||
- [ ] Configure CI credentials in `.github/workflows/ci.yml` (optional)
|
||
- [ ] Remove this checklist section and the warning box above
|
||
|
||
For detailed guidance, see the [Plugin SDK Documentation](https://docs.formae.io/plugin-sdk).
|
||
|
||
---
|
||
|
||
# Example Plugin for formae
|
||
|
||
*TODO: Update title and description for your plugin*
|
||
|
||
Example Formae plugin template - replace this with a description of what your plugin manages.
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
# Install the plugin
|
||
make install
|
||
```
|
||
|
||
## Supported Resources
|
||
|
||
*TODO: Document your supported resource types*
|
||
|
||
| Resource Type | Description |
|
||
| ------------------------------ | ----------------------------------------------------- |
|
||
| `PROXMOX::Service::Resource` | Example resource (replace with your actual resources) |
|
||
|
||
## Configuration
|
||
|
||
Configure a target in your Forma file:
|
||
|
||
```pkl
|
||
new formae.Target {
|
||
label = "my-target"
|
||
namespace = "PROXMOX" // TODO: Update with your namespace
|
||
config = new Mapping {
|
||
["region"] = "us-east-1"
|
||
// TODO: Add your provider-specific configuration
|
||
}
|
||
}
|
||
```
|
||
|
||
## Examples
|
||
|
||
See the [examples/](examples/) directory for usage examples.
|
||
|
||
```bash
|
||
# 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](https://pkl-lang.org/main/current/pkl-cli/index.html)
|
||
- Cloud provider credentials (for conformance testing)
|
||
|
||
### Building
|
||
|
||
```bash
|
||
make build # Build plugin binary
|
||
make test # Run unit tests
|
||
make lint # Run linter
|
||
make install # Build + install locally
|
||
```
|
||
|
||
### Local Testing
|
||
|
||
```bash
|
||
# 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.
|
||
|
||
```bash
|
||
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/
|