콘텐츠로 이동
한국어

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.

ThreatMitigation
EavesdroppingTLS 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
Replay of a captured gossip frameTLS, plus the per-sender frame sequence every cluster enforces
A member speaking for another node in a payloadFramework handlers hold a payload’s claimed identity against the connection’s peer — see what a replica trusts from its peers
A peer addressing a framework actor (/system/…) by nameRefused unconditionally: framework actors are reachable only through the per-path handler each registers, at both the cluster wire and the ClusterClientReceptionist
A peer addressing arbitrary application actors by nameactor-ts.remote.untrusted-mode = true plus trusted-selection-paths — see configuration

The /system row needs nothing configured and cannot be turned off. An envelope carries the path the sender chose, and resolving it against the actor tree is the one place a remote party picks the target — reaching a coordinator, a singleton manager or the pub-sub mediator that way went round the handler that would have known which connection the frame came in on. The row below it is the same question for /user, where the answer is a deployment’s own: naming an application actor is how an ActorRef works across nodes, so it stays open until you narrow it. Refusals land on cluster_envelope_refusals_total{reason, frame}.

mTLS is what makes the “speaking for another node” row work rather than something it duplicates: holding a claim against the connection’s peer is only worth anything once the peer is authenticated.

That row covers the in-process worker mesh too, which used to be the one path where it did not hold: WorkerBroker re-addresses every frame to the MessagePort it arrived on, so a worker cannot write a sibling’s address into from. Nothing has to be configured for it, and no mTLS underwrites it — the host assigns each worker’s address and holds its port, so the binding is structural rather than authenticated.

The cluster transport refuses one claim with or without a certificate: a node refuses a peer that claims the node’s own address, and closes the connection.

import { TcpTransport, TcpTransportOptions, NodeAddress, Cluster, ClusterOptions } from 'actor-ts/cluster';
import fs from 'node:fs';
const transportOptions = TcpTransportOptions.create().withTls({
cert: fs.readFileSync('./tls/cluster.crt'),
key: fs.readFileSync('./tls/cluster.key'),
ca: fs.readFileSync('./tls/ca.crt'),
rejectUnauthorized: true,
});
const transport = new TcpTransport(
NodeAddress.parse('my-app@10.0.0.5:2552'),
system.log,
transportOptions,
);
const clusterOptions = ClusterOptions.create()
.withHost('10.0.0.5')
.withPort(2552)
.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. The transport’s address is the node’s own — my-app is the actor system’s name, and withHost / withPort repeat its host and port. A node addressed by IP, as here, is verified against an IP SAN in its certificate, which the cert layout below puts there.

The minimum:

  • A CA cert + private key (used to sign per-node certs).
  • A per-node cert + private key (signed by the CA).
Terminal window
# 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, naming every address the node is dialled at:
openssl req -newkey rsa:4096 -keyout node-1.key -out node-1.csr -nodes \
-subj "/CN=node-1.cluster.local"
printf 'subjectAltName=IP:10.0.0.5,DNS:node-1.cluster.local\n' > node-1.ext
openssl x509 -req -in node-1.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
-out node-1.crt -days 365 -extfile node-1.ext

The subject alternative names are what a peer checks. A node dialled at an IP literal is verified against an IP: entry — no server name is announced for an IP, so there is nothing else to check — and one dialled by host name against a DNS: entry.

Each node loads:

  • Its own cert + key.
  • The CA cert (to verify peers’ certs).
{
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.

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.

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.

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.