Skip to content

Secret Store & Port Installation

The port is the CloudTaser Port component that runs alongside your EU-hosted OpenBao (or HashiCorp Vault) instance. It connects outbound to the beacon relay and proxies secret requests from your Kubernetes cluster to the secret store. Secrets travel through an mTLS tunnel -- the beacon relay sees only encrypted bytes.

What the port does

The port is the secret-store-side half of the beacon relay connection. It connects outbound to the beacon on TCP 443, authenticates the operator broker via mTLS, and forwards secret requests to the local OpenBao instance. No inbound ports are required on the secret store.

Prerequisites

Requirement Minimum Recommended
Secret store OpenBao 2.x (also compatible with HashiCorp Vault 1.15+) OpenBao (no license concerns)
KV v2 secrets engine Enabled Enabled at secret/ path
TLS Required TLS with a trusted CA certificate
Beacon relay Deployed and reachable on TCP 443 See Beacon Relay Installation
cloudtaser CLI v0.19.102 Latest

Jurisdiction matters

The secret store must run in an EU jurisdiction. Deploying outside the EU undermines the entire sovereignty model. Choose an EU data center, or an EU cloud region such as europe-west1 (Belgium), europe-west3 (Frankfurt), or europe-west4 (Netherlands).

Step 1: Deploy the secret store

If you already have an OpenBao or HashiCorp Vault instance running in the EU with KV v2 enabled, skip to Step 2.

Option A: Kubernetes (Helm)

Deploy OpenBao on Kubernetes using the CLI:

cloudtaser-cli source install --type kubernetes \
  --namespace cloudtaser-vault

This installs OpenBao via Helm, initializes it, unseals it, and enables KV v2. Unseal keys are stored at ~/.cloudtaser/openbao-init.json.

For HA (3-node Raft cluster):

cloudtaser-cli source install --type kubernetes \
  --replicas 3 \
  --namespace cloudtaser-vault

Preview before applying

Pass --dry-run to see the generated Helm values without deploying:

cloudtaser-cli source install --type kubernetes --dry-run

Option B: Docker Compose

Generate a Docker Compose project for single-host deployments:

cloudtaser-cli source install --type docker

Option C: Linux host (systemd)

Generate a systemd service for bare-metal or VM deployments:

cloudtaser-cli source install --type linux

Option D: Use HashiCorp Vault

If you run HashiCorp Vault, pass --backend vault:

cloudtaser-cli source install --type kubernetes \
  --backend vault \
  --image hashicorp/vault \
  --tag 1.17

Step 2: Configure the secret store

After the secret store is running, configure the policies, roles, and Kubernetes auth method required for cloudtaser:

cloudtaser-cli source configure \
  --openbao-addr https://vault.eu.example.com \
  --token hvs.YOUR_ADMIN_TOKEN

This command:

  1. Enables audit logging
  2. Enables the KV v2 secrets engine (if not already enabled)
  3. Enables the Kubernetes auth backend
  4. Creates the cloudtaser policy with read access to secret paths
  5. Creates the cloudtaser role bound to the operator service account
  6. Creates the operator-specific policy and role

Preview before applying

Pass --dry-run to see the configuration changes without applying them:

cloudtaser-cli source configure \
  --openbao-addr https://vault.eu.example.com \
  --token hvs.YOUR_ADMIN_TOKEN \
  --dry-run

Step 3: Optional advanced pre-registration

The normal ctb1 simple-connect path uses cloudtaser-cli source install port --beacon-token-file on the secret-store side and cloudtaser-cli target install --beacon-token-file on the target side. In that flow, the port auto-registers the target fingerprint during the authenticated init exchange.

Use source register only for advanced or bulk pre-registration workflows where you want to approve fingerprints before the target cluster connects.

On the cluster side, get the cluster fingerprint:

cloudtaser-cli target fingerprint

On the secret-store side, pre-register the cluster:

cloudtaser-cli source register \
  --fingerprint <cluster-fingerprint> \
  --secretstore-address https://vault.eu.example.com \
  --secretstore-token hvs.YOUR_ADMIN_TOKEN

This command:

  1. Generates mTLS certificates (CA, port cert, broker cert) -- all in memory
  2. Stores the certificates and configuration in the secret store
  3. Computes the info hash used to match port and broker through the beacon
  4. Creates a dedicated namespace in the secret store for the cluster at cloudtaser/<fingerprint[:8]>
  5. Registers the cluster fingerprint

Step 4: Start the port

The port runs alongside your secret store and connects outbound to the beacon. Deploy it using one of the following methods.

cloudtaser-cli source install port \
  --namespace cloudtaser-vault \
  --secretstore-k8s-namespace cloudtaser-vault \
  --beacon-token-file ./beacon.token

The public CloudTaser Helm repository does not publish a cloudtaser/cloudtaser-port chart. source install port is the supported Kubernetes flow: it configures the port from the ctb1 beacon token, verifies the port image, and deploys the Kubernetes workload.

Systemd service (bare-metal or VM secret stores)

For OpenBao installations running directly on a Linux host:

cloudtaser-port \
  --vault-addr https://127.0.0.1:8200 \
  --beacon-address beacon.example.com:443 \
  --beacon-info-hash <generated-hash> \
  --tls-cert /etc/cloudtaser/port/client.crt \
  --tls-key /etc/cloudtaser/port/client.key \
  --tls-ca /etc/cloudtaser/port/ca.crt

Or as a systemd unit:

[Unit]
Description=cloudtaser Port (Beacon Relay)
After=network-online.target openbao.service
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/cloudtaser-port \
  --vault-addr https://127.0.0.1:8200 \
  --beacon-address beacon.example.com:443 \
  --beacon-info-hash <generated-hash> \
  --tls-cert /etc/cloudtaser/port/client.crt \
  --tls-key /etc/cloudtaser/port/client.key \
  --tls-ca /etc/cloudtaser/port/ca.crt
Restart=always
RestartSec=5
User=openbao

[Install]
WantedBy=multi-user.target

In the normal ctb1 flow, source install port --beacon-token-file configures the port from the beacon token and auto-registration supplies per-cluster material during init. In advanced pre-registration flows, the info hash is output by cloudtaser-cli source register in Step 3.

Step 5: Verify

Confirm the port has connected to the beacon and the secret store is reachable:

cloudtaser-cli source status \
  --secretstore-address https://vault.eu.example.com \
  --secretstore-token hvs.YOUR_ADMIN_TOKEN

Check the port logs for a successful beacon connection:

port: connected to beacon at beacon.example.com:443
port: mTLS tunnel established with broker

If you see init peer closed connection cleanly in the port logs, the most likely cause is a beacon-salt or fingerprint mismatch. Verify the fingerprint exists in the secret store:

bao kv list cloudtaser/data/clusters/

The fingerprint stored there must match the cluster fingerprint from cloudtaser-cli target fingerprint.

Next steps

The secret store and port are ready. Proceed to deploy the cloudtaser operator on your Kubernetes cluster:

  1. Operator Installation -- deploy the operator and eBPF agent via Helm
  2. Quick Start -- store a test secret, annotate a workload, and verify injection

Once the operator is installed, it connects to the beacon automatically and starts accepting secret requests through the relay.

Troubleshooting

Symptom Cause Fix
Port cannot connect to beacon Egress firewall blocking TCP 443 Allow outbound TCP 443 to the beacon address
init peer closed connection cleanly in port logs Fingerprint or beacon-salt mismatch For normal ctb1 installs, re-run source install port and target install with the same beacon token. For advanced pre-registration, verify the pre-registered fingerprint matches target fingerprint
Port connects but secrets not fetching Kubernetes auth not configured Run source configure or verify the auth method in the secret store
source install fails with init error Secret store already initialized Skip to Step 2 (configure) if the secret store is already running
permission denied from the secret store Admin token expired or insufficient policy Provide a valid root or admin token with --secretstore-token

For more details, see Troubleshooting.