Use Services in the examples of port-forwarding

The Service name stays consistent, whereas Pod names change, so this
provides an easier example for working with the PostgreSQL Operator.

Author: Jonathan S. Katz

docs/content/Installation/install-pgo-client/_index.md

@@ -33,7 +33,7 @@ The following will setup the `pgo` client to be used on a Linux or MacOS system.
 ### Installing the Client
 
 First, download the `pgo` client from the
-[GitHub official releases](https://github.com/CrunchyData/postgres-operator/releases). Crunchy Enterprise Customers can download the pgo binaries from https://access.crunchydata.com/ on the downloads page. 
+[GitHub official releases](https://github.com/CrunchyData/postgres-operator/releases). Crunchy Enterprise Customers can download the pgo binaries from https://access.crunchydata.com/ on the downloads page.
 
 Next, install `pgo` in `/usr/local/bin` by running the following:
 
@@ -115,13 +115,17 @@ ensure connection can be made outside of the cluster:
 
 ```bash
 # If deployed to Kubernetes
-kubectl port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443
+kubectl port-forward -n pgo svc/postgres-operator 8443:8443
 
 # If deployed to OpenShift
-oc port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443
+oc port-forward -n pgo svc/postgres-operator 8443:8443
 ```
 
-**Note**: the port-forward will be required for the duration of `pgo` usage.
+In the above examples, you can substitute `pgo` for the namespace that you
+deployed the PostgreSQL Operator into.
+
+**Note**: The port-forward will be required for the duration of using the
+PostgreSQL client.
 
 Next, set the following environment variable to configure the API server address:
 
@@ -141,18 +145,18 @@ source ${HOME?}/.bashrc
 
 ## PGO-Client Container
 
-The following will setup the `pgo` client image in a Kubernetes or Openshift 
+The following will setup the `pgo` client image in a Kubernetes or Openshift
 environment. The image must be installed using the Ansible installer.
 
 ### Installing the PGO-Client Container
 The pgo-client container can be installed with the Ansible installer by updating
-the `pgo_client_container_install` variable in the inventory file. Set this 
-variable to true in the inventory file and run the ansible-playbook. As part of 
+the `pgo_client_container_install` variable in the inventory file. Set this
+variable to true in the inventory file and run the ansible-playbook. As part of
 the install the `pgo.tls` and `pgouser-<username>` secrets are used to configure
-the `pgo` client. 
+the `pgo` client.
 
 ### Using the PGO-Client Deployment
-Once the container has been installed you can access it by exec'ing into the 
+Once the container has been installed you can access it by exec'ing into the
 pod. You can run single commands with the kubectl or oc command line tools
 or multiple commands by exec'ing into the pod with bash.
 
@@ -255,13 +259,17 @@ ensure connection can be made outside of the cluster:
 
 ```bash
 # If deployed to Kubernetes
-kubectl port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443
+kubectl port-forward -n pgo svc/postgres-operator 8443:8443
 
 # If deployed to OpenShift
-oc port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443
+oc port-forward -n pgo svc/postgres-operator 8443:8443
 ```
 
-**Note**: the port-forward will be required for the duration of `pgo` usage.
+In the above examples, you can substitute `pgo` for the namespace that you
+deployed the PostgreSQL Operator into.
+
+**Note**: The port-forward will be required for the duration of using the
+PostgreSQL client.
 
 Next, set the following environment variable to configure the API server address:
 

docs/content/Installation/install-with-ansible/installing-metrics.md

@@ -7,19 +7,19 @@ weight: 22
 
 # Installing
 
-PostgreSQL clusters created by the Crunchy PostgreSQL Operator can optionally be 
-configured to serve performance metrics via Prometheus Exporters.  The metric exporters 
-included in the database pod serve realtime metrics for the database container.  In 
-order to store and view this data, Grafana and Prometheus are required.  The Crunchy 
-PostgreSQL Operator does not create this infrastructure, however, they can be installed 
+PostgreSQL clusters created by the Crunchy PostgreSQL Operator can optionally be
+configured to serve performance metrics via Prometheus Exporters.  The metric exporters
+included in the database pod serve realtime metrics for the database container.  In
+order to store and view this data, Grafana and Prometheus are required.  The Crunchy
+PostgreSQL Operator does not create this infrastructure, however, they can be installed
 using the provided Ansible roles.
 
 ## Prerequisites
 
 The following assumes the proper [prerequisites are satisfied](/installation/install-with-ansible/prerequisites/)
 we can now install the PostgreSQL Operator.
 
-At a minimum, the following inventory variables should be configured to install the 
+At a minimum, the following inventory variables should be configured to install the
 metrics infrastructure:
 
 | Name                              | Default     | Description                                                                                                                                                                      |
@@ -45,7 +45,7 @@ metrics infrastructure:
 | `prometheus_storage_class_name`   |             | Set to the name of the storage class used when creating Prometheus persistent volumes.                                                                                           |
 
 {{% notice tip %}}
-Administrators can choose to install Grafana, Prometheus or both by configuring the 
+Administrators can choose to install Grafana, Prometheus or both by configuring the
 `grafana_install` and `prometheus_install` variables in the inventory files.
 {{% /notice %}}
 
@@ -60,7 +60,7 @@ For more information on storage classes see the [official Kubernetes documentati
 
 ## Installing on Linux
 
-On a Linux host with Ansible installed we can run the following command to install 
+On a Linux host with Ansible installed we can run the following command to install
 the Metrics stack:
 
 ```bash
@@ -79,7 +79,7 @@ ansible-playbook -i /path/to/inventory --tags=install-metrics --ask-become-pass
 
 ## Installing on MacOS
 
-On a MacOS host with Ansible installed we can run the following command to install 
+On a MacOS host with Ansible installed we can run the following command to install
 the Metrics stack:
 
 ```bash
@@ -88,7 +88,7 @@ ansible-playbook -i /path/to/inventory --tags=install-metrics main.yml
 
 ## Installing on Windows
 
-On a Windows host with the Ubuntu subsystem we can run the following commands to install 
+On a Windows host with the Ubuntu subsystem we can run the following commands to install
 the Metrics stack:
 
 ```bash
@@ -97,7 +97,7 @@ ansible-playbook -i /path/to/inventory --tags=install-metrics main.yml
 
 ## Verifying the Installation
 
-This may take a few minutes to deploy.  To check the status of the deployment run 
+This may take a few minutes to deploy.  To check the status of the deployment run
 the following:
 
 ```bash
@@ -112,15 +112,15 @@ oc get pods -n <NAMESPACE_NAME>
 
 ## Verify Grafana
 
-In a separate terminal we need to setup a port forward to the Crunchy Grafana deployment 
+In a separate terminal we need to setup a port forward to the Crunchy Grafana deployment
 to ensure connection can be made outside of the cluster:
 
 ```bash
 # If deployed to Kubernetes
-kubectl port-forward <GRAFANA_POD_NAME> -n <METRICS_NAMESPACE> 3000:3000
+kubectl port-forward -n <METRICS_NAMESPACE> svc/grafana 3000:3000
 
 # If deployed to OpenShift
-oc port-forward <GRAFANA_POD_NAME> -n <METRICS_NAMESPACE> 3000:3000
+oc port-forward -n <METRICS_NAMESPACE> svc/grafana 3000:3000
 ```
 
 In a browser navigate to `http://127.0.0.1:3000` to access the Grafana dashboard.
@@ -136,21 +136,21 @@ pgo create cluster <NAME OF CLUSTER> --metrics --namespace=<NAMESPACE>
 
 ## Verify Prometheus
 
-In a separate terminal we need to setup a port forward to the Crunchy Prometheus deployment 
+In a separate terminal we need to setup a port forward to the Crunchy Prometheus deployment
 to ensure connection can be made outside of the cluster:
 
 ```bash
 # If deployed to Kubernetes
-kubectl port-forward <PROMETHEUS_POD_NAME> -n <METRICS_NAMESPACE> 9090:9090
+kubectl port-forward -n <METRICS_NAMESPACE> svc/prometheus  9090:9090
 
 # If deployed to OpenShift
-oc port-forward <PROMETHEUS_POD_NAME> -n <METRICS_NAMESPACE> 9090:9090
+oc port-forward -n <METRICS_NAMESPACE> svc/prometheus 9090:9090
 ```
 
 In a browser navigate to `http://127.0.0.1:9090` to access the Prometheus dashboard.
 
 {{% notice tip %}}
-No metrics will be scraped if no exporters are available.  To create a PostgreSQL 
+No metrics will be scraped if no exporters are available.  To create a PostgreSQL
 cluster with metric exporters run the following command:
 
 ```bash

docs/content/Installation/install-with-ansible/installing-operator.md

@@ -105,13 +105,16 @@ Operator to ensure connection can be made outside of the cluster:
 
 ```bash
 # If deployed to Kubernetes
-kubectl port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443
+kubectl port-forward -n pgo svc/postgres-operator 8443:8443
 
 # If deployed to OpenShift
-oc port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443
+oc port-forward -n pgo svc/postgres-operator 8443:8443
 ```
 
-On a separate terminal verify the `pgo` can communicate with the Crunchy PostgreSQL
+You can subsitute `pgo` in the above examples with the namespace that you
+deployed the PostgreSQL Operator into.
+
+On a separate terminal verify the PostgreSQL client can communicate with the Crunchy PostgreSQL
 Operator:
 
 ```bash

docs/content/Installation/install-with-ansible/updating-operator.md

@@ -7,7 +7,7 @@ weight: 30
 
 # Updating
 
-Updating the Crunchy PostgreSQL Operator is essential to the lifecycle management 
+Updating the Crunchy PostgreSQL Operator is essential to the lifecycle management
 of the service.  Using the `update` flag will:
 
 * Update and redeploy the operator deployment
@@ -19,8 +19,8 @@ of the service.  Using the `update` flag will:
 The following assumes the proper [prerequisites are satisfied](/installation/install-with-ansible/prerequisites/)
 we can now update the PostgreSQL Operator.
 
-The commands should be run in the directory where the Crunchy PostgreSQL Operator 
-playbooks is stored.  See the `ansible` directory in the Crunchy PostgreSQL Operator 
+The commands should be run in the directory where the Crunchy PostgreSQL Operator
+playbooks is stored.  See the `ansible` directory in the Crunchy PostgreSQL Operator
 project for the inventory file, main playbook and ansible roles.
 
 ## Updating on Linux
@@ -62,7 +62,7 @@ ansible-playbook -i /path/to/inventory --tags=update --ask-become-pass main.yml
 
 ## Verifying the Update
 
-This may take a few minutes to deploy.  To check the status of the deployment run 
+This may take a few minutes to deploy.  To check the status of the deployment run
 the following:
 
 ```bash
@@ -77,7 +77,7 @@ oc get pods -n <NAMESPACE_NAME>
 
 ## Configure Environment Variables
 
-After the Crunchy PostgreSQL Operator has successfully been updated we will need 
+After the Crunchy PostgreSQL Operator has successfully been updated we will need
 to configure local environment variables before using the `pgo` client.
 
 To configure the environment variables used by `pgo` run the following command:
@@ -104,25 +104,25 @@ source ~/.bashrc
 
 ## Verify `pgo` Connection
 
-In a separate terminal we need to setup a port forward to the Crunchy PostgreSQL 
+In a separate terminal we need to setup a port forward to the Crunchy PostgreSQL
 Operator to ensure connection can be made outside of the cluster:
 
 ```bash
 # If deployed to Kubernetes
-kubectl port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443
+kubectl port-forward -n pgo svc/postgres-operator 8443:8443
 
 # If deployed to OpenShift
-oc port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443
+oc port-forward -n pgo svc/postgres-operator 8443:8443
 ```
+In the above examples, you can substitute `pgo` for the namespace that you
+deployed the PostgreSQL Operator into.
 
-Note: If a port other than 8443 was configured, update the above command accordingly.
-
-On a separate terminal verify the `pgo` can communicate with the Crunchy PostgreSQL 
-Operator:
+On a separate terminal verify the PostgreSQL Operator client can communicate
+with the PostgreSQL Operator:
 
 ```bash
 pgo version
 ```
 
-If the above command outputs versions of both the client and API server, the Crunchy 
+If the above command outputs versions of both the client and API server, the Crunchy
 PostgreSQL Operator has been updated successfully.

docs/content/architecture/eventing.md

@@ -27,7 +27,7 @@ event stream.  If you have the correct priviledges
 to connect to the Operator pod, you can port forward
 as follows to form a connection to the event stream:
 
-    kubectl port-forward postgres-operator-XXXXXX 14150:4150 -n pgo
+    kubectl port-forward svc/postgres-operator 14150:4150 -n pgo
 
 ## Event Topics