Update Quickstart

This reflects the easier installation methodology available (i.e.
that default storage classes do work, and they're glorious), and
expands on some of the other things that people want to get
started, i.e. being able to connect to a database.

Author: Jonathan S. Katz

docs/content/quickstart/_index.md

@@ -16,72 +16,30 @@ There are two paths to quickly get you up and running with the PostgreSQL Operat
   - Installation via [Operator Lifecycle Manager]({{< relref "/installation/other/operator-hub.md" >}})
   - Installation via [Google Cloud Marketplace]({{< relref "/installation/other/google-cloud-marketplace.md" >}})
 
-Marketplaces can help you get more quickly started in your environment as they provide a mostly automated process, but there are a few steps you will need to take to ensure you can fully utilize your PostgreSQL Operator environment.
+Marketplaces can help you get more quickly started in your environment as they provide a mostly automated process, but there are a few steps you will need to take to ensure you can fully utilize your PostgreSQL Operator environment. You can find out more information about how to get started with one of those installers in the [Installation]({{< relref "/installation/_index.md" >}}) section.
 
 # PostgreSQL Operator Installer
 
 Below will guide you through the steps for installing and using the PostgreSQL Operator using an installer that works with Ansible.
 
-## The Very, VERY Quickstart
+## Installation
 
-If your environment is set up to use hostpath storage (found in things like [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) or [OpenShift Code Ready Containers](https://developers.redhat.com/products/codeready-containers/overview), the following command could work for you:
+### Install the PostgreSQL Operator
+
+On environments that have a [default storage class](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/) set up (which is most modern Kubernetes environments), the below command should work:
 
 ```
 kubectl create namespace pgo
 kubectl apply -f https://raw.githubusercontent.com/CrunchyData/postgres-operator/v{{< param operatorVersion >}}/installers/kubectl/postgres-operator.yml
 ```
 
-If not, please read onward: you can still get up and running fairly quickly with just a little bit of configuration.
-
-## Step 1: Configuration
-
-### Get the PostgreSQL Operator Installer Manifest
-
-You will need to download the PostgreSQL Operator Installer manifest to your environment, which you can do with the following command:
-
-```
-curl https://raw.githubusercontent.com/CrunchyData/postgres-operator/v{{< param operatorVersion >}}/installers/kubectl/postgres-operator.yml > postgres-operator.yml
-```
-
-If you wish to download a specific version of the installer, you can substitute `master` with the version of the tag, i.e.
-
-```
-curl https://raw.githubusercontent.com/CrunchyData/postgres-operator/v{{< param operatorVersion >}}/installers/kubectl/postgres-operator.yml > postgres-operator.yml
-```
-
-### Configure the PostgreSQL Operator Installer
-
-There are many [configuration parameters]({{< relref "/installation/configuration.md">}}) to help you fine tune your installation, but there are a few that you may want to change to get the PostgreSQL Operator to run in your environment. Open up the `postgres-operator.yml` file and edit a few variables.
-
-Find the `pgo_admin_password` variable. This is the password you will use with the [`pgo` client]({{< relref "/installation/pgo-client" >}}) to manage your PostgreSQL clusters. The default is `password`, but you can change it to something like `hippo-elephant`.
-
-You will also need to set the storage default storage classes that you would like the PostgreSQL Operator to use. These variables are called `primary_storage`, `replica_storage`, `backup_storage`, and `backrest_storage`. There are several storage configurations listed out in the configuration file under the heading `storage[1-9]_name`. Find the one that you want to use, and set it to that value.
-
-For example, if your Kubernetes environment is using NFS storage, you would set these variables to the following:
-
-```
-backrest_storage: "nfsstorage"
-backup_storage: "nfsstorage"
-primary_storage: "nfsstorage"
-replica_storage: "nfsstorage"
-```
+This will launch the `pgo-deployer` container that will run the various setup and installation jobs. This can take a few minutes to complete depending on your Kubernetes cluster.
 
-If you are using either Openshift or CodeReady Containers, you will need to set `disable_fsgroup` to 'true' in order to deploy the PostgreSQL Operator in OpenShift environments that have the typical restricted Security Context Constraints.
+If your install is unsuccessful, you may need to modify your configuration. Please read the ["Troubleshooting"](#troubleshooting) section. You can still get up and running fairly quickly with just a little bit of configuration.
 
-For a full list of available storage types that can be used with this installation method, please review the [configuration parameters]({{< relref "/installation/configuration.md">}}).
+### Install the `pgo` Client
 
-## Step 2: Installation
-
-Installation is as easy as executing:
-
-```
-kubectl create namespace pgo
-kubectl apply -f postgres-operator.yml
-```
-
-This will launch the `pgo-deployer` container that will run the various setup and installation jobs. This can take a few minutes to complete depending on your Kubernetes cluster.
-
-While the installation is occurring, download the `pgo` client set up script. This will help set up your local environment for using the PostgreSQL Operator:
+During or after the installation of the PostgreSQL Operator, download the `pgo` client set up script. This will help set up your local environment for using the PostgreSQL Operator:
 
 ```
 curl https://raw.githubusercontent.com/CrunchyData/postgres-operator/v{{< param operatorVersion >}}/installers/kubectl/client-setup.sh > client-setup.sh
@@ -123,13 +81,13 @@ source ~/.bashrc
 
 **NOTE**: For macOS users, you must use `~/.bash_profile` instead of `~/.bashrc`
 
-## Step 3: Verification
+### Post-Installation Setup
 
 Below are a few steps to check if the PostgreSQL Operator is up and running.
 
-By default, the PostgreSQL Operator installs into a namespace called `pgo`. First, see that the the Kubernetes Deployment of the Operator exists and is healthy:
+By default, the PostgreSQL Operator installs into a namespace called `pgo`. First, see that the Kubernetes Deployment of the Operator exists and is healthy:
 
-```shell
+```
 kubectl -n pgo get deployments
 ```
 
@@ -142,7 +100,7 @@ postgres-operator   1/1     1            1           16h
 
 Next, see if the Pods that run the PostgreSQL Operator are up and running:
 
-```shell
+```
 kubectl -n pgo get pods
 ```
 
@@ -157,13 +115,13 @@ Finally, let's see if we can connect to the PostgreSQL Operator from the `pgo` c
 
 In a new console window, run the following command to set up a port forward:
 
-```shell
+```
 kubectl -n pgo port-forward svc/postgres-operator 8443:8443
 ```
 
 Back to your original console window, you can verify that you can connect to the PostgreSQL Operator using the following command:
 
-```shell
+```
 pgo version
 ```
 
@@ -174,17 +132,17 @@ pgo client version {{< param operatorVersion >}}
 pgo-apiserver version {{< param operatorVersion >}}
 ```
 
-## Step 4: Have Some Fun - Create a PostgreSQL Cluster
+## Create a PostgreSQL Cluster
 
 The quickstart installation method creates a namespace called `pgo` where the PostgreSQL Operator manages PostgreSQL clusters. Try creating a PostgreSQL cluster called `hippo`:
 
-```shell
+```
 pgo create cluster -n pgo hippo
 ```
 
-Alternatively, because we set the [`PGO_NAMESPACE`](/pgo-client/#general-notes-on-using-the-pgo-client) environmental variable in our `.bashrc` file, we could omit the `-n` flag from the [`pgo create cluster`](/pgo-client/reference/pgo_create_cluster/) command and just run this:
+Alternatively, because we set the [`PGO_NAMESPACE`]({{< relref "pgo-client/reference/pgo_create_cluster.md" >}}#general-notes-on-using-the-pgo-client) environmental variable in our `.bashrc` file, we could omit the `-n` flag from the [`pgo create cluster`]({{< relref "pgo-client/reference/pgo_create_cluster.md" >}}) command and just run this:
 
-```shell
+```
 pgo create cluster hippo
 ```
 
@@ -197,9 +155,9 @@ created Pgcluster hippo
 workflow id 1cd0d225-7cd4-4044-b269-aa7bedae219b
 ```
 
-This will create a PostgreSQL cluster named `hippo`. It may take a few moments for the cluster to be provisioned. You can see the status of this cluster using the `pgo test` command:
+This will create a PostgreSQL cluster named `hippo`. It may take a few moments for the cluster to be provisioned. You can see the status of this cluster using the [`pgo test`]({{< relref "pgo-client/reference/pgo_test.md" >}}) command:
 
-```shell
+```
 pgo test -n pgo hippo
 ```
 
@@ -215,3 +173,166 @@ cluster : hippo
 
 The `pgo test` command provides you the basic information you need to connect to your PostgreSQL cluster from within your Kubernetes environment. For more detailed information, you can use `pgo show cluster -n pgo hippo`.
 
+## Connect to a PostgreSQL Cluster
+
+By default, the PostgreSQL Operator creates a database inside the cluster with the same name of the cluster, in this case, `hippo`. Below demonstrates how we can connect to `hippo`.
+
+### How Users Work
+
+You can get information about the users in your cluster with the [`pgo show user`]({{< relref "pgo-client/reference/pgo_show_user.md" >}}) command:
+
+```
+pgo show user -n pgo hippo
+```
+
+This will give you all the unprivileged, non-system PostgreSQL users for the `hippo` PostgreSQL cluster, for example:
+
+```
+CLUSTER USERNAME PASSWORD                 EXPIRES STATUS ERROR
+------- -------- ------------------------ ------- ------ -----
+hippo   testuser datalake                 never   ok
+```
+
+To get the information about all PostgreSQL users that the PostgreSQL Operator is managing, you will need to use the `--show-system-accounts` flag:
+
+```
+pgo show user -n pgo hippo --show-system-accounts
+```
+
+which returns something similar to:
+
+```
+CLUSTER USERNAME       PASSWORD                 EXPIRES STATUS ERROR
+------- -------------- ------------------------ ------- ------ -----
+hippo   postgres       <REDACTED>               never   ok
+hippo   primaryuser    <REDACTED>               never   ok
+hippo   testuser       datalake                 never   ok
+```
+
+The `postgres` user represents the [database superuser](https://www.postgresql.org/docs/current/role-attributes.html) and has every privilege granted to it. The PostgreSQL Operator securely interfaces through the `postgres` account to perform certain actions, such as managing users.
+
+The `primaryuser` is the used for replication and [high availability]({{< relref "architecture/high-availability/_index.md" >}}). You should never need to interface with this user account.
+
+### Connecting via `psql`
+
+Let's see how we can connect to `hippo` using [`psql`](https://www.postgresql.org/docs/current/app-psql.html), the command-line tool for accessing PostgreSQL. Ensure you have [installed the `psql` client](https://www.crunchydata.com/developers/download-postgres/binaries/postgresql12).
+
+The PostgreSQL Operator creates a service with the same name as the cluster. See for yourself! Get a list of all of the Services available in the `pgo` namespace:
+
+```
+kubectl -n pgo get svc
+
+NAME                         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
+hippo                        ClusterIP   10.96.218.63    <none>        2022/TCP,5432/TCP            59m
+hippo-backrest-shared-repo   ClusterIP   10.96.75.175    <none>        2022/TCP                     59m
+postgres-operator            ClusterIP   10.96.121.246   <none>        8443/TCP,4171/TCP,4150/TCP   71m
+```
+
+Let's connect the `hippo` cluster. First, in a different console window, set up a port forward to the `hippo` service:
+
+```
+kubectl -n pgo port-forward svc/hippo 5432:5432
+```
+
+You can connect to the database with the following command, substituting `datalake` for your actual password:
+
+```
+PGPASSWORD=datalake psql -h localhost -p 5432 -U testuser hippo
+```
+
+You should then be greeted with the PostgreSQL prompt:
+
+```
+psql (12.4)
+Type "help" for help.
+
+hippo=>
+```
+
+### Connecting via [pgAdmin 4]({{< relref "architecture/pgadmin4.md" >}})
+
+[pgAdmin 4]({{< relref "architecture/pgadmin4.md" >}}) is a graphical tool that can be used to manage and query a PostgreSQL database from a web browser. The PostgreSQL Operator provides a convenient integration with pgAdmin 4 for managing how users can log into the database.
+
+To add pgAdmin 4 to `hippo`, you can execute the following command:
+
+```
+pgo create pgadmin -n pgo hippo
+```
+
+It will take a few moments to create the pgAdmin 4 instance. The PostgreSQL Operator also creates a pgAdmin 4 service. See for yourself! Get a list of all of the Services available in the `pgo` namespace:
+
+```
+kubectl -n pgo get svc
+
+NAME                         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
+hippo                        ClusterIP   10.96.218.63    <none>        2022/TCP,5432/TCP            59m
+hippo-backrest-shared-repo   ClusterIP   10.96.75.175    <none>        2022/TCP                     59m
+hippo-pgadmin                ClusterIP   10.96.165.27    <none>        5050/TCP                     5m1s
+postgres-operator            ClusterIP   10.96.121.246   <none>        8443/TCP,4171/TCP,4150/TCP   71m
+```
+
+Let's connect to our `hippo` cluster via pgAdmin 4! In a different terminal, set up a port forward to pgAdmin 4:
+
+```
+kubectl -n pgo port-forward svc/hippo-pgadmin 5050:5050
+```
+
+Navigate your browser to http://localhost:5050 and use your database username (`testuser`) and password (e.g. `datalake`) to log in. Though the prompt says “email address”, using your PostgreSQL username will work:
+
+![pgAdmin 4 Login Page](/images/pgadmin4-login2.png)
+
+(There are occasions where the initial credentials do not properly get set in pgAdmin 4. If you have trouble logging in, try running the command `pgo update user -n pgo hippo --username=testuser --password=datalake`).
+
+Once logged into pgAdmin 4, you will be automatically connected to your database. Explore pgAdmin 4 and run some queries!
+
+For more information, please see the section on [pgAdmin 4]({{< relref "architecture/pgadmin4.md" >}}).
+
+## Troubleshooting
+
+### Installation Failures
+
+Some Kubernetes environments may require you to customize the configuration for the PostgreSQL Operator installer. The below provides a guide on the common parameters that require modification, though this may vary based on your installation. For a full reference, please visit the [Installation]({{< relref "/installation/_index.md" >}}) section.
+
+If you already attempted to install the PostgreSQL Operator and that failed, the easiest way to clean up that installation is to delete the [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) that you attempted to install the PostgreSQL Operator into. **Note: This deletes all of the other objects in the Namespace, so please be sure this is OK!**
+
+To delete the namespace, you can run the following command:
+
+```
+kubectl delete namespace pgo
+```
+
+#### Get the PostgreSQL Operator Installer Manifest
+
+You will need to download the PostgreSQL Operator Installer manifest to your environment, which you can do with the following command:
+
+```
+curl https://raw.githubusercontent.com/CrunchyData/postgres-operator/v{{< param operatorVersion >}}/installers/kubectl/postgres-operator.yml > postgres-operator.yml
+```
+
+#### Configure the PostgreSQL Operator Installer
+
+There are many [configuration parameters]({{< relref "/installation/configuration.md">}}) to help you fine tune your installation, but there are a few that you may want to change to get the PostgreSQL Operator to run in your environment. Open up the `postgres-operator.yml` file and edit a few variables.
+
+Find the `pgo_admin_password` variable. This is the password you will use with the [`pgo` client]({{< relref "/installation/pgo-client" >}}) to manage your PostgreSQL clusters. The default is `password`, but you can change it to something like `hippo-elephant`.
+
+You may also need to set the storage default storage classes that you would like the PostgreSQL Operator to use. These variables are called `primary_storage`, `replica_storage`, `backup_storage`, and `backrest_storage`. There are several storage configurations listed out in the configuration file under the heading `storage[1-9]_name`. Find the one that you want to use, and set it to that value.
+
+For example, if your Kubernetes environment is using NFS storage, you would set these variables to the following:
+
+```
+backrest_storage: "nfsstorage"
+backup_storage: "nfsstorage"
+primary_storage: "nfsstorage"
+replica_storage: "nfsstorage"
+```
+
+If you are using either Openshift or CodeReady Containers and you have a `restricted` Security Context Constraint, you will need to set `disable_fsgroup` to `true` in order to deploy the PostgreSQL Operator.
+
+For a full list of available storage types that can be used with this installation method, please review the [configuration parameters]({{< relref "/installation/configuration.md">}}).
+
+When you are done editing the file, you can install the PostgreSQL Operator by running the following commands:
+
+```
+kubectl create namespace pgo
+kubectl apply -f postgres-operator.yml
+```