What it does
Setting KYNETRA_REPLICATION_TLS_CONFIG to a private bundle puts replica pulls into strict mode. The primary serves the log stream on a dedicated listener that requires a client certificate for an allowed workload, and refuses the stream in plaintext on its public listener. The replica reaches the primary over HTTPS and requires the primary's certificate to name the expected workload.
How it works
Each node has a workload identity carried in a certificate as a URI name of the form kynetra://workload/<id>, where the id follows a strict lowercase DNS-label grammar. A certificate with no workload name, or with more than one, is refused. The server configuration requires the peer certificate, checks the chain, validity window, and signature, and then requires the workload id to be on an allow-list. The client side checks the chain and validity as usual and also requires the server's exact workload name, so a certificate from the same authority and the right DNS name but the wrong workload is refused before any HTTP payload is exchanged.
The bundle is one JSON file naming, in the same directory, up to eight trusted root certificates, the node's certificate and its PKCS#8 private key. It sets the listener address, between one and 128 allowed client workloads, and optionally the primary's HTTPS origin with its expected workload. The schema is exact: unknown or duplicate fields, an unsupported version, a zero port and an origin that is not a plain HTTPS origin are rejected. Loading is strict. The directory must be absolute, owned by the server's user and private to it, files must be regular, singly linked, owned by that user and within size limits, and nothing is followed through symlinks. Loading is supported on Unix operating systems. The material is read once at boot, so changing certificates needs a restart.
In strict mode the primary answers the public /v1/replica/stream route with a 403 and the code replication_tls_required, and serves the stream on a dedicated listener instead. That listener has one route, a connection cap, a handshake and header deadline and a connection lifetime limit. A request must still carry the instance service key as a bearer token, compared in constant time, so a stream needs both a valid workload certificate and the key. A replica in strict mode uses a client pinned to the configured primary origin for its boot pull and for steady tailing, and it will not start without a primary mapping.
A bind collision, a malformed bundle or a missing primary mapping fails the server before it reports healthy. A runtime test suite drives primaries and replicas against each other over loopback and checks the handshake, including a wrong server workload, a wrong primary key and a plaintext request.
Where you reach it
- Config
KYNETRA_REPLICATION_TLS_CONFIG (absolute path to the JSON bundle; absent means legacy bearer-key mode) - HTTP
Dedicated mTLS listener serving GET /v1/replica/stream; public route answers 403 replication_tls_required in strict mode
Example
{
"version": 1,
"trust_roots_der": ["root.der"],
"identity": { "leaf_der": "node.der", "private_key_pkcs8_der": "node.pk8" },
"listener": { "bind": "0.0.0.0:9443", "allowed_client_workloads": ["db-replica"] },
"primary": { "origin": "https://primary.example.com:9443/", "expected_workload": "db-primary" }
}Limits
- It covers the log pull. Quorum pushes, Raft messages and the replica write proxy do not use it.
- Certificates are supplied by the operator as files. The server does not issue, renew or reload them.
- The tests that exercise it use loopback, and no multi-host run is published.
- The instance service key is still required in strict mode.
- The server performs no certificate revocation checks (no revocation list and no online status check). To stop trusting a node, remove its workload from the allowed list or replace the trusted roots, then restart.
Evidence
- On this siteReliability
- TestsCovered in the engine repository by 16 mutual-TLS tests and 21 hardening tests in the workload crate, about 20 bundle loading and configuration tests in the server, and 12 runtime tests for strict and legacy modes
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to talk through the limits above against your own workload.