spire

Documentation

Overview

Package spire provides integration with SPIRE for X.509 SVID management.

The SPIRE bridge connects the SPIRE Delegated Identity API to the Aether agent's xDS snapshot cache. It subscribes to X.509 SVIDs (Secure Workload Identity Documents) and trust bundles from a SPIRE agent and converts them to Envoy Secret resources. These secrets are pushed to the xDS cache and delivered to Envoy proxies for mTLS.

The bridge implements controller-runtime's Runnable interface for lifecycle management within the agent's Manager. It uses goroutines to handle asynchronous SVID and bundle subscription streams from SPIRE.

SPIRE integration is optional and can be disabled via the spire-enabled flag. If disabled, the agent skips the SPIRE bridge but still functions normally.

Package spire provides a bridge between the SPIRE Delegated Identity API and Envoy's Secret Discovery Service (SDS) via go-control-plane.

The bridge subscribes to X.509 SVIDs and trust bundles from the SPIRE Agent's admin socket using the Delegated Identity API, converts them to Envoy Secret resources, and pushes them into the xDS snapshot cache for delivery to Envoy proxies via ADS.

Index

• func BundleToValidationContextSecret(trustDomain string, derCACerts []byte) (*tlsv3.Secret, error)
• func PodSelectors(namespace, serviceAccount, podName, uid string) []*apitypes.Selector
• func SVIDToTLSCertificateSecret(svid *delegatedidentityv1.X509SVIDWithKey) (*tlsv3.Secret, error)
• func X509SVIDToTLSCertificateSecret(svid *x509svid.SVID) (*tlsv3.Secret, error)
• type Bridge
  • func NewBridge(socketPath string, store SecretStore, nodeSource X509SVIDSource, ...) *Bridge
  • func (b *Bridge) Start(ctx context.Context) error
  • func (b *Bridge) Started() <-chan struct{}
  • func (b *Bridge) SubscribePod(netns, spiffeID string, selectors []*apitypes.Selector) error
  • func (b *Bridge) UnsubscribePod(ctx context.Context, netns string) error
• type Client
  • func NewClient(ctx context.Context, socketPath string, log *slog.Logger) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) SubscribeBundles(ctx context.Context) (<-chan *delegatedidentityv1.SubscribeToX509BundlesResponse, error)
  • func (c *Client) SubscribeSVIDsBySelectors(ctx context.Context, selectors []*apitypes.Selector) (<-chan *delegatedidentityv1.SubscribeToX509SVIDsResponse, error)
• type NodeIdentitySink
• type SecretStore
• type X509SVIDSource

Functions

func BundleToValidationContextSecret

func BundleToValidationContextSecret(trustDomain string, derCACerts []byte) (*tlsv3.Secret, error)

BundleToValidationContextSecret converts a trust domain's CA certificates to an Envoy validation context Secret. trustDomain may be a bare trust domain name ("example.org") or a SPIFFE URI ("spiffe://example.org") — the SPIRE Delegated Identity bundle map is keyed by the latter. Either way the secret is named with the canonical SPIFFE URI (e.g. "spiffe://example.org") to match the validation context name referenced by inbound listeners and the SVID secret naming. The DER-encoded CA certs are PEM-encoded.

func PodSelectors

func PodSelectors(namespace, serviceAccount, podName, uid string) []*apitypes.Selector

PodSelectors builds the SPIRE k8s workload selectors that identify a pod by its namespace, service account, name and UID. SPIRE issues the SVID of any registration entry whose selectors are a subset of these; the spire-controller-manager binds entries by k8s:pod-uid, which is unique per pod.

func SVIDToTLSCertificateSecret

func SVIDToTLSCertificateSecret(svid *delegatedidentityv1.X509SVIDWithKey) (*tlsv3.Secret, error)

SVIDToTLSCertificateSecret converts a SPIRE X509SVIDWithKey to an Envoy TLS certificate Secret. The secret name is the full SPIFFE ID URI. DER-encoded cert chain and PKCS#8 private key are PEM-encoded for Envoy.

func X509SVIDToTLSCertificateSecret

func X509SVIDToTLSCertificateSecret(svid *x509svid.SVID) (*tlsv3.Secret, error)

X509SVIDToTLSCertificateSecret converts a go-spiffe X.509 SVID (as returned by the Workload API source) to an Envoy TLS certificate Secret. The secret name is the full SPIFFE ID URI. This is used to serve the agent's own node identity to the proxy for node-originated upstream mTLS and the node-health listener, distinct from the per-pod workload SVIDs served via the Delegated Identity API.

Types

type Bridge

type Bridge struct {
	// contains filtered or unexported fields
}

Bridge connects the SPIRE Delegated Identity API to the xDS snapshot cache. It subscribes to X.509 SVIDs and trust bundles from SPIRE and converts them to Envoy Secret resources. Bridge implements controller-runtime's Runnable interface for lifecycle management.

func NewBridge

func NewBridge(socketPath string, store SecretStore, nodeSource X509SVIDSource, log *slog.Logger) *Bridge

NewBridge creates a new SPIRE bridge. nodeSource is the agent's own Workload API SVID source used to serve the node identity; it may be nil to disable node-SVID serving.

func (*Bridge) Start

func (b *Bridge) Start(ctx context.Context) error

Start connects to the SPIRE agent and begins subscribing to trust bundles. It blocks until the context is canceled. Implements controller-runtime Runnable.

func (*Bridge) Started

func (b *Bridge) Started() <-chan struct{}

Started returns a channel that is closed once the bridge has connected to the SPIRE agent and can accept subscriptions. Callers re-subscribing stored pods after an agent restart wait on it (selecting on their context as well, since the channel never closes if Start fails before connecting).

func (*Bridge) SubscribePod

func (b *Bridge) SubscribePod(netns, spiffeID string, selectors []*apitypes.Selector) error

SubscribePod starts an SVID subscription for the pod in the given network namespace using its Kubernetes workload selectors (namespace, service account, pod name and UID). The SPIRE agent returns the SVIDs of every registration entry whose selectors are satisfied — no process attestation, so no container PID is required. spiffeID is used as the secret name for Envoy. It is a no-op if the bridge has not been started yet or the netns is already subscribed. The subscription is bound to the bridge's lifetime, not any request context.

func (*Bridge) UnsubscribePod

func (b *Bridge) UnsubscribePod(ctx context.Context, netns string) error

UnsubscribePod stops the SVID subscription for the pod in the given network namespace. The pod's SVID secret is removed only when no other subscribed pod shares the same SPIFFE ID (service account), so a rolling restart that briefly runs two same-identity pods never drops the live SVID. No-op if the bridge has not been started or the netns is not subscribed.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client wraps the SPIRE Delegated Identity gRPC client.

func NewClient

func NewClient(ctx context.Context, socketPath string, log *slog.Logger) (*Client, error)

NewClient creates a new SPIRE Delegated Identity client connected to the admin socket at the given path.

func (*Client) Close

func (c *Client) Close() error

Close closes the underlying gRPC connection.

func (*Client) SubscribeBundles

func (c *Client) SubscribeBundles(ctx context.Context) (<-chan *delegatedidentityv1.SubscribeToX509BundlesResponse, error)

SubscribeBundles opens a SubscribeToX509Bundles stream and returns a channel that receives bundle updates. The channel is closed when the stream ends or the context is canceled.

func (*Client) SubscribeSVIDsBySelectors

func (c *Client) SubscribeSVIDsBySelectors(ctx context.Context, selectors []*apitypes.Selector) (<-chan *delegatedidentityv1.SubscribeToX509SVIDsResponse, error)

SubscribeSVIDsBySelectors opens a SubscribeToX509SVIDs stream for the given workload selectors. The SPIRE agent returns the SVIDs of every registration entry whose selectors are a subset of those provided, without attesting a process. The channel is closed when the stream ends or the context is cancelled.

type NodeIdentitySink

type NodeIdentitySink interface {
	SetNodeIdentity(ctx context.Context, nodeSpiffeID string) error
}

NodeIdentitySink receives the agent's node SPIFFE ID when the node SVID is served, so resources that reference it (the outbound clusters' no-match upstream client cert) can be generated. The xDS snapshot cache satisfies it; the bridge calls it only when its store also implements this interface.

type SecretStore

type SecretStore interface {
	SetSecrets(ctx context.Context, secrets []*tlsv3.Secret) error
}

SecretStore is the interface for pushing secrets into the xDS snapshot cache.

type X509SVIDSource

type X509SVIDSource interface {
	GetX509SVID() (*x509svid.SVID, error)
}

X509SVIDSource provides the agent's own node SVID. It is satisfied by the go-spiffe Workload API X509Source the agent already uses for registrar mTLS.