// Module included in the following assemblies:
//
// * security/zero_trust_workload_identity_manager/zero-trust-manager-spire-federation.adoc

:_mod-docs-content-type: REFERENCE
[id="zero-trust-manager-federation-field-reference_{context}"]
= Federation configuration field reference

[role="_abstract"]
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::

[cols="2,1,1,2,3",options="header"]
|===
|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::

[cols="2,1,1,2,3",options="header"]
|===
|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::

[cols="2,1,1,2,3",options="header"]
|===
|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::

[cols="2,1,1,2,3",options="header"]
|===
|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::

[cols="2,1,1,2,3",options="header"]
|===
|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::

[cols="2,1,1,2,3",options="header"]
|===
|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
