Skip to main content

High availability

A Knocknoc deployment has three parts: the Server (web app), its Database (PostgreSQL), and one or more Orchestration Agents. How you run the first two decides your availability; the Agents are resilient by design (see below).

One thing makes Knocknoc forgiving here: a Server outage does not revoke access. Agents keep enforcing existing grants and reconnect on their own, so a short outage during maintenance or failover is harmless. You do not need zero-downtime rolling upgrades to stay safe.

Choosing a topology

These are example deployments, not fixed products. The web tier, the database, and the load balancer are independent choices, so mix them to suit your environment. Web nodes can run hot/hot or hot/cold. The database can live on a web node, on a dedicated host, or on a managed service (DBaaS). Replication is optional. The patterns below are common starting points, not the only supported ones.

Topology Web tier Database Best for
Single node One host Local, on the same host Smaller deployments, or where host-level failover is enough
Shared-primary Multiple, behind a load balancer On a web node, exposed to the others Growing from one node without separate DB infrastructure
Multi-node Multiple, behind an external LB/WAF Dedicated host or DBaaS Keeping the database managed independently of the web tier
All-in-one One host, with a local reverse-proxy Agent Local Isolated "in a box" deployments needing in-line HTTP/TCP protection

Single node

Web app and PostgreSQL on one host. PostgreSQL is local only and not externally reachable. Simple to run and the default after a standard install. Scale it vertically.

Single node topology

Shared-primary

Several web apps share one database that runs on (and is exposed from) one of the web nodes. A load balancer spreads web traffic across the nodes; run them hot/hot or hot/cold as you prefer. This is the natural next step from a single node: Knocknoc can expose its existing local database without you provisioning separate infrastructure. Add a replicated standby (shown in the diagram) for database failover, or point the nodes at a DBaaS instead. Replication and the standby are optional.

Shared-primary topology

Multi-node

Several web apps run against a single database backend that lives off the web tier, on a dedicated host or a managed service (Amazon RDS, Google Cloud SQL, Azure Database, Digital Ocean, Heroku, and similar). An external HTTP load balancer or WAF spreads web traffic and can fail over on health or performance; run the nodes hot/hot or hot/cold. Keeping the database separate lets you manage and scale it independently of the web tier, and lean on your provider's database HA if you use a managed service.

Multi-node topology

All-in-one with reverse proxy

Web app, database, and a local Agent in reverse-proxy mode on one host. The Agent provides in-line HTTP/TCP protection in front of a protected app while also orchestrating external systems, host firewalls, or cloud control layers. A self-contained way to drop Knocknoc into an isolated environment.

All-in-one reverse-proxy topology

Agent high-availability

Agents are resilient without special configuration:

  • Deploy them next to what they orchestrate. Agents do not need Server-to-Agent connectivity; they subscribe to the Server for instructions, so place them alongside the assets they manage. See the Agent documentation.
  • One Agent connects to every web node. An Agent is multi-server aware, so point a single Agent at all of your web nodes to keep logins applied promptly. You do not run one Agent per Server.
  • Run several Agents for redundancy. Where multiple Agents run, every Agent receives each grant job, so grant and revoke still happen if one Agent is down.

Setting up multiple web nodes

To go from a single node to a shared-primary deployment, expose the existing database, then add web nodes that connect to it.

1. Expose the database on the primary

Run knocker exposedb --init on the primary host. It binds PostgreSQL to 0.0.0.0:5432, creates a user with a random password, links that user to your existing database using the connection string from your Knocknoc config, and prints the connection string to use on the other nodes. (You can also configure PostgreSQL for external access by hand if you prefer; exposedb just does it for you.)

$ sudo /opt/knocknoc/knocker/knocker exposedb --init

Copy the connection string from the output; you will need it on each secondary node.

2. Allow-list the secondary nodes

External access is denied until you allow each source IP. Add the secondary web nodes (and any other trusted sources); list or remove entries as needed.

$ sudo /opt/knocknoc/knocker/knocker exposedb --add "203.0.113.7/32"
$ sudo /opt/knocknoc/knocker/knocker exposedb --list
$ sudo /opt/knocknoc/knocker/knocker exposedb --remove "203.0.113.7/32"

A node that is not on this list cannot connect to the database. Run knocker exposedb --help for all options, including --conn for a non-default connection string.

3. Install the web nodes

Install Knocknoc on each secondary node. Bind it to a reachable address (for example 0.0.0.0:8756), then at the database question choose option 3 to connect to the existing remote Knocknoc database (option 1 is a new local database, option 2 is a fresh external database). If the node sits behind a load balancer or reverse proxy, set TrustedForwarders to that proxy's address so client IPs are read correctly; the default is safe when there is no proxy in front, and you can change it later:

Enter IP and port to listen on (default: 127.0.0.1:8756): 0.0.0.0:8756

If you're running behind a reverse-proxy, set the trusted forwarders.
Default is safe if not. You can adjust this later, see Server Install on https://docs.knocknoc.io
Enter TrustedForwarders (default: 127.0.0.1/32): 192.168.100.1/32

Knocknoc stores its data in PostgreSQL, and you can choose how to configure the database.
You have three options:
  1) Use a local PostgreSQL installation (default)
  2) Use a new external or preconfigured PostgreSQL database
  3) This Server is a web node only, use pre-existing external Knocknoc database

Option 1, 2, or 3? (default is 1): 3

Enter pre-existing external Knocknoc database connection string: postgres://knocknoc:[email protected]:5432/knocknoc

If a node cannot reach the database, confirm its IP has been added with exposedb --add on the primary.

4. Front the nodes with a load balancer

Distribute inbound traffic across the web nodes with a load balancer. You can set up HAProxy locally with Knocker or use your own LB/WAF. Persistence is normally handled by a load-balancer cookie, as is standard practice.

Health-check each node on the /_status route (for example https://example.knocknoc.io/_status). This is required, not optional: the route reports whether a server is up and whether its version is in step with the database, so the load balancer can pull a node that is down or out of date out of rotation on its own. It is also what makes the upgrade process below safe.

Upgrading servers in an HA deployment

When multiple servers share one database, upgrade them one at a time with only one server serving traffic during the change. The first server you upgrade updates the shared database to the new version. Older servers still in rotation are then out of step with that database, which risks errors. The steps below avoid that.

Server downtime during an upgrade is a few seconds at most, and access to protected resources is unaffected throughout.

1. Check server status and settings

Server settings in the admin portal

In the admin portal, confirm every server sharing the database is listed and online. A missing or offline server points to an existing problem; fix it before upgrading.

Then check two things:

  • The Automatically stop a server from serving when it is older than the database setting is enabled. It stops an out-of-date server from serving once the database has moved to a newer version, which is the risk this process avoids. Leave it on unless you have a specific reason not to.
  • Your load balancer health-checks each server on the /_status route (see above). This process relies on it to pull out-of-date nodes out of rotation.

2. Take all but one server out of rotation

Leave only the server you will upgrade first in rotation; take the rest out. This guarantees no older server can talk to the database once it has been migrated.

Taking a server out of rotation

Wait up to 90 seconds after each change for the load balancer to stop serving from those servers.

3. Upgrade the in-rotation server

Upgrade the one server still in rotation, following your organisation's standards. It migrates the database as it restarts. See Updates and upgrades for the upgrade itself.

4. Upgrade the remaining servers and restore rotation

Upgrade each remaining server the same way, then bring it back into rotation. Once every server is on the new version, the fleet is fully in service again.

Back to top