Operations
How to run and deploy Virtufin — from a laptop to a Kubernetes cluster. Pick the mode that matches what you are doing; the services and their contracts are identical in all of them. The normative contract lives in the deployment spec.
| Mode | Best for | Runtime |
|---|---|---|
| Native local | Day-to-day development, debugging | dapr run, .NET SDK |
| Helm | Direct/manual Kubernetes installs | Kubernetes + Dapr |
| Ansible | Production clusters | Kubernetes + Dapr |
The backend services share the same shape: an HTTP port for health checks and a gRPC port for all other traffic. The API Gateway is the only public face; Dapr is the only component that talks to the broker and state store (see Architecture).
Native local (deploy-local)
Runs the backend services natively via
Dapr (dapr run). No service containers —
Dapr manages its own sidecars, and the services run as local
processes.
Prerequisites
- Dapr CLI
initialized (
dapr init) - .NET SDK 10.0+
- Redis on
localhost:6379(Dapr state store and pub/sub)
Start the stack
git clone https://git.haenerconsulting.com/virtufin/deploy-local.git
cd deploy-local
# All backend services
./scripts/deploy_backend.sh
# Or individual services
./scripts/deploy_workmanager.sh
Stop
./scripts/undeploy_backend.sh
./scripts/undeploy_workmanager.sh
Ports and build settings live in .env. See the
deploy-local README
for the full variable table and the components/ Dapr definitions.
The docker-compose repo is archived; deploy-local is the local
path.
Kubernetes with Helm
The platform ships as a single chart, virtufin/virtufin, published
by the virtufin/helm
repo to a private Gitea Helm registry. Each service can be enabled,
disabled, and versioned independently.
Prerequisites (asserted, never installed by the chart)
- Kubernetes 1.27+
- Dapr installed on the cluster
- A Dapr state store and pub/sub: Redis/Valkey by default, or any
other Dapr provider (
stateStore.type/pubsub.typeplus itsmetadata; see the chart README's "Other providers") - A Harbor image pull secret
Install
The registry is private, so pass credentials when adding it:
helm repo add virtufin \
--username <user> --password <token> \
https://git.haenerconsulting.com/api/packages/virtufin/helm
helm repo update
helm upgrade --install virtufin virtufin/virtufin \
--namespace virtufin --create-namespace \
-f values.yaml
Keep credentials, API keys, and Redis hosts in a values.yaml
rather than on the command line. The settings you will normally
set:
| Value | Purpose | Default |
|---|---|---|
api.image.tag |
API Gateway image tag | pinned by the release |
workmanager.image.tag |
WorkManager image tag | pinned by the release |
workmanagerRuntime.image.tag |
WorkManager Runtime image tag | pinned by the release |
stateStore.redis.host / pubsub.redis.host |
Redis/Valkey host (Redis providers only) | redis-primary.redis.svc.cluster.local |
api.auth.keys |
API keys (name -> key) |
{} (auth disabled) |
api.ingress.enabled / api.ingress.host |
Public gRPC endpoint | true / api.virtufin.com |
imagePullSecrets |
Harbor pull secret | regcredharbor |
workmanager.nugetAuth |
Gitea package credentials for worker code sources | — |
See the Helm chart README for the complete values reference, ingress/auth detail, and the Harbor secret setup.
Workload placement
The chart uses two Kubernetes workload types:
| Service | Workload | Scaling |
|---|---|---|
| API Gateway | Deployment |
api.replicaCount (default 3) |
| WorkManager | DaemonSet |
One pod per eligible worker node |
| WorkManager Runtime | DaemonSet |
One pod per eligible worker node |
WorkManager and its Runtime default to DaemonSets because their capacity is meant to follow the worker nodes: a new eligible worker gets a pod automatically, and draining a worker removes its pod. The default affinity excludes control-plane/master nodes and adds no control-plane tolerations.
A manager can use a fixed replica count instead, for example on a constrained or development cluster:
workmanager:
workloadKind: Deployment
replicaCount: 3
workmanagerRuntime:
workloadKind: Deployment
replicaCount: 3
replicaCount is only rendered when workloadKind is Deployment.
Changing an existing manager between Deployment and DaemonSet
changes the Kubernetes resource kind, which cannot be updated in
place — the old object must be deleted first (the Ansible path below
does this automatically).
Kubernetes with Ansible (recommended)
Production clusters are owned by Ansible. The
k3s.common.virtufin_backend role in
kubernetes/k3s-common
pins the chart version and image tags, renders api.auth.keys from
the cluster .env, applies the chart, and verifies the result. The
per-service deploy-*/undeploy-* scripts and CI workflows were
retired so there is a single writer for the release.
Prerequisites — install these roles first:
install_dapr(thecomponents.dapr.ioCRD anddapr-operator)install_redis(theredis-primaryService)
Deploy
From the cluster repo (kubernetes/cluster-medusa):
cd cluster-medusa
./install_virtufin_backend
The role:
- Asserts the Dapr, Redis, and Traefik prerequisites.
- Downloads the pinned
virtufin-<version>.tgzfrom the registry with auth (the index points chart URLs at a different Gitea hostname, so a plainhelm repo addwould strip credentials). - Applies the chart into namespace
virtufin. - Removes any pre-DaemonSet manager Deployments before the chart creates the DaemonSets (a one-time short interruption).
- Waits for the API Deployment and both manager DaemonSets, then asserts the running images match the pinned tags.
Override a value
./install_virtufin_backend \
--extra-vars virtufin_backend_api_image_tag=0.8.2
Uninstall
./uninstall_virtufin_backend
Secrets come from the cluster .env via group_vars:
VIRTUFIN_REGISTRY_USER/TOKEN (Gitea packages),
VIRTUFIN_DOCKER_USER/TOKEN (Harbor robot), and
VIRTUFIN_API_AUTH_KEYS (a JSON name -> key map). The key map
must be non-empty — the API's api-auth health check crash-loops
the pod without at least one key.
Verify
kubectl -n virtufin get deployment,daemonset,pods -o wide
kubectl -n virtufin get events --sort-by=.lastTimestamp
helm -n virtufin status virtufin
A healthy production release:
deployment/api—3/3ready.daemonset/workmanager— one ready pod on every worker node.daemonset/workmanager-runtime— one ready pod on every worker node.- No
workmanagerDeployment remains after the DaemonSet migration.
Each pod runs 2/2: the service container plus its Dapr sidecar.
Benchmarks
The WorkManager benchmarks run nightly (02:00 UTC) and on demand against their own deployments on medusa. The report of the latest run, compared with the rolling median of earlier runs, is at benchmarks.docs.virtufin.com: engine overhead (each engine called directly, without API, Redis or actor), pipeline (publish to worker to subscriber at a fixed rate: throughput and latency) and pipeline saturation (the same, publishing as fast as possible), per engine. A regression opens an issue in virtufin/benchmarks, which closes after 3 healthy runs. The harness is described in the workmanager repo.
The pipeline series run once per backend variant, so the report compares
the backing services side by side. A variant is the same stack (same image
pins as the main backend, one replica each) in its own namespace with its own
broker. Name and namespace say both backing services: the variant is
<pubsub>-<state>, its namespace virtufin-benchmark-<pubsub>-<state>,
labelled virtufin.com/benchmark-backend=<pubsub>-<state>:
| Variant | Namespace | Pub/sub | State store |
|---|---|---|---|
redis-redis |
virtufin-benchmark-redis-redis |
pubsub.redis on its own Redis |
state.redis on the same Redis |
nats-redis |
virtufin-benchmark-nats-redis |
pubsub.jetstream on its own single-node, memory-only NATS |
state.redis on its own Redis |
nats-postgres |
virtufin-benchmark-nats-postgres |
pubsub.jetstream on its own single-node, memory-only NATS |
state.postgresql on its own PostgreSQL |
nats-postgres is a stack without any Redis. Next to nats-redis it shows
what the state store alone costs, since both use the same pub/sub.
The virtufin_backend role deploys them from virtufin_benchmark_variants
(one pubsub/state pair per variant) with the rest of the backend. For a
variant with NATS as pub/sub it also creates
the NATS stream (virtufin, in memory, one subject <root>.> per topic root),
because the Dapr component publishes into a stream but creates none: a new
topic root must be added to virtufin_benchmark_nats_stream_roots. Until then
no publish to it is stored: the API answers success: false (it raises no
gRPC error) and logs nats: no response from stream. JetStream also drops a
message whose id it saw in the stream during the stream's duplicate window
(virtufin_benchmark_nats_stream_duplicate_window, kept at JetStream's minimum
of 100 ms), on any topic, and Dapr sends the CloudEvent id as that id. The
publish still answers success: true. So on NATS a worker's output must never
carry its input's id: published within the window, it is dropped as a second
copy of the input.
For a variant with PostgreSQL as state store the role deploys a single
PostgreSQL (postgres-benchmark) that keeps nothing: no volume, and fsync,
synchronous_commit and full_page_writes off
(virtufin_benchmark_postgres_config), so the numbers measure the store and
not the node's disk. Like the benchmark Redis and NATS it asks for no password:
the role virtufin reaches the database virtufin without one from the pod
network (virtufin_benchmark_postgres_client_cidr) only. It has no
NetworkPolicy, because the cluster enforces one for a new pod only about 0.3 s
after the pod starts, and a Dapr sidecar pings its state store sooner and exits
when the connection is refused. Two things differ from Redis on this store (see
the chart's
README):
QueryState needs API 0.15.17 or later, and an expired key stays in query
results until Dapr's hourly cleanup.
Each variant keeps its own history and regression baseline, so a slower backend never counts as a regression of a faster one.