Beacon Relay Connectivity¶
CloudTaser's beacon relay provides zero-config vault-to-cluster connectivity. Both the EU vault (bridge) and the Kubernetes cluster (operator broker) connect outbound to a stateless beacon relay server on TCP 443. The beacon matches them cryptographically and relays encrypted mTLS traffic. No direct network path between vault and cluster is needed.
When to use beacon relay¶
Beacon relay is the default connectivity mode. Use it when:
- Your vault and cluster have no direct network path
- Both sides are behind NAT or firewalls
- You only allow outbound TCP 443 traffic
- You want zero-config connectivity (no VPN, no IPsec, no SSH tunnels)
Use reverse-connect (--mode reverse) instead when:
- You have a direct network path and want lower latency
- You can expose a LoadBalancer or public endpoint on the cluster
Use direct (--mode direct) only for legacy setups where pods connect directly to the vault.
Default mode
Beacon relay is the default when running cloudtaser-cli target install. You do not need to specify --mode beacon unless overriding a previous configuration.
Architecture¶
EU Jurisdiction Beacon US Cloud Provider
┌──────────────────────────┐ ┌────────────────────┐ ┌──────────────────────────┐
│ │ │ │ │ │
│ OpenBao / Vault │ │ Stateless relay │ │ Managed Kubernetes │
│ + Bridge │─────────>│ port 443 only │<──────│ + Operator (broker) │
│ │ outbound │ │ │ │
└──────────────────────────┘ │ Matches by │ │ ┌──────────────────┐ │
│ info_hash │ │ │ Protected pods │ │
│ │ │ │ → Broker → Beacon │ │
│ Relays encrypted │ │ │ → Bridge → Vault│ │
│ mTLS bytes │ │ └──────────────────┘ │
└────────────────────┘ └──────────────────────────┘
Data flow for secret delivery:
- The bridge runs alongside the vault and connects outbound to the beacon
- The operator (broker) connects outbound to the beacon from the K8s cluster
- The beacon matches them by their shared info hash (SHA-256 of the bridge CA certificate)
- After matching, the beacon relays bytes bidirectionally
- Through the relay, bridge and broker establish mTLS (end-to-end encrypted)
- The beacon never sees plaintext -- it only relays encrypted traffic
Security¶
mTLS end-to-end¶
Bridge and broker authenticate each other via certificates generated during the self-bootstrap protocol. The beacon relay is transparent -- it forwards bytes without inspecting or modifying them. Even if the beacon is compromised, the attacker cannot decrypt the traffic.
Info hash as capability¶
The info hash is the SHA-256 of the bridge CA certificate. Only parties that possess the same CA certificate compute the same hash. The beacon uses this hash to match bridge and broker connections. Without the correct info hash, a connection cannot be paired.
Beacon is stateless¶
The beacon holds no secrets, no keys, no configuration state. It is a pure relay: accept connections, match by info hash, forward bytes. If the beacon process restarts, bridge and broker reconnect automatically.
Zero trust¶
The security model does not trust the beacon. Even under full compromise of the beacon server, the attacker sees only TLS-encrypted bytes. Secrets remain protected by the mTLS tunnel between bridge and broker.
In-memory certificates¶
All mTLS certificates for the bridge-to-broker connection are stored in vault and loaded into operator process memory at runtime. No certificates are stored in Kubernetes Secrets. See Zero Kubernetes Secrets Architecture for details.
Setup¶
The recommended setup uses the self-bootstrap protocol, which requires only a cluster fingerprint and a single Helm parameter. See Self-Bootstrap Protocol for the full walkthrough.
Quick setup (self-bootstrap)¶
1. Get cluster fingerprint (target side):
2. Register cluster (vault side):
cloudtaser-cli source register \
--fingerprint <cluster-fingerprint> \
--vault-address https://vault.eu.example.com \
--vault-token $TOKEN
This generates mTLS certificates, stores them in vault, and registers the cluster. The bridge detects the new registration and connects to the beacon automatically.
3. Deploy operator (target side):
helm install cloudtaser oci://ghcr.io/cloudtaser/cloudtaser-helm/cloudtaser \
--namespace cloudtaser-system \
--create-namespace \
--set operator.beacon.address=beacon.cloudtaser.io:443
The operator self-bootstraps through the beacon relay -- it receives its certificates from the bridge and transitions to operational mode automatically. No certificates, tokens, or vault addresses in the Helm values.
4. Deploy workloads:
Annotate pods with CloudTaser annotations -- no vault address needed in beacon mode:
annotations:
cloudtaser.io/inject: "true"
cloudtaser.io/secret-paths: "secret/data/myapp/config"
cloudtaser.io/env-map: "password=DB_PASSWORD"
Secrets are fetched through the beacon relay automatically. The wrapper connects to the in-cluster broker, which tunnels requests through the beacon to the bridge, which forwards them to the local vault instance.
Manual setup¶
For environments where self-bootstrap is not suitable, you can configure the beacon relay manually.
1. Connect cluster to vault:
cloudtaser-cli target connect \
--vault-address https://vault.example.com \
--vault-token $TOKEN \
--beacon-address beacon.cloudtaser.io:443
This command performs the following:
- Generates mTLS certificates (CA, bridge cert, broker cert)
- Stores the certificates and configuration in the vault
- Computes the info hash from the CA certificate
- Configures the Kubernetes auth backend in the vault
- Creates a vault namespace for the cluster at
cloudtaser/<fingerprint[:8]>
Preview before applying
Use --dry-run to see what changes will be made before applying them:
2. Start the bridge (vault side):
cloudtaser-bridge \
--vault-addr https://127.0.0.1:8200 \
--beacon-address beacon.cloudtaser.io:443 \
--beacon-info-hash <generated-hash> \
--tls-cert /path/to/client.crt \
--tls-key /path/to/client.key \
--tls-ca /path/to/ca.crt
Or via the cloudtaser-onprem Helm chart which includes the bridge as a sidecar:
helm install cloudtaser-onprem cloudtaser/cloudtaser-onprem \
--set bridge.beacon.enabled=true \
--set bridge.beacon.address=beacon.cloudtaser.io:443 \
--set bridge.beacon.infoHash=<generated-hash>
Or as a systemd service for bare-metal vault deployments:
[Unit]
Description=CloudTaser Bridge (Beacon Relay)
After=network-online.target vault.service
Wants=network-online.target
[Service]
ExecStart=/usr/local/bin/cloudtaser-bridge \
--vault-addr https://127.0.0.1:8200 \
--beacon-address beacon.cloudtaser.io:443 \
--beacon-info-hash <generated-hash> \
--tls-cert /etc/cloudtaser/bridge/client.crt \
--tls-key /etc/cloudtaser/bridge/client.key \
--tls-ca /etc/cloudtaser/bridge/ca.crt
Restart=always
RestartSec=5
User=vault
[Install]
WantedBy=multi-user.target
3. Install operator with beacon config:
helm install cloudtaser cloudtaser/cloudtaser \
--namespace cloudtaser-system \
--create-namespace \
--set operator.broker.beacon.enabled=true \
--set operator.broker.beacon.address=beacon.cloudtaser.io:443 \
--set operator.broker.beacon.infoHash=<generated-hash>
Beacon deployment¶
CloudTaser-hosted (default)¶
beacon.cloudtaser.io:443 is operated by CloudTaser. No setup needed. The hosted beacon runs in EU data centers and is designed to be stateless -- it never holds secrets or configuration.
Self-hosted¶
The beacon is a static Go binary with zero dependencies:
# Download
curl -sfL https://github.com/cloudtaser/cloudtaser-beacon/releases/latest/download/cloudtaser-beacon-linux-amd64 \
-o /usr/local/bin/cloudtaser-beacon
chmod +x /usr/local/bin/cloudtaser-beacon
# Run
cloudtaser-beacon \
--addr :443 \
--tls-cert /path/to/cert.pem \
--tls-key /path/to/key.pem
For high availability, run multiple beacon instances behind a load balancer or configure clients with comma-separated addresses:
Self-hosted beacon requirements
The beacon needs a public IP or DNS name reachable from both the vault network and the cluster network on TCP 443. It does not need access to either the vault or the cluster -- it is a pure relay.
Network requirements¶
| Side | Direction | Destination | Port | Protocol |
|---|---|---|---|---|
| Vault (bridge) | Outbound | Beacon server | 443 | TCP/TLS |
| Cluster (broker) | Outbound | Beacon server | 443 | TCP/TLS |
| Beacon server | Inbound | From bridge and broker | 443 | TCP/TLS |
No inbound ports are required on either the vault or the cluster. Both sides initiate outbound connections only.
Comparison of connectivity modes¶
| Feature | Direct | Reverse-Connect | Beacon Relay |
|---|---|---|---|
| Network requirement | Vault reachable from pods | Broker reachable from vault | Outbound TCP 443 only |
| Configuration | Vault address per pod | Bridge endpoint | Zero-config (info hash) |
| NAT traversal | No | Partial | Full |
| Default mode | No | No | Yes |
| Latency | Lowest | Low | Low (+1 hop) |
| Vault inbound ports | Required | None | None |
| Cluster inbound ports | None | Required (LoadBalancer) | None |
| Third-party dependency | None | None | Beacon server |
Troubleshooting¶
| Symptom | Cause | Fix |
|---|---|---|
| Broker cannot connect to beacon | Egress firewall blocking TCP 443 to beacon address | Allow outbound TCP 443 to beacon.cloudtaser.io |
| Bridge cannot connect to beacon | Vault server egress restricted | Allow outbound TCP 443 to beacon.cloudtaser.io |
| Bridge and broker connected but mTLS fails | Mismatched info hash or certificates | Re-run cloudtaser-cli source register to regenerate certificates |
| Secrets not fetching after relay established | Vault Kubernetes auth not configured | Verify with cloudtaser-cli target validate |
| High latency on secret fetch | Beacon server geographically distant | Self-host a beacon closer to both sides, or use reverse-connect mode |
cloudtaser-cli target debug shows relay errors |
Beacon connection dropping | Check network stability; create a DebugReport CR for diagnostics |
Related¶
- Self-Bootstrap Protocol -- zero-config cluster onboarding via fingerprint
- Reverse-Connect Architecture -- alternative mode when you can expose a LoadBalancer
- Enterprise Deployment Architecture -- CLI-as-orchestrator and air-gap workflows
- GKE Deployment Guide -- step-by-step GKE setup
- Security Model -- trust boundaries and threat model