Skip to content

Conversation

@jason-lynch
Copy link
Member

@jason-lynch jason-lynch commented Dec 16, 2025

Summary

Adds a new docs page that describes how to configure mTLS in the Control Plane and demonstrates this feature with it with a tutorial.

Testing

If you want to test the tutorial with the Lima test fixture, you'll need to make some modifications to the instructions to use your IP addresses and to include the peer IP as a SAN in each server certificate. For example, these were the modifications I used to test this:

step certificate create tutorial ./ca.crt ./ca.key \
  --no-password \
  --insecure \
  --profile=root-ca \
  --not-after 8760h

step certificate create lima-host-1 lima-host-1.crt lima-host-1.key \
  --san '192.168.105.2' \
  --san '192.168.104.3' \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key

step certificate create lima-host-2 lima-host-2.crt lima-host-2.key \
  --san '192.168.105.3' \
  --san '192.168.104.4' \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key

step certificate create lima-host-3 lima-host-3.crt lima-host-3.key \
  --san '192.168.105.4' \
  --san '192.168.104.5' \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key

step certificate create client client.crt client.key \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key

ssh -F ~/.lima/host-1/ssh.config lima-host-1 'sudo mkdir -p /opt/pgedge/control-plane'
ssh -F ~/.lima/host-2/ssh.config lima-host-2 'sudo mkdir -p /opt/pgedge/control-plane'
ssh -F ~/.lima/host-3/ssh.config lima-host-3 'sudo mkdir -p /opt/pgedge/control-plane'

ssh -F ~/.lima/host-1/ssh.config lima-host-1 'sudo tee /opt/pgedge/control-plane/ca.crt > /dev/null' < ./ca.crt
ssh -F ~/.lima/host-1/ssh.config lima-host-1 'sudo tee /opt/pgedge/control-plane/server.crt > /dev/null' < ./lima-host-1.crt
ssh -F ~/.lima/host-1/ssh.config lima-host-1 'sudo tee /opt/pgedge/control-plane/server.key > /dev/null' < ./lima-host-1.key

ssh -F ~/.lima/host-2/ssh.config lima-host-2 'sudo tee /opt/pgedge/control-plane/ca.crt > /dev/null' < ./ca.crt
ssh -F ~/.lima/host-2/ssh.config lima-host-2 'sudo tee /opt/pgedge/control-plane/server.crt > /dev/null' < ./lima-host-2.crt
ssh -F ~/.lima/host-2/ssh.config lima-host-2 'sudo tee /opt/pgedge/control-plane/server.key > /dev/null' < ./lima-host-2.key

ssh -F ~/.lima/host-3/ssh.config lima-host-3 'sudo tee /opt/pgedge/control-plane/ca.crt > /dev/null' < ./ca.crt
ssh -F ~/.lima/host-3/ssh.config lima-host-3 'sudo tee /opt/pgedge/control-plane/server.crt > /dev/null' < ./lima-host-3.crt
ssh -F ~/.lima/host-3/ssh.config lima-host-3 'sudo tee /opt/pgedge/control-plane/server.key > /dev/null' < ./lima-host-3.key

I also recommend running these commands to sync each VM's clock if they were running while your laptop was in sleep:

ssh -F ~/.lima/host-1/ssh.config lima-host-1 'sudo chronyc makestep'
ssh -F ~/.lima/host-2/ssh.config lima-host-2 'sudo chronyc makestep'
ssh -F ~/.lima/host-3/ssh.config lima-host-3 'sudo chronyc makestep'

Also, make sure you set PGEDGE_IPV4_ADDRESS to the peer IP address for each host in your stack.

PLAT-302

@jason-lynch jason-lynch force-pushed the docs/PLAT-302/mtls-docs branch from 44c54a9 to 4703259 Compare December 17, 2025 13:04
@jason-lynch jason-lynch marked this pull request as draft December 17, 2025 14:30
Adds a new docs page that describes how to configure mTLS in the
Control Plane and demonstrates this feature with it with a tutorial.

If you want to test the tutorial with the Lima test fixture, you'll need
to make some modifications to the instructions to use your IP addresses
and to include the peer IP as a SAN in each server certificate. For
example, these were the modifications I used to test this:

```sh
step certificate create tutorial ./ca.crt ./ca.key \
  --no-password \
  --insecure \
  --profile=root-ca \
  --not-after 8760h

step certificate create lima-host-1 lima-host-1.crt lima-host-1.key \
  --san '192.168.105.2' \
  --san '192.168.104.3' \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key

step certificate create lima-host-2 lima-host-2.crt lima-host-2.key \
  --san '192.168.105.3' \
  --san '192.168.104.4' \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key

step certificate create lima-host-3 lima-host-3.crt lima-host-3.key \
  --san '192.168.105.4' \
  --san '192.168.104.5' \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key

step certificate create client client.crt client.key \
  --no-password \
  --insecure \
  --profile leaf \
  --not-after 2160h \
  --ca ./ca.crt \
  --ca-key ./ca.key

ssh -F ~/.lima/host-1/ssh.config lima-host-1 'sudo mkdir -p /opt/pgedge/control-plane'
ssh -F ~/.lima/host-2/ssh.config lima-host-2 'sudo mkdir -p /opt/pgedge/control-plane'
ssh -F ~/.lima/host-3/ssh.config lima-host-3 'sudo mkdir -p /opt/pgedge/control-plane'

ssh -F ~/.lima/host-1/ssh.config lima-host-1 'sudo tee /opt/pgedge/control-plane/ca.crt > /dev/null' < ./ca.crt
ssh -F ~/.lima/host-1/ssh.config lima-host-1 'sudo tee /opt/pgedge/control-plane/server.crt > /dev/null' < ./lima-host-1.crt
ssh -F ~/.lima/host-1/ssh.config lima-host-1 'sudo tee /opt/pgedge/control-plane/server.key > /dev/null' < ./lima-host-1.key

ssh -F ~/.lima/host-2/ssh.config lima-host-2 'sudo tee /opt/pgedge/control-plane/ca.crt > /dev/null' < ./ca.crt
ssh -F ~/.lima/host-2/ssh.config lima-host-2 'sudo tee /opt/pgedge/control-plane/server.crt > /dev/null' < ./lima-host-2.crt
ssh -F ~/.lima/host-2/ssh.config lima-host-2 'sudo tee /opt/pgedge/control-plane/server.key > /dev/null' < ./lima-host-2.key

ssh -F ~/.lima/host-3/ssh.config lima-host-3 'sudo tee /opt/pgedge/control-plane/ca.crt > /dev/null' < ./ca.crt
ssh -F ~/.lima/host-3/ssh.config lima-host-3 'sudo tee /opt/pgedge/control-plane/server.crt > /dev/null' < ./lima-host-3.crt
ssh -F ~/.lima/host-3/ssh.config lima-host-3 'sudo tee /opt/pgedge/control-plane/server.key > /dev/null' < ./lima-host-3.key
```

I also recommend running these commands to sync each VM's clock if
they were running while your laptop was in sleep:

```
ssh -F ~/.lima/host-1/ssh.config lima-host-1 'sudo chronyc makestep'
ssh -F ~/.lima/host-2/ssh.config lima-host-2 'sudo chronyc makestep'
ssh -F ~/.lima/host-3/ssh.config lima-host-3 'sudo chronyc makestep'
```

Also, make sure you set PGEDGE_IPV4_ADDRESS to the peer IP address for
each host in your stack.

PLAT-302
@jason-lynch jason-lynch force-pushed the docs/PLAT-302/mtls-docs branch from 4703259 to b459e38 Compare December 17, 2025 14:43
@jason-lynch jason-lynch marked this pull request as ready for review December 17, 2025 14:44
@mmols mmols merged commit 49a16a2 into main Dec 17, 2025
2 checks passed
@mmols mmols deleted the docs/PLAT-302/mtls-docs branch December 17, 2025 17:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants