Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
170 lines (128 sloc) 8.34 KB

SPIRE Agent

SPIRE agent runs on every node and is responsible for requesting SVIDs from the SPIRE server, attesting the identity of local workloads, and providing them SVIDs via the workload API.

Architecture

The SPIRE agent comprises three plugin types in addition to some core logic. The plugin architecture affords SPIRE a great deal of flexibility, allowing it to be deployed in a myriad of environments and platforms. Plugins may either be built in or executed out-of-process.

spire agent architecture

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.

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 x509_pop A node attestor which attests agent identity using an existing X.509 certificate
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

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.

Configuration Description Default
data_dir A directory the agent can use for its runtime data $PWD
log_file File to write logs to
log_level Sets the logging level <DEBUG|INFO|WARN|ERROR> INFO
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 workload API socket $PWD/spire_api
trust_bundle_path Path to the SPIRE server CA bundle
trust_domain The trust domain that this agent belongs to
join_token An optional token which has been generated by the SPIRE server

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.

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
-config Path to a SPIRE config file conf/server/server.conf

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 workload API socket /tmp/agent.sock
-write Write SVID data to the specified path

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 workload API socket /tmp/agent.sock

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 workload API socket /tmp/agent.sock
-spiffeID The SPIFFE ID of the JWT being requested (optional)

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 workload API socket /tmp/agent.sock
-svid The JWT-SVID to be validated

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

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 {
        }
    }
}

Further reading