spire-agent | Ringleader Docs

Installs SPIRE Agent, points it at a SPIRE server you operate, and runs it as a managed service, so ordinary SPIFFE client libraries on the workstation obtain SVIDs from the Workload API with nothing written for them. Give it the four things it needs to join your trust domain:

devtools:
  - name: spire-agent
    config:
      serverAddress: spire.acme.example
      trustDomain: acme.example
      nodeAttestor: gcp_iit
      trustBundle: |
        -----BEGIN CERTIFICATE-----
        MIIB...
        -----END CERTIFICATE-----

Use it on cloud workstations. A local VM has no platform proof for a node attestor to consume, so the agent would install and start there and then fail to attest; nodeAttestor accepts only the three cloud attestors for that reason.

The rest of this page covers the fields, what the agent sets up, and two limits worth knowing before you rely on it.

`config` fields

Field	Type	Description
`serverAddress`	`string`	Required. Your SPIRE server’s host.
`trustDomain`	`string`	Required. The SPIFFE trust domain to join, e.g. `acme.example`.
`nodeAttestor`	`string`	Required. One of `gcp_iit`, `aws_iid`, `azure_msi`.
`trustBundle`	`string`	Required. The PEM bootstrap bundle the agent uses to authenticate the server.
`serverPort`	`string`	Optional. Defaults to SPIRE’s own `8081`.

All four required keys must be present together. With an incomplete set the binary is still installed, but no service is started, and the workstation records a message naming exactly which keys are missing.

This is delivery, not identity

Your SPIRE server remains the system of record. Ringleader installs, configures and runs the agent; it does not mint, verify or map any identity of its own here. A workstation’s own Ringleader identity is a separate mechanism.

Version behavior

`version`	Result
omitted	a pinned, known-good SPIRE release
`1.15.2`, `v1.15.2`	that release

The release archive for the workstation’s architecture is downloaded and only the agent binary is installed, not the server and not the rest of the distribution.

What it sets up

The Workload API socket at /run/spire/agent/public/api.sock. Workloads reach it by peer credential, so its location under /run does not need to be writable by them.
SPIFFE_ENDPOINT_SOCKET exported in login shells, the variable every SPIFFE client library reads. This is what makes “a client obtains an SVID with nothing written for it” true.
A managed service that runs the agent and restarts it on failure.
Persistent agent state, so a rebooted workstation does not have to re-attest, which matters because the cloud node attestors are one-shot per instance.

Two limits

Local providers are not covered. See above: use this on cloud workstations.

This does not give you a SPIRE registration per workstation. Workstations are created on demand and torn down, so nobody can pre-create a SPIRE entry per machine. The workable shape on the SPIRE side is a node alias parented on a coarse platform selector (the project, the subscription, the account), with per-workload distinction coming from the entries above it. Every workstation under that selector is then one node identity inside SPIRE. Choose it knowingly; it is not a substitute for a per-machine identity.

Example

apiVersion: workstations.ringleader.dev/v1
kind: WorkstationConfig
metadata:
  name: spiffe-box
  namespace: dev
spec:
  selector:
    matchLabels:
      tier: dev
  devtools:
    - name: spire-agent
      config:
        serverAddress: spire.acme.example
        serverPort: "8081"
        trustDomain: acme.example
        nodeAttestor: gcp_iit
        trustBundle: |
          -----BEGIN CERTIFICATE-----
          MIIBxTCCAWugAwIBAgIQ...
          -----END CERTIFICATE-----

Notes

A value that fails validation is dropped, and the workstation records how many declared values were unusable, so a malformed trust bundle shows up as a message.
Works on Debian, Ubuntu and Alpine: SPIRE’s Linux build is statically linked, so one artifact serves both families.