System Architecture

Catalyst Enterprise Self-Hosted is designed to provide a secure, flexible and reliable environment for running your applications, while being managed through the Diagrid Cloud control plane. This document provides an overview of the system architecture to help you understand the key components, data flows, dependencies, and infrastructure requirements of a Catalyst Enterprise Self-Hosted deployment.

Components

A Catalyst Enterprise Self-Hosted deployment consists of the following key components:

• Agent
• Management Service
• Gateway
• Telemetry Collectors
• Catalyst Dapr Control Plane
• Catalyst Dapr Servers
• Catalyst Tunneling Service (optional)

Agent

The Agent is responsible for managing the lifecycle of all the Catalyst resources within the Kubernetes cluster. It securely connects to the Diagrid Cloud control plane using mTLS and SPIFFE based workload identity. Once connected, it installs and manages the Telemetry Collectors, Catalyst Dapr Control Plane and any other configured infrastructure services such as PostgreSQL. The Agent then subscribes to any relevant resource updates from the control plane and ensures the desired state is maintained within the cluster. This includes the provisioning of Catalyst Projects and other related resources.

Management Service

The Management Service serves 3 main purposes:

1. Provides a REST API for access from your private network to view application data.
2. Provides an internal communication channel to allow the control plane to securely read and write secrets to your self-hosted region.
3. Provides an internal configuration stream for Catalyst Dapr Servers to dynamically receive updates from the Agent.

The Management Service is not exposed to the public internet and is only accessible from within your private network. It uses reverse tunneling to securely connect to the Diagrid Cloud control plane, allowing it to receive configuration updates and securely manage secrets without exposing any endpoints to the public internet.

Gateway

The Gateway is an Envoy control plane that manages access from within your private network to services running within your Catalyst region.

This includes exposing:

• Catalyst Dapr Servers to your applications.
• The Management Service API to the CLI or web UI served from within your private network.
• Workload identity trust anchors for trust distribution
• Catalyst Dapr Control Plane and configuration API for externally running Dapr servers.

Telemetry Collectors

The Telemetry Collectors are responsible for collecting and exporting specific metrics and log data from the Catalyst Dapr Servers. This data is used to provide observability features in the Diagrid Cloud control plane. The collectors are Diagrid distributions of the open-source OpenTelemetry Collector project.

Catalyst Dapr Control Plane

The Catalyst Dapr Control Plane is a Diagrid distribution of the Dapr control plane that runs as a shared service within your cluster. It provides the standard Dapr control plane features such as workload identity, configuration management, actor placement and job scheduling to the Catalyst Dapr Servers.

Catalyst Dapr Servers

The Catalyst Dapr Servers are a standalone distribution of the Dapr runtime, often times referred as the Dapr Sidecars, deployed to serve Dapr APIs to your applications. They run and scale independently of your applications, which are deployed separately. The Catalyst Dapr Servers expose the following standard Dapr APIs to your applications:

Dapr API Compatibility

• Conversation
• Workflows
• Service invocation
• State management
• Pub/Sub
• Actors
• Secrets
• Configuration
• Bindings
• Distributed Lock
• Jobs

Catalyst Tunneling Service (optional, opt-out)

Catalyst hosts a tunneling service known as piko that provides the capability for applications and other clients to securely expose themselves to the Catalyst Dapr Servers directly over a tunnel without the need for additional ingress. This is the capability that powers the diagrid listen and diagrid dev run commands.

Networking & Data Flows

Catalyst Enterprise Self-Hosted is designed to ensure that all application data remains within your private network and is not exposed to Diagrid or the public internet. The Diagrid Cloud control plane manages the lifecycle of resources within your region, but does not have access to any of the application data flowing through the Catalyst Dapr Servers. The control plane also does not persist any of the secret resource configuration data, instead it securely stores those within your private installation and only keeps references to resolve them at runtime.

The only endpoint you need to expose from your self-hosted region is the Gateway, which is accessed by your applications and users from within your private network.

To provide a better user experience, we optionally (opt-out) export the following data from your self-hosted region to the Diagrid Cloud control plane:

• Dapr Servers metrics and logs.
• Agent installation metadata such as k8s version.
• Resource installation and lifecycle status and metadata.

Outbound Network Connections

Catalyst Enterprise Self-Hosted requires outbound connectivity to Diagrid Cloud. Ensure your network allows access to:

Domain	Description	Required
api.r1.diagrid.io	Region join (installation only).	Yes
catalyst-cloud.r1.diagrid.io	Resource configuration updates.	Yes
sentry.r1.diagrid.io	Workload identity (mTLS).	Yes
trust.r1.diagrid.io	Trust anchors (mTLS).	Yes
tunnels.trust.diagrid.io	OIDC provider for Piko tunnels.	No
client-events.r1.diagrid.io	Event publishing.	Yes
catalyst-metrics.r1.diagrid.io	Dapr runtime metrics.	No
catalyst-logs.r1.diagrid.io	Dapr runtime logs.	No

Note: mTLS is used for secure communication. Ensure your proxy/firewall does not inspect this traffic.

Network Policies

Each Catalyst Project runs in its own dedicated Kubernetes namespace (prj-<project-id>). Catalyst reconciles a set of Kubernetes NetworkPolicy resources in each project namespace to enforce a deny-by-default posture, allowing only the traffic required for Catalyst to operate. By default, Dapr Servers in one project cannot reach workloads in another project's namespace or internal services on your cluster network.

The default posture can be tuned via the following Helm values under agent.config.project. See the Helm Chart Reference for the full set of options and examples:

Key	Purpose
blocked_egress	CIDRs denied from the Dapr Server egress. Defaults cover RFC1918 and the cloud metadata range (169.254.0.0/16).
allowed_egress	Additive allow rules for Dapr Server egress, by CIDRs and/or namespaces, optionally scoped to ports. Use this to allow traffic to services blocked by blocked_egress rules.
allowed_ingress	Additive allow rules for ingress into project namespaces. The cra-agent and monitoring namespaces are always permitted so management traffic and metrics scraping are never blocked.
disable_network_policies	Disables network policy creation entirely. Not recommended for production usage.

Allow rules always win over block rules, so you can punch narrow holes through blocked_egress without weakening it. For example, to allow Dapr Servers to reach an internal database:

agent:
  config:
    project:
      allowed_egress:
        - name: rds
          cidrs: ["10.4.5.6/32"]
          ports:
            - port: 5432
              protocol: TCP

Security

Catalyst builds on top of the security foundations of Dapr. This includes using mTLS and SPIFFE based workload identity for all communication between Catalyst Dapr Servers, Catalyst Components and the Diagrid Cloud control plane.

Workload Identity

Every Catalyst component and Dapr Server is issued a SPIFFE identity in the form of a short-lived X.509 SVID, signed by a Dapr Sentry and automatically rotated in the background. These identities are what drive mTLS authentication across the system, so every connection — between components, between Dapr Servers, and between the region and Diagrid Cloud — is mutually authenticated using verifiable cryptographic identities rather than shared secrets.

Trust domains and sentries

Catalyst Enterprise Self-Hosted operates two sentries across two trust domains:

• Dataplane Sentry — runs inside your cluster as part of the Catalyst Dapr Control Plane. It issues SPIFFE identities under a regional trust domain to in-cluster Catalyst components and Catalyst Dapr Servers. The root of trust for this sentry is owned and managed by the user.
• Public Sentry — runs in Diagrid Cloud (sentry.r1.diagrid.io) under the trust.diagrid.io trust domain. It issues identities to components that communicate with the Diagrid Cloud control plane. The root of trust for this sentry is owned and managed by Diagrid.

Components that bridge your private network and Diagrid Cloud — the Agent, Gateway, and Management Service — hold dual identities, one from each sentry. The security layer transparently selects the correct credential to present based on the peer's trust domain.

The SPIFFE ID format follows the standard spiffe://<trust-domain>/ns/<namespace>/<identity> pattern. For example, a Dapr Server in a Catalyst Project receives an identity like spiffe://<regional-trust-domain>/ns/prj-<project-id>/<app-id>.

Trust anchor distribution

To verify each other's certificates, components maintain three sets of trust anchors, one per trust domain in use:

• Diagrid CA — the root CA for identities issued by the Public Sentry. Fetched from trust.r1.diagrid.io.
• Region Host CA — the root CA for identities issued by the Dataplane Sentry. Distributed in-cluster and served to external clients via the Gateway's trust distribution endpoint.
• Workload Identity CA — established per external workload during join, used only to validate the workload's bootstrap certificate.

When a component receives a peer certificate, it looks up the peer's trust domain, finds the matching CA, and validates the signature — allowing the system to recognize multiple authorities without conflating them.

Secret Management

Catalyst Enterprise Self-Hosted provides pluggable secrets providers that are configured per installation. By default, it uses a Kubernetes secrets provider that stores secrets within your cluster.

We never store any secrets you provide to the control plane in our infrastructure and instead rely on this secrets provider, so you can be confident that your secrets remain within your environment and are only accessed securely at runtime by the Catalyst Dapr Servers when they need to resolve a secret reference.

The available secrets providers are:

• Kubernetes Secrets (default)
• AWS Secrets Manager
• PostgreSQL (with automated data encryption)

See the Helm Chart Reference for the full set of secrets provider options.

Dependencies

Kubernetes

Catalyst Enterprise Self-Hosted is designed to run on Kubernetes 1.24 or later. It is packaged and distributed as a single Helm chart.

PostgreSQL

Features such as Managed Workflows, Agents and KV Store rely on PostgreSQL as a backing datastore. By default, a PostgreSQL instance will be installed by the Agent into your Kubernetes cluster as part of the installation process. However, this is not suitable for production workloads and we recommend using an external managed PostgreSQL instance for production deployments. Refer to the Helm Chart Reference documentation for configuration options to use an external PostgreSQL instance.

Kafka

Features such as Managed Pub/Sub rely on Kafka as a backing datastore. By default, a lightweight Kafka instance will be installed by the Agent into your Kubernetes cluster as part of the installation process. However, this is not suitable for production workloads and we recommend using an external managed Kafka instance for production deployments. Refer to the Helm Chart Reference documentation for configuration options to use an external Kafka instance.