Skip to content

UI Deployment Topologies

Cloud-Native DCS does not impose a single way to split editing, testing, and production. The product gives you a small set of interfaces. The deployment instance composes them into the topology that fits your organization.

This page catalogs the supported configurations, what changes between them, and which is the recommended starting point.

What the product guarantees

Regardless of topology, the product gives you:

  • One UI binary, two run modes. The same dcs-gateway runs as an in-cluster pod (multi-user, service-account auth) or as a standalone tool on an engineer's laptop (single-user, kubeconfig auth, static assets bundled in). Both speak to the same CRDs, render the same forms, and produce the same ChangeRequest artifacts.
  • One CRD set. The same engineering and operational CRDs apply everywhere. Topology does not change the schema.
  • One promote pipeline. "Promote" always produces a ChangeRequest whose backend can be configured per environment: direct apply, Git PR via the configured repository, or in-cluster review queue.
  • Configurable admission enforcement. Helm values turn admission policies on per-environment, naming which service accounts may write which CRDs. The mechanism is the same, and the policy is yours.

What changes between topologies is where the UI runs, which clusters hold which environments, and which writes are permitted where.

Topology spectrum

A. Single cluster, single namespace

Everything in one place: pod-mode UI, all CRDs, all data, no separation. Useful for evaluation and demos.

  • Promote has nothing to promote against. The UI applies changes directly.
  • Admission enforcement typically off.
  • Audit still works — AuditRecord captures every change — but there is no review gate.

Not appropriate for production. Documented because it is the shortest path to "is this thing real?" in an evaluation.

Two namespaces in one cluster: dcs-dev and dcs-prod. Pod-mode UI in both. RBAC restricts who can write where. Flux reconciles dcs-prod from a Git repo, and dcs-dev accepts direct UI writes.

  • Promote computes the diff between dcs-dev and the Git source for dcs-prod, opens a ChangeRequest, captures e-signature, and on approval merges to Git. Flux reconciles dcs-prod shortly after.
  • Admission enforcement rejects writes to engineering CRDs in dcs-prod from anyone but the Flux service account and the break-glass admin role.
  • Audit is complete on both sides — direct writes in dcs-dev, reconciled writes in dcs-prod.

This is the recommended starting point. It exercises every product interface (laptop mode, pod mode, ChangeRequest, admission policy, Flux reconciliation), avoids the cost of a second cluster, and scales up to topology C without changing the model.

C. Two clusters, dev and prod

Separate clusters: a dev cluster the engineering team owns, and a prod cluster the platform team owns. Pod-mode UI in both. Flux reconciles prod, and dev is direct-write.

  • Promote has the same shape as topology B, but the diff source is the dev cluster's API and the target is the prod repo.
  • Admission enforcement in prod is identical to topology B.
  • Operational isolation is stronger. A dev-cluster outage cannot affect prod, and a prod incident cannot disrupt engineering work.
  • Cost is roughly twice the infrastructure of topology B.

Appropriate when regulatory or organizational constraints require hard isolation between dev and prod control planes, or when the dev environment is shared across many engineers and runs continuously.

D. Laptop-mode UI as the developer workstation

Each engineer runs the UI on their own laptop, pointed at a personal sandbox cluster (kind, k3d, Docker Desktop, or a remote dev cluster they have credentials for). Prod runs pod-mode UI under strict GitOps.

  • Promote target is configured by the engineer's local UI and always points at the prod repo. The engineer's sandbox is private until they Promote.
  • Admission enforcement in prod is identical to topology B.
  • Per-engineer isolation is total. Two engineers cannot collide on the same dev resource because they have different dev clusters.
  • Cost is near zero per engineer. The laptop is the dev environment.

This is the topology that most cleanly mirrors a "personal copy of DeltaV on the engineer's workstation" experience without the licensing cost or operational overhead. Recommended as a power-user option once the team is comfortable with the model in B or C.

Running the laptop UI

The single dcs binary embeds the gateway UI, so no extra install step is required. Point it at any kubeconfig context with the CRDs installed and the gateway runs locally with kubeconfig-based auth:

# default kubeconfig + current-context, opens a browser at http://localhost:8200
dcs ui

# specific kubeconfig and context (kind / k3d / remote dev cluster)
dcs ui --kubeconfig ~/.kube/dev --context kind-dev

# fixed port, suppress auto-open (useful for SSH-forwarded UIs)
dcs ui --port 8200 --no-browser
Flag Default Purpose
--kubeconfig <path> $KUBECONFIG/~/.kube/config Which kubeconfig file to read
--context <name> current-context Which context inside that kubeconfig
--system-namespace <ns> discovered Where the DCS operators run — see below
--port <n> 8200 → ephemeral Local listen port; falls back to a kernel-assigned ephemeral port if 8200 is busy
--bind-address <ip> 127.0.0.1 Listen address; the default keeps the UI off the LAN
--no-browser off Print the URL but do not auto-open a browser

An in-cluster gateway reads its own namespace from its service account. Laptop mode has no such file, so on startup it finds the operators by asking the cluster: the chart labels everything it installs app.kubernetes.io/part-of: cloud-native-dcs, and the namespace those workloads are in is the one the health rollup queries. The startup banner states which namespace it settled on. Pass --system-namespace when the cluster carries more than one install, or when nothing is installed yet and you want the health view pointed somewhere specific anyway.

The laptop-mode gateway runs with --auth-mode=none baked in and treats the local user as a cluster admin. Cluster authorization is whatever your kubeconfig grants. The same kubectl auth can-i rules apply, because the gateway uses your kubeconfig credentials when talking to the API server.

Pod-mode is unchanged: the in-cluster gateway still uses its ServiceAccount (auto-detected via /var/run/secrets/kubernetes.io/serviceaccount/token), the same UI assets, and the same forms.

One binary, two run modes: dcs ui serves the same System app from the engineer's laptop against a sandbox context, and the plant it renders is the real cluster the kubeconfig points at.

E. Hybrid combinations

Topologies B, C, and D are not exclusive. Common combinations:

  • B + D — single shared cluster with dcs-dev and dcs-prod namespaces, plus engineers running laptop-mode UI against either the shared dev namespace or their own kind cluster.
  • C + D — separate dev and prod clusters, plus engineers running laptop-mode UI for prototyping before pushing to the shared dev cluster.

The product does not need to know which combination you have chosen. The same binaries and CRDs work in all of them.

F. Filesystem authoring (your own files in Git, no cluster)

Topologies A–E are all interfaces to the Kubernetes API. Every editor Save writes to a cluster, and Git is reached only later, at Promote. Topology F is different. The editor authors directly against YAML files in a local working tree, and you commit and push them with your own Git tooling. There is no cluster in the loop while you author.

# open the visual editors against the YAML tree in ./plant
dcs edit ./plant

# current directory, fixed port, no auto-open
dcs edit --port 8200 --no-browser
  • No cluster required. dcs edit runs entirely offline. The working copy is a Git working tree, so local branch / diff / revert / offline all work with the tools you already use.
  • The editor stays Git-agnostic. It never stages, commits, pushes, or reasons about branches, remotes, or credentials. Its only job here is "a visual editor for the YAML files you happen to keep in Git." You drive Git with the CLI, VS Code, or gh.
  • Save writes files. Each Save serializes the edited resource back to its YAML file (existing files keep their location, and brand-new resources land under <dir>/<namespace>/<group>/<kind>/). Multi-document files are preserved.
  • Live-equipment features degrade gracefully. Runtime tag values, diagnostics, and historian trends need a cluster. In file mode they are unavailable and the UI signposts a banner. Connect with dcs ui to use them.
  • Review happens in your Git tooling. The semantic diff that the Promote UI shows is available off-product as dcs diff so you do not lose domain-level review in a GitHub PR. The 21 CFR Part 11 review-of-record stays at Promote (see below).

This slots in alongside A–E, and it replaces none of them. Author against files in F, then push to a dev cluster (B/C/D) and Promote to prod when the change is ready.

Reviewing changes with dcs diff

When you review a file-mode change in your own Git tooling, the raw diff is YAML text (enterpriseName: pharma-corp → pharma-corp-eu). dcs diff renders the same semantic diff the gateway Promote UI shows, using the gateway's own renderers:

# semantic diff between two revisions you have on disk
dcs diff ./old/plant-site.yaml ./new/plant-site.yaml

dcs diff is informational only. It creates no audit record and no electronic signature, and it is not the review-of-record. Its exit status is 0 when the files are semantically identical and 1 when they differ, so it composes in scripts and as a Git difftool.

Decision matrix

Concern A: single ns B: dev/prod ns C: two clusters D: laptop F: files
Setup cost Lowest Low Moderate Lowest per engineer None (no cluster)
Operational isolation None Namespace-level Cluster-level Per-engineer Per-working-tree
Suitable for production No Yes Yes Dev only Authoring only
GitOps enforcement Optional Recommended Required Required (prod side) N/A until pushed
Best for Evaluation, demos Most pharma sites Multi-team or regulated isolation Solo engineers, prototyping Offline / Git-first authoring

What the deployment instance owns

These are not product decisions. They are configured per deployment, typically through Helm values, RBAC, and the Flux configuration in your deploy repository:

  • Which topology above (or hybrid) you are running.
  • Which Kubernetes service accounts may write which CRDs in which namespaces (i.e., the admission policy content).
  • The Git repository that "Promote" targets, per Site or Area.
  • The approval routing graph (single approver, two-person rule, departmental sign-off).
  • Concurrent-edit handling — the product does not ship a lock CRD, but you may layer one if your team requires checkout-style editing.
  • The break-glass role and its audit-severity level.

If the product appears to be making one of these decisions for you, that is a bug. File an issue.