From a4d7c073fd6b41437542a2be5c4875350e8aaf26 Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Fri, 23 Apr 2021 15:02:11 -0500 Subject: [PATCH 1/5] feat: connecting an external postgres --- guides/deployments/postgres.md | 109 +++++++++++++++++++++++++++++++++ manifest.json | 3 + 2 files changed, 112 insertions(+) create mode 100644 guides/deployments/postgres.md diff --git a/guides/deployments/postgres.md b/guides/deployments/postgres.md new file mode 100644 index 000000000..0cd276595 --- /dev/null +++ b/guides/deployments/postgres.md @@ -0,0 +1,109 @@ +--- +title: "Connect an External PostgreSQL" +description: "Learn how connect Coder to an external postgreSQL database." +--- + +This guide walks through the steps to deploying Coder with an external +PostgreSQL database connected. + +## Connecting to an external PostgreSQL + +By default, Coder will deploy a [TimescaleDB](https://www.timescale.com) inside +the Kubernetes cluster used to install Coder. However, this is _only_ +recommended for evaluation purposes, as the database is not backed up, and can +be lost if the cluster goes down. + +For those reasons, we recommend bringing in your own PostgreSQL for production +deployments, and hosting it external to the cluster. Below are the steps to do +so: + +1. Spin up a PostgreSQL instance if you have not already done so + +1. Configure a private IP address for the PostgreSQL instance + +- This private IP will be referenced in the Coder helm chart configuration + +1. If your PostgreSQL instance has a password, follow the below: + +- Open the terminal, connect to your cluster and create a secret: + + ```console + kubectl create secret generic \ + --from-literal=password= \ + ``` + +1. Get the port number for your PostgreSQL instance + +- When you install PostgreSQL, the default port number is set to `5432`. + Otherwise, you can get the port number by running the following in your + database: + +```sql +SELECT * +FROM pg_settings +WHERE name = 'port'; +``` + +1. Get the user of the PostgreSQL instance + +- You can find the user by running the following command in your database: + +```sql +\du +``` + +1. Get the name of the database _within_ your PostgreSQL instance + +- You can get the name of the current database you are working in by running the + following command in your database: + +```sql +SELECT current_database(); +``` + +1. Get the name of the secret you created for the database password + +- You can get the secret name by running the following command: + +```console +kubectl get secrets -n +``` + +From there, we can now modify the helm chart to include the PostgreSQL values we +received above, which are necessary for completing the connection. To get your +current helm chart and save it to a file, run the following command in your +terminal: + +```console +helm helm get values --namespace coder > current-values.yml +``` + +Next, modify the helm chart fields with the values below: + +```yaml +postgres: + useDefault: false + host: "" + port: "" + user: "" + database: "" + passwordSecret: "" +``` + +Once complete, you can now install (or upgrade) your Coder instance with the +modified helm chart using the following commands: + +- For install: + +```console +helm install coder coder/coder -n --version= -f current-values.yml +``` + +- For upgrading: + +```console +helm upgrade coder coder/coder -n --version= -f current-values.yml +``` + +If successful, you should be able to access your Coder application from the +`EXTERNAL_IP` of the ingress controller in your cluster. diff --git a/manifest.json b/manifest.json index eb67f000b..4dec804bb 100644 --- a/manifest.json +++ b/manifest.json @@ -297,6 +297,9 @@ }, { "path": "./guides/deployments/teardown.md" + }, + { + "path": "./guides/deployments/external-postgres.md" } ] }, From b2f89b3e32cc89c19f23d3b8a4d5d28fbc087fd4 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 28 Apr 2021 10:57:31 -0500 Subject: [PATCH 2/5] Edit text --- guides/deployments/postgres.md | 124 +++++++++++++++------------------ 1 file changed, 58 insertions(+), 66 deletions(-) diff --git a/guides/deployments/postgres.md b/guides/deployments/postgres.md index 0cd276595..7e0c50666 100644 --- a/guides/deployments/postgres.md +++ b/guides/deployments/postgres.md @@ -1,84 +1,76 @@ --- -title: "Connect an External PostgreSQL" +title: "PostgreSQL" description: "Learn how connect Coder to an external postgreSQL database." --- -This guide walks through the steps to deploying Coder with an external -PostgreSQL database connected. +This guide walks you through deploying Coder with an external PostgreSQL +database. -## Connecting to an external PostgreSQL +## Background -By default, Coder will deploy a [TimescaleDB](https://www.timescale.com) inside -the Kubernetes cluster used to install Coder. However, this is _only_ -recommended for evaluation purposes, as the database is not backed up, and can -be lost if the cluster goes down. +By default, Coder deploys a [TimescaleDB](https://www.timescale.com) inside the +Kubernetes cluster to which you've installed Coder. However, we recommend this +**only for evaluation purposes**, since the database isn't backed up and can be +lost if the cluster goes down. -For those reasons, we recommend bringing in your own PostgreSQL for production -deployments, and hosting it external to the cluster. Below are the steps to do -so: +As such, we strongly recommend using a PostgreSQL database for production +deployments and hosting it **outside** the Kubernetes cluster hosting Coder. -1. Spin up a PostgreSQL instance if you have not already done so +1. Set up a PostgreSQL instance (if you don't already have one that you can use + with Coder). How you can do this depends on your cloud provider, but the + following resources are good starting points: -1. Configure a private IP address for the PostgreSQL instance + - [Amazon Relational Database Service (RDS) backup & restore using AWS + Backup](https://aws.amazon.com/getting-started/hands-on/amazon-rds-backup-restore-using-aws-backup) + - [Quickstart: Create an Azure Database for PostgreSQL server by using the + Azure + portal](https://docs.microsoft.com/en-us/azure/postgresql/quickstart-create-server-database-portal) + - [Deploying highly available PostgreSQL with + GKE](https://cloud.google.com/architecture/deploying-highly-available-postgresql-with-gke) -- This private IP will be referenced in the Coder helm chart configuration +1. Configure a private IP address for use with your PostgreSQL instance (you'll + need to refer to this IP address in your [Helm + chart](../admin/helm-charts.md)). -1. If your PostgreSQL instance has a password, follow the below: +1. If your PostgreSQL instance requires a password, open the terminal, connect + to your cluster, and create a secret for the password: -- Open the terminal, connect to your cluster and create a secret: + ```console + kubectl create secret generic --from-file=test=/dev/stdin + ``` - ```console - kubectl create secret generic \ - --from-literal=password= \ - ``` +1. Get the port number for your PostgreSQL instance: -1. Get the port number for your PostgreSQL instance + ```sql + SELECT * + FROM pg_settings + WHERE name = 'port'; + ``` -- When you install PostgreSQL, the default port number is set to `5432`. - Otherwise, you can get the port number by running the following in your - database: +1. Get the user of the PostgreSQL instance: -```sql -SELECT * -FROM pg_settings -WHERE name = 'port'; -``` - -1. Get the user of the PostgreSQL instance - -- You can find the user by running the following command in your database: - -```sql -\du -``` - -1. Get the name of the database _within_ your PostgreSQL instance - -- You can get the name of the current database you are working in by running the - following command in your database: + ```sql + \du + ``` -```sql -SELECT current_database(); -``` - -1. Get the name of the secret you created for the database password +1. Get the name of the database *within* your PostgreSQL instance in which + you're currently working: -- You can get the secret name by running the following command: + ```sql + SELECT current_database(); + ``` -```console -kubectl get secrets -n -``` +1. Get the name of the secret you created for your PostgreSQL instance's + password: -From there, we can now modify the helm chart to include the PostgreSQL values we -received above, which are necessary for completing the connection. To get your -current helm chart and save it to a file, run the following command in your -terminal: - -```console -helm helm get values --namespace coder > current-values.yml -``` + ```console + kubectl get secrets -n + ``` -Next, modify the helm chart fields with the values below: +At this point, you can [modify your Helm chart](../admin/helm-charts.md) to +include the database name, port number, user, and password secret that you +identified in the previous steps (these values are required to connect to your +PostgreSQL instance): ```yaml postgres: @@ -90,20 +82,20 @@ postgres: passwordSecret: "" ``` -Once complete, you can now install (or upgrade) your Coder instance with the -modified helm chart using the following commands: +At this point, you can install/upgrade your Coder instance using the updated +Helm chart. -- For install: +To install Coder: ```console helm install coder coder/coder -n --version= -f current-values.yml ``` -- For upgrading: +To upgrade Coder: ```console helm upgrade coder coder/coder -n --version= -f current-values.yml ``` -If successful, you should be able to access your Coder application from the -`EXTERNAL_IP` of the ingress controller in your cluster. +If this process is successful, you'll be able to access Coder using the external +IP address of the ingress controller in your cluster. From 5dd918c70dc42575c9d594b122d57c7026b2b2dc Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 28 Apr 2021 10:58:08 -0500 Subject: [PATCH 3/5] Update secret create instructions in install --- setup/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup/installation.md b/setup/installation.md index a4a52afb2..1a33e39a7 100644 --- a/setup/installation.md +++ b/setup/installation.md @@ -85,7 +85,7 @@ kubectl config set-context --current --namespace=coder ``` To create the `passwordSecret`, run - `kubectl create secret generic secret-name --from-literal=password=UserDefinedPassword` + `kubectl create secret generic --from-file=test=/dev/stdin` (be sure to replace `UserDefinedPassword` with your actual password). You can find/define these values in your From 0728e1aeb37376751d35f4dc6c8ffcdc95b12be5 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 28 Apr 2021 11:52:49 -0500 Subject: [PATCH 4/5] Update manifest.json --- manifest.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manifest.json b/manifest.json index 4dec804bb..5660a2726 100644 --- a/manifest.json +++ b/manifest.json @@ -299,7 +299,7 @@ "path": "./guides/deployments/teardown.md" }, { - "path": "./guides/deployments/external-postgres.md" + "path": "./guides/deployments/postgres.md" } ] }, From 24a81570ce78fc3fcc16ea694a68a8edabb8b641 Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Wed, 28 Apr 2021 15:02:18 -0500 Subject: [PATCH 5/5] add link to guide --- setup/installation.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/setup/installation.md b/setup/installation.md index 1a33e39a7..72f125ec1 100644 --- a/setup/installation.md +++ b/setup/installation.md @@ -91,6 +91,9 @@ kubectl config set-context --current --namespace=coder You can find/define these values in your [PostgreSQL server configuration file](https://www.postgresql.org/docs/current/config-setting.html). + > For more information, [see our guide](../guides/deployments/postgres.md) on + setting up a PostgreSQL instance. + 1. [Enable dev URL usage](../admin/devurls.md). Dev URLs allow users to access the web servers running in your workspace. To enable, provide a wildcard domain and its DNS certificate and update your helm chart accordingly. This