SPIRE Agent Configuration Reference

Command line options, agent.conf settings, and built-in plugins for SPIRE Agent

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.
SVIDStore Stores X509-SVIDs (Private key, leaf certificate and intermediates if any), bundle, and federated bundles into a trust store.

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
SVIDStore aws_secretsmanager An SVIDstore which stores secrets in the AWS secrets manager with the resulting X509-SVIDs of the entries that the agent is entitled to.
SVIDStore gcp_secretmanager An SVIDStore which stores secrets in the Google Cloud Secret Manager with the resulting X509-SVIDs of the entries that the agent is entitled to.

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
admin_socket_path Location to bind the admin API socket (disabled as default)
allow_unauthenticated_verifiers Allow agent to release trust bundles to unauthenticated verifiers false
allowed_foreign_jwt_claims List of trusted claims to be returned when validating foreign JWTSVIDs
authorized_delegates A SPIFFE ID list of the authorized delegates. See Delegated Identity API for more information
data_dir A directory the agent can use for its runtime data $PWD
insecure_bootstrap If true, the agent bootstraps without verifying the server’s identity false
join_token An optional token which has been generated by the SPIRE server
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
profiling_enabled If true, enables a net/http/pprof endpoint false
profiling_freq Frequency of dumping profiling data to disk. Only enabled when profiling_enabled is true and profiling_freq > 0.
profiling_names List of profile names that will be dumped to disk on each profiling tick, see Profiling Names
profiling_port Port number of the net/http/pprof endpoint. Only used when profiling_enabled is true.
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 SPIRE Agent API socket /tmp/spire-agent/public/api.sock
sds Optional SDS configuration section
trust_bundle_path Path to the SPIRE server CA bundle
trust_bundle_url URL to download the initial SPIRE server trust bundle
trust_domain The trust domain that this agent belongs to (should be no more than 255 characters)

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

Configuration Description Default
default_svid_name The TLS Certificate resource name to use for the default X509-SVID with Envoy SDS default
default_bundle_name The Validation Context resource name to use for the default X.509 bundle with Envoy SDS ROOTCA
default_all_bundles_name The Validation Context resource name to use for all bundles (including federated) with Envoy SDS ALL

Profiling Names

These are the available profiles that can be set in the profiling_freq configuration value:

  • goroutine
  • threadcreate
  • heap
  • block
  • mutex
  • trace
  • cpu

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

Command Action Default
-allowUnauthenticatedVerifiers Allow agent to release trust bundles to unauthenticated verifiers
-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
-trustBundleUrl URL to download the SPIRE server CA bundle
-trustDomain The trust domain that this agent belongs to (should be no more than 255 characters)

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 SPIRE Agent API socket /tmp/spire-agent/public/api.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 SPIRE Agent API socket /tmp/spire-agent/public/api.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 SPIRE Agent API socket /tmp/spire-agent/public/api.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 SPIRE Agent API socket /tmp/spire-agent/public/api.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 SPIRE Agent API socket /tmp/spire-agent/public/api.sock

spire-agent healthcheck

Checks SPIRE agent’s health.

Command Action Default
-shallow Perform a less stringent health check
-socketPath Path to the SPIRE Agent API socket /tmp/spire-agent/public/api.sock
-verbose Print verbose information

spire-agent validate

Validates a SPIRE agent configuration file.

Command Action Default
-config Path to a SPIRE agent configuration file agent.conf
-expandEnv Expand environment $VARIABLES in the config file false

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/spire-agent/public/api.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 {
        }
    }
}

Delegated Identity API

SPIRE agent has support for Delegated Identity API. This API is intended for use cases where a (authorized) workload wants access to the X509-SVIDs and bundles on behalf of another workload. A list of authorized delegates SPIFFE IDs of workloads are defined for this purpose. The API is served over the same Unix domain socket as the admin API socket. Based on workload’s selectors, a (authorized) workload could be subscribed to get X509-SVIDs and federated bundles from the registered entries that match the provided selectors.

In order to use this API, you shall configure the admin_socket_path and authorized_delegates (SPIFFE ID list of authorized delegates identities), as the following example:

agent {
    trust_domain = "example.org"
    ...
    admin_socket_path = "/tmp/spire-agent/private/admin.sock"
    authorized_delegates = [
        "spiffe://example.org/authorized_client1",
        "spiffe://example.org/authorized_client2",
    ]
}

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). In addition, two other special resource names are available. The first, which defaults to “ROOTCA”, provides the CA certificates for the trust domain the agent belongs to. The second, which defaults to “ALL”, returns the trusted CA certificates for both the trust domain the agent belongs to as well as any federated trust domains applicable to the Envoy workload. The default names for these resource names are configurable via the default_bundle_name and default_all_bundles_name, respectively. The “ALL” resource name requires support for the SPIFFE Certificate Validator extension, which is only available starting with Envoy 1.18. The default name is configurable (see default_all_bundles_name under SDS Configuration.

OpenShift Support

The default security profile of OpenShift forbids access to host level resources. A custom set of policies can be applied to enable the level of access needed by Spire to operate within OpenShift.

Note: A user with cluster-admin privileges is required in order to apply these policies.

Security Context Constraints

Actions performed by pods are controlled by Security Context Constraints (SCC’s) and every pod that is admitted is assigned a particular SCC depending on range of conditions. The following custom SCC with the name spire can be used to enable the necessary host level access needed by the Spire Agent

allowHostDirVolumePlugin: true
allowHostIPC: true
allowHostNetwork: true
allowHostPID: true
allowHostPorts: true
allowPrivilegeEscalation: true
allowPrivilegedContainer: false
allowedCapabilities: null
apiVersion: security.openshift.io/v1
defaultAddCapabilities: null
fsGroup:
  type: MustRunAs
groups: []
kind: SecurityContextConstraints
metadata:
  annotations:
    include.release.openshift.io/self-managed-high-availability: "true"
    kubernetes.io/description: Customized policy for Spire to enable host level access.
    release.openshift.io/create-only: "true"
  name: spire
priority: null
readOnlyRootFilesystem: false
requiredDropCapabilities:
  - KILL
  - MKNOD
  - SETUID
  - SETGID
runAsUser:
  type: RunAsAny
seLinuxContext:
  type: MustRunAs
supplementalGroups:
  type: RunAsAny
users: []
volumes:
  - hostPath
  - configMap
  - downwardAPI
  - emptyDir
  - persistentVolumeClaim
  - projected
  - secret

Associating A Security Constraint With a Workload

Workloads can be granted access to Security Context Constraints through Role Based Access Control Policies by associating the SCC with the Service Account referenced by the pod.

In order to leverage the spire SCC, a ClusterRole leveraging use verb referencing the SCC must be created:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations:
    include.release.openshift.io/self-managed-high-availability: "true"
    rbac.authorization.kubernetes.io/autoupdate: "true"
  name: system:openshift:scc:spire
rules:
- apiGroups:
  - security.openshift.io
  resourceNames:
  - spire
  resources:
  - securitycontextconstraints
  verbs:
  - use

Finally, associate the system:openshift:scc:spire ClusterRole to the spire-agent Service account by creating a RoleBinding in the spire namespace

Note: Create the spire namespace if it does exist prior to applying the following policy.

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: system:openshift:scc:spire
  namespace: spire
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:openshift:scc:spire
subjects:
  - kind: ServiceAccount
    name: spire-agent
    namespace: spire

As SCC’s are applied at pod admission time, remove any existing Spire Agent pods. All newly admitted pods will make use of the spire SCC enabling their use within OpenShift.

Further reading