Skip to main content

Installation

This guide walks you through a production HA installation. It assumes you have completed the Prerequisites.

Guided deployment

On-premise installations are performed together with DuoKey engineering. The commands below are illustrative of the reference flow; your delivery package includes the exact manifests and Helm values for your environment.

Installation at a glance​

Installation at a glance
1. Prepare cluster & namespaces
2. Deploy OpenBao (VMs)
3. Wire secrets · ESO to OpenBao
4. Deploy data tier
5. Bootstrap GitOps · ArgoCD
6. Deploy DuoKey app
7. Observability
8. Verify & first login

The reference deployment flow, from preparing the cluster through first login.

Phase 1 — Prepare the cluster​

Create the namespaces (projects) and apply baseline security:

# Application + platform namespaces
oc new-project duokey
oc new-project duokey-observability

# Label for pod anti-affinity / zone spreading is applied via the
# application manifests in later phases.

Confirm storage and ingress are ready:

oc get storageclass
oc get ingresscontroller -n openshift-ingress-operator

Phase 2 — Deploy OpenBao (external VM tier)​

On the dedicated OpenBao VMs, initialize an HA cluster with Raft integrated storage, then unseal and enable the Kubernetes auth method:

# On each OpenBao node (illustrative)
bao operator init # capture unseal keys + root token securely
bao operator unseal # repeat on each node to form the Raft quorum

# Enable Kubernetes auth so OpenShift pods can authenticate
bao auth enable kubernetes
bao write auth/kubernetes/config \
    kubernetes_host="https://<openshift-api>:6443"
Protect the unseal keys

Store unseal keys and the root token in a secure offline location (or use auto- unseal backed by your HSM). Loss of these prevents recovery of the secrets engine.

Phase 3 — Wire secrets (External Secrets Operator)​

Install ESO from OperatorHub, then connect it to OpenBao with a SecretStore and a ServiceAccount-based role:

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: openbao
  namespace: duokey
spec:
  provider:
    vault:
      server: "https://openbao.duokey.example.local:8200"
      path: "secret"
      version: "v2"
      auth:
        kubernetes:
          mountPath: "kubernetes"
          role: "duokey"
          serviceAccountRef:
            name: "duokey"

Secrets are then materialized on demand into tmpfs-backed Kubernetes Secrets via ExternalSecret resources (shipped with the application manifests).

Phase 4 — Deploy the data tier​

Provision PostgreSQL (HA) and Redis. Using a PostgreSQL operator in-cluster:

oc apply -f postgres-cluster.yaml # CloudNativePG / Patroni Cluster CR
oc apply -f redis-cluster.yaml # sharded Redis StatefulSet

Or point the application at the external PostgreSQL VM cluster via the connection string stored in OpenBao (recommended for the reference architecture).

Phase 5 — Bootstrap GitOps (ArgoCD)​

Install OpenShift GitOps, then register the DuoKey application repository so ArgoCD reconciles all subsequent changes:

oc apply -f argocd-application-duokey.yaml
argocd app sync duokey # initial sync

From this point on, all changes flow through Git — ArgoCD detects drift and keeps the cluster aligned with the declared state.

Phase 6 — Deploy the DuoKey application​

The application manifests deploy the Cockpit frontend and API backend with pod anti-affinity and the Ingress route:

# Typically reconciled by ArgoCD; shown here for clarity
oc apply -k manifests/duokey/overlays/on-prem
oc get pods -n duokey -o wide # confirm spread across nodes/zones

Phase 7 — Deploy observability​

oc apply -f victoria-metrics-stack.yaml -n duokey-observability
oc apply -f victoria-logs.yaml -n duokey-observability
oc apply -f grafana.yaml -n duokey-observability

Import the DuoKey Grafana dashboards (included in your delivery package).

Phase 8 — Verify & first login​

Run through the verification checklist:

# All pods Running and Ready
oc get pods -n duokey

# Ingress route resolves and serves TLS
oc get route -n duokey
curl -I https://cockpit.duokey.example.local

# Secrets are being injected (no plaintext on disk)
oc get externalsecret -n duokey

Health checklist

  • All application pods are Running and spread across ≥ 3 nodes/zones
  • OpenBao is unsealed and reachable from the cluster
  • PostgreSQL primary + replicas are healthy and replicating
  • ArgoCD shows the application as Synced / Healthy
  • Grafana dashboards are receiving metrics and logs
  • The Cockpit UI loads over HTTPS and you can authenticate

When all checks pass, hand the environment over to your operations team and continue to Monitoring and Backup & Disaster Recovery.

tip

Keep your initial OpenBao unseal keys, ArgoCD admin credentials, and the first admin account stored in your organization's privileged-access vault.