The base formae agent image at
ghcr.io/platform-engineering-labs/formae ships with the standard plugin set:
aws, azure, gcp, oci, ovh, and auth-basic. If you deploy through one
of the cloud install guides to manage one of those clouds, you are done, with no
extra steps.
To manage anything else (grafana, datadog, k8s, gha, gitlab, compose,
databricks, and so on) build a derived image that layers the plugin on top of
the base, then point your deployment at the derived image. formae plugin install
runs locally on the host that invokes it; for a cloud-deployed agent the derived
image is the supported path.
Dockerfile pattern
Replace <plugin-name> with the plugin you want. Add more plugins to the same
install invocation by space-separating them.
The chown -R pel:pel /opt/pel is required. The plugin install runs as root
and can leave root-owned files under /opt/pel. The agent runs as pel and
refuses to start when its install tree is root-owned, and the image has no sudo,
so restore ownership at build time.
Build and verify locally
The plugin you added should appear alongside the standard set. To confirm the
agent loads it at startup:
Look for a Plugin registered: namespace=<UPPERCASE> line for the plugin you
added.
Deploy the derived image
Each install path pulls the agent image from its own registry. Push the derived
image to the registry your deployment reads from, then point the deployment at it
instead of ghcr.io/.../formae:latest.
- AWS (Bootstrap): push to ECR, then pass the derived image as
--formae-image when you install or upgrade the agent.
- Azure Container Instances: push to ACR (or any registry the ACI managed identity can read), then set
--image on the Azure deploy.
- GCP Cloud Run: push to an Artifact Registry repository in the same project, then set
--image on the GCP deploy.
- Kubernetes / Helm: push to any registry the cluster can pull from, then override the chart image with
--set image.repository=<your-registry>/formae-extended --set image.tag=<your-tag> on the Helm install.
Verify the running agent
formae plugin list reads the local /opt/pel tree only; there is no remote API
for plugin inspection. To verify a cloud-deployed agent loaded the plugin, exec
into the running container or read its startup logs.
Known constraints
- The formae CLI talks only to an agent on the same version. Whoever runs the CLI against a derived-image deployment must run the version the image ships. Update the local CLI with
formae update <version>.
BASE_VERSION pins the image tag, not the agent binary: a :0.87.1 image can ship a slightly newer binary because the base resolves the version at build time. To pin the binary deterministically, add an explicit setup.sh install --yes formae@<exact-version> step before the plugin install.
