cloudtaser-cli beacon install

Installs a cloudtaser-beacon relay as a systemd service, a docker-compose project, or a Kubernetes Deployment. HA (--replicas > 1) is only supported on Kubernetes; systemd and docker modes are single-host installs.

Requires cloudtaser-beacon v0.2.0+ for HA (gossip + consistent-hash ring + inner-hop mTLS forwarding).

Two-node clusters are refused. A 2-node beacon cluster has no tiebreaker and strictly adds a failure mode over single-instance, so the CLI and the beacon both reject --replicas=2.

--type is required. With --type=systemd the command installs the beacon directly on the local host (requires root). For airgapped hosts or audit review, pass --dry-run to print the install script + unit + env file to stdout without installing or changing service state. Only explicitly selected credential output files are written. A no-secret audit script references the mode-0600 file selected by --beacon-auth-key-out.

K8s mode uses the cloudtaser-beacon Helm chart as the single source of truth for layout decisions. Chart 0.3.17 delivers all beacon keys from OpenBao through a fetch-keys init container into a Memory emptyDir — no secret bytes embedded in Helm release values, no Kubernetes Secrets. When --secretstore-address and a token are provided, the CLI writes beacon keys to OpenBao and creates the Kubernetes auth role + read-only policy the init container needs.

Systemd audit events default to stdout, where journald owns retention and rotation. Use --audit-log=off only as an explicit opt-out.

The generated ctb1 credential is written to an exclusive mode-0600 file under the user's persistent config directory by default. Override the destination with --beacon-token-out; non-interactive installs never put the raw token in logs.

Usage

cloudtaser-cli beacon install [flags]

Examples

# Single-instance systemd install (installs directly; must run as root)
  sudo cloudtaser-cli beacon install \
    --type systemd \
    --advertise-addr beacon.example.com:443 \
    --public-cert-file /etc/letsencrypt/live/beacon.example.com/fullchain.pem \
    --public-key-file  /etc/letsencrypt/live/beacon.example.com/privkey.pem

  # Audit / airgapped: export the raw daemon key to a protected file and print a secret-free installer
  cloudtaser-cli beacon install \
    --type systemd \
    --advertise-addr beacon.example.com:443 \
    --beacon-auth-key-out ./beacon-auth.key \
    --beacon-token-out ./beacon.token \
    --dry-run

  # Single-instance K8s with OpenBao key delivery (no secret bytes in Helm release values)
  cloudtaser-cli beacon install \
    --type k8s \
    --advertise-addr beacon.example.com:443 \
    --namespace cloudtaser-beacon \
    --secretstore-address https://openbao.example.com:8200 \
    --secretstore-token-file ./admin-token

  # 3-node HA on Kubernetes with OpenBao key delivery
  cloudtaser-cli beacon install \
    --type k8s \
    --replicas 3 \
    --advertise-addr beacon.example.com:443 \
    --gossip-key-file /etc/cloudtaser/beacon/gossip.key \
    --internal-ca-cert-file /etc/cloudtaser/beacon/internal-ca.crt \
    --internal-ca-key-file /etc/cloudtaser/beacon/internal-ca.key \
    --internal-cert-file /etc/cloudtaser/beacon/internal.crt \
    --internal-key-file /etc/cloudtaser/beacon/internal.key \
    --namespace cloudtaser-beacon \
    --bootstrap-from beacon.example.com \
    --secretstore-address https://openbao.example.com:8200 \
    --secretstore-token-file ./admin-token

Flags

Flag	Type	Default	Required	Description
--acme	string	auto	no	ACME/Let's Encrypt TLS: auto (an explicit --acme-domain, else a DNS --advertise-addr unless --public-cert-file/--public-key-file are supplied), on (ACME; a supplied pair is only the fallback until ACME issues), or off (never; the supplied or self-signed certificate is operator-renewed)
--acme-cache-dir	string	(empty)	no	directory for ACME certificate cache (default: /etc/cloudtaser/acme)
--acme-domain	string	(empty)	no	domain for automatic TLS via ACME/Let's Encrypt (with --acme=auto, a DNS --advertise-addr is used when no certificate pair is supplied)
--acme-email	string	(empty)	no	contact email for ACME certificate notifications
--advertise-addr	string	(empty)	no	public host:port clients dial (required for every install type before keys are written)
--allow-any-sni	bool	false	no	explicitly allow any TLS ServerName when a DNS allowlist cannot be used (for IP-literal systemd/docker installs; mutually exclusive with --allowed-sni)
--allow-unsigned	bool	false	no	DANGEROUS: allow installing without cosign verification when SHA256SUMS.sig is missing or cosign is absent (env: CLOUDTASER_ALLOW_UNSIGNED=1; dev workflows only)
--allowed-sni	string	(empty)	no	comma-separated exact TLS ServerName values accepted by local systemd/docker installs (default: derive the DNS name from --advertise-addr)
--audit-log	string	(empty)	no	systemd security audit sink: stdout (default, journald), stderr, off, or a file under /var/log/cloudtaser-beacon
--auth-key	string	(empty)	no	base64-encoded auth key (from source configure --generate-beacon-auth-key). If omitted, a new key is generated.
--beacon-auth-key-out	string	(empty)	no	exclusive mode-0600 output path for the raw daemon registration key (required for no-secret systemd dry-runs without a secret store; env: CLOUDTASER_BEACON_AUTH_KEY_OUT)
--beacon-token-out	string	~/.config/cloudtaser/beacon.token	no	persistent output path for the generated ctb1 token (created mode 0600 without overwrite; default: user config directory; env: CLOUDTASER_BEACON_TOKEN_OUT)
--beacon-version	string	(empty)	no	cloudtaser-beacon release tag (default: reviewed CLI companion pin v0.6.23; an override must be a release >= v0.6.21; never resolved from mutable latest)
--bootstrap-from	string	(empty)	no	public DNS name the beacon resolves at startup to discover peers (mutually exclusive with --peers)
--chart	string	cloudtaser-beacon	no	Helm chart name (default: cloudtaser-beacon) or local path
--chart-path	string	(empty)	no	local chart path (overrides --chart/--chart-repo; used for testing)
--chart-repo	string	https://charts.cloudtaser.io	no	Helm repo URL when --chart is a bare chart name
--chart-version	string	0.3.19	no	Helm chart version to pin
--cosign-public-key	string	(empty)	no	path to a custom cosign public key (PEM) for verifying SHA256SUMS.sig (env: CLOUDTASER_COSIGN_PUBLIC_KEY); defaults to the embedded CloudTaser pipeline key
--dry-run	bool	false	no	render artefacts to stdout without applying (systemd: prints the install script + unit + env file for audit / airgapped review)
--expected-members	int	0	no	expected cluster size for the beacon_gossip_expected_members alert (0 = derive from peer count)
--gossip-key-file	string	(empty)	no	path to a file containing a base64-encoded 16/24/32-byte AES key for memberlist gossip (required in HA mode)
--helm-install	bool	false	no	Use 'helm install' semantics (tracked Helm release) instead of server-side apply
--help, -h	bool	false	no	help for install
--image	string	(empty)	no	container image reference (default: chart image.repository + image.tag)
--internal-ca-cert-file	string	(empty)	no	path to the dedicated inner-hop mTLS CA cert (required in HA mode)
--internal-ca-key-file	string	(empty)	no	path to the dedicated inner-hop mTLS CA key (required in HA mode; reused when join-rotating)
--internal-cert-file	string	(empty)	no	path to the inner-hop mTLS leaf cert (required in HA mode)
--internal-key-file	string	(empty)	no	path to the inner-hop mTLS leaf key (required in HA mode)
--namespace, -n	string	cloudtaser-beacon	no	Kubernetes namespace (--type=k8s only)
--openbao-auth-path	string	kubernetes	no	OpenBao Kubernetes auth mount name (--type=k8s only)
--openbao-ca-cert	string	(empty)	no	PEM CA certificate for the OpenBao server (public data; --type=k8s only)
--openbao-role	string	(empty)	no	OpenBao Kubernetes auth role bound to the beacon ServiceAccount (--type=k8s only; created during install when --secretstore-address is set)
--peers	string	(empty)	no	comma-separated peer host:port seeds (mutually exclusive with --bootstrap-from)
--public-cert-file	string	(empty)	no	path to the beacon's public :443 TLS cert (optional; beacon can boot without TLS for development)
--public-key-file	string	(empty)	no	path to the beacon's public :443 TLS private key
--release-name	string	cloudtaser-beacon	no	Helm release name (--type=k8s only)
--replicas	int	1	no	number of beacon replicas (1 or >=3; 2 is refused; >1 requires --type=k8s)
--secretstore-address	string	(empty)	no	secret store address for storing the generated beacon auth key (env: CLOUDTASER_SECRETSTORE_ADDRESS, VAULT_ADDR)
--secretstore-allow-insecure	bool	false	no	allow explicitly requested insecure secret store TLS options (development only)
--secretstore-skip-verify	bool	false	no	skip secret store TLS certificate verification (requires --secretstore-allow-insecure; development only)
--secretstore-token	string	(empty)	no	secret store token (prefer --secretstore-token-file or SECRETSTORE_TOKEN to avoid process-list exposure)
--secretstore-token-file	string	(empty)	no	path to a file containing the secret store token, or '-' to read it from stdin
--tenant-mode	string	single	no	beacon trust-boundary model; single configures one beacon per trust boundary, multi requires beacon tenant issue and separately managed tenant-map deployment
--timeout	duration	20m0s	no	maximum time for the command to complete (default 20m0s; also CLOUDTASER_TIMEOUT env)
--type	string	(empty)	yes	install type: systemd, docker, k8s, or kubernetes (required)
--yes, -y	bool	false	no	assume yes on interactive prompts, including cosign auto-install

All commands