Skip to main content

Deployment & Upgrades Deep Dive

The Topologies deep dive designed a shape: a three-node NATS cluster, east, carrying the ORDERS stream. This chapter takes that exact cluster and runs it in production.

Topologies covered the shapes: one server, a cluster, a super-cluster, leaf nodes. This chapter covers the operations that turn a shape into a running system. Those operations are the resources a node needs, the manifests that stand it up, the SIGHUP that reloads its config without dropping a connection, the lame-duck mode that upgrades it without losing the stream, and the systemd flags that restrict its access.

This is the runbook rather than the theory. Each page names the mechanism, gives the exact command or manifest you run, and links the why out to the chapter that covers it.

By the end you'll have​

A production runbook for the same Acme ORDERS cluster you've followed through every other Learn chapter:

  • A sizing baseline for the workload: the four resources a node spends (CPU, memory, disk, file descriptors), and how an R3 stream counts against the ORDERS account limits.
  • The cluster running on Kubernetes as a three-replica StatefulSet with pods nats-0, nats-1, nats-2 (the same n1-east, n2-east, n3-east cluster you designed in Topologies; the Kubernetes page spells out that mapping), with the ORDERS stream and the shipping and analytics consumers declared as CRDs.
  • The ability to change config live: split into per-account and per-region includes, reloaded with a SIGHUP, with zero downtime and no client reconnect.
  • A safe rolling upgrade procedure that walks a new server version through nats-0..2 while the R3 ORDERS stream stays available and clients stay connected.
  • A hardened cluster: TLS on every link, the ACME credentials mounted, a locked-down systemd unit, and the monitor port closed to the internet.

Who this is for​

You're an operator standing the cluster up for real. You've read the Topologies deep dive and know the shapes, and you've skimmed the JetStream and Security deep dives. This chapter reuses the ORDERS stream and the ACME operator rather than re-introducing them.

This chapter is deliberately the runbook half. It divides the work with four sibling chapters, and each owns part of it:

  • Which shape to deploy is Topologies. This chapter assumes the three-node ORDERS cluster shape is already decided.
  • How Raft and replication work underneath is Clustering. This chapter triggers a leadership transfer during an upgrade; it doesn't explain how Raft elects a leader.
  • The auth model (operators, accounts, users, JWTs) is Security. This chapter mounts the credentials and turns on TLS; the model is taught there.
  • What to watch once it's live is Monitoring. This chapter sets up the cluster; monitoring watches it.

If a sentence here would be at home verbatim in one of those four, it belongs there, and this chapter links to it instead.

How to read it​

Each page introduces at most two new concepts and carries the same cluster forward. You size it, deploy it, edit its config live, upgrade it, and harden it. The node names (n1-east/n2-east/n3-east), the ORDERS stream, the order-svc publisher, and the ACME operator stay fixed throughout, so you keep a mental picture of one Acme system getting production-ready rather than a new example each time.

Every page covers only the configuration keys this deployment needs. The full set of server configuration options lives in Reference → Configuration; each page points there for the exhaustive knob list.

Map​

PageWhat you learn
Deployment & UpgradesWhat this chapter operates and the order of the runbook
Sizing & resourcesThe four resources a node spends, and how an R3 stream counts against account limits
KubernetesStand the cluster up as a StatefulSet with the NATS Helm chart, and declare streams as CRDs
Config managementSplit config into includes and reload it live with a SIGHUP: no downtime, no reconnect
Rolling upgradesUse lame-duck mode and the right upgrade order to roll a new version through the cluster
HardeningTLS on every link, mounted credentials, and a locked-down systemd unit
Where to go nextThe production checklist and a map of what's beyond running the cluster

Prerequisites​

You'll need:

  • A running three-node ORDERS cluster, or the willingness to stand one up while you read. The Topologies deep dive builds it step by step.
  • The nats CLI installed and pointed at the cluster, for the inspection commands (nats account info, nats server info, nats stream info) that anchor each page.
  • For the Kubernetes pages, a cluster you can kubectl against and helm installed. The NATS Helm chart and the NACK controller are the canonical path this chapter follows.

Open a terminal and turn to Sizing & resources.

See also​