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

Built-in plugins

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.

Initial trust bundle configuration

The agent needs an initial trust bundle in order to connect securely to the SPIRE server. There are three options:

1. If the trust_bundle_path option is used, the agent will read the initial trust bundle from the file at that path. You need to copy or share the file before starting the SPIRE agent.
2. If the trust_bundle_url option is used, the agent will read the initial trust bundle from the specified URL. The URL must start with https:// for security, and the server must have a valid certificate (verified with the system trust store). This can be used to rapidly deploy SPIRE agents without having to manually share a file. Keep in mind the contents of the URL need to be kept up to date.
3. If the insecure_bootstrap option is set to true, then the agent will not use an initial trust bundle. It will connect to the SPIRE server without authenticating it. This is not a secure configuration, because a man-in-the-middle attacker could control the SPIRE infrastructure. It is included because it is a useful option for testing and development.

Only one of these three options may be set at a time.

SDS Configuration

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:

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 = "8080"
        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:

spire-agent api fetch

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

spire-agent api fetch jwt

Calls the workload API to fetch a JWT-SVID.

spire-agent api fetch x509

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

spire-agent api validate jwt

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

spire-agent api watch

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

spire-agent healthcheck

Checks SPIRE agent’s health.

spire-agent validate

Validates a SPIRE agent configuration file.

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 support for the Envoy Secret Discovery Service (SDS). 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 X509-SVIDs can be fetched using the SPIFFE ID of the workload as the resource name (e.g. spiffe://example.org/database). Alternatively, if the default name “default” is used, the auth.TlsCertificate containing the default X509-SVID for the workload (i.e. Envoy) is fetched. The default name is configurable (see default_svid_name under SDS Configuration).

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). Alternatively, if the default name “ROOTCA” is requested, the auth.CertificateValidationContext containing the trusted CA certificates for the agent’s trust domain is fetched. The default name is configurable (see default_bundle_name under SDS Configuration).

Further reading

• SPIFFE Reference Implementation Architecture
• Design Document: SPIFFE Reference Implementation (SRI)