SPIRE Agent Configuration Reference

This document is a configuration reference for SPIRE Agent. It includes information about plugin types, built-in plugins, the agent configuration file, plugin configuration, and command line options for spire-agent commands.

Plugin types

Type	Description
KeyManager	Generates and stores the agent's private key. Useful for binding keys to hardware, etc.
NodeAttestor	Gathers information used to attest the agent's identity to the server. Generally paired with a server plugin of the same type.
WorkloadAttestor	Introspects a workload to determine its properties, generating a set of selectors associated with it.

Built-in plugins

Type	Name	Description
KeyManager	disk	A key manager which writes the private key to disk
KeyManager	memory	An in-memory key manager which does not persist private keys (must re-attest after restarts)
NodeAttestor	aws_iid	A node attestor which attests agent identity using an AWS Instance Identity Document
NodeAttestor	azure_msi	A node attestor which attests agent identity using an Azure MSI token
NodeAttestor	gcp_iit	A node attestor which attests agent identity using a GCP Instance Identity Token
NodeAttestor	join_token	A node attestor which uses a server-generated join token
NodeAttestor	k8s_sat	A node attestor which attests agent identity using a Kubernetes Service Account token
NodeAttestor	k8s_psat	A node attestor which attests agent identity using a Kubernetes Projected Service Account token
NodeAttestor	sshpop	A node attestor which attests agent identity using an existing ssh certificate
NodeAttestor	x509pop	A node attestor which attests agent identity using an existing X.509 certificate
WorkloadAttestor	docker	A workload attestor which allows selectors based on docker constructs such `label` and `image_id`
WorkloadAttestor	k8s	A workload attestor which allows selectors based on Kubernetes constructs such `ns` (namespace) and `sa` (service account)
WorkloadAttestor	unix	A workload attestor which generates unix-based selectors like `uid` and `gid`

Agent configuration file

The following table outlines the configuration options for SPIRE agent. These may be set in a top-level agent { ... } section of the configuration file. Most options have a corresponding CLI flag which, if set, takes precedence over values defined in the file.

SPIRE configuration files may be represented in either HCL or JSON. Please see the sample configuration file section for a complete example.

If the -expandEnv flag is passed to SPIRE, $VARIABLE or ${VARIABLE} style environment variables are expanded before parsing. This may be useful for templating configuration files, for example across different trust domains, or for inserting secrets like join tokens.

Configuration	Description	Default
`data_dir`	A directory the agent can use for its runtime data	$PWD
`log_file`	File to write logs to
`log_level`	Sets the logging level <DEBUG\|INFO\|WARN\|ERROR>	INFO
`log_format`	Format of logs, <text\|json>	Text
`server_address`	DNS name or IP address of the SPIRE server
`server_port`	Port number of the SPIRE server
`socket_path`	Location to bind the workload API socket	$PWD/spire_api
`trust_bundle_path`	Path to the SPIRE server CA bundle
`insecure_bootstrap`	Disables verifying the server's identity when the agent starts for the first time
`trust_domain`	The trust domain that this agent belongs to
`join_token`	An optional token which has been generated by the SPIRE server
`enable_sds`	Enables Envoy SDS support	false

Either trust_bundle_path or insecure_bootstrap must be set to configure the agent to bootstrap trust with the server. insecure_bootstrap is useful for testing purposes but should not be used in production since it makes person-in-the-middle attacks possible when the agent is first being introduced to the server. Since the server provides agents with the public keys that it (and its workloads) should trust, it is paramount that the agent verify that it has reached the intended server(s).

Plugin configuration

The agent configuration file also contains the configuration for the agent plugins. Plugin configurations are under the plugins { ... } section, which has the following format:

plugins {
    pluginType "pluginName" {
        ...
        plugin configuration options here
        ...
    }
}

The following configuration options are available to configure a plugin:

Configuration	Description
plugin_cmd	Path to the plugin implementation binary (optional, not needed for built-ins)
plugin_checksum	An optional sha256 of the plugin binary (optional, not needed for built-ins)
enabled	Enable or disable the plugin (enabled by default)
plugin_data	Plugin-specific data

Please see the built-in plugins section for information on plugins that are available out-of-the-box.

Telemetry configuration

Please see the Telemetry Configuration guide for more information about configuring SPIRE Agent to emit telemetry.

Health check configuration

The agent can expose additional endpoint that can be used for health checking. It is enabled by setting listener_enabled = true. Currently it exposes 2 paths: one for liveness (is agent up) and one for readiness (is agent ready to serve requests). By default, health checking endpoint will listen on localhost:80, unless configured otherwise.

health_checks {
        listener_enabled = true
        bind_address = "localhost"
        bind_port = "80"
        live_path = "/live"
        ready_path = "/ready"
}

Command line options

`spire-agent run`

All of the configuration file above options have identical command-line counterparts. In addition, the following flags are available:

Command	Action	Default
`-config`	Path to a SPIRE config file	conf/agent/agent.conf
`-dataDir`	A directory the agent can use for its runtime data
`-expandEnv`	Expand environment $VARIABLES in the config file
`-joinToken`	An optional token which has been generated by the SPIRE server
`-logFile`	File to write logs to
`-logFormat`	Format of logs, <text\|json>
`-logLevel`	DEBUG, INFO, WARN or ERROR
`-serverAddress`	IP address or DNS name of the SPIRE server
`-serverPort`	Port number of the SPIRE server
`-socketPath`	Location to bind the workload API socket
`-trustBundle`	Path to the SPIRE server CA bundle
`-trustDomain`	The trust domain that this agent belongs to

`spire-agent api fetch`

Calls the workload API to fetch an X509-SVID. This command is aliased to spire-agent api fetch x509.

Command	Action	Default
`-silent`	Suppress stdout
`-socketPath`	Path to the workload API socket	/tmp/agent.sock
`-timeout`	Time to wait for a response	1s
`-write`	Write SVID data to the specified path

`spire-agent api fetch jwt`

Calls the workload API to fetch a JWT-SVID.

Command	Action	Default
`-audience`	A comma separated list of audience values
`-socketPath`	Path to the workload API socket	/tmp/agent.sock
`-spiffeID`	The SPIFFE ID of the JWT being requested (optional)
`-timeout`	Time to wait for a response	1s

`spire-agent api fetch x509`

Calls the workload API to fetch a x.509-SVID.

Command	Action	Default
`-silent`	Suppress stdout
`-socketPath`	Path to the workload API socket	/tmp/agent.sock
`-timeout`	Time to wait for a response	1s
`-write`	Write SVID data to the specified path

`spire-agent api validate jwt`

Calls the workload API to validate the supplied JWT-SVID.

Command	Action	Default
`-audience`	A comma separated list of audience values
`-socketPath`	Path to the workload API socket	/tmp/agent.sock
`-svid`	The JWT-SVID to be validated
`-timeout`	Time to wait for a response	1s

`spire-agent api watch`

Attaches to the workload API and watches for X509-SVID updates, printing details when updates are received.

Command	Action	Default
`-socketPath`	Path to the workload API socket	/tmp/agent.sock

`spire-agent healthcheck`

Checks SPIRE agent's health.

Command	Action	Default
`-shallow`	Perform a less stringent health check
`-socketPath`	Path to the workload API socket	/tmp/agent.sock
`-verbose`	Print verbose information

Sample configuration file

This section includes a sample configuration file for formatting and syntax reference

agent {
    trust_domain = "example.org"
    trust_bundle_path = "/opt/spire/conf/initial_bundle.crt"

    data_dir = "/opt/spire/.data"
    log_level = "DEBUG"
    server_address = "spire-server"
    server_port = "8081"
    socket_path ="/tmp/agent.sock"
}

telemetry {
    Prometheus {
        port = 1234
    }
}

plugins {
    NodeAttestor "join_token" {
        plugin_data {
        }
    }
    KeyManager "disk" {
        plugin_data {
            directory = "/opt/spire/.data"
        }
    }
    WorkloadAttestor "k8s" {
        plugin_data {
            kubelet_read_only_port = "10255"
        }
    }
    WorkloadAttestor "unix" {
        plugin_data {
        }
    }
}

Envoy SDS Support

SPIRE agent has beta support for the Envoy Secret Discovery Service (SDS). When enabled, SDS is served over the same Unix domain socket as the Workload API. Envoy processes connecting to SDS are attested as workloads.

auth.TlsCertificate resources containing X.509-SVIDs can be fetched using the SPIFFE ID of the workload as the resource name (e.g. spiffe://example.org/database).

auth.CertificateValidationContext resources containing trusted CA certificates can be fetched using the SPIFFE ID of the desired trust domain as the resource name (e.g. spiffe://example.org).

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

spire_agent.md

spire_agent.md

SPIRE Agent Configuration Reference

Plugin types

Built-in plugins

Agent configuration file

Plugin configuration

Telemetry configuration

Health check configuration

Command line options

`spire-agent run`

`spire-agent api fetch`

`spire-agent api fetch jwt`

`spire-agent api fetch x509`

`spire-agent api validate jwt`

`spire-agent api watch`

`spire-agent healthcheck`

Sample configuration file

Envoy SDS Support

Further reading

Files

spire_agent.md

Latest commit

History

spire_agent.md

File metadata and controls

SPIRE Agent Configuration Reference

Plugin types

Built-in plugins

Agent configuration file

Plugin configuration

Telemetry configuration

Health check configuration

Command line options

spire-agent run

spire-agent api fetch

spire-agent api fetch jwt

spire-agent api fetch x509

spire-agent api validate jwt

spire-agent api watch

spire-agent healthcheck

Sample configuration file

Envoy SDS Support

Further reading

`spire-agent run`

`spire-agent api fetch`

`spire-agent api fetch jwt`

`spire-agent api fetch x509`

`spire-agent api validate jwt`

`spire-agent api watch`

`spire-agent healthcheck`