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
| Requirement | Detail |
|---|---|
| Two Kubernetes clusters | One per site, of a version that Install supports, reached with the kubeconfig contexts site-a and site-b. |
Kernel modules wireguard and nf_tables | On 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 privileged | In 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 a | Site 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 pods | Recommended, 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. |
| CloudNativePG | At 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. |
| Tools | kubectl, helm, wg from wireguard-tools, and the strait CLI (Install, on Windows). |
| A shell | The 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).
| Cluster | cnpg.enabled |
|---|---|
Runs a SiteService with the cnpg plugin | true, the default. With false, each of its members at this site is Unknown, reason PluginDisabled. |
Runs no SiteService with the cnpg plugin | true or false. |
| Gets CloudNativePG after Strait | true. 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:
| Item | Value |
|---|---|
| Strait namespace | strait-system |
| Helm release | strait |
| WireGuard Secret | strait-wireguard, key privateKey |
| WireGuard listen port | 32100 |
| Tunnel addresses | Site 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:
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
doneThe 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:
site:
name: a
spec:
wireguard:
privateKeySecretRef:
name: strait-wireguardvalues-b.yaml is the same, with name: b.
| Value | Why |
|---|---|
site.name | The site's name. Members and peers refer to it. Required. |
site.spec | The Site's spec, as in api/v1. The chart renders the Site from it. |
site.spec.wireguard.privateKeySecretRef.name | The 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:
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
donestrait status now shows each site, its controller's version, its active gateway pod, and the site's WireGuard public key:
strait --context site-a status
strait --context site-b status3. 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.
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:
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
EOFSite b declares its peer a and a link that dials a node of site a:
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| Field | Value here | Why |
|---|---|---|
SitePeer name | The peer's site.name | A peer's observation document names its site. A document whose site differs from the SitePeer's name is rejected. |
wireguard.publicKey | The peer's public key | The link accepts only this key. |
wireguard.listenPort | 32100 | The 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.endpoint | Site b only | Site b dials, and keeps the path open with keepalives. Site a waits. Traffic flows both ways once b has dialed. |
wireguard.address, wireguard.peerAddress | A /30 that no other network at either site uses | The 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.:
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
doneApply:
kubectl --context site-a apply -f site-a.yaml
kubectl --context site-b apply -f site-b.yamlCheck the link and the peer at each site:
strait --context site-a links
strait --context site-a peers
strait --context site-b links
strait --context site-b peers| Command | Expected |
|---|---|
strait links | The link to the peer: HEALTHY true, ACTIVE true. |
strait peers | The 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:
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| Field | Means |
|---|---|
metadata.name, metadata.namespace | The application name: Service pg in namespace app. Strait creates and owns it. |
spec.mode: Single | Route to the one writable member. |
spec.plugin.cnpg.role: primary | Observe CloudNativePG Clusters, and route to the primary. |
spec.plugin.cnpg.confirmRole | Optional, 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.members | One member per Cluster, with the site that hosts it. Each site observes only its own members. |
spec.policy.unknownHold | How long a routed member stays in the route while its site cannot be read. |
spec.policy.startupHold | Optional, 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.connections | Optional. 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.isolationTimeout | Optional, 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:
strait validate -f pg.yaml
kubectl --context site-a apply -f pg.yaml
kubectl --context site-b apply -f pg.yaml5. Check the route
strait --context site-a status -n app
strait --context site-b explain pg -n appWhile pg-a is the primary:
| Site | ROUTE | REASON | PATH of pg-a in strait explain |
|---|---|---|---|
| a | pg-a | Active | Local: its own pods. |
| b | pg-a | Active | Gateway: 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.
6. Add a direct link
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:
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.21Site b gets the same with name: a-direct, peer: a, and site a's address.
| Field or value | Means |
|---|---|
encryption: None | Required on a direct link. Traffic crosses it in clear. |
cost: 10 | Lower than the WireGuard link's default, 100. |
direct.address | The peer gateway's IP address on the private path. |
site.spec.gateway.directService | How 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
| Topic | Where |
|---|---|
| The checks before production | Before production |
| A name routed nowhere, Unknown members, unhealthy links | Troubleshooting |
| Every command and flag | strait --help, the man pages |
| Design and rules | rfcs/ |