Skip to main content

Reference Architecture

The DuoKey on-premise deployment is a highly available (HA), production-grade hybrid architecture. It combines an OpenShift cluster for containerized application workloads with a dedicated VM infrastructure for core data, CI/CD, and secret management — all backed by a comprehensive backup and restore plan.

DuoKey on-premise OpenShift reference architecture

At a glance: the OpenShift cluster (application workloads), the VM infrastructure (secrets, data, CI/CD), and the backup & restore plan.

The same design as a logical flow:

On-premise reference architecture
Users / Office / M365
443
OpenShift Ingress RouterTLS termination · load balancing
OpenShift cluster — application workloads
Cockpit Frontendui · SPA
internal
Cockpit APIKMS · DKE · KMIPACME/EST · XKS
PostgreSQL clusterprimary + replicas
Redissharded cluster
OpenBaoRaft · secrets on VMs
DuoKey MPC KMSoptional · 3+ node cluster
Securosys HSMoptional hardware
ArgoCD (GitOps)deploys frontend + API
VictoriaMetrics · VictoriaLogsGrafana · scrape / logs
Edge / proxyFrontend (ui)APIDataSecrets / key custodyGitOps / observabilityOptional

Office clients reach the OpenShift Ingress Router over 443; it fronts the Cockpit frontend and API, which talk to the data tier, OpenBao, and key custody. ArgoCD deploys the workloads and VictoriaMetrics observes them.

Designed for adaptation

The architecture below describes the recommended reference design. Storage, ingress, and object-store choices can be adapted to your environment (bare metal, VMware, OpenStack, or Nutanix) — your DuoKey representative will help you tailor it.

No Kubernetes? See the VM-only model

If your site has no OpenShift/Kubernetes platform, DuoKey also runs on a VM-only topology — the same components on plain virtual machines, with single-site HA behind a load balancer and multi-site HA via a Geo load balancer.

Core components​

1. Centralized secrets — external OpenBao​

  • Standalone isolation — OpenBao (the Linux Foundation's community-driven, open-source fork of Vault) runs externally on dedicated virtual machines, configured in an HA setup with a Raft consensus storage engine.
  • Secure auth handshake — the OpenShift cluster runs the External Secrets Operator (ESO). When an application pod starts, ESO authenticates with OpenBao via the Kubernetes Auth Method using the pod's ServiceAccount token.
  • Dynamic, non-persistent injection — credentials, database connection strings, and cache keys are fetched on demand from OpenBao and injected as native Kubernetes Secret primitives mapped to ephemeral, in-memory (tmpfs) volumes. No raw secret is ever written to cluster storage or hardcoded into Git.
Key custody options

Key custody defaults to the built-in Software Vault. Where a deployment needs it, you can add the DuoKey MPC KMS — DuoKey's own multi-party-computation cluster (3+ nodes; no single node ever holds a complete key) — or a Securosys HSM for a hardware root of trust. See Prerequisites → Key custody for details.

2. Continuous delivery & source control — GitLab​

  • Source & registry hub — code repositories, CI pipelines, and custom base container images reside on a self-hosted GitLab instance running on a standalone VM. This can be replaced by GitLab's SaaS offering where policy allows.

3. Persistent database — PostgreSQL cluster​

  • Database high availability — PostgreSQL runs under a cloud-native database operator (such as CloudNativePG or Patroni), maintaining a primary read-write node and multiple hot-standby replicas.

4. Platform & application orchestration​

  • OpenShift control plane — leverages built-in OpenShift Operators to manage lifecycle, networking, routing, and platform upgrades automatically.
  • Ingress & load balancing — the built-in, highly available OpenShift Ingress Router handles edge traffic, terminates TLS, and load-balances across the frontend pods. Internal routing between the frontend and the API backend uses native headless and ClusterIP Kubernetes Services.
  • HA topology — all frontend and backend pods use explicit pod anti-affinity rules, guaranteeing workloads are spread across different worker nodes and separate availability zones (AZs).
  • GitOps reconciliation — the in-cluster OpenShift GitOps (ArgoCD) operator continuously tracks branches in GitLab. When application manifests change, ArgoCD detects drift and pushes updates cleanly to the targeted namespaces.

5. Persistent data tier​

  • Stateful orchestration — database and caching engines are deployed as StatefulSets to preserve network identities and block-device mappings across restarts.
  • Storage provider — persistence is provided by OpenShift Data Foundation (ODF) or a CSI driver appropriate to your platform (e.g. OpenStack Cinder, vSphere CSI).
  • Cache high availability — Redis is configured as a multi-node sharded cluster with automated master/replica failover.

6. Observability — VictoriaMetrics & VictoriaLogs​

  • Metrics — lightweight vmagent instances scrape performance endpoints and route them to a distributed VictoriaMetrics stack (vmstorage, vminsert, vmselect).
  • Logs — Vector agents harvest stdout/stderr and forward them to VictoriaLogs for structured search.
  • Dashboards — an integrated Grafana connects to both as data sources for operational dashboards.

Request & data flow​

Request & data flow
User / Client
HTTPS request
Ingress RouterTLS-terminated · load-balanced
internal ClusterIP service
Cockpit Frontend
forward request
Cockpit API
fetch secret · K8s auth, on demand
OpenBao (VMs)returns short-lived credential (tmpfs)
query / persist data
PostgreSQL (HA)returns result
response rendered back to user
Rendered result

A user request is TLS-terminated at the Ingress Router, routed through the frontend to the API, which fetches a short-lived secret from OpenBao and reads or writes PostgreSQL before the response is rendered back.

Network & availability zones​

  • Application pods are distributed across at least three worker nodes spanning separate availability zones / failure domains.
  • The dedicated VM tier (OpenBao, PostgreSQL, GitLab) is segmented onto isolated networks, ideally with a separate, hardened VLAN for any HSM.
  • All inter-component traffic is encrypted in transit (TLS); OpenBao is reached only over mutually authenticated channels.

See Prerequisites → Network for the concrete network and firewall requirements.