Skip to content

Getting started ​

This guide installs Strait on two clusters, sites a and b, joins them with a WireGuard link, and points the name pg.app.svc at the CloudNativePG primary, wherever it runs.

Prerequisites ​

RequirementDetail
Two Kubernetes clustersOne per site, of a version that Install supports, reached with the kubeconfig contexts site-a and site-b.
Kernel modules wireguard and nf_tablesOn every node that can run a gateway pod. The gateway agent does not load them. It uses nftables to filter what arrives on its WireGuard interfaces. Without nftables, it holds no interface.
Pod Security level privilegedIn the gateway's namespace. The gateway agent runs as root with NET_ADMIN, to hold the WireGuard interfaces (RFC0007).
A UDP path from site b to site aSite b dials a node of site a on UDP port 32100. Here, 203.0.113.10 stands for that node's address.
Socket load balancing for podsRecommended, where the CNI load-balances Services. For Cilium: socket LB on, with socketLB.hostNamespaceOnly=false. Without it, a new connection can still reach the previous member after a route change: RFC0002, Route changes and connections.
CloudNativePGAt both sites, installed before Strait. One Cluster per site in namespace app, in CloudNativePG's distributed topology: pg-a at site a, pg-b at site b. Strait only reads them.
Toolskubectl, helm, wg from wireguard-tools, and the strait CLI (Install, on Windows).
A shellThe commands are for bash. On Windows, a line that runs only strait or kubectl strait works as written in PowerShell. The others need bash, for example in WSL.

The chart value cnpg.enabled turns on the cnpg plugin, which is two things: the chart's read-only rule for postgresql.cnpg.io, and the controller's flag --cnpg. While it is on, the controller watches CloudNativePG's kinds if their CRDs exist when the controller starts (RFC0003, requirement 13).

Clustercnpg.enabled
Runs a SiteService with the cnpg plugintrue, the default. With false, each of its members at this site is Unknown, reason PluginDisabled.
Runs no SiteService with the cnpg plugintrue or false.
Gets CloudNativePG after Straittrue. Install CloudNativePG, then restart the controller, for example kubectl --context site-a -n strait-system rollout restart deployment/strait-controller.

Names used at both sites:

ItemValue
Strait namespacestrait-system
Helm releasestrait
WireGuard Secretstrait-wireguard, key privateKey
WireGuard listen port32100
Tunnel addressesSite a 100.64.0.1/30, site b 100.64.0.2/30

1. Namespace and WireGuard key ​

At each site, create the namespace with the Pod Security level privileged, and a Secret that holds a new WireGuard private key:

sh
for s in a b; do
  kubectl --context site-$s create namespace strait-system
  kubectl --context site-$s label namespace strait-system pod-security.kubernetes.io/enforce=privileged
  wg genkey | kubectl --context site-$s -n strait-system create secret generic strait-wireguard \
    --from-file=privateKey=/dev/stdin
done

The private key goes from wg genkey straight into the Secret, and is never printed or written to a file. Each site has its own key.

2. Install the chart ​

values-a.yaml:

yaml
site:
  name: a
  spec:
    wireguard:
      privateKeySecretRef:
        name: strait-wireguard

values-b.yaml is the same, with name: b.

ValueWhy
site.nameThe site's name. Members and peers refer to it. Required.
site.specThe Site's spec, as in api/v1. The chart renders the Site from it.
site.spec.wireguard.privateKeySecretRef.nameThe Secret from step 1. The chart lets the gateway agent read this Secret and no other.

Size gateway.resources.envoy to the site's traffic: Envoy slows down when its node runs short of CPU (benchmark). Every other value is in values.yaml.

Check the rendered Site, then install at both sites:

sh
helm template strait oci://ghcr.io/takodotid/charts/strait --version 1.5.0 \
  --namespace strait-system --values values-a.yaml | strait validate -f -

for s in a b; do
  helm --kube-context site-$s install strait oci://ghcr.io/takodotid/charts/strait --version 1.5.0 \
    --namespace strait-system --values values-$s.yaml --wait
done

strait status now shows each site, its controller's version, its active gateway pod, and the site's WireGuard public key:

sh
strait --context site-a status
strait --context site-b status

3. Join the sites ​

Read each site's public key. The active gateway agent writes it into the Site's status once it has read the Secret. Both values must be set before the next step.

sh
A_KEY=$(kubectl --context site-a get site a -o jsonpath='{.status.wireGuardPublicKey}')
B_KEY=$(kubectl --context site-b get site b -o jsonpath='{.status.wireGuardPublicKey}')

Site a declares its peer b and a link that waits for b to dial:

sh
cat > site-a.yaml <<EOF
apiVersion: strait.tako.id/v1
kind: SitePeer
metadata:
  name: b
spec:
  wireguard:
    publicKey: ${B_KEY}
---
apiVersion: strait.tako.id/v1
kind: SiteLink
metadata:
  name: b-wan
spec:
  peer: b
  transport: wireguard
  wireguard:
    listenPort: 32100
    address: 100.64.0.1/30
    peerAddress: 100.64.0.2
EOF

Site b declares its peer a and a link that dials a node of site a:

sh
cat > site-b.yaml <<EOF
apiVersion: strait.tako.id/v1
kind: SitePeer
metadata:
  name: a
spec:
  wireguard:
    publicKey: ${A_KEY}
---
apiVersion: strait.tako.id/v1
kind: SiteLink
metadata:
  name: a-wan
spec:
  peer: a
  transport: wireguard
  wireguard:
    listenPort: 32100
    endpoint: 203.0.113.10:32100
    address: 100.64.0.2/30
    peerAddress: 100.64.0.1
EOF
FieldValue hereWhy
SitePeer nameThe peer's site.nameA peer's observation document names its site. A document whose site differs from the SitePeer's name is rejected.
wireguard.publicKeyThe peer's public keyThe link accepts only this key.
wireguard.listenPort32100The gateway's WireGuard Service is a NodePort by default, and each node port is the same number as its port. The listen port must be in the cluster's node port range, 30000-32767 by default. The default listen port, 31820, is in it.
wireguard.endpointSite b onlySite b dials, and keeps the path open with keepalives. Site a waits. Traffic flows both ways once b has dialed.
wireguard.address, wireguard.peerAddressA /30 that no other network at either site usesThe tunnel's addresses. They live in the gateway pods only.

Check each site's objects together with its Site. The output must end with Errors: 0. Warnings: 0.:

sh
for s in a b; do
  helm template strait oci://ghcr.io/takodotid/charts/strait --version 1.5.0 \
    --namespace strait-system --values values-$s.yaml | strait validate -f - -f site-$s.yaml
done

Apply:

sh
kubectl --context site-a apply -f site-a.yaml
kubectl --context site-b apply -f site-b.yaml

Check the link and the peer at each site:

sh
strait --context site-a links
strait --context site-a peers
strait --context site-b links
strait --context site-b peers
CommandExpected
strait linksThe link to the peer: HEALTHY true, ACTIVE true.
strait peersThe peer: REACHABLE true, LAST SEEN a few seconds ago.

If not, see Troubleshooting.

4. Point a name at the database ​

pg.yaml, the same at both sites:

yaml
apiVersion: strait.tako.id/v1
kind: SiteService
metadata:
  name: pg
  namespace: app
spec:
  mode: Single
  port:
    name: postgres
    port: 5432
  plugin:
    cnpg:
      role: primary
  members:
    - name: pg-a
      site: a
      cnpg:
        cluster: pg-a
    - name: pg-b
      site: b
      cnpg:
        cluster: pg-b
  policy:
    unknownHold: 30s
FieldMeans
metadata.name, metadata.namespaceThe application name: Service pg in namespace app. Strait creates and owns it.
spec.mode: SingleRoute to the one writable member.
spec.plugin.cnpg.role: primaryObserve CloudNativePG Clusters, and route to the primary.
spec.plugin.cnpg.confirmRoleOptional, off unless true. Also ask each local database pg_is_in_recovery(), and count a member as Unknown when the answer disagrees with the Cluster, or there is none. Needs a role with LOGIN and nothing else, and its Secret named in the chart value cnpg.confirmRole.secretName. RFC0003, Confirming the role.
spec.membersOne member per Cluster, with the site that hosts it. Each site observes only its own members.
spec.policy.unknownHoldHow long a routed member stays in the route while its site cannot be read.
spec.policy.startupHoldOptional, off unless set. After the controller starts, the time it waits to read every other site before it routes to a local member. With it, a site that was lost and comes back still primary does not serve writes until it has seen what the other sites declare. RFC0002, Startup hold.
spec.policy.connectionsOptional. Keep, the default, keeps every established connection when the route changes. EndGateway ends the sessions through this site's gateway to a member that leaves the route, so that remote clients reconnect to the new one. Open transactions on them fail. Local clients keep their sessions. Needs the chart value envoy.drainTimeSeconds set to a few seconds. RFC0002, What EndGateway covers and costs.
spec.policy.isolationTimeoutOptional, off unless set. A site that has read no other site for this long stops routing to its own member, so its clients stop writing to a primary that another site may replace. Turn it on with three or more sites, or when a site that loses the others must stop writing. With two sites, the site that survives a site loss stops too, until the operator sets it to 0s there. RFC0002, The isolated-site policy.

Every field and rule: RFC0002.

Check, then apply at both sites:

sh
strait validate -f pg.yaml
kubectl --context site-a apply -f pg.yaml
kubectl --context site-b apply -f pg.yaml

5. Check the route ​

sh
strait --context site-a status -n app
strait --context site-b explain pg -n app

While pg-a is the primary:

SiteROUTEREASONPATH of pg-a in strait explain
apg-aActiveLocal: its own pods.
bpg-aActiveGateway: gateway b, over the link.

Applications at both sites connect to pg.app.svc:5432. A client that checks the server's host name, such as one with sslmode=verify-full, needs that name in each Cluster's spec.certificates.serverAltDNSNames.

To move the primary, use CloudNativePG's own procedure for its distributed topology. Strait follows: both sites route nowhere while the primary moves, then route to pg-b. The sequence: RFC0002, why declarations matter.

A private path between the sites, if there is one, can carry the traffic with no tunnel. Give its link a lower cost: it carries the traffic while it is healthy, and the WireGuard link takes over within 5 seconds when it fails.

At site a:

yaml
apiVersion: strait.tako.id/v1
kind: SiteLink
metadata:
  name: b-direct
spec:
  peer: b
  transport: direct
  encryption: None
  cost: 10
  direct:
    address: 192.0.2.21

Site b gets the same with name: a-direct, peer: a, and site a's address.

Field or valueMeans
encryption: NoneRequired on a direct link. Traffic crosses it in clear.
cost: 10Lower than the WireGuard link's default, 100.
direct.addressThe peer gateway's IP address on the private path.
site.spec.gateway.directServiceHow peers reach the control port and the export ports over the direct link. It is ClusterIP by default, which a peer cannot reach over a direct link. Set it in the chart's values, then run helm upgrade. Expose it on the private path only. NodePort suits nodes that no other network reaches. Otherwise use LoadBalancer, with the annotations that make the load balancer internal. Only the peer gateways need to reach it. The fields that let only them in: RFC0007, Sources of the gateway Services.

With endpointDirect: true on the direct link, and pod addresses routable between the sites, the name points straight at the remote member's pods, with no gateway hop (RFC0005). In production, set endpointCIDRs on that link to the peer's pod CIDRs, so a peer's document cannot point the name anywhere else. Without it, strait validate warns, and the link's condition EndpointsLimited is False.

Next ​

TopicWhere
The checks before productionBefore production
A name routed nowhere, Unknown members, unhealthy linksTroubleshooting
Every command and flagstrait --help, the man pages
Design and rulesrfcs/

Released under the Apache License 2.0.