SPIRE Server Configuration Reference

Command line options, server.conf settings, and built-in plugins for SPIRE Server

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

Plugin types

Type Description
DataStore Provides persistent storage and HA features. Note: Pluggability for the DataStore is no longer supported. Only the built-in SQL plugin can be used.
KeyManager Implements both signing and key storage logic for the server’s signing operations. Useful for leveraging hardware-based key operations.
NodeAttestor Implements validation logic for nodes attempting to assert their identity. Generally paired with an agent plugin of the same type.
NodeResolver A plugin capable of discovering platform-specific metadata of nodes which have been successfully attested. Discovered metadata is stored as selectors and can be used when creating registration entries.
UpstreamAuthority Allows SPIRE server to integrate with existing PKI systems.
Notifier Notified by SPIRE server for certain events that are happening or have happened. For events that are happening, the notifier can advise SPIRE server on the outcome.

Built-in plugins

Type Name Description
DataStore sql An sql database storage for SQLite, PostgreSQL and MySQL databases for the SPIRE datastore
KeyManager aws_kms A key manager which manages keys in AWS KMS
KeyManager disk A key manager which manages keys persisted on disk
KeyManager memory A key manager which manages unpersisted keys in memory
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 validates agents attesting with server-generated join tokens
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
NodeResolver azure_msi A node resolver which extends the azure_msi node attestor plugin to support selecting nodes based on additional properties (such as Network Security Group).
Notifier gcs_bundle A notifier that pushes the latest trust bundle contents into an object in Google Cloud Storage.
Notifier k8sbundle A notifier that pushes the latest trust bundle contents into a Kubernetes ConfigMap.
UpstreamAuthority disk Uses a CA loaded from disk to sign SPIRE server intermediate certificates.
UpstreamAuthority aws_pca Uses a Private Certificate Authority from AWS Certificate Manager to sign SPIRE server intermediate certificates.
UpstreamAuthority awssecret Uses a CA loaded from AWS SecretsManager to sign SPIRE server intermediate certificates.
UpstreamAuthority gcp_cas Uses a Private Certificate Authority from GCP Certificate Authority Service to sign SPIRE Server intermediate certificates.
UpstreamAuthority vault Uses a PKI Secret Engine from HashiCorp Vault to sign SPIRE server intermediate certificates.
UpstreamAuthority spire Uses an upstream SPIRE server in the same trust domain to obtain intermediate signing certificates for SPIRE server.
UpstreamAuthority cert-manager Uses a referenced cert-manager Issuer to request intermediate signing certificates.

Server configuration file

The following table outlines the configuration options for SPIRE server. These may be set in a top-level server { ... } 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 database connection passwords.

Configuration Description Default
admin_ids SPIFFE IDs that, when present in a caller’s X509-SVID, grant that caller admin privileges. The admin IDs must reside in the same trust domain as the server and need not have a corresponding admin registration entry with the server.
agent_ttl The TTL to use for agent SVIDs The value of default_svid_ttl
audit_log_enabled If true, enables audit logging false
bind_address IP address or DNS name of the SPIRE server 0.0.0.0
bind_port HTTP Port number of the SPIRE server 8081
ca_key_type The key type used for the server CA (both X509 and JWT), <rsa-2048|rsa-4096|ec-p256|ec-p384> ec-p256 (the JWT key type can be overridden by jwt_key_type)
ca_subject The Subject that CA certificates should use (see below)
ca_ttl The default CA/signing key TTL 24h
data_dir A directory the server can use for its runtime
default_svid_ttl The default SVID TTL 1h
experimental The experimental options that are subject to change or removal (see below)
federation Bundle endpoints configuration section used for federation
jwt_key_type The key type used for the server CA (JWT), <rsa-2048|rsa-4096|ec-p256|ec-p384> The value of ca_key_type or ec-p256 if not defined
jwt_issuer The issuer claim used when minting JWT-SVIDs
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.
ratelimit Rate limiting configurations, usually used when the server is behind a load balancer (see below)
socket_path Path to bind the SPIRE Server API socket to /tmp/spire-server/private/api.sock
trust_domain The trust domain that this server belongs to (should be no more than 255 characters)
ca_subject Description Default
country Array of Country values
organization Array of Organization values
common_name The CommonName value
experimental Description Default
cache_reload_interval The amount of time between two reloads of the in-memory entry cache. Increasing this will mitigate high database load for extra large deployments, but will also slow propagation of new or updated entries to agents. 5s
auth_opa_policy_engine The auth opa_policy engine used for authorization decisions default SPIRE authorization policy
ratelimit Description Default
attestation Whether or not to rate limit node attestation. If true, node attestation is rate limited to one attempt per second per IP address. true
signing Whether or not to rate limit JWT and X509 signing. If true, JWT and X509 signing are rate limited to 500 requests per second per IP address (separately). true
auth_opa_policy_engine Description Default
local Local OPA configuration for authorization policy.
auth_opa_policy_engine.local Description Default
rego_path File to retrieve OPA rego policy for authorization.
policy_data_path File to retrieve databindings for policy evaluation.

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 server configuration file also contains a configuration section for the various SPIRE server plugins. Plugin configurations live inside the top-level 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 below for information on plugins that are available out-of-the-box.

Federation configuration

SPIRE Server can be configured to federate with others SPIRE Servers living in different trust domains. SPIRE supports configuring federation relationships in the SPIRE Server configuration file (static relationships) and through the Trust Domain API (dynamic relationships). This section describes how to configure statically defined relationships in the configuration file.

Note: static relationships override dynamic relationships. If you need to configure dynamic relationships, see the federation command. Static relationships are not reflected in the federation command.

Configuring a federated trust domain allows a trust domain to authenticate identities issued by other SPIFFE authorities, allowing workloads in one trust domain to securely autenticate workloads in a foreign trust domain. A key element to achieve federation is the use of SPIFFE bundle endpoints, these are resources (represented by URLs) that serve a copy of a trust bundle for a trust domain. Using the federation section you will be able to set up SPIRE as a SPIFFE bundle endpoint server and also configure the federated trust domains that this SPIRE Server will fetch bundles from.

server {
    .
    .
    .
    federation {
        bundle_endpoint {
            address = "0.0.0.0"
            port = 8443
            acme {
                domain_name = "example.org"
                email = "mail@example.org"
            }
        }
        federates_with "domain1.test" {
            bundle_endpoint_url = "https://1.2.3.4:8443"
            bundle_endpoint_profile "https_web" {}
        }
        federates_with "domain2.test" {
            bundle_endpoint_url = "https://5.6.7.8:8443"
            bundle_endpoint_profile "https_spiffe" {
                endpoint_spiffe_id = "spiffe://domain2.test/beserver"
            }
        }
    }
}

The federation.bundle_endpoint section is optional and is used to set up a SPIFFE bundle endpoint server in SPIRE Server. The federation.federates_with section is also optional and is used to configure the federation relationships with foreign trust domains. This section is used for each federated trust domain that SPIRE Server will periodically fetch the bundle.

Configuration options for federation.bundle_endpoint

This optional section contains the configurables used by SPIRE Server to expose a bundle endpoint.

Configuration Description
address IP address where this server will listen for HTTP requests
port TCP port number where this server will listen for HTTP requests
acme Automated Certificate Management Environment configuration section (see below)

Configuration options for federation.bundle_endpoint.acme

Configuration Description Default
directory_url Directory endpoint URL https://acme-v02.api.letsencrypt.org/directory"
domain_name Domain for which the certificate manager tries to retrieve new certificates
email Contact email address. This is used by CAs, such as Let’s Encrypt, to notify about problems with issued certificates
tos_accepted ACME Terms of Service acceptance. If not true, and the provider requires acceptance, then certificate retrieval will fail false

Configuration options for federation.federates_with["<trust domain>"].bundle_endpoint

The optional federates_with section is a map of bundle endpoint profile configurations keyed by the name of the "<trust domain>" this server wants to federate with. This section has the following configurables:

Configuration Description Default
bundle_endpoint_url URL of the SPIFFE bundle endpoint that provides the trust bundle to federate with. Must use the HTTPS protocol.
bundle_endpoint_profile “<https_web|https_spiffe>” Configuration of the SPIFFE endpoint profile type.

SPIRE supports the https_web and https_spiffe bundle endpoint profiles.

The https_web profile does not require additional settings.

Trust domains configured with the https_spiffe bundle endpoint profile must specify the expected SPIFFE ID of the remote SPIFFE bundle endpoint server using the endpoint_spiffe_id setting as part of the configuration.

For more information about the different profiles defined in SPIFFE, along with the security considerations for setting up SPIFFE Federation, please refer to the SPIFFE Federation standard.

Telemetry configuration

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

Health check configuration

The server can expose an 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 server up?) and one for readiness (is server 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-server run

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

Command Action Default
-bindAddress IP address or DNS name of the SPIRE server
-config Path to a SPIRE config file conf/server/server.conf
-dataDir Directory to store runtime data to
-expandEnv Expand environment $VARIABLES in the config file
-logFile File to write logs to
-logFormat Format of logs, <text|json>
-logLevel DEBUG, INFO, WARN or ERROR
-serverPort Port number of the SPIRE server
-socketPath Path to bind the SPIRE Server API socket to
-trustDomain The trust domain that this server belongs to (should be no more than 255 characters)

spire-server token generate

Generates one node join token and creates a registration entry for it. This token can be used to bootstrap one spire-agent installation. The optional -spiffeID can be used to give the token a human-readable registration entry name in addition to the token-based ID.

Command Action Default
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock
-spiffeID Additional SPIFFE ID to assign the token owner (optional)
-ttl Token TTL in seconds 600

spire-server entry create

Creates registration entries.

Command Action Default
-admin If set, the SPIFFE ID in this entry will be granted access to the Server APIs
-data Path to a file containing registration data in JSON format (optional, if specified, other flags related with entry information must be omitted). If set to ‘-', read the JSON from stdin.
-dns A DNS name that will be included in SVIDs issued based on this entry, where appropriate. Can be used more than once
-downstream A boolean value that, when set, indicates that the entry describes a downstream SPIRE server
-entryExpiry An expiry, from epoch in seconds, for the resulting registration entry to be pruned from the datastore. Please note that this is a data management feature and not a security feature (optional).
-federatesWith A list of trust domain SPIFFE IDs representing the trust domains this registration entry federates with. A bundle for that trust domain must already exist
-node If set, this entry will be applied to matching nodes rather than workloads
-parentID The SPIFFE ID of this record’s parent.
-selector A colon-delimited type:value selector used for attestation. This parameter can be used more than once, to specify multiple selectors that must be satisfied.
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock
-spiffeID The SPIFFE ID that this record represents and will be set to the SVID issued.
-ttl A TTL, in seconds, for any SVID issued as a result of this record. The TTL configured with default_svid_ttl
-storeSVID A boolean value that, when set, indicates that the resulting issued SVID from this entry must be stored through an SVIDStore plugin

spire-server entry update

Updates registration entries.

Command Action Default
-admin If true, the SPIFFE ID in this entry will be granted access to the Server APIs
-data Path to a file containing registration data in JSON format (optional, if specified, other flags related with entry information must be omitted). If set to ‘-', read the JSON from stdin.
-dns A DNS name that will be included in SVIDs issued based on this entry, where appropriate. Can be used more than once
-downstream A boolean value that, when set, indicates that the entry describes a downstream SPIRE server
-entryExpiry An expiry, from epoch in seconds, for the resulting registration entry to be pruned
-entryID The Registration Entry ID of the record to update
-federatesWith A list of trust domain SPIFFE IDs representing the trust domains this registration entry federates with. A bundle for that trust domain must already exist
-parentID The SPIFFE ID of this record’s parent.
-selector A colon-delimited type:value selector used for attestation. This parameter can be used more than once, to specify multiple selectors that must be satisfied.
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock
-spiffeID The SPIFFE ID that this record represents and will be set to the SVID issued.
-ttl A TTL, in seconds, for any SVID issued as a result of this record. The TTL configured with default_svid_ttl
storeSVID A boolean value that, when set, indicates that the resulting issued SVID from this entry must be stored through an SVIDStore plugin

spire-server entry count

Displays the total number of registration entries.

Command Action Default
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock

spire-server entry delete

Deletes a specified registration entry.

Command Action Default
-entryID The Registration Entry ID of the record to delete
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock

spire-server entry show

Displays configured registration entries.

Command Action Default
-downstream A boolean value that, when set, indicates that the entry describes a downstream SPIRE server
-entryID The Entry ID of the record to show.
-federatesWith SPIFFE ID of a trust domain an entry is federate with. Can be used more than once
-parentID The Parent ID of the records to show.
-selector A colon-delimeted type:value selector. Can be used more than once to specify multiple selectors.
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock
-spiffeID The SPIFFE ID of the records to show.

spire-server bundle count

Displays the total number of bundles.

Command Action Default
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock

spire-server bundle show

Displays the bundle for the trust domain of the server.

Command Action Default
-format The format to show the bundle. Either pem or spiffe pem
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock

spire-server bundle list

Displays federated bundles.

Command Action Default
-id The trust domain SPIFFE ID of the bundle to show. If unset, all trust bundles are shown
-format The format to show the federated bundles. Either pem or spiffe pem
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock

spire-server bundle set

Creates or updates bundle data for a trust domain. This command cannot be used to alter the server trust domain bundle, only bundles for other trust domains.

Command Action Default
-id The trust domain SPIFFE ID of the bundle to set.
-path Path on disk to the file containing the bundle data. If unset, data is read from stdin.
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock
-format The format of the bundle to set. Either pem or spiffe pem

spire-server bundle delete

Deletes bundle data for a trust domain. This command cannot be used to delete the server trust domain bundle, only bundles for other trust domains.

Command Action Default
-id The trust domain SPIFFE ID of the bundle to delete.
-mode One of: restrict, dissociate, delete. restrict prevents the bundle from being deleted if it is associated to registration entries (i.e. federated with). dissociate allows the bundle to be deleted and removes the association from registration entries. delete deletes the bundle as well as associated registration entries. restrict
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock

spire-server federation create

Creates a dynamic federation relationship with a foreign trust domain.

Command Action Default
-bundleEndpointProfile Endpoint profile type. Either https_web or https_spiffe.
-bundleEndpointURL URL of the SPIFFE bundle endpoint that provides the trust bundle (must use the HTTPS protocol).
-data Path to a file containing federation relationships in JSON format (optional, if specified, other flags related with federation relationship information must be omitted). If set to ‘-', read the JSON from stdin.
-endpointSpiffeID SPIFFE ID of the SPIFFE bundle endpoint server. Only used for https_spiffe profile.
-socketPath Path to the SPIRE Server API socket. /tmp/spire-server/private/api.sock
-trustDomain Name of the trust domain to federate with (e.g., example.org)
-trustDomainBundleFormat The format of the bundle data (optional). Either pem or spiffe. pem
-trustDomainBundlePath Path to the trust domain bundle data (optional).

spire-server federation delete

Deletes a dynamic federation relationship.

Command Action Default
-id SPIFFE ID of the trust domain of the relationship.
-socketPath Path to the SPIRE Server API socket. /tmp/spire-server/private/api.sock

spire-server federation list

Lists all the dynamic federation relationships.

Command Action Default
-id SPIFFE ID of the trust domain of the relationship
-socketPath Path to the SPIRE Server API socket. /tmp/spire-server/private/api.sock

spire-server federation refresh

Refreshes the bundle from the specified federated trust domain.

Command Action Default
-id SPIFFE ID of the trust domain of the relationship
-socketPath Path to the SPIRE Server API socket. /tmp/spire-server/private/api.sock

spire-server federation show

Shows a dynamic federation relationship.

Command Action Default
-socketPath Path to the SPIRE Server API socket. /tmp/spire-server/private/api.sock
-trustDomain The trust domain name of the federation relationship to show (e.g., example.org)

spire-server federation update

Updates a dynamic federation relationship with a foreign trust domain.

Command Action Default
-bundleEndpointProfile Endpoint profile type. Either https_web or https_spiffe.
-bundleEndpointURL URL of the SPIFFE bundle endpoint that provides the trust bundle (must use the HTTPS protocol).
-data Path to a file containing federation relationships in JSON format (optional, if specified, other flags related with federation relationship information must be omitted). If set to ‘-', read the JSON from stdin.
-endpointSpiffeID SPIFFE ID of the SPIFFE bundle endpoint server. Only used for https_spiffe profile.
-socketPath Path to the SPIRE Server API socket. /tmp/spire-server/private/api.sock
-trustDomain Name of the trust domain to federate with (e.g., example.org)
-trustDomainBundleFormat The format of the bundle data (optional). Either pem or spiffe. pem
-trustDomainBundlePath Path to the trust domain bundle data (optional).

spire-server agent ban

Ban attested node given its spiffeID. A banned attested node is not able to re-attest.

Command Action Default
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock
-spiffeID The SPIFFE ID of the agent to ban (agent identity)

spire-server agent count

Displays the total number of attested nodes.

Command Action Default
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock

spire-server agent evict

De-attesting an already attested node given its spiffeID.

Command Action Default
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock
-spiffeID The SPIFFE ID of the agent to evict (agent identity)

spire-server agent list

Displays attested nodes.

Command Action Default
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock

spire-server agent show

Displays the details (including node selectors) of an attested node given its spiffeID.

Command Action Default
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock
-spiffeID The SPIFFE ID of the agent to show (agent identity)

spire-server healthcheck

Checks SPIRE server’s health.

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

spire-server validate

Validates a SPIRE server configuration file. Arguments are the same as spire-server run. Typically, you may want at least:

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

spire-server x509 mint

Mints an X509-SVID.

Command Action Default
-dns A DNS name that will be included in SVID. Can be used more than once
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock
-spiffeID The SPIFFE ID of the X509-SVID
-ttl The TTL of the X509-SVID The TTL configured with default_svid_ttl
-write Directory to write output to instead of stdout

spire-server jwt mint

Mints a JWT-SVID.

Command Action Default
-audience Audience claim that will be included in the SVID. Can be used more than once
-socketPath Path to the SPIRE Server API socket /tmp/spire-server/private/api.sock
-spiffeID The SPIFFE ID of the JWT-SVID
-ttl The TTL of the JWT-SVID
-write File to write token to instead of stdout

JSON object for -data

A JSON object passed to -data for entry create/update expects the following form:

{
    "entries":[]
}

The entry object is described by RegistrationEntry in the common protobuf file.

Note: to create node entries, set parent_id to the special value spiffe://<your-trust-domain>/spire/server. That’s what the code does when the -node flag is passed on the cli.

Sample configuration file

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

server {
    trust_domain = "example.org"

    bind_address = "0.0.0.0"
    bind_port = "8081"
    log_level = "INFO"
    data_dir = "/opt/spire/.data/"
    default_svid_ttl = "6h"
    ca_ttl = "72h"
    ca_subject {
        country = ["US"]
        organization = ["SPIRE"]
        common_name = ""
    }
}

telemetry {
    Prometheus {
        port = 1234
    }
}

plugins {
    DataStore "sql" {
        plugin_data {
            database_type = "sqlite3"
            connection_string = "/opt/spire/.data/datastore.sqlite3"
        }
    }
    NodeAttestor "join_token" {
        plugin_data {}
    }
    KeyManager "disk" {
        plugin_data {
            keys_path = "/opt/spire/.data/keys.json"
        }
    }
}

Further reading