Project: SPIRE (Provisioning / Key Management)
File: spire_agent.md

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. | 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. | | Type | Name | Description | ||-|--| | KeyManager | | A key manager which writes the private key to disk | | KeyManager | | An in-memory key manager which does not persist private keys (must re-attest after restarts) | | NodeAttestor | | A node attestor which attests agent identity using an AWS Instance Identity Document | | NodeAttestor | | A node attestor which attests agent identity using an Azure MSI token | | NodeAttestor | | A node attestor which attests agent identity using a GCP Instance Identity Token | | NodeAttestor | | A node attestor which uses a server-generated join token | | NodeAttestor | (deprecated) | A node attestor which attests agent identity using a Kubernetes Service Account token | | NodeAttestor | | A node attestor which attests agent identity using a Kubernetes Projected Service Account token | | NodeAttestor | | A node attestor which attests agent identity using an existing ssh certificate | | NodeAttestor | | A node attestor which attests agent identity using an existing X.509 certificate | | WorkloadAttestor | | A workload attestor which allows selectors based on docker constructs such `label` and `image_id` | | WorkloadAttestor | | A workload attestor which allows selectors based on Kubernetes constructs such `ns` (namespace) and `sa` (service account) | | WorkloadAttestor | | A workload attestor which generates unix-based selectors like `uid` and `gid` | | WorkloadAttestor | | A workload attestor which generates selectors based on systemd unit properties such as `Id` and `FragmentPath` | | SVIDStore | | 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 | | 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. | 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 section for a complete example. If the -expandEnv flag is passed to SPIRE, `$VARIABLE` or `${VARIABLE}` style environment variables are expanded before

This may be useful for templating configuration files, for example across different trust domains, or for inserting secrets like join tokens. | Configuration | Description | Default | |--||-| | `adminsocketpath` | Location to bind the admin API socket (disabled as default) | | | `allowunauthenticatedverifiers` | Allow agent to release trust bundles to unauthenticated verifiers | false | | `allowedforeignjwt_claims` | List of trusted claims to be returned when validating foreign JWTSVIDs | | | `authorized_delegates` | A SPIFFE ID list of the authorized delegates. See for more information | | | `data_dir` | A directory the agent can use for its runtime data | $PWD | | `experimental` | The experimental options that are subject to change or removal (see below) | | | `insecure_bootstrap` | If true, the agent bootstraps without verifying the server's identity | false | | `retry_bootstrap` | If true, the agent retries bootstrap with backoff | 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 &lt;DEBUG&vert;INFO&vert;WARN&vert;ERROR&gt; | INFO | | `log_format` | Format of logs, &lt;text&vert;json&gt; | Text | | `logsourcelocation` | If true, logs include source file, line number, and method name fields (adds a bit of runtime cost) | false | | `profiling_enabled` | If true, enables a endpoint | false | | `profilingfreq` | Frequency of dumping profiling data to disk. Only enabled when `profilingenabled` is `true` and `profiling_freq` > 0. | | | `profiling_names` | List of profile names that will be dumped to disk on each profiling tick, see | | | `profilingport` | Port number of the endpoint. Only used when `profilingenabled` 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 (Unix only) | /tmp/spire-agent/public/api.sock | | `sds` | Optional SDS configuration section | | | `trustbundlepath` | Path to the SPIRE server CA bundle | | | `trustbundleurl` | URL to download the initial SPIRE server trust bundle | | | `trustbundleformat` | Format of the initial trust bundle, pem or spiffe | pem | | `trust_domain` | The trust domain that this agent belongs to (should be no more than 255 characters) | | | `workloadx509svidkeytype` | The workload X509 SVID key type &lt;rsa-2048&vert;ec-p256&gt; | ec-p256 | | `availability_target` | The minimum amount of time desired to gracefully handle SPIRE Server or Agent downtime. This configurable influences how aggressively X509 SVIDs should be rotated. If set, must be at least

See | | | `disablereattestto_renew` | Allow agent to renew certificate when it expires rather than reattest | false | | experimental | Description | Default | |:|--|-| | `namedpipename` | Pipe name to bind the SPIRE Agent API named pipe (Windows only) | \spire-agent\public\api | | `sync_interval` | Sync interval with SPIRE server with exponential backoff | 5 sec | | `x509svidcachemaxsize` | Soft limit of max number of SVIDs that would be stored in LRU cache | 1000 | | `disablelrucache` | Reverts back to use the SPIRE Agent non-LRU cache for storing SVIDs | false | The agent needs an initial trust bundle in order to connect securely to the SPIRE server. There are three options: If the `trustbundlepath` 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. If the `trustbundleurl` 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. 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. | Configuration | Description | Default | |-|-|| | `defaultsvidname` | The TLS Certificate resource name to use for the default X509-SVID with Envoy SDS | default | | `defaultbundlename` | The Validation Context resource name to use for the default X.509 bundle with Envoy SDS | ROOTCA | | `defaultallbundles_name` | The Validation Context resource name to use for all bundles (including federated) with Envoy SDS | ALL | | `disablespiffecert_validation` | Disable Envoy SDS custom validation | false | These are the available profiles that can be set in the `profiling_names` configuration value: `goroutine` `threadcreate` `heap` `block` `mutex` `trace` `cpu` Note: The `availabilitytarget` only affects the agent SVIDs and workload X509-SVIDs, but not JWT-SVIDs._ If the `availabilitytarget` is set, the agent will rotate an X509 SVID when its remaining lifetime reaches the `availabilitytarget`. To guarantee the `availabilitytarget`, grace period (`SVID lifetime - availabilitytarget`) must be at least 12h. If not satisfied, the agent will rotate the SVID by the default rotation strategy (1/2 of lifetime). The agent configuration file also contains the configuration for the agent plugins. Plugin configurations are under the `plugins { ... }` section, which has the following format: ```hcl 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 section for information on plugins that are available

Please see the guide for more information about configuring SPIRE Agent to emit telemetry. 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. ```hcl health_checks { listener_enabled = true bind_address = "localhost" bind_port = "8080" live_path = "/live" ready_path = "/ready" } ``` 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, &lt;text&vert;json&gt; | | | `-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) | | On Windows platform, SPIRE Agent can optionally be run as a Windows service. When running as a Windows service, the only command supported is the `run` command. _Note: SPIRE does not automatically create the service in the system, it must be created by the user. When starting the service, all the arguments to execute SPIRE Agent with the `run` command must be passed as service arguments._ ```bash sc.exe create spire-agent binpath=c:\spire\bin\spire-agent.exe ``` ```bash sc.exe start spire-agent run -config c:\spire\conf\agent\agent.conf ``` 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 | | 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 | Calls the workload API to fetch a

| 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 | | 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 | 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 | 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 | | 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 | This section includes a sample configuration file for formatting and syntax reference ```hcl agent { trust_domain = "example.org" trustbundlepath = "/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 { kubeletreadonly_port = "10255" } } WorkloadAttestor "unix" { plugin_data { } } } ``` The Delegated Identity API allows an authorized (i.e. delegated) workload to obtain SVIDs and bundles on behalf of workloads that cannot be attested by SPIRE Agent directly. The authorized workload does so by providing SPIRE Agent the selectors that would normally be obtained during workload attestation. The Delegated Identity API is served over the admin API endpoint. To enable the Delegated Identity API, configure the admin API endpoint address and the list of SPIFFE IDs for authorized delegates. For example: Unix systems: ```hcl agent { trust_domain = "example.org" ... adminsocketpath = "/tmp/spire-agent/private/admin.sock" authorized_delegates = [ "spiffe://example.org/authorized_client1", "spiffe://example.org/authorized_client2", ] } ``` Windows: ```hcl agent { trust_domain = "example.org" ... experimental { adminnamedpipe_name = "\\spire-agent\\private\\admin" } authorized_delegates = [ "spiffe://example.org/authorized_client1", "spiffe://example.org/authorized_client2", ] } ``` SPIRE agent has support for the (SDS). SDS is served over the same Unix domain socket as the Workload API. Envoy processes connecting to SDS are attested as workloads. 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 `tlsv3.TlsCertificate` containing the default X509-SVID for the workload (i.e. Envoy) is fetched. The default name is configurable (see `defaultsvidname` under

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 `defaultbundlename` and `defaultallbundles_name`, respectively. The "ALL" resource name requires support for the extension, which is only available starting with Envoy 1.18. The default name is configurable (see `defaultallbundles_name` under . The 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 `disablespiffecertvalidation` in . Individual Envoy instances can also override the default behavior by configuring setting a `disablespiffecertvalidation` key in the Envoy node metadata. The default security profile of 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. 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 ```yaml 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 ``` 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: ```yaml 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. ```yaml 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.