Navigation :

Install `pgo` Client

Install the Postgres Operator (pgo) Client

The following will install and configure the pgo client on all systems. For the purpose of these instructions it’s assumed that the Crunchy PostgreSQL Operator is already deployed.

Prerequisites

  • For Kubernetes deployments: kubectl configured to communicate with Kubernetes
  • For OpenShift deployments: oc configured to communicate with OpenShift

The Crunchy Postgres Operator als requires the following in order to authenticate with the apiserver:

  • Client CA Certificate
  • Client TLS Certificate
  • Client Key
  • pgouser file containing <username>:<password>

All of the requirements above should be obtained from an administrator who installed the Crunchy PostgreSQL Operator.

Linux and MacOS

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. 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:

sudo mv /PATH/TO/pgo /usr/local/bin/pgo
sudo chmod +x /usr/local/bin/pgo

Verify the pgo client is accessible by running the following in the terminal:

pgo --help

Configuring Client TLS

With the client TLS requirements satisfied we can setup pgo to use them.

First, create a directory to hold these files by running the following command:

mkdir ${HOME?}/.pgo
chmod 700 ${HOME?}/.pgo

Next, copy the certificates to this new directory:

cp /PATH/TO/client.crt ${HOME?}/.pgo/client.crt && chmod 600 ${HOME?}/.pgo/client.crt
cp /PATH/TO/client.pem ${HOME?}/.pgo/client.pem && chmod 400 ${HOME?}/.pgo/client.pem

Finally, set the following environment variables to point to the client TLS files:

cat <<EOF >> ${HOME?}/.bashrc
export PGO_CA_CERT="${HOME?}/.pgo/client.crt"
export PGO_CLIENT_CERT="${HOME?}/.pgo/client.crt"
export PGO_CLIENT_KEY="${HOME?}/.pgo/client.pem"
EOF

Apply those changes to the current session by running:

source ~/.bashrc

Configuring pgouser

The pgouser file contains the username and password used for authentication with the Crunchy PostgreSQL Operator.

To setup the pgouser file, run the following:

echo "<USERNAME_HERE>:<PASSWORD_HERE>" > ${HOME?}/.pgo/pgouser
cat <<EOF >> ${HOME?}/.bashrc
export PGOUSER="${HOME?}/.pgo/pgouser"
EOF

Apply those changes to the current session by running:

source ${HOME?}/.bashrc

Configuring the API Server URL

If the Crunchy PostgreSQL Operator is not accessible outside of the cluster, it’s required to setup a port-forward tunnel using the kubectl or oc binary.

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:

# If deployed to Kubernetes
kubectl port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443

# If deployed to OpenShift
oc port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443

Note: the port-forward will be required for the duration of pgo usage.

Next, set the following environment variable to configure the API server address:

cat <<EOF >> ${HOME?}/.bashrc
export PGO_APISERVER_URL="https://<IP_OF_OPERATOR_API>:8443"
EOF

Note: if port-forward is being used, the IP of the Operator API is 127.0.0.1

Apply those changes to the current session by running:

source ${HOME?}/.bashrc

PGO-Client Container

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 install the pgo.tls and pgouser-<username> secrets are used to configure the pgo client.

Using the PGO-Client Deployment

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.

kubectl exec -it -n pgo <pgo-client-deployment-name> -c "pgo version"

# or

kubectl exec -it -n pgo <pgo-client-deployment-name> bash

The deployment does not require any configuration to connect to the operator.

Windows

The following will setup the pgo client to be used on a Windows system.

Installing the Client

First, download the pgo.exe client from the GitHub official releases.

Next, create a directory for pgo using the following:

  • Left click the Start button in the bottom left corner of the taskbar
  • Type cmd to search for Command Prompt
  • Right click the Command Prompt application and click “Run as administrator”
  • Enter the following command: mkdir "%ProgramFiles%\postgres-operator"

Within the same terminal copy the pgo.exe binary to the directory created above using the following command:

copy %HOMEPATH%\Downloads\pgo.exe "%ProgramFiles%\postgres-operator"

Finally, add pgo.exe to the system path by running the following command in the terminal:

setx path "%path%;C:\Program Files\postgres-operator"

Verify the pgo.exe client is accessible by running the following in the terminal:

pgo --help

Configuring Client TLS

With the client TLS requirements satisfied we can setup pgo to use them.

First, create a directory to hold these files using the following:

  • Left click the Start button in the bottom left corner of the taskbar
  • Type cmd to search for Command Prompt
  • Right click the Command Prompt application and click “Run as administrator”
  • Enter the following command: mkdir "%HOMEPATH%\pgo"

Next, copy the certificates to this new directory:

copy \PATH\TO\client.crt "%HOMEPATH%\pgo"
copy \PATH\TO\client.pem "%HOMEPATH%\pgo"

Finally, set the following environment variables to point to the client TLS files:

setx PGO_CA_CERT "%HOMEPATH%\pgo\client.crt"
setx PGO_CLIENT_CERT "%HOMEPATH%\pgo\client.crt"
setx PGO_CLIENT_KEY "%HOMEPATH%\pgo\client.pem"

Configuring pgouser

The pgouser file contains the username and password used for authentication with the Crunchy PostgreSQL Operator.

To setup the pgouser file, run the following:

  • Left click the Start button in the bottom left corner of the taskbar
  • Type cmd to search for Command Prompt
  • Right click the Command Prompt application and click “Run as administrator”
  • Enter the following command: echo USERNAME_HERE:PASSWORD_HERE > %HOMEPATH%\pgo\pgouser

Finally, set the following environment variable to point to the pgouser file:

setx PGOUSER "%HOMEPATH%\pgo\pgouser"

Configuring the API Server URL

If the Crunchy PostgreSQL Operator is not accessible outside of the cluster, it’s required to setup a port-forward tunnel using the kubectl or oc binary.

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:

# If deployed to Kubernetes
kubectl port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443

# If deployed to OpenShift
oc port-forward <OPERATOR_POD_NAME> -n <OPERATOR_NAMESPACE> 8443:8443

Note: the port-forward will be required for the duration of pgo usage.

Next, set the following environment variable to configure the API server address:

  • Left click the Start button in the bottom left corner of the taskbar
  • Type cmd to search for Command Prompt
  • Right click the Command Prompt application and click “Run as administrator”
  • Enter the following command: setx PGO_APISERVER_URL "https://<IP_OF_OPERATOR_API>:8443"
    • Note: if port-forward is being used, the IP of the Operator API is 127.0.0.1

Verify the Client Installation

After completing all of the steps above we can verify pgo is configured properly by simply running the following:

pgo version

If the above command outputs versions of both the client and API server, the Crunchy PostgreSQL Operator client has been installed successfully.