Skip to content

Commit

Permalink
Merge branch 'master' into jsnctl/fix-k8s-quickstart-ns
Browse files Browse the repository at this point in the history
  • Loading branch information
jsnctl committed May 11, 2024
2 parents 0c660cf + c6f3d32 commit daa799b
Show file tree
Hide file tree
Showing 10 changed files with 119 additions and 157 deletions.
27 changes: 12 additions & 15 deletions content/docs/latest/deploying/configuring.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ If this configuration is changed from the default on the server, then the config
# Configuring node attestation
_This configuration applies to the SPIRE Server and SPIRE Agent_

A SPIFFE Server identifies and attests Agents through the process of *node attestation* and *resolution* (read more about this in [SPIRE Concepts](/docs/latest/spire/understand/concepts/)). This is accomplished through Node Attestor and Node Resolver plugins, which you configure and enable in the server. 
A SPIFFE Server identifies and attests Agents through the process of *node attestation* (read more about this in [SPIRE Concepts](/docs/latest/spire/understand/concepts/)). This is accomplished through Node Attestor plugins, which you configure and enable in the server. 

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 each Agent.

Expand Down Expand Up @@ -143,45 +143,42 @@ Many cloud providers offer privileged APIs that allow a process running on a par

### Google Compute Engine Instances

Google Compute Engine (GCE) node attestation and resolution allows a SPIRE Server to identify and authenticate a SPIRE Agent running on a GCP GCE instance automatically. In brief, it is accomplished through the following:
Google Compute Engine (GCE) node attestation allows a SPIRE Server to identify and authenticate a SPIRE Agent running on a GCP GCE instance automatically. In brief, it is accomplished through the following:

1. The SPIRE Agent gcp\_iit Node Attestor plugin retrieves a GCP instance's [instance identity token](https://cloud.google.com/compute/docs/instances/verifying-instance-identity), and identifies itself to the SPIRE Server gcp\_iit Node Attestor plugin.
2. The SPIRE Server gcp\_iit Node Attestor plugin calls a GCP API to verify the validity of the token, if the `use_instance_metadata` configuration value is set to `true`.
3. Once verification takes place, the SPIRE Agent is considered attested, and issued its own SPIFFE ID
4. Finally, SPIRE issues SVIDs to workloads on the nodes if they match a registration entry. The registration entry may include selectors exposed by the Node Attestor or Resolver, or have the SPIFFE ID of the SPIRE Agent as a parent.
3. Once verification takes place, the SPIRE Agent is considered attested, and issued its own SPIFFE ID.
4. Finally, SPIRE issues SVIDs to workloads on the nodes if they match a registration entry. The registration entry may include selectors exposed by the Node Attestor, or have the SPIFFE ID of the SPIRE Agent as a parent.

To use GCP IIT Node Attestation, configure and enable the gcp_iit Node Attestor plugin on the [SPIRE Server](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_server_nodeattestor_gcp_iit.md) and [SPIRE Agent](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_agent_nodeattestor_gcp_iit.md).

### Amazon EC2 Instances

EC2 node attestation and resolution allows a SPIRE Server to identify and authenticate a SPIRE Agent running on an AWS EC2 Instance automatically. In brief, it is accomplished through the following:
EC2 node attestation allows a SPIRE Server to identify and authenticate a SPIRE Agent running on an AWS EC2 Instance automatically. In brief, it is accomplished through the following:

1. The SPIRE Agent aws\_iid Node Attestor plugin retrieves an AWS instance's instance identity document, and identifies itself to the SPIRE Server aws\_iid Node Attestor plugin.
2. The SPIRE Server aws\_iid Node Attestor plugin calls an AWS API to verify the validity of the document, using an AWS IAM role with limited permissions. 
3. If the aws_iid Node Resolver plugin is configured, then SPIRE will use the verified identity of the node to look up additional information about the node. This metadata can be used as a selector in a registration entry.
4. Once verification takes place, the SPIRE Agent is considered attested, and issued its own SPIFFE ID
5. Finally, SPIRE issues SVIDs to workloads on the nodes if they match a registration entry. The registration entry may include selectors exposed by the Node Attestor or Resolver, or have the SPIFFE ID of the SPIRE Agent as a parent.
3. Once verification takes place, the SPIRE Agent is considered attested, and issued its own SPIFFE ID.
4. Finally, SPIRE issues SVIDs to workloads on the nodes if they match a registration entry. The registration entry may include selectors exposed by the Node Attestor or Resolver, or have the SPIFFE ID of the SPIRE Agent as a parent.

For more information on configuring AWS EC2 Node Attestors or Resolver plugins, refer to the corresponding SPIRE documentation for the AWS [SPIRE Server Node Attestor](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_server_nodeattestor_aws_iid.md) and [SPIRE Server Node Resolver](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_server_noderesolver_aws_iid.md) on the SPIRE Server, and the [SPIRE Agent Node Attestor](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_agent_nodeattestor_aws_iid.md) on the agent.
For more information on configuring AWS EC2 Node Attestor plugins, refer to the corresponding SPIRE documentation for the AWS [SPIRE Server Node Attestor](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_server_nodeattestor_aws_iid.md) on the SPIRE Server and the [SPIRE Agent Node Attestor](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_agent_nodeattestor_aws_iid.md) on the agent.

### Azure Virtual Machines

Azure MSI node attestation and resolution
allows a SPIRE Server to identify and authenticate a SPIRE Agent running on an Azure VM automatically. SPIRE uses MSI tokens in order to attest the agent. The MSI tokens must be scoped to mitigate abuse if intercepted. In brief, it is accomplished through the following:
Azure MSI node attestation allows a SPIRE Server to identify and authenticate a SPIRE Agent running on an Azure VM automatically. SPIRE uses MSI tokens in order to attest the agent. The MSI tokens must be scoped to mitigate abuse if intercepted. In brief, it is accomplished through the following:

1. The SPIRE Agent azure\_msi Node Attestor plugin retrieves an Azure VM's MSI token, and identifies itself to the SPIRE Server azure\_msi Node Attestor plugin.
2. The SPIRE Server azure\_msi Node Attestor plugin retrieves the JSON Web Key Set (JWKS) document from Azure–via an API call and uses JWKS information to validate the MSI token. 
3. The SPIRE Server azure\_msi Node Resolver plugin interacts with Azure to obtain information about the agent VM--such as subscription ID, VM name, network security group, virtual network, and virtual network subnet–to build up a set of attributes about the agent VM that can then be used as node selectors for the Azure node set.
4. Once verification takes place, the SPIRE Agent is considered attested, and issued its own SPIFFE ID
5. Finally, SPIRE issues SVIDs to workloads on the nodes if they match a registration entry. The registration entry may include selectors exposed by the Node Attestor or Resolver, or have the SPIFFE ID of the SPIRE Agent as a parent.
3. Once verification takes place, the SPIRE Agent is considered attested, and issued its own SPIFFE ID.
4. Finally, SPIRE issues SVIDs to workloads on the nodes if they match a registration entry. The registration entry may include selectors exposed by the Node Attestor or have the SPIFFE ID of the SPIRE Agent as a parent.

{{< warning >}}
The default resource–assigned by the agent plugin–is scoped relatively widely; it uses the Azure Resource Manager(`https://management.azure.com` endpoint)'s resource id. For security reasons, consider using a custom resource id, to scope more narrowly. 

If you configure a custom resource ID in the agent configuration file, you must specify custom resource IDs for each tenant, in the `NodeAttestor` stanza of the `server.conf` configuration file.
{{< /warning >}}

For more information on configuring Azure MSI Node Attestors or Resolver plugins, refer to the corresponding SPIRE documentation for the Azure MSI [SPIRE Server Node Attestor](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_server_nodeattestor_azure_msi.md) and [SPIRE Server Node Resolver](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_server_noderesolver_azure_msi.md) on the SPIRE Server, and the [SPIRE Agent Node Attestor](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_agent_nodeattestor_azure_msi.md) on the agent.
For more information on configuring Azure MSI Node Attestor plugins, refer to the corresponding SPIRE documentation for the Azure MSI [SPIRE Server Node Attestor](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_server_nodeattestor_azure_msi.md) on the SPIRE Server and the [SPIRE Agent Node Attestor](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_agent_nodeattestor_azure_msi.md) on the agent.

# Configuring workload attestation
_This configuration applies to the SPIRE Agent_
Expand Down
6 changes: 5 additions & 1 deletion content/docs/latest/deploying/registering.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ Different selectors are available depending on the platform or architecture on w
|-----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Kubernetes** | The [configuration reference page for the Kubernetes Node Attestor](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_server_nodeattestor_k8s_sat.md) |
| **AWS** | The [configuration reference page for the AWS Node Attestor](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_server_nodeattestor_aws_iid.md) |
| **Azure** | The [configuration reference page for the Azure Managed Service Identity Node Resolver](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_server_noderesolver_azure_msi.md) |
| **Azure** | The [configuration reference page for the Azure Managed Service Identity Node Attestor](https://github.com/spiffe/spire/blob/{{< spire-latest "tag" >}}/doc/plugin_server_nodeattestor_azure_msi.md) |

## 2. Defining the SPIFFE ID of the Workload

Expand Down Expand Up @@ -119,6 +119,10 @@ To learn more about the `spire-server entry delete` command and options, consult

A workload registration entry can have a single parent ID. This could be the SPIFFE ID of a specific node (i.e. the SPIFFE ID of an agent as given through node attestation) or it could also be the SPIFFE ID of a node registration entry (sometimes referred to as a node alias/set). A node alias (or set) is a group of nodes that share similar characteristics that are given a shared identity. The node registration entry has the node selectors that are required in order for a node to qualify for the shared identity. Meaning that any node that has at least the selectors defined by a node registration entry is given that alias (or belongs to that node set). When a workload registration entry uses the SPIFFE ID of a node alias as the parent, any node with that alias is authorized to obtain SVIDs for that workload

```
spire-server entry create -node -spiffeID spiffe://acme.org/mynodealias -selector aws_iid:tag:<TAG_NAME>:<TAG_VALUE>
```

# Where next?

Once you've learned how to create, update and delete registration entries, consider reviewing the guide on [How to use SVIDs](/docs/latest/spire/developing/svids/).
10 changes: 1 addition & 9 deletions content/docs/latest/planning/extending.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,14 +27,6 @@ In addition, known third-party Node Attestor plugins include:

* https://github.com/zlabjp/spire-openstack-plugin - This plugin allows SPIRE to attest to nodes deployed by OpenStack and identify them by the OpenStack project ID and instance ID.

# Node Resolver plugins

Once the identity of an individual node has been determined, in some cases it is valuable to be able to expose additional verified metadata about that node as selectors for registration entries. For example, the AWS EC2 IID Node Attestor plugin can be used to prove the Instance ID of a given EC2 instance, but the AWS EC2 IID Node Resolver plugin will - by looking up additional instance metadata in AWS - expose additional selectors (such as instance tag or label) based on this verified metadata.

Node Resolver plugins are typically coupled to a specific Node Attestor plugin (such as the AWS EC2 IID Node Attestor), since they will rely on that plugin to verify the initial identity of the node.

SPIRE comes with a set of built-in Node Resolver plugins for the [Server](/docs/latest/deploying/spire_server/).

# Workload Attestor plugins

While Node Attestors help SPIRE verify the identity of a node running a workload, Workload Attestors identify a specific workload running on that node. Workload attestors run on the Agent. A workload attestor may leverage kernel metadata retrieved during a call to the Workload API to determine the identity of a workload, but it may also choose to interrogate other local sources (such as the calling binary, the Docker daemon or the Kubernetes kubelet) to verify the identity of a workload. As with Node Attestor plugins, Workload Attestor plugins expose selectors that allow registration entries to be created for workloads based on the properties of the workload that the attestor verified.
Expand All @@ -57,7 +49,7 @@ SPIRE comes with a set of built-in Key Manager plugins for the [Server](/docs/la

Notifier plugins allow actions to be triggered in other systems when certain events occur on the SPIRE Server, and in some cases interrupt the event itself. Notifier plugins can support a number of different use cases, such as when certificate rotation events occur.

SPIRE comes with a set of built-in Notifier plugins for the [Server](/docs/latest/deploying/spire_server/).
SPIRE comes with a set of built-in Notifier plugins for the [Server](/docs/latest/deploying/spire_server/) and [Agent](/docs/latest/deploying/spire_agent/).

# Working with first-party plugins

Expand Down
4 changes: 2 additions & 2 deletions content/docs/latest/spiffe-about/get-involved.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,5 +36,5 @@ Day to day contributions are vetted by the project's maintainers. Overall projec

Find SPIFFE and SPIRE logos here:

* [SPIFFE](https://branding.cncf.io/projects/spiffe)
* [SPIRE](https://branding.cncf.io/projects/spire)
* [SPIFFE](https://github.com/cncf/artwork/tree/main/projects/spiffe)
* [SPIRE](https://github.com/cncf/artwork/tree/main/projects/spire)
2 changes: 1 addition & 1 deletion content/docs/latest/spire-about/comparisons.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Secrets managers typically control, audit and securely store sensitive informati

A common architectural challenge in deploying secrets managers is how to securely store the credential that is used by the workload to access the secret store itself. This is sometimes called "credential zero", the "bootstrap credential", or more broadly, the process of "secure introduction".

By contrast, while SPIRE does _generate_ SPIFFE identities that can be used to [authenticate to other systems](/docs/latest/spire-integrations/use-cases/), SPIRE does not aim to store existing keys (such as a database password) on behalf of a workload.
By contrast, while SPIRE does _generate_ SPIFFE identities that can be used to [authenticate to other systems](/docs/latest/spire-about/use-cases/), SPIRE does not aim to store existing keys (such as a database password) on behalf of a workload.

SPIRE's attestation policies provide a flexible and powerful solution for secure introduction to secrets managers. A common use of SPIRE-issued [SVIDs](/docs/latest/spiffe/concepts/#spiffe-verifiable-identity-document-svid) is to authenticate to secret stores to allow an application to retrieve secrets.

Expand Down
Loading

0 comments on commit daa799b

Please sign in to comment.