From fb198ac99c45f49a2121e929eaf9b74a7e294c08 Mon Sep 17 00:00:00 2001
From: Eric Paulsen <ericpaulsen@coder.com>
Date: Sat, 24 Feb 2024 20:16:56 -0500
Subject: [PATCH] docs: add steps for postgres server verification (#12072)

* docs: add steps for postgres server verification

* make: fmt

* refactor to guide

* add manifest
---
 docs/guides/postgres-ssl.md | 77 +++++++++++++++++++++++++++++++++++++
 docs/install/kubernetes.md  | 33 +++++++++++++++-
 docs/manifest.json          |  5 +++
 3 files changed, 114 insertions(+), 1 deletion(-)
 create mode 100644 docs/guides/postgres-ssl.md

diff --git a/docs/guides/postgres-ssl.md b/docs/guides/postgres-ssl.md
new file mode 100644
index 0000000000..f1934b60e9
--- /dev/null
+++ b/docs/guides/postgres-ssl.md
@@ -0,0 +1,77 @@
+# Configure Coder to connect to PostgreSQL using SSL
+
+<div>
+  <a href="https://github.com/ericpaulsen" style="text-decoration: none; color: inherit;">
+    <span style="vertical-align:middle;">Eric Paulsen</span>
+    <img src="https://github.com/ericpaulsen.png" width="24px" height="24px" style="vertical-align:middle; margin: 0px;"/>
+  </a>
+</div>
+February 24, 2024
+
+---
+
+Your organization may require connecting to the database instance over SSL. To
+supply Coder with the appropriate certificates, and have it connect over SSL,
+follow the steps below:
+
+## Client verification (server verifies the client)
+
+1. Create the certificate as a secret in your Kubernetes cluster, if not already
+   present:
+
+```shell
+kubectl create secret tls postgres-certs -n coder --key="postgres.key" --cert="postgres.crt"
+```
+
+1. Define the secret volume and volumeMounts in the Helm chart:
+
+```yaml
+coder:
+  volumes:
+    - name: "pg-certs-mount"
+      secret:
+        secretName: "postgres-certs"
+  volumeMounts:
+    - name: "pg-certs-mount"
+      mountPath: "$HOME/.postgresql"
+      readOnly: true
+```
+
+1. Lastly, your PG connection URL will look like:
+
+```shell
+postgres://<user>:<password>@databasehost:<port>/<db-name>?sslmode=require&sslcert="$HOME/.postgresql/postgres.crt&sslkey=$HOME/.postgresql/postgres.key"
+```
+
+## Server verification (client verifies the server)
+
+1. Download the CA certificate chain for your database instance, and create it
+   as a secret in your Kubernetes cluster, if not already present:
+
+```shell
+kubectl create secret tls postgres-certs -n coder --key="postgres-root.key" --cert="postgres-root.crt"
+```
+
+1. Define the secret volume and volumeMounts in the Helm chart:
+
+```yaml
+coder:
+  volumes:
+    - name: "pg-certs-mount"
+      secret:
+        secretName: "postgres-certs"
+  volumeMounts:
+    - name: "pg-certs-mount"
+      mountPath: "$HOME/.postgresql/postgres-root.crt"
+      readOnly: true
+```
+
+1. Lastly, your PG connection URL will look like:
+
+```shell
+postgres://<user>:<password>@databasehost:<port>/<db-name>?sslmode=verify-full&sslrootcert="/home/coder/.postgresql/postgres-root.crt"
+```
+
+> More information on connecting to PostgreSQL databases using certificates can
+> be found
+> [here](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT).
diff --git a/docs/install/kubernetes.md b/docs/install/kubernetes.md
index 4458ae17b7..654b902aa9 100644
--- a/docs/install/kubernetes.md
+++ b/docs/install/kubernetes.md
@@ -198,6 +198,8 @@ Your organization may require connecting to the database instance over SSL. To
 supply Coder with the appropriate certificates, and have it connect over SSL,
 follow the steps below:
 
+### Client verification (server verifies the client)
+
 1. Create the certificate as a secret in your Kubernetes cluster, if not already
    present:
 
@@ -222,7 +224,36 @@ coder:
 1. Lastly, your PG connection URL will look like:
 
 ```shell
-postgres://<user>:<password>@databasehost:<port>/<db-name>?sslmode=require&sslcert=$HOME/.postgresql/postgres.crt&sslkey=$HOME/.postgresql/postgres.key"
+postgres://<user>:<password>@databasehost:<port>/<db-name>?sslmode=require&sslcert="$HOME/.postgresql/postgres.crt&sslkey=$HOME/.postgresql/postgres.key"
+```
+
+### Server verification (client verifies the server)
+
+1. Download the CA certificate chain for your database instance, and create it
+   as a secret in your Kubernetes cluster, if not already present:
+
+```shell
+kubectl create secret tls postgres-certs -n coder --key="postgres-root.key" --cert="postgres-root.crt"
+```
+
+1. Define the secret volume and volumeMounts in the Helm chart:
+
+```yaml
+coder:
+  volumes:
+    - name: "pg-certs-mount"
+      secret:
+        secretName: "postgres-certs"
+  volumeMounts:
+    - name: "pg-certs-mount"
+      mountPath: "$HOME/.postgresql/postgres-root.crt"
+      readOnly: true
+```
+
+1. Lastly, your PG connection URL will look like:
+
+```shell
+postgres://<user>:<password>@databasehost:<port>/<db-name>?sslmode=verify-full&sslrootcert="/home/coder/.postgresql/postgres-root.crt"
 ```
 
 > More information on connecting to PostgreSQL databases using certificates can
diff --git a/docs/manifest.json b/docs/manifest.json
index 4bfaf6aadb..1b70f9147d 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -1060,6 +1060,11 @@
           "description": "Creating ImagePullSecrets for private registries",
           "path": "./guides/image-pull-secret.md"
         },
+        {
+          "title": "Postgres SSL",
+          "description": "Configure Coder to connect to Postgres over SSL",
+          "path": "./guides/postgres-ssl.md"
+        },
         {
           "title": "Azure Federation",
           "description": "Federating Coder to Azure",