Skip to main content

Security and TLS

Clustron Zaris secures a cluster in two independent layers:

  1. Authentication and authorization — who is calling, and may they? Every request carries a signed token; the node checks the token's signature and the permissions its roles grant. Unauthorized calls are rejected.
  2. Transport security (TLS) — is the connection private and the peer genuine? Traffic is encrypted, and certificates are validated against a shared cluster certificate authority (CA).

You can enable them independently, but in production you usually want both: tokens prove identity and rights, TLS protects the channel.

Authentication with tokens​

Authentication and authorization are handled by Clustron's built-in security layer, a token system. The manager issues a signed bearer token; the node verifies it and enforces role-based permissions.

The manager issues a signed bearer token to the operator, who presents it to the node on each request; the node verifies the token locally and offline against the issuer's public key and checks role permissions before returning a result or a rejection.

  • The manager signs tokens with a private key. Nodes hold the matching public key, so a node verifies a token locally, without calling back to the manager — verification is fast and survives a manager outage.
  • Both the control plane and the data plane share one permission catalog, so a token's roles resolve the same way on the manager and on every node. A node resolves the token's roles offline — it needs no policy store.
  • Authorization is permission-based. Data-plane permissions are data.read, data.write, data.delete, data.scan, and data.clear; control-plane permissions cover store and node lifecycle, role grants, diagnostics, and metrics.
  • Preset roles bundle those permissions: ClusterAdmin, StoreOperator, Observer, DataWriter, and DataReader. Hand out DataReader for read-only access and DataWriter for read/write, and keep admin rights to ClusterAdmin.

Once security is on, your client presents the token on every data-plane call:

Connect-ZrStore -ConnectionString "zaris://node-01:7861,node-02:7861/orders?token=$token"

Transport security with TLS​

TLS in Clustron Zaris always validates the peer's certificate against the cluster CA — trust is decided against the cluster's own CA roots, never the machine's OS trust store. What differs by path is whether both sides present a certificate.

PathTLS modeWho presents a certificate
Node ↔ node (gossip and replication)Mutual TLSBoth peers — each proves it is a cluster member
Client → node (data plane)Server-authenticated TLSThe node only — the client validates the node's cert and proves its own identity with the token

This is why a client does not need its own certificate: on the client-facing path the node authenticates to the client, and the client authenticates with its bearer token. Mutual TLS is reserved for node-to-node traffic, where every peer must be a cluster member.

The cluster CA issues a leaf certificate to each node; node-to-node traffic uses mutual TLS where both peers present a certificate, while a client uses server-authenticated TLS, validating the node leaf against the CA and authenticating with a token instead of a client certificate.

Peer identity checks​

Once a certificate chains to the cluster CA, Clustron Zaris checks the peer's identity. The default mode, CA-and-identity, requires the certificate to match the expected node ID (its common name) or a matching host or IP in the subject alternative names. A looser CA-only mode chains without an identity check, and a stricter full-hostname mode requires a host/IP match. An acceptor that does not know which member is dialing in falls back to CA-only for that handshake. The trust anchor is a list of roots, so you can trust an old and a new CA during a rotation. Revocation checking (CRL/OCSP) is not enabled in this version; leaf certificates are kept short-lived instead.

Getting certificates onto the nodes​

There are two ways to provision leaf certificates, and four ways to supply the CA that signs them.

  • Self-enrollment — the manager holds the cluster CA, and each node enrolls on first boot to receive its own leaf certificate. Simplest to run.
  • Mounted secrets — you issue a leaf certificate per node ahead of time and mount it read-only. The cluster comes up encrypted on the very first start with no runtime enrollment step. This is the model for a reproducible, declaratively-secured cluster.

The CA itself can be supplied in one of four modes:

ModeWhat you provideHow to configure it
Generated CANothing — Clustron generates the cluster CAEnable-ZrStoreTls generates one when none exists
Your root CAA PKCS#12 with your root CA cert and keyImport-ZrClusterCa before Enable-ZrStoreTls; leaves chain straight to your root
Your intermediate CAAn intermediate that chains to your enterprise rootImport-ZrClusterCa; the leaf bundles the intermediate so peers can build leaf → intermediate → root
Pre-issued leavesLeaf certificates you issued yourselfMount them read-only; nodes load them directly, no enrollment

Turning it on​

How you enable security depends on the deployment model.

Supervisor modeAttach mode
How security is appliedThe manager owns the nodes, so you enable security and TLS from the console or CLI and it provisions and restarts the nodesThe manager only observes, so security is declared in the node configuration the orchestrator mounts; nodes come up already secured
Runtime "turn on TLS"YesNo — an observer manager cannot reconfigure a running node

A node's declarative security block looks like this:

{
  "security": {
    "enabled": true,
    "issuer": "clustron://zaris",
    "publicKeys": [
      { "keyId": "…", "spkiBase64": "…" }
    ],
    "tls": {
      "enabled": true,
      "mode": "MutualTls",
      "peerVerification": "CaAndIdentity",
      "trustAnchors": [
        { "keyId": "cluster-ca", "pem": "-----BEGIN CERTIFICATE----- …" }
      ],
      "nodeCertificate": { "path": "/var/lib/clustron/certs/${NODE_ID}.pfx" }
    }
  }
}
  • issuer + publicKeys let the node verify tokens locally.
  • tls.mode selects ServerAuth (client-facing) or MutualTls (node-to-node); Off disables TLS.
  • tls.peerVerification selects CaOnly, CaAndIdentity (default), or FullHostname.
  • tls.trustAnchors pins the cluster CA roots the node trusts.
  • tls.nodeCertificate points at this node's leaf certificate (a mounted secret, or the enrolled cert).
note

Cluster transport TLS (data plane and node-to-node) is separate from management-plane HTTPS, which secures the manager's HTTP surface and the web console API. Management HTTPS is off by default and opt-in; its server certificate is minted from the cluster CA (default) or supplied by you. Enabling one does not enable the other.

How a secured client connects​

A client talking to a token-and-TLS cluster needs two things: the token (to authenticate) and the cluster CA (to validate the node certificates). It does not need its own client certificate.

Connect-ZrStore -ConnectionString "zariss://node-01:7861,node-02:7861/orders?token=$token&ca=file:cluster-ca.crt"

Export the CA the clients trust with Get-ZrClusterCaCert -OutFile cluster-ca.crt.

Next steps​