Self-hosted deployment

In a self-hosted deployment, you host both the control plane and the data plane. You choose the topology that fits your operational and regulatory requirements — both planes in a single Kubernetes cluster, in separate clusters, in different regions, or any combination. Union.ai gives you complete control over the installation with full data sovereignty.

When to use self-hosted deployment

Choose self-hosted deployment when:

• You need full control over both control plane and data plane
• You have strict data locality or sovereignty requirements
• You want to minimize network egress costs
• You are running in an air-gapped or restricted network environment
• You need to colocate the control plane with the data plane for latency, isolation, or regulatory reasons

Choose self-managed deployment when:

• You want Union.ai to manage the control plane
• You need Union.ai’s managed services and support

Topologies

Self-hosted deployments support two topologies, distinguished by how the control plane and data plane are placed relative to each other:

• Separate-cluster (default and recommended) — control plane in one Kubernetes cluster, one or more data planes in separate clusters (often per environment, region, or business unit). Communication is via the control plane’s external ingress; each data plane authenticates to the CP as a workload identity. Data planes may run on different cloud providers than the CP. This is the topology Infrastructure requirements is written around.
• Intra-cluster (special case) — both planes in the same Kubernetes cluster, communicating over cluster-local Services. The simplest topology; used by the Getting started walkthrough and for footprint-constrained or evaluation deployments. Enable by setting CONTROLPLANE_GRPC_ENDPOINT + QUEUE_GRPC_ENDPOINT to cluster-local svc URLs in your values.{aws,gcp}.yaml — see Getting started → Optional: intracluster topology. Infrastructure requirements → Intra-cluster topology covers the substrate trade-offs.

The architecture diagram below shows the intra-cluster topology — the simplest layout to visualize. Separate-cluster uses the same chart components in different cluster boundaries.

Architecture

In an intra-cluster deployment, the control plane and data plane communicate using Kubernetes internal networking rather than external endpoints.

            graph TB
    subgraph cluster["Kubernetes Cluster"]
        subgraph cp["Controlplane Namespace"]
            cpingress["NGINX Ingress\n(TLS/HTTP2)\nClusterIP"]
            admin["Admin"]
            identity["Identity"]
            services["Services"]

            cpingress --> admin
            cpingress --> identity
            cpingress --> services
        end

        subgraph dp["Dataplane Namespace"]
            dpingress["NGINX Ingress\nClusterIP"]
            operator["Operator"]
            propeller["Propeller"]
            clusterresource["Cluster Resource\nSync"]

            dpingress --> operator
            dpingress --> propeller
            dpingress --> clusterresource
        end

        subgraph external["External Resources"]
            db["PostgreSQL"]
            storage["Object Storage\n(S3 / GCS)"]
        end

        dpingress -.->|"Internal DNS"| cpingress
        cpingress -.->|"Internal DNS"| dpingress

        admin --> db
        identity --> db
        services --> db
        admin --> storage
        operator --> storage
    end
        

Key characteristics:

• Simplified networking: All communication stays within the cluster via Kubernetes DNS
• No external dependencies: No internet connectivity required for control plane to data plane communication
• Cost-effective: No network egress costs between control plane and data plane
• Self-signed certificates: Can use self-signed certificates for intra-cluster TLS
• Single-tenant mode: Simplified security model with explicit organization configuration

Deployment guides

Start with Getting started for an end-to-end walkthrough. Review Infrastructure requirements before provisioning your cloud substrate. The remaining pages cover individual deployment components in depth.