Extension Examples
Working implementations of Defakto extensions, each one a complete walkthrough from source code to a verified deployment. Each guide lists its own prerequisites.
These pages are task-oriented. For configuration fields, wire protocols, and troubleshooting, see the reference page for the extension point you are using.
Which extension do you need?
Defakto has four extension points. They run in different places, are configured through different mechanisms, and are not interchangeable, so it is worth confirming which one you need before following a guide. Two questions narrow it down.
Where does the data or the decision live?
- On the workload's own host — hardware present on the node, a local file, the workload's binary. Only an agent-side extension can see these.
- In a central system — a CMDB, an asset inventory, a service catalog, a policy engine. A server-side extension reaches these without granting every node access to them.
At which point in the lifecycle?
- A workload asks for an SVID → workload attestation.
- An agent connects to the Trust Domain Server → agent attestation.
- A workload asks the server directly, with no agent involved → serverless attestation.
The four surfaces
| Surface | Runs | Your code is | Configured with |
|---|---|---|---|
| Server workload attestation | Trust Domain Server, on each SVID request | An HTTPS webhook | spirl-server Helm values, under trustDomainDeployment.deployment.extensionWorkloadAttestation |
| Agent workload attestation | Every agent host, on each SVID request | A local executable speaking JSON over stdin and stdout | spirl-system Helm values, under agent.extensionWorkloadAttestation |
| Agent attestation | Both, when an agent logs in | An executable on the host and a webhook on the server | Managed Configuration, AgentAttestation policy |
| Serverless attestation | Trust Domain Server, on each SVID request | An HTTPS webhook, with the proof produced in the workload through the SDK | Managed Configuration, ServerlessAttestation policy |
Three differences catch people out:
- Only the server workload attestation surface can be scoped.
invokeForClusterIdsandinvokeForWorkloadAttributesnarrow which workloads reach your webhook. The agent runs its executable for every workload on the node, with no equivalent filter. - Rollout differs. The two workload attestation surfaces are Helm values, so a change rolls pods: server pods for one, the agent DaemonSet for the other. Agent and serverless attestation are Managed Configuration and apply without restart.
- Both workload attestation surfaces can deny as well as enrich. Returning an
errorrefuses the identity. The choice between them is about where the decision's inputs live, not about what the extension is allowed to do.
Examples by task and surface
The agent-side and server-side surfaces do the same two jobs, so the guides pair up:
| What you want to do | On the agent host | From a central webhook |
|---|---|---|
| Add custom attributes | GPU Detection | Add Custom Attributes |
| Refuse an identity | Binary Verification | Deny SVID Issuance |
| Control SPIFFE ID naming | — | Registration Entries |
If the pair on a row both look plausible, pick by the first question above: The host-local input belongs on the agent, the centrally-maintained one belongs in a webhook.
Examples
Examples are grouped by the surface they use, since that is the choice you make first.
Server Workload Attestation
Webhook examples that run on the server.
Agent Workload Attestation
Executable examples that run on agent hosts.