diff --git a/docs/other-tools/postgres/images/connection-properties.png b/docs/other-tools/postgres/images/connection-properties.png new file mode 100644 index 000000000..135e837fc Binary files /dev/null and b/docs/other-tools/postgres/images/connection-properties.png differ diff --git a/docs/other-tools/postgres/images/crunchy_postgres_for_K8s_operator.png b/docs/other-tools/postgres/images/crunchy_postgres_for_K8s_operator.png new file mode 100644 index 000000000..30bbb2a16 Binary files /dev/null and b/docs/other-tools/postgres/images/crunchy_postgres_for_K8s_operator.png differ diff --git a/docs/other-tools/postgres/images/pgadmin-console.png b/docs/other-tools/postgres/images/pgadmin-console.png new file mode 100644 index 000000000..366bd5451 Binary files /dev/null and b/docs/other-tools/postgres/images/pgadmin-console.png differ diff --git a/docs/other-tools/postgres/images/pgadmin-database-explorer.png b/docs/other-tools/postgres/images/pgadmin-database-explorer.png new file mode 100644 index 000000000..cead87f39 Binary files /dev/null and b/docs/other-tools/postgres/images/pgadmin-database-explorer.png differ diff --git a/docs/other-tools/postgres/images/pgadmin.png b/docs/other-tools/postgres/images/pgadmin.png new file mode 100644 index 000000000..3a0a66eb5 Binary files /dev/null and b/docs/other-tools/postgres/images/pgadmin.png differ diff --git a/docs/other-tools/postgres/postgres-cluster-setup.md b/docs/other-tools/postgres/postgres-cluster-setup.md new file mode 100644 index 000000000..c25972c9f --- /dev/null +++ b/docs/other-tools/postgres/postgres-cluster-setup.md @@ -0,0 +1,497 @@ +# Create a Postgres Cluster + +In the NERC OpenShift environment, the [Crunchy Postgres for Kubernetes](https://www.crunchydata.com/products/crunchy-postgresql-for-kubernetes) +Operator is already installed, configured, and ready for general users to provision +and manage PostgreSQL clusters. + +![Crunchy Postgres for Kubernetes Operator](images/crunchy_postgres_for_K8s_operator.png) + +Built on **Postgres Operator from Crunchy Data (PGO)**, the Postgres Operator from +Crunchy Data, Crunchy Postgres for Kubernetes gives you a declarative Postgres +solution that automatically manages your PostgreSQL clusters. + +## Steps + +### Using the CLI (oc command) on your local Terminal + +Make sure you have the `oc` CLI tool installed and configured on your local +machine following [these steps](../../openshift/logging-in/setup-the-openshift-cli.md#first-time-usage). + +!!! info "Information" + + Some users may have access to multiple projects. Run the following command to + switch to a specific project space: `oc project `. + +### Set up a PostgreSQL cluster + +Run the following command in your terminal to set up a PostgreSQL cluster named +`hippo-pg`: + +!!! danger "Very Important: Changing the Server Name" + + You can change the server name, e.g., `hippo-pg`, but make sure that all + references to this name are updated in the subsequent steps. + +```sh +cat < 38m +hippo-pg-instance1-wksp-pgwal Bound pvc-9c26989e-ad67-4de5-b39f-e82a233e85f3 10Gi RWO ocs-external-storagecluster-ceph-rbd 38m +``` + +When your PostgreSQL cluster is initialized using the script above to set up the +cluster named `hippo-pg`, **PGO** creates a set of Kubernetes Services that provide +stable endpoints for connecting to your PostgreSQL databases. These endpoints +ensure a consistent and reliable way for your application to access and interact +with your data. To see which services are available, you can run the following command: + +```sh +oc get svc --selector=postgres-operator.crunchydata.com/cluster=hippo-pg +``` + +The output should look similar to: + +```sh +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +hippo-pg-ha ClusterIP 172.30.243.135 5432/TCP 138m +hippo-pg-ha-config ClusterIP None 138m +hippo-pg-pods ClusterIP None 138m +hippo-pg-primary ClusterIP None 5432/TCP 138m +hippo-pg-replicas ClusterIP 172.30.250.15 5432/TCP 138m +``` + +You don't need to worry about most of these Services, as they are primarily used +to manage the overall health of your PostgreSQL cluster. For connecting your application +to the database, the Service you should use is `hippo-pg-primary`. + +You can query the pod using: + +```sh +oc get pod -o name -l postgres-operator.crunchydata.com/cluster=hippo-pg,postgres-operator.crunchydata.com/role=master +``` + +The **PGO** will also bootstrap a database and create PostgreSQL users (e.g. `admin` +and `postgres`) as defined in `spec:users`. These accounts can be used by your +application to access the database i.e. `postgres`. + +This information is stored in a **Secret** named with the pattern +`-pguser-`. For our `hippo-pg` cluster, the Secrets are +called `hippo-pg-pguser-admin` and `hippo-pg-pguser-postgres`, corresponding to +the `admin` and `postgres` users. + +```sh +oc get secrets --selector=postgres-operator.crunchydata.com/cluster=hippo-pg +``` + +The output should look similar to: + +```sh +NAME TYPE DATA AGE +hippo-pg-cluster-cert Opaque 3 46m +hippo-pg-instance1-wksp-certs Opaque 4 46m +hippo-pg-pguser-admin Opaque 8 46m +hippo-pg-pguser-postgres Opaque 8 46m +hippo-pg-replication-cert Opaque 3 46m +``` + +These Secrets contain the information needed to connect your application to the +PostgreSQL database: + +- **user**: The name of the user account. + +- **password**: The password for the user account. + +- **dbname**: The default database that the user has access to. + +- **host**: The host name of the database, referencing the **Service** of the + primary PostgreSQL Cluster instance. + +- **port**: The port on which the database is listening. + +- **uri**: A [PostgreSQL connection URI](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) + containing all information for logging into the database. + +- **jdbc-uri**: A [PostgreSQL JDBC connection URI](https://jdbc.postgresql.org/documentation/use/) + for connecting via a JDBC driver. + +### Connect via `psql` in the local Terminal + +If you are on the same network as your PostgreSQL cluster, you can connect directly +to it using the following command: + +```sh +psql $(oc get secrets hippo-pg-pguser-postgres -o go-template='{{.data.uri | base64decode}}') +``` + +### Connect Using a Port-Forward + +To access PostgreSQL Cluster without public exposure, you can use port forwarding +to the cluster's primary pod - on port `5432`: + +```sh +PG_CLUSTER_PRIMARY_POD=$(oc get pod -o name -l postgres-operator.crunchydata.com/cluster=hippo-pg,postgres-operator.crunchydata.com/role=master) +oc port-forward "${PG_CLUSTER_PRIMARY_POD}" 5432:5432 +``` + +You should see output similar to: + +```sh +Forwarding from 127.0.0.1:5432 -> 5432 +Forwarding from [::1]:5432 -> 5432 +``` + +Run the following commands to establish a connection to the PostgreSQL cluster: + +```sh +PG_CLUSTER_USER_SECRET_NAME=hippo-pg-pguser-postgres + +PGUSER=$(oc get secrets "${PG_CLUSTER_USER_SECRET_NAME}" -o go-template='{{.data.user | base64decode}}') \ +PGPASSWORD=$(oc get secrets "${PG_CLUSTER_USER_SECRET_NAME}" -o go-template='{{.data.password | base64decode}}') \ +PGDATABASE=$(oc get secrets "${PG_CLUSTER_USER_SECRET_NAME}" -o go-template='{{.data.dbname | base64decode}}') \ +psql -h localhost -p 5432 +``` + +### Connecting With `pgAdmin` + +Crunchy Postgres for Kubernetes also provides a `pgAdmin` image for users who +prefer working with a graphical user interface. + +Let's create the `pgAdmin` database browser. + +- Create a secret for pgAdmin password: + + ```sh + export PGADMIN_PASSWORD='' + ``` + +- Create a secret for pgAdmin password: + + ```sh + oc create secret generic pgadmin-password-secret \ + --from-literal=pgadmin-admin-password=$PGADMIN_PASSWORD + ``` + +- Run the below command to create pgAdmin instance + + ```sh + cat < 5050 + Forwarding from [::1]:5050 -> 5050 + ``` + + Once the port-forward is active, open your browser and navigate to: + + ```sh + http://localhost:5050 + ``` + + Use the following credentials to log in to the opened `pgAdmin` database explorer: + + **username:** admin@example.com + + **password:** $PGADMIN_PASSWORD + +- To access **pgAdmin** publicly, create a route for the `pgAdmin` database explorer: + + ```sh + cat < + + **password:** $PGADMIN_PASSWORD + +Once logged in, you can access the **pgAdmin** console as shown below: + +![pgAdmin Web Console](images/pgadmin-console.png) + +Click the **Crunchy Postgres for Kubernetes** server group to view the existing +server, e.g., `hippo-pg`. + +To configure server connections, right-click on `hippo-pg` and select **Properties** +to open the **Server** dialog. + +Use the **Server** dialog to define a connection to the server. Click the +**Connection** tab to continue. + +In the **Connection** tab, configure the connection using the following fields: + +![Connection Properties](images/connection-properties.png) + +- **Maintenance database**: Specify the name of the initial database to which + the client will connect. + +- **Username**: Specify the role name used to authenticate with the server. + +- **Password**: Enter the password used for authentication. + +- **Save password?**: Check this box to save the password for future use. Use + **Clear Saved Password** to remove it if needed. + +To retrieve these information, run the following commands: + +```sh +PG_CLUSTER_USER_SECRET_NAME=hippo-pg-pguser-postgres + +oc get secrets "${PG_CLUSTER_USER_SECRET_NAME}" -o go-template='{{.data.dbname | base64decode}}' +oc get secrets "${PG_CLUSTER_USER_SECRET_NAME}" -o go-template='{{.data.user | base64decode}}' +oc get secrets "${PG_CLUSTER_USER_SECRET_NAME}" -o go-template='{{.data.password | base64decode}}' +``` + +These commands extract the **database name**, **username**, and **password** from +the Kubernetes Secret associated with the specified user in your PostgreSQL cluster. + +!!! tip "Admin User Secret" + + For the `admin` user, set the Secret name as follows: + + ```sh + PG_CLUSTER_USER_SECRET_NAME=hippo-pg-pguser-admin + ``` + + To retrieve this information for the `admin` user, run the following commands: + + ```sh + oc get secret "${PG_CLUSTER_USER_SECRET_NAME}" -o go-template='{{.data.dbname | base64decode}}' + oc get secret "${PG_CLUSTER_USER_SECRET_NAME}" -o go-template='{{.data.user | base64decode}}' + oc get secret "${PG_CLUSTER_USER_SECRET_NAME}" -o go-template='{{.data.password | base64decode}}' + ``` + +Once the database connection is successful, you will see the `pgAdmin` console as +shown below: + +![Connection Successful](images/pgadmin.png) + +### Deleting the `pgAdmin` + +If `pgAdmin` was created as a *PGAdmin* custom resource, you can delete it by running: + +```sh +oc delete pgadmin hippo-pgadmin +``` + +If `pgAdmin` was exposed with a *Route*, you can also delete the route: + +```sh +oc delete route route-pgadmin +``` + +### Delete the Postgres Cluster + +There comes a time when it is necessary to delete your Postgres Cluster. If you +have been following along with the example, you can delete your cluster by simply +running: + +```sh +oc delete postgrescluster hippo-pg +``` + +This removes the *PostgresCluster* resource and all associated components managed +by the PGO. + +--- diff --git a/mkdocs.yaml b/mkdocs.yaml index 8cad67d13..48ad2b4dd 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -184,6 +184,7 @@ nav: - MLflow: - MLflow Overview: other-tools/mlflow/mlflow-overview.md - MLflow Server Setup: other-tools/mlflow/mlflow-server-setup.md + - PostgresSQL Cluster: other-tools/postgres/postgres-cluster-setup.md - Setup NFS Server and Client: other-tools/nfs/nfs-server-client-setup.md theme: name: material