Can't wait to try outCrunchy Postgres for Kubernetes? Let us show you the quickest possible path to getting up and running.

This quick start is forkustomize andkubectl. We also have instructions for installing viaHelm andOperatorHub, as well as more detailed instructions forkustomize.

Prerequisites

Please be sure you have the following utilities installed on your host machine:

• kubectl
• git

Installation

Step 1: Download the Examples

First, go to GitHub andfork the Postgres Operator examples repository:

https://github.com/CrunchyData/postgres-operator-examples/fork

Once you have forked this repo, you can download it to your working environment with a command similar to this:

YOUR_GITHUB_UN="$YOUR_GITHUB_USERNAME"git clone--depth1"git@github.com:${YOUR_GITHUB_UN}/postgres-operator-examples.git"cd postgres-operator-examplesCopy

For Powershell environments:

$env:YOUR_GITHUB_UN="YOUR_GITHUB_USERNAME"git clone--depth 1"git@github.com:$env:YOUR_GITHUB_UN/postgres-operator-examples.git"cd postgres-operator-examplesCopy

Step 2: Install PGO, the Postgres Operator

You can install PGO, the Postgres Operator from Crunchy Data, using the command below:

kubectl apply-k kustomize/install/namespacekubectl apply --server-side-k kustomize/install/defaultCopy

This will create a namespace calledpostgres-operator and create all of the objects required to deploy PGO.

To check on the status of your installation, you can run the following command:

kubectl-n postgres-operator get pods--selector=postgres-operator.crunchydata.com/control-plane=postgres-operator --field-selector=status.phase=RunningCopy

If the PGO Pod is healthy, you should see output similar to:

NAME                                READY   STATUS    RESTARTS   AGEpostgres-operator-9dd545d64-t4h8d1/1     Running0          3sCopy

Create a Postgres Cluster

Let's create a simple Postgres cluster. You can do this by executing the following command:

kubectl apply-k kustomize/postgresCopy

This will create a Postgres cluster namedhippo in thepostgres-operator namespace. You can track the progress of your cluster using the following command:

kubectl-n postgres-operator describe postgresclusters.postgres-operator.crunchydata.com hippoCopy

Connect to the Postgres cluster

As part of creating a Postgres cluster, the Postgres Operator creates a PostgreSQL user account. The credentials for this account are stored in a Secret that has the name<clusterName>-pguser-<userName>.

Within this Secret are attributes that provide information to let you log into the PostgreSQL cluster. These include:

• user: The name of the user account.
• password: The password for the user account.
• dbname: The name of the database that the user has access to by default.
• host: The name of the host of the database. This references theService of the primary Postgres instance.
• port: The port that the database is listening on.
• uri: APostgreSQL connection URI that provides all the information for logging into the Postgres database.
• jdbc-uri: APostgreSQL JDBC connection URI that provides all the information for logging into the Postgres database via the JDBC driver.

If you deploy your Postgres cluster with thePgBouncer connection pooler, there are additional values that are populated in the user Secret, including:

• pgbouncer-host: The name of the host of the PgBouncer connection pooler. This references theService of the PgBouncer connection pooler.
• pgbouncer-port: The port that the PgBouncer connection pooler is listening on.
• pgbouncer-uri: APostgreSQL connection URI that provides all the information for logging into the Postgres database via the PgBouncer connection pooler.
• pgbouncer-jdbc-uri: APostgreSQL JDBC connection URI that provides all the information for logging into the Postgres database via the PgBouncer connection pooler using the JDBC driver.

Note thatall connections use TLS. PGO sets up a public key infrastructure (PKI) for your Postgres clusters. You can also choose to bring your own PKI / certificate authority; this is covered later in the documentation.

Connect viapsql in the Terminal

Connect Directly

If you are on the same network as your PostgreSQL cluster, you can connect directly to it using the following command:

psql$(kubectl-n postgres-operator get secrets hippo-pguser-hippo-o go-template='{{.data.uri | base64decode}}')Copy

Connect Using a Port-Forward

In a new terminal, create a port forward. If you are using Bash, you can run the following commands:

PG_CLUSTER_PRIMARY_POD=$(kubectl get pod-n postgres-operator-o name-l postgres-operator.crunchydata.com/cluster=hippo,postgres-operator.crunchydata.com/role=master)kubectl-n postgres-operator port-forward"${PG_CLUSTER_PRIMARY_POD}"5432:5432Copy

For Powershell environments:

$env:PG_CLUSTER_PRIMARY_POD=(kubectl get pod-n postgres-operator-o name-l postgres-operator.crunchydata.com/cluster=hippo,postgres-operator.crunchydata.com/role=master)kubectl-n postgres-operator port-forward"$env:PG_CLUSTER_PRIMARY_POD" 5432:5432Copy

Establish a connection to the PostgreSQL cluster. If you are using Bash, you can run:

PG_CLUSTER_USER_SECRET_NAME=hippo-pguser-hippoPGPASSWORD=$(kubectl get secrets-n postgres-operator"${PG_CLUSTER_USER_SECRET_NAME}"-o go-template='{{.data.password | base64decode}}')\PGUSER=$(kubectl get secrets-n postgres-operator"${PG_CLUSTER_USER_SECRET_NAME}"-o go-template='{{.data.user | base64decode}}')\PGDATABASE=$(kubectl get secrets-n postgres-operator"${PG_CLUSTER_USER_SECRET_NAME}"-o go-template='{{.data.dbname | base64decode}}')\ psql-h localhostCopy

For Powershell environments:

$env:PG_CLUSTER_USER_SECRET_NAME="hippo-pguser-hippo"$env:PGPASSWORD=(kubectl get secrets-n postgres-operator"$env:PG_CLUSTER_USER_SECRET_NAME"-o go-template='{{.data.password | base64decode}}')$env:PGUSER=(kubectl get secrets-n postgres-operator"$env:PG_CLUSTER_USER_SECRET_NAME"-o go-template='{{.data.user | base64decode}}')$env:PGDATABASE=(kubectl get secrets-n postgres-operator"$env:PG_CLUSTER_USER_SECRET_NAME"-o go-template='{{.data.dbname | base64decode}}') psql-h localhostCopy

Create a user schema

Starting inPostgres 15,PUBLIC creation permission on the public schema has been removed, but there is a simple way forward to allow you to start writing queries.As described in our helpfulblog post on the subject, after connecting viapsql as thehippo user, just execute

CREATESCHEMA hippoAUTHORIZATION hippo;Copy

and you will be able to create tables in thehippo schema without any additional steps or permissions.

Connect an Application

The information provided in the user Secret will allow you to connect an application directly to your PostgreSQL database.

For example, let's connectKeycloak. Keycloak is a popular open source identity management tool that is backed by a PostgreSQL database. Using thehippo cluster we created, we can deploy the following manifest file:

cat <<EOF>> keycloak.yamlapiVersion: apps/v1kind: Deploymentmetadata:name: keycloaknamespace: postgres-operatorlabels:app.kubernetes.io/name: keycloakspec:selector:matchLabels:app.kubernetes.io/name: keycloaktemplate:metadata:labels:app.kubernetes.io/name: keycloakspec:containers:-image: quay.io/keycloak/keycloak:latestargs:["start-dev"]name: keycloakenv:-name: KC_DBvalue:"postgres"-name: KC_DB_URL_HOSTvalueFrom:{secretKeyRef:{name: hippo-pguser-hippo,key: host}}-name: KC_DB_URL_PORTvalueFrom:{secretKeyRef:{name: hippo-pguser-hippo,key: port}}-name: KC_DB_URL_DATABASEvalueFrom:{secretKeyRef:{name: hippo-pguser-hippo,key: dbname}}-name: KC_DB_USERNAMEvalueFrom:{secretKeyRef:{name: hippo-pguser-hippo,key: user}}-name: KC_DB_PASSWORDvalueFrom:{secretKeyRef:{name: hippo-pguser-hippo,key: password}}-name: KC_BOOTSTRAP_ADMIN_USERNAMEvalue:"admin"-name: KC_BOOTSTRAP_ADMIN_PASSWORDvalue:"admin"-name: KC_PROXY_HEADERSvalue:"xforwarded"ports:-name: httpcontainerPort:8080-name: httpscontainerPort:8443readinessProbe:httpGet:path: /realms/masterport:8080restartPolicy: AlwaysEOFkubectl apply-f keycloak.yamlCopy

There is a full example for how to deploy Keycloak with the Postgres Operator in thekustomize/keycloak folder.

Next Steps

Congratulations, you've got your Postgres cluster up and running, perhaps with an application connected to it!

You can find out more about thepostgresclusters custom resource definition through thedocumentation and throughkubectl explain, i.e.:

kubectl explain postgresclustersCopy

You’ve seen how easy it is to get a Postgres database up and running and connected to your applications using Crunchy Postgres for Kubernetes. In the next section we will take a closer look at CPK and how its different components work together to provide everything you need for a production-ready Postgres cluster.