Federated Services

A Federated Service exposes a workload to one or more remote trust domains, enabling clients in those trust domains to discover and connect to it over mTLS. The Cofide Agent orchestrates the necessary resources on both the server cluster (where the service runs) and the client clusters (where it is imported). Federated Services use Istio for gateway routing and currently require Istio to be installed on the server cluster. Note that Istio does not need to be configured with SPIRE as its certificate authority for federated services to work.

Before creating a Federated Service, a federation must exist between the trust domains involved. See Communication Patterns for examples of how different client types connect to a Federated Service.

Creating a Federated Service

Cofide Federated Services are created using Kubernetes Custom Resources (CRs). The Custom Resource Definition (CRD) is included in the Cofide Agent Helm chart.

The following example exposes a ping-pong server running in the demo namespace to two remote trust domains, other1.domain and other2.domain.

---
apiVersion: registry.cofide.io/v1alpha1
kind: FederatedService
metadata:
  name: ping-pong
  namespace: demo
spec:
  name: server
  namespace: demo
  exportedTrustDomains:
    - other1.domain
    - other2.domain
  workloadLabels:
    app: ping-pong-server
  port: 8443
  tlsMode: Mtls

Apply this manifest to the Kubernetes cluster in which the server is running. You do not need to create any Istio resources manually - the Cofide Agent handles this automatically. The above configuration exposes the service on one or more gateways found through auto-discovery.

Spec fields

Field	Required	Description
spec.name	yes	Logical name for the service, used as part of the hostname that remote clients connect to. Independent of metadata.name.
spec.namespace	yes	Namespace of the server workload.
spec.exportedTrustDomains	yes	List of remote trust domains that can access this service. A federation must exist between the server’s trust domain and each listed trust domain.
spec.workloadLabels	yes	Label selector identifying the pods that back this service. A Kubernetes Service matching these labels must exist in the same namespace.
spec.port	yes	Port the server listens on.
spec.tlsMode	yes	How mTLS is handled. Must be Mtls or IstioMtls. See TLS mode below.
spec.gateways	no	Manual gateway overrides. If omitted, gateways are discovered automatically. See Manual gateway configuration below.

TLS mode

spec.tlsMode controls how mutual TLS is handled for the federated service. It must be set explicitly; there is no default.

Mtls

The server application handles TLS directly using SPIRE-issued SVIDs. The Istio sidecar (if present) passes traffic on the federated service port through untouched. The Istio gateway operates in PASSTHROUGH mode.

Use Mtls when the server application terminates mTLS itself.

IstioMtls

The server’s Istio proxy sidecar terminates mTLS. The server application handles plain-text traffic only. The Istio gateway operates in AUTO_PASSTHROUGH mode.

Use IstioMtls when the server is deployed with an Istio proxy sidecar and TLS termination should be handled by that sidecar.

Resources created by the agent

When a Federated Service is reconciled, the Cofide Agent creates Istio resources on both the server and client clusters.

Server cluster

The agent always creates a ServiceEntry for the federated service. If an ingress gateway is present, it additionally creates:

• A PeerAuthentication scoped to the server workload, configuring TLS behaviour on the federated service port according to spec.tlsMode.
• An Istio Gateway routing inbound traffic from the ingress gateway to the service by SNI.
• A VirtualService matching on the service hostname and routing traffic through to the ServiceEntry.

All of these resources are owned by the FederatedService CR and are cleaned up automatically when the CR is deleted.

Client clusters

The Cofide Agent running in each client cluster receives federated service updates from Connect and reconciles local resources accordingly. For clusters using Istio, the agent creates:

• A ServiceEntry for the federated service hostname, making it resolvable within the local mesh.
• A WorkloadEntry pointing at the remote cluster’s eastwest gateway, telling Istio to route traffic for that hostname via the gateway.

For non-Istio clusters, the agent exposes an xDS API that Envoy-based clients can consume directly. This provides cluster and endpoint configuration for each federated service, resolving the service hostname to the remote ingress gateway address and port. The agent also serves a local DNS resolver that maps federated service hostnames to localhost, so that workloads can connect by hostname without any DNS changes. See Communication Patterns for examples of non-Istio client setups using the xDS API.

Connecting to a Federated Service

Remote workloads connect to a Federated Service using the hostname:

{spec.name}.{spec.namespace}.{serverTrustDomain}

For example, if spec.name is server, spec.namespace is demo, and the server’s trust domain is local.domain, remote clients connect to server.demo.local.domain.

For Istio mesh clients, this hostname is available as a ServiceEntry created automatically by the Cofide Agent in the client cluster. For non-Istio clients, the Cofide Agent’s xDS API resolves the hostname to the gateway address and port. See Communication Patterns for details on each client type.

Manual gateway configuration

By default, the Cofide Agent discovers gateway addresses automatically from the istio-eastwestgateway and istio-ingressgateway services in the istio-system namespace. In cases where more control is required, gateway addresses can be specified manually using spec.gateways:

---
apiVersion: registry.cofide.io/v1alpha1
kind: FederatedService
metadata:
  name: ping-pong
  namespace: demo
spec:
  name: server
  namespace: demo
  exportedTrustDomains:
    - other1.domain
    - other2.domain
  workloadLabels:
    app: ping-pong-server
  port: 8443
  tlsMode: Mtls
  gateways:
    - type: istio-ingressgateway
      hostname: gw.example.com
      port: 5432
    - type: istio-eastwestgateway
      ip: 1.2.3.4
      port: 4321

Each entry in spec.gateways has the following fields:

Field	Required	Description
type	yes	Gateway type. Must be istio-ingressgateway or istio-eastwestgateway.
port	yes	Port the gateway listens on.
hostname	no	Hostname of the gateway. Mutually exclusive with ip.
ip	no	IP address of the gateway. Mutually exclusive with hostname.

Checking status

The Federated Service CR has a status subresource that shows the gateways discovered by the agent and whether reconciliation has succeeded.

kubectl get federatedservice ping-pong -n demo -o yaml

The status.gatewayEntries field lists the gateways the agent discovered and registered with Connect. The status.conditions field indicates whether reconciliation succeeded. If status.gatewayEntries is empty and no gateways are specified manually, check that the istio-eastwestgateway or istio-ingressgateway services exist in the namespace where Istio is installed (typically istio-system) and are externally reachable.