Assumptions

This walkthrough demonstrates how to deploy SPIRE to identify a single workload running on a node running Linux. It sets up the SPIRE Server and SPIRE Agent so that they’re running on the same node. In an actual deployment, these would typically run on different nodes.

In the walkthrough, the workload to which SPIRE will issue an identity is running under a specific UNIX user id; SPIRE users will use this user id to generate an SVID for the workload.

This guide also illustrates node attestation using join tokens—a pre-shared key between a server and an agent—the simplest node attestation strategy.

Finally, this guide assumes the user is running Ubuntu 16.04.

Step 1: Plan

Plan Your Configuration

To customize the behavior of the SPIRE Server and SPIRE Agent to meet your application’s needs you edit configuration files for the server and agent.

Note that the some of the configuration file default settings – such as those for database choice for server data, key management backend, and upstream – will work well for most evaluations.

The following decisions influence how you set values in the configuration file:

What you will name your server trust domain and your agent trust domain

Trust domain names must be identical in the server and the agent.

Which node attestation method your application requires

This depends on your where your workload is running. Your choice of node attestation method determines which node-attestor plugins you configure SPIRE to use in Server Plugins and Agent Plugins sections of the SPIRE configuration files. You must configure at least one node attestor on the server and only one node attestor on the agent.

For simplicity’s sake, this guide demonstrates using the join token method for node attestation.

SPIRE employs a database to persist data related to workload identities and registration entries. By default, SPIRE bundles SQLite and sets it as the default for storage of server data. SPIRE currently also supports PostgreSQL. For production purposes, you should carefully consider which database to use.

Which key management backend your application requires

The key manager generates and persists the public-private key pair used for the agent SVID. You must choose whether to store the private key on disk or in memory. For production purposes, you also might consider integrating a custom backend for storage purposes, such as a secret store.

Step 2: Obtain the SPIRE Binaries

Step 3: Install the Server and Agent

As stated above, this guide illustrates installs the server and agent on the same node. More typically, your architecture will have the the server installed on one node and one or more agents installed on distinct nodes.

To install the server and agent:

Obtain the latest tarball from the SPIRE downloads page and then extract it into the /opt/spire directory using the following commands:

When you customize these instructions for your architecture, you will substitute the appropriate path values to point to your application’s key and certs.

Configure Server Plugins

As described above in the Plan Your Configuration section, before installing and configuring you determine which plugin you configure the server to use for node attestation. You must edit the configuration file to point to the path to the binary of the plugin your application will use.

Server Configuration Reference

Step 5: Configure the Agent

When connecting to the SPIRE Server for the first time, the agent uses a configured X.509 CA certificate to verify the initial connection. SPIRE releases include a “dummy” certificate for this purpose. For a production implementation, a separate key should be generated. See the next section.

Generate a Key

Use the tool of your choice – such as openssl, cfssl, or an equivalent tool – to generate a key for the server and certificate, to be bundled with the agent.

Configure the Trust Bundle Path

To configure the trust bundle on the agent side, edit the configuration file so that the agent looks for the trust bundle at the correct path:

Configure Agent Plugins

As described above in the Plan Your Configuration section, before installing and configuring you determine which plugin you configure the agent to use for node attestation and workload attestation.

Node Attestor Plugin

The agent node attestor plugin must match the node attestor plugin type you choose when you configured the server.

For simplicity’s sake, this guide illustrates node attestation using the join token method. As this is SPIRE’s default configuration setting for node attestation, you do not need to make changes to the node attestation plugins section in the agent configuration file.

Workload Attestor Plugin

Choose the workload attestor pertinent to your application, for example, Kubernetes or UNIX.

This guide’s example uses UNIX as a workload attestor plugin. For this reason, the Workload Attestor entry in the agent configuration file is set to “unix”.

Datastore Plugin

As described above in the Plan Your Configuration section, before installing and configuring you determine whether SPIRE’s default datastore plugin – SQLite3 – is sufficient for your application. For high availability, in which you might have multiple SPIRE servers running against your database, you may want to choose the Postgres datastore plugin.

If your application required that, you would need to edit the DataStore entry in the plugins section of the /opt/spire/conf/server/server.conf file to specify the Postgres plugin.

Keymanager Plugin

During node attestation, the server assigns the agent a SVID; the agent must store a private key for that SVID. The agent receives a signed certificate and must choose between storing it in memory or on disk.

The advantage of storing it on disk is that the is no need to redo node attestation if the agent is restarted.

The default is to store it in memory. To set it to store its private key on disk, edit the KeyManager entry in the agent.conf file:

Agent Configuration Reference

Step 6: Start Up the Server and Agent

In this example, we will start a server and join an agent to it using the join token attestation method.

Here are the steps:

Start up the server, passing in the path to the server configuration file:

sudo spire-server run -config /opt/spire/conf/server/server.conf

In a different terminal, generate a one time join token using the spire-server token generate sub command. Use the -spiffeID option to associate the join token with spiffe://example.org/host SPIFFE ID:

The default Time to Live (ttl) for the join token is 600 seconds. To overwrite the default, pass a different value via the -ttl option to the spire-server token generate command.

Staying in the same terminal, start up the agent, passing in the path to the agent configuration file, as well as the join token you just generated.
s
shell
sudo spire-agent run -config /opt/spire/conf/agent/agent.conf -joinToken aaaaaaaa-bbbb-cccc-dddd-111111111111

You have the option to adding the join token to the NodeAttestor entry in the agent configuration file instead of passing it at the command line.

Step 7 Register Workloads

In order to enable SPIRE to perform workload attestation – which allows the agent to identify the workload to attest to its agent – you must register the workload in the server. This tells SPIRE how to identify the workload and which SPIFFE ID to give it.

On this machine, we have assumed our workload can be most easily identified by its UNIX user ID (UID). Therefore we’re going to create this selector using a UID Unix selector that will be mapped to a target SPIFFE ID. We first need to create a new user that we will call “workload”:

More on Registration Entries

The contents of a registration entry vary depending on the platform the workload is running on, but all workload registration entries contain:

the parent ID: the agent’s SPIFFE ID, which tells SPIRE which agent this workload belongs to
a ttl for the SVID issued

Because this guide assumes we’re running on UNIX, we also specify the following selectors:

UNIX process id

UNIX user id

UNIX group id

Not that the minimum requirement for a UNIX kernel selector is just one of these.

Step 8: Retrieve Workload SVIDs

At this point, the registration API has been called and the target workload has been registered with the SPIRE Server. We can now call the workload API using a command line program to request the workload’s SVID from the agent, as illustrated in the next section.

Simple Illustration: Retrieve a Workload’s SVID

If you’re curious to see the contents of a workload SVID, follow the instructions in this section to retrieve the SVID bundle and then write the SVID and key to disk, in order to examine them in detail with openssl.

To confirm that OpenSSL is installed, run sudo dpkg -l openssl. If it is not installed, install it with sudo apt -y install openssl.

We simulate the workload API interaction and retrieve the workload SVID bundle by running the api subcommand in the agent. Run the command as the user workload that we created in the previous section.

Getting help

If you have any questions about how SPIRE works, or how to get it up and running, the best place to ask questions is the SPIFFE Slack Organization. Most of the maintainers monitor the #spire channel there, and can help direct you to other channels if need be. Please feel free to drop by any time!