adds documentation on expected shell environment (#1049)

* adds documentation on expected shell environment

While environment variables are primarily used by the Bash installation
but utility scripts also expect common environment variables to exist.

This restructuring helps clarify the necessary execution environment,
whether the installation is performed via Ansible or Bash.

* incorporates review feedback recommending linkage

Updates prerequisite information in the Bash and Ansible installs to
directly refer to the environment configuration if missed from the TOC

Author: wilybrace

hugo/content/Installation/common-env.md

@@ -0,0 +1,38 @@
+---
+title: "Operator Environment"
+date:
+draft: false
+weight: 50
+---
+
+For various scripts used by the Operator, the `expenv` utility is required as are certain environment variables.
+
+Download the `expenv` utility from its [Github Releases page](https://github.com/blang/expenv/releases), and place it into your PATH (e.g. $HOME/odev/bin).
+
+The following environment variables are heavily used in the Bash installation procedures and may be used in Operator helper scripts.
+
+Variable | Ansible Inventory | Example | Description
+-------- | ----------------- | ------- | -----------
+`DISABLE_EVENTING` | pgo_disable_eventing | false | Disable Operator eventing subsystem
+`DISABLE_TLS` | pgo_disable_tls | false | Disable TLS for Operator
+`GOPATH` |  | $HOME/odev | Golang project directory 
+`GOBIN` |  | $GOPATH/bin | Golang binary target directory 
+`NAMESPACE` | namespace | pgouser1 | Namespaces monitored by Operator 
+`PGOROOT` |  | $GOPATH/src/github.com/crunchydata/postgres-operator | Operator repository location 
+`PGO_APISERVER_PORT` | pgo_apiserver_port | 8443 | HTTP(S) port for Operator API server 
+`PGO_BASEOS` |  | centos7 | Base OS for container images 
+`PGO_CA_CERT` |  | $PGOROOT/conf/postgres-operator/server.crt | Server certificate and CA trust
+`PGO_CMD` |  | kubectl | Cluster management tool executable
+`PGO_CLIENT_CERT` |  | $PGOROOT/conf/postgres-operator/server.crt | TLS Client certificate
+`PGO_CLIENT_KEY` |  | $PGOROOT/conf/postgres-operator/server.crt | TLS Client certificate private key
+`PGO_IMAGE_PREFIX` | pgo_image_prefix | crunchydata | Container image prefix
+`PGO_IMAGE_TAG` | pgo_image_tag | $PGO_BASEOS-$PGO_VERSION | OS/Version tagging info for images 
+`PGO_INSTALLATION_NAME` | pgo_installation_name | devtest | Unique name given to Operator installation 
+`PGO_OPERATOR_NAMESPACE` | pgo_operator_namespace | pgo | Kubernetes namespace for the operator 
+`PGO_VERSION` |  | 4.1.0 | Operator version 
+`TLS_NO_VERIFY` | pgo_tls_no_verify | false | Disable certificate verification (e.g. strict hostname checking)
+
+{{% notice tip %}}
+`examples/envs.sh` contains the above variable definitions as well
+{{% /notice %}}
+

hugo/content/Installation/developer-setup.md

@@ -2,7 +2,7 @@
 title: "Developer Setup"
 date:
 draft: false
-weight: 305
+weight: 300
 ---
 
 # Developing

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

@@ -2,7 +2,7 @@
 title: "Install `pgo` Client"
 date:
 draft: false
-weight: 1
+weight: 400
 ---
 
 # Install the Postgres Operator (`pgo`) Client

hugo/content/Installation/install-with-ansible/_index.md

@@ -2,7 +2,7 @@
 title: "Install Operator Using Ansible"
 date:
 draft: false
-weight: 1
+weight: 100
 ---
 
 # Crunchy Data PostgreSQL Operator Playbooks

hugo/content/Installation/install-with-ansible/prerequisites.md

@@ -32,6 +32,10 @@ are required:
 * [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
 * [Ubuntu for Windows](https://www.microsoft.com/en-us/p/ubuntu/9nblggh4msv6)
 
+## Environment
+
+Ensure the appropriate [environment variables]({{< relref "common-env.md" >}}) are set.
+
 ## Permissions
 
 The installation of the Crunchy PostgreSQL Operator requires elevated privileges.  
@@ -46,8 +50,6 @@ can install:
 
 However, if the user wishes to add a new watched namespace after installation, where the user would normally use pgo create namespace to add the new namespace, they should instead run the add-targeted-namespace.sh script or they may give themselves cluster-admin privileges instead of having to run setupnamespaces.sh script. Again, this is only required when running on a Kuberenetes distribution whose version is below 1.12. In Kubernetes version 1.12+ the pgo create namespace command works as expected.
 
-add-targeted-namespace.sh requires the additional environment variable PGO_INSTALLATION_NAME set to the unique name given to the Operator's installation
-
 {{% /notice %}}
 
 ## Obtaining Operator Ansible Role

hugo/content/Installation/operator-install.md

@@ -2,7 +2,7 @@
 title: "Install Operator Using Bash"
 date:
 draft: false
-weight: 300
+weight: 200
 ---
 
 A full installation of the Operator includes the following steps:
@@ -43,6 +43,9 @@ Environment variables control aspects of the Operator installation.  You can cop
     cat $HOME/odev/src/github.com/crunchydata/postgres-operator/examples/envs.sh >> $HOME/.bashrc
     source $HOME/.bashrc
 
+To manually configure the environment variables, refer to the [environment documentation]({{< relref "common-env.md" >}}).
+
+
 For various scripts used by the Operator, the *expenv* utility is required, download this utility from the Github Releases page, and place it into your PATH (e.g. $HOME/odev/bin).
 {{% notice tip %}}There is also a Makefile target that includes is *expenv* and several other dependencies that are only needed if you plan on building from source: 
 
@@ -83,8 +86,6 @@ created as part of the default installation.
 
 However, if the user wishes to add a new watched namespace after installation, where the user would normally use pgo create namespace to add the new namespace, they should instead run the add-targeted-namespace.sh script or they may give themselves cluster-admin privileges instead of having to run setupnamespaces.sh script. Again, this is only required when running on a Kuberenetes distribution whose version is below 1.12. In Kubernetes version 1.12+ the pgo create namespace command works as expected.
 
-add-targeted-namespace.sh requires the additional environment variable PGO_INSTALLATION_NAME set to the unique name given to the Operator's installation
-
 {{% /notice %}}
 
 The *PGO_OPERATOR_NAMESPACE* environment variable is a comma separated list