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

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:

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/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 endpoint address as the admin API. 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:

Unix systems:

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",
    ]
}

Windows:

agent {
    trust_domain = "example.org"
    ...
    experimental {
        admin_named_pipe_name = "\\spire-agent\\private\\admin"
    }
    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.

The SPIFFE Certificate Validator configures Envoy to perform SPIFFE authentication. The validation context returned by SPIRE Agent contains this extension by default. However, if standard X.509 chain validation is desired, SPIRE Agent can be configured to omit the extension. The default behavior can be changed by configuring disable_spiffe_cert_validation in SDS Configuration. Individual Envoy instances can also override the default behavior by configuring setting a disable_spiffe_cert_validation key in the Envoy node metadata.

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

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