Cluster security

The cluster transport defaults to unauthenticated plain TCP. Fine inside a private network where every host is already trusted. Not fine anywhere else — public internet, multi-tenant K8s, untrusted intermediaries.

This page is the how-to for securing the cluster transport. For the operational context, see Operations — Cluster security.

What needs securing

Threat	Mitigation
Eavesdropping	TLS on cluster transport
MITM (interception + modification)	TLS + cert verification
Unauthorized join (anyone with port access can join)	mTLS (cert-based peer auth)
Compromised cert (issued for a stolen identity)	Cert rotation + revocation

Enabling TLS

import { TcpTransport, NodeAddress, Cluster, ClusterOptions } from 'actor-ts';

const transport = new TcpTransport(
  NodeAddress.parse('actor-ts://my-app@10.0.0.5:2552'),
  system.log,
  {
    cert: fs.readFileSync('./tls/cluster.crt'),
    key:  fs.readFileSync('./tls/cluster.key'),
    ca:   fs.readFileSync('./tls/ca.crt'),
    rejectUnauthorized: true,
  },
);

const clusterOptions = ClusterOptions.create()
  .withHost(host)
  .withPort(port)
  .withSeeds(seeds)
  .withTransport(transport);
await Cluster.join(
  system,
  clusterOptions,
);

TLS-wrapped TCP, all-or-nothing per cluster. Every node uses the same TLS config; mixed plain + TLS doesn’t work.

Cert layout

The minimum:

• A CA cert + private key (used to sign per-node certs).
• A per-node cert + private key (signed by the CA).

# Generate CA (one time):
openssl req -x509 -newkey rsa:4096 -keyout ca.key -out ca.crt -days 3650 -nodes \
  -subj "/CN=actor-ts-ca"

# Per-node cert:
openssl req -newkey rsa:4096 -keyout node-1.key -out node-1.csr -nodes \
  -subj "/CN=node-1.cluster.local"

openssl x509 -req -in node-1.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out node-1.crt -days 365

Each node loads:

• Its own cert + key.
• The CA cert (to verify peers’ certs).

Mutual TLS

{
  cert: fs.readFileSync('./tls/this-node.crt'),
  key:  fs.readFileSync('./tls/this-node.key'),
  ca:   fs.readFileSync('./tls/ca.crt'),
  rejectUnauthorized: true,        // ← reject peers without valid certs
}

With rejectUnauthorized: true + a shared CA, every connection requires both sides to present a valid cert signed by the CA. No anonymous joins; no plain-text fallback.

In K8s

cert-manager + secrets is the standard pattern:

# Cert managed by cert-manager:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: actor-ts-cluster
spec:
  secretName: actor-ts-cluster-tls
  issuerRef:
    name: actor-ts-ca
    kind: ClusterIssuer
  commonName: actor-ts
  dnsNames:
    - actor-ts-cluster.svc
  duration: 8760h
  renewBefore: 720h

---
# Pod mounts the TLS secret:
apiVersion: v1
kind: Pod
spec:
  containers:
    - name: app
      volumeMounts:
        - name: tls
          mountPath: /etc/tls
          readOnly: true
  volumes:
    - name: tls
      secret:
        secretName: actor-ts-cluster-tls

cert-manager auto-renews certs; pods reload them on restart. For zero-downtime cert rotation, use a rolling restart after new certs are in place.

Firewall

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: cluster-internal-only
spec:
  podSelector:
    matchLabels:
      app: actor-ts
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: actor-ts
      ports:
        - protocol: TCP
          port: 2552

Only app=actor-ts pods can reach port 2552. Combined with mTLS, this is two independent layers.

Performance impact

TLS adds ~5-15 % overhead per byte on the transport. For typical actor messages (small payloads, modest rate), imperceptible. For high-throughput cluster traffic, measurable but rarely the bottleneck.

When NOT to enable

Trusted network, single tenant

Internal corp network, dedicated VLAN, all nodes you control

Plain TCP is fine here. Adding TLS adds operational cost (cert rotation) without security benefit. Threat model first.

Self-signed for production

// Same self-signed cert, no rotation strategy

Self-signed is fine for dev / staging. Production needs a CA + rotation plan — cert-manager or equivalent.

`rejectUnauthorized: false`

rejectUnauthorized: false,

Defeats authentication. Accepts any cert. Never in production.

Where to next

• Operations — Cluster security — operational walk-through.
• TLS everywhere — TLS across other components.
• Transports — the cluster transport interface.
• Configuration — the TLS HOCON keys.