Skip to main content

CA and trust modes

Every TLS certificate is only as trustworthy as the certificate authority (CA) that signed it. The central question when you secure a cluster is therefore not "is traffic encrypted?" but "whose CA signs the node certificates, and how do clients come to trust that CA?"

Zaris answers this with four trust models. They exist so that you can align the cluster with your organization's existing public-key infrastructure (PKI) rather than working around it. All four produce the same end state — nodes present certificates that peers and clients validate against a trust anchor — but they differ in who owns the CA key and whether Clustron signs anything. A trust anchor is the certificate a peer or client trusts as the root of validation; every node certificate must chain back to it.

A decision tree for picking a trust mode: no private CA leads to auto-generated Mode 0, while handing Zaris a root key, an intermediate key, or nothing selects Mode 1, Mode 2, or Mode 3.

#ModeCA key held byClustron signs leavesTrust anchor distributed to clients
0Auto-generatedThe cluster (generated)YesThe generated cluster CA (cluster-ca.crt)
1Bring-your-own CAYou (given to the cluster)YesYour CA root
2Bring-your-own intermediateYou (intermediate given to the cluster)YesYour enterprise root
3Pre-issued leavesYou (never given to the cluster)NoYour root (configured as a trust anchor)

In configuration terms, Modes 0 through 2 are the Ca.Source setting — Generate for Mode 0, Provided for Modes 1 and 2 (the difference is whether the supplied PKCS#12 is a root or an intermediate). Mode 3 sets no CA at all: the node loads a mounted NodeCertificate and validates peers against configured TrustAnchors.

How node certificates are issued​

Before the modes, it helps to understand the two ways a node can get its certificate — because the trust mode determines which one applies.

  • Enrollment (Clustron signs). The node generates its private key locally and sends only a certificate-signing request (CSR) to the Management Service, gated by a one-time enrollment token. The manager signs the CSR with the cluster CA and returns the public leaf. The private key never leaves the node. This is how Modes 0, 1, and 2 work, and it is the default in the supervisor deployment model.
  • Mounted (Clustron signs nothing). An external system issues each node's certificate and delivers it to the node (a file, a Kubernetes secret, a mounted volume). Zaris loads it and presents it. This is Mode 3, natural in the attach deployment model.

During enrollment a node generates its keypair locally and sends only a CSR plus a one-time token; the Management Service has the Cluster CA sign it and returns the leaf, while the private key never leaves the node.

Mode 0 — Auto-generated (default)​

Use this when you don't already run a CA and want a secure cluster with the least effort.

The cluster generates a self-signed cluster CA the first time TLS is enabled, stores the CA key encrypted at rest on the issuer, and signs every node's leaf certificate from its CSR. You distribute one public file — cluster-ca.crt — to clients as their trust anchor.

Configure it​

Nothing to configure — it is the default. Enabling TLS provisions the CA automatically:

Enable-ZrStoreTls -Store orders -Restart

Under the hood this corresponds to the configuration:

{
  "Enabled": true,
  "Mode": "MutualTls",
  "Ca": { "Source": "Generate" }
}

Distribute the CA to clients​

Clients need the cluster CA to validate node certificates. Two ways:

  • Automatic (recommended). When a client connects with -Credential/-ManagementUrl, Connect-ZrStore fetches and caches the CA from the Management Service, so you often don't have to distribute anything: 
    Connect-ZrStore -ConnectionString "zariss://10.0.0.10:7861/orders" `
                    -Credential (Get-Credential) -ManagementUrl "http://10.0.0.10:7801"
  • Explicit (pinned). Export the CA once and hand it to clients to pin: 
    Get-ZrClusterCaCert -OutFile cluster-ca.crt          # writes the public CA; prints its SHA-256 thumbprint
    Get-ZrStoreTlsStatus -Store orders -ShowCertificates # cross-check the trust-anchor thumbprint
    Then on the client: Connect-ZrStore -ConnectionString "zariss://10.0.0.10:7861/orders?ca=file:C:\path\cluster-ca.crt".
tip

The auto-generated CA is a full-fledged private CA scoped to your cluster. It is backed up and restorable (see Certificate management), so "auto" does not mean "disposable."

Mode 1 — Bring-your-own CA​

Use this when you already operate a private CA and want Zaris to issue node certificates from it.

You provide a full CA — the certificate and its private key — as a password-protected PKCS#12 (.pfx) file. Zaris imports it, validates that it is a usable CA (basic constraints CA:true, and, if a key-usage extension is present, KeyCertSign), and signs node leaves with it exactly as in Mode 0. Clients trust your CA root, which they very likely already do.

Configure it​

Point the store at your CA and enable TLS in one step:

Enable-ZrStoreTls -Store orders -CaFile C:\pki\corp-ca.pfx -CaPassword (Read-Host -AsSecureString) -Restart

Equivalent configuration:

{
  "Enabled": true,
  "Mode": "MutualTls",
  "Ca": { "Source": "Provided", "ProvidedRootPath": "C:\\pki\\corp-ca.pfx" }
}

Or import the CA onto every connected manager first (a CA swap), then enable TLS per store:

Import-ZrClusterCa -CaFile C:\pki\corp-ca.pfx -CaPassword (Read-Host -AsSecureString)
Enable-ZrStoreTls -Store orders -Restart

Import-ZrClusterCa adopts your CA cluster-wide (it has no -Store parameter); Enable-ZrStoreTls then keeps the imported CA instead of generating one.

warning

The CA private key is sensitive. Zaris stores it encrypted at rest and never transmits it to nodes (nodes only ever receive signed public leaves). Protect the source .pfx and its password as you would any CA key.

Mode 2 — Bring-your-own intermediate​

Use this when your enterprise root is offline or must not be handed to any application — the standard enterprise PKI posture.

You provide an intermediate CA (certificate + key) that chains to your enterprise root, with the root itself (public) also in the same PKCS#12 bundle. An intermediate is a CA that is itself signed by a higher CA rather than being self-signed. Zaris signs node leaves with the intermediate and — crucially — bundles the intermediate into every issued leaf, so a node presents the full chain [leaf, intermediate]. Peers and clients trust only the root; they build leaf → intermediate → root and validate. Zaris serves the enterprise root (the self-signed certificate found in the bundle) as the trust anchor, not the intermediate.

The enterprise root signs the intermediate, Zaris signs node leaves with the intermediate, and each node presents the full leaf-plus-intermediate chain, which peers validate back to the root they trust.

Configure it​

Provide the intermediate bundle (a .pfx containing the intermediate cert + key and the root cert). The command is the same as Mode 1 — Zaris detects that the supplied CA is an intermediate and captures the chain:

Enable-ZrStoreTls -Store orders -CaFile C:\pki\corp-intermediate.pfx -CaPassword (Read-Host -AsSecureString) -Restart

The trust anchor served to clients is your enterprise root (not the intermediate), so clients that already trust the root need nothing new. Verify the chain with:

Get-ZrStoreTlsStatus -Store orders -ShowCertificates
note

Mode 2 is what makes Zaris fit a real corporate PKI: the root never leaves your control, yet the cluster still issues short-lived node certificates on demand. The chain-bundling is automatic — you do not configure it.

Mode 3 — Pre-issued leaves​

Use this when an external system already issues every certificate — a service mesh, cert-manager, or your own provisioning pipeline — and Zaris should sign nothing.

Each node's certificate (leaf + private key) is delivered to the node out-of-band and mounted at a known path. Zaris loads it, presents it, and validates peers against one or more trust anchors you configure (your root, or roots). Because Clustron issues nothing, there is no cluster CA and no enrollment.

Configure it​

Each node's config points at its mounted certificate and the trust anchor(s):

{
  "Enabled": true,
  "Mode": "MutualTls",
  "PeerVerification": "CaAndIdentity",
  "NodeCertificate": { "Path": "/var/lib/clustron/certs/node-0.pfx" },
  "TrustAnchors": [ { "KeyId": "corp-root", "Pem": "-----BEGIN CERTIFICATE-----\n...your root...\n-----END CERTIFICATE-----" } ]
}

This is the natural fit for the attach deployment model, where an orchestrator already manages certificates. See the secured Docker Compose sample for a complete, mounted-secret example.

tip

In Mode 3 you own renewal and rotation entirely — Zaris just reloads the certificate file when it changes. If a leaf is issued by an intermediate, mount the full chain ([leaf, intermediate]) so peers can build the path to your root.

Peer verification: how strictly a peer is checked​

Independent of the trust mode, you choose how strictly a node validates its peers with PeerVerification. All three values require the peer certificate to chain to a trusted anchor first.

ValueA peer is accepted when…Use when
CaOnlyits certificate chains to a trusted anchoryou accept any certificate your CA signed as a legitimate member (loosest; avoid in production)
CaAndIdentityit chains and its identity (CN / SAN) matches the expected nodethe default: a stolen-but-valid cert still can't impersonate a different node
FullHostnameit chains and a SAN entry (host / IP) matches strictlystatic-IP deployments that pin hostname or address

CaAndIdentity is the default and the recommended choice for production.

Choosing a mode — summary​

  • Just want it secure? → Mode 0 (Auto-generated).
  • Already run a private CA and can share its key? → Mode 1 (BYO CA).
  • Have an enterprise root you won't export? → Mode 2 (BYO intermediate).
  • Certificates come from a mesh / cert-manager / external pipeline? → Mode 3 (Pre-issued leaves).

All four are configuration, not forks — you can migrate between them (for example, start on Mode 0 and later import your corporate CA with Import-ZrClusterCa).

Next steps​