Federation configuration field reference

This reference provides detailed information about all configuration fields available for SPIRE federation in the SpireServer custom resource. Use this reference when customizing your federation setup.

Top-level federation fields
Field Type Required Default Description

federation.bundleEndpoint

object

Yes

N/A

Configuration for this cluster’s federation endpoint that exposes the trust bundle to remote clusters.

federation.federatesWith

array

No

[]

List of remote trust domains to federate with.

federation.managedRoute

string

No

"true"

Enable or disable automatic OpenShift Route creation. Set to "true" for operator-managed routes or "false" for manual route management.

bundleEndpoint configuration fields
Field Type Required Default Description

federation.bundleEndpoint.profile

string (enum)

Yes

https_spiffe

Authentication profile for the bundle endpoint. Valid values: https_spiffe or https_web. This value is immutable after initial configuration.

federation.bundleEndpoint.refreshHint

integer

No

300

Suggested interval (in seconds) for remote servers to refresh the trust bundle. Valid range: 60-3600.

federation.bundleEndpoint.httpsWeb

object

Conditional

N/A

Required when profile is https_web. Contains certificate configuration.

httpsWeb configuration fields
Field Type Required Default Description

federation.bundleEndpoint.httpsWeb.acme

object

Conditional

N/A

ACME configuration for automatic certificate management. Mutually exclusive with servingCert.

federation.bundleEndpoint.httpsWeb.servingCert

object

Conditional

N/A

Manual certificate configuration. Mutually exclusive with acme.

ACME configuration fields
Field Type Required Default Description

federation.bundleEndpoint.httpsWeb.acme.directoryUrl

string

Yes

N/A

ACME directory URL. For Let’s Encrypt production: https://acme-v02.api.letsencrypt.org/directory. For staging: https://acme-staging-v02.api.letsencrypt.org/directory

federation.bundleEndpoint.httpsWeb.acme.domainName

string

Yes

N/A

Fully qualified domain name for the certificate. Typically the federation endpoint hostname.

federation.bundleEndpoint.httpsWeb.acme.email

string

Yes

N/A

Email address for ACME account registration and certificate expiration notifications.

federation.bundleEndpoint.httpsWeb.acme.tosAccepted

string

No

"false"

Accept the ACME provider’s Terms of Service. Must be "true" to obtain certificates.

servingCert configuration fields
Field Type Required Default Description

federation.bundleEndpoint.httpsWeb.servingCert.fileSyncInterval

integer

No

86400

Interval (in seconds) to check for certificate updates. Valid range: 3600-7776000 (1 hour to 90 days).

federation.bundleEndpoint.httpsWeb.servingCert.externalSecretRef

string

Yes

N/A

Name of the Kubernetes Secret containing the TLS certificate (tls.crt) and private key (tls.key) for the federation route.

federatesWith configuration fields
Field Type Required Default Description

federation.federatesWith[].trustDomain

string

Yes

N/A

Trust domain name of the remote SPIRE deployment (for example, cluster2.example.com).

federation.federatesWith[].bundleEndpointUrl

string

Yes

N/A

HTTPS URL of the remote federation endpoint (for example, https://federation.apps.cluster2.example.com).

federation.federatesWith[].bundleEndpointProfile

string (enum)

Yes

N/A

Authentication profile of the remote endpoint. Valid values: https_spiffe or https_web.

federation.federatesWith[].endpointSpiffeId

string

Conditional

N/A

SPIFFE ID of the remote SPIRE server (for example, spiffe://cluster2.example.com/spire/server). Required when bundleEndpointProfile is https_spiffe.

Field validation rules

The following validation rules are enforced by the operator:

  • Profile immutability: The bundleEndpoint.profile field cannot be changed after initial configuration. Changing it requires deleting and recreating the SpireServer resource (re-installation of the system).

  • Mutual exclusivity: Within httpsWeb, only one of acme or servingCert can be specified.

  • Conditional requirements: When profile is https_web, the httpsWeb object must be present with either acme or servingCert configured.

  • SPIFFE ID requirement: When bundleEndpointProfile is https_spiffe in the federatesWith list, the endpointSpiffeId field is required.

  • Array limits: The federatesWith array supports a maximum of 50 entries.

  • Numeric ranges:

    • refreshHint: 60-3600 seconds

    • fileSyncInterval: 3600-7776000 seconds