Skip to content
antalos

Zammad · Architecture

The chart runs two NGINX replicas and two Rails replicas with anti-affinity. Scheduler and WebSocket each have one replica. PostgreSQL uses two CNPG instances; Redis has two data members and a third Sentinel voter; Elasticsearch has two data/master members and an RTX master-only voter. Garage supplies object storage, while chart initialization jobs prepare the application.

Component boundaries

Zammad · component flow
  1. Tickets
    • Browser / email channels
    • Traefik HTTPS
  2. Support platform
    • 2 NGINX / 2 Rails
    • 1 scheduler / 1 WebSocket
  3. Data and search
    • PostgreSQL pair / Garage objects
    • Redis · 2 data + 3 Sentinels
    • Elasticsearch · 2 data + 1 voter
Arrows show the main flow between responsibility groups. Parallel boxes are related components, not interchangeable replicas; the text below defines their individual failure and recovery behavior.

State and recovery contract

Back up PostgreSQL, Garage objects, and application credentials. Elasticsearch indexes can be rebuilt from authoritative application data using the upstream procedure, but search remains degraded until rebuilding completes. Preserve identity and email-channel configuration stored in the database.

Availability and failure behavior

Availability classification: Partially HA: paired HTTP tiers and data services, with singleton real-time/background roles and Redis/search caveats.

This is an interpretation of the checked-in configuration, assuming the declared replicas are healthy, separated as intended, and their required dependencies are reachable. It is not a live-health result or a completed failure drill.

What supplies redundancy

Component Declared layout Mechanism
HTTP 2 NGINX + 2 Rails replicas Separate-node placement leaves a serving web path.
Async / real-time 1 scheduler + 1 WebSocket Feature recovery waits for the single process to restart.
PostgreSQL 2 CNPG members Preferred synchronous policy and stable read/write Service.
Redis 2 data + 3 Sentinels Intended discovery/election across main workers and RTX.
Elasticsearch 2 data/master + 1 master-only member Election redundancy is distinct from per-index shard replication.
Attachments External Garage objects A shared dependency even if ticket metadata survives.

How a failure is handled

A new HTTP request can reach a surviving Rails/NGINX pair once routing converges. Database and Redis primary changes require separate promotion/election and reconnection. Losing scheduler or WebSocket interrupts their features until restart even while the main ticket page loads. Search also needs the relevant shards on surviving data nodes.

Failure scenarios

Failure Expected behavior and remaining dependency
One main worker One web path and one member of each paired data tier can remain with two voters. Email polling/background tasks or real-time updates can pause depending on singleton placement. Test attachment retrieval separately from ticket-list rendering.
RTX worker only Removes the third Sentinel and the master-only Elasticsearch member. Two main-worker voters remain if correctly connected; no further independent failure is covered.
A second failure before recovery Outside the stated single-failure envelope; assess remaining data copies, quorum, endpoints, and capacity before further maintenance.

An RTX worker VM failure is not the same as an RTX Proxmox host failure. The latter also removes its control-plane VM and the configured API address. Read the physical failure-domain explanation before making a whole-host HA claim.

Upgrades and voluntary maintenance

Chart init/migration Jobs gate the upgrade. PDB/paired HTTP replicas do not guarantee compatible schema operation or continuous scheduler/WebSocket service. Keep initialization status separate from current HTTP readiness.

What prevents a stronger HA claim

Redis persists role changes and data-side Sentinel topology on each existing PVC. Startup consults Sentinel before rejoining; first migration of an existing dataset requires agreement from two voters. Verify promotion and former-primary rejoin before asserting automatic recovery. Protected Sentinel listeners require matching credentials and working client discovery authentication. Search HA also requires actual replica-shard allocation, which is not established by the three master-eligible processes.

What would improve the availability contract

Establish Redis election/rejoin correctness and shard-copy evidence, protect Garage, and assess whether the deployed version supports replication of scheduler/WebSocket roles. Record email-to-ticket, reply, attachment, and search behavior through one-node loss.

These are operational/design requirements, not changes made to the deployment by this documentation. The shared availability reference explains election, replication, durability, recovery time, and shared dependencies; the manifest links below identify this service’s source.

Configuration ownership

apps/zammad/ owns this service’s Kubernetes resources. Hostnames, addresses, versions, node names, and volume sizes belong in apps/variables.yaml. Runtime settings stored in a product database need that product’s backup and administration procedure.

Continue

Read the deployment guide for dependency order, initial credentials, and integration work. The official documentation explains the upstream product; the topology above describes this repository.