Helm Chart
The PostgreSQL Operator Helm Chart
Overview
The PostgreSQL Operator comes with a container called pgo-deployer
which
handles a variety of lifecycle actions for the PostgreSQL Operator, including:
- Installation
- Upgrading
- Uninstallation
After configuring the values.yaml
file with you configuration options, the
installer will be run using the helm
command line tool and takes care of
setting up all of the objects required to run the PostgreSQL Operator.
The postgres-operator
Helm chart is available in the Helm
directory in the PostgreSQL Operator repository.
Requirements
RBAC
The Helm chart will create the ServiceAccount, ClusterRole, and ClusterRoleBinding
that are required to run the pgo-deployer
. If you have already configured the
ServiceAccount and ClusterRoleBinding for the installation process (e.g. from a
previous installation), you can disable their creation using the rbac.create
and serviceAccount.create
variables in the values.yaml
file. If these options
are disabled, you must provide the name of your preconfigured ServiceAccount using
serviceAccount.name
.
Namespace
In order to install the PostgreSQL Operator using the Helm chart you will need
to first create the namespace in which the pgo-deployer
will be run. By default,
it will run in the namespace that is provided to helm
at the command line.
kubectl create namespace <namespace>
helm install postgres-operator -n <namespace> /path/to/chart_dir
The PostgreSQL Operator has the ability to manage PostgreSQL clusters across multiple Kubernetes Namespaces, including the ability to add and remove Namespaces that it watches. Doing so does require the PostgreSQL Operator to have elevated privileges, and as such, the PostgreSQL Operator comes with three “namespace modes” to select what level of privileges to provide. Detailed information about these “namespace modes” can be found in the Namespace section here.
Config Map
The pgo-deployer
uses a Kubernetes ConfigMap
to pass configuration options into the installer. The values in your values.yaml
file will be used to populate the configuation options in the ConfigMap.
Configuration - values.yaml
The values.yaml
file contains all of the configuration parametes for deploying
the PostgreSQL Operator. The values.yaml file contains the defaults that
should work in most Kubernetes environments, but it may require some customization.
For a detailed description of each configuration parameter, please read the PostgreSQL Operator Installer Configuration Reference
Installation
Once you have configured the PostgreSQL Operator Installer to your specification, you can install the PostgreSQL Operator with the following command:
helm install <name> -n <namespace> /path/to/chart_dir
name
used when installing, this name
will be used to
upgrade and uninstall the PostgreSQL Operator.Install the pgo
Client
To use the pgo
Client,
there are a few additional steps to take in order to get it to work with your
PostgreSQL Operator installation. For convenience, you can download and run the
client-setup.sh
script in your local environment:
curl https://raw.githubusercontent.com/CrunchyData/postgres-operator/master/installers/kubectl/client-setup.sh > client-setup.sh
chmod +x client-setup.sh
./client-setup.sh
pgo
client binary, pgouser
,
client.crt
, and client.key
files to be overwritten.The client-setup.sh
script performs the following tasks:
- Sets
$PGO_OPERATOR_NAMESPACE
topgo
if it is unset. This is the default namespace that the PostgreSQL Operator is deployed to - Checks for valid Operating Systems and determines which
pgo
binary to download - Creates a directory in
$HOME/.pgo/$PGO_OPERATOR_NAMESPACE
(e.g./home/hippo/.pgo/pgo
) - Downloads the
pgo
binary, saves it to in$HOME/.pgo/$PGO_OPERATOR_NAMESPACE
, and sets it to be executable - Pulls the TLS keypair from the PostgreSQL Operator
pgo.tls
Secret so that thepgo
client can communicate with the PostgreSQL Operator. These are saved asclient.crt
andclient.key
in the$HOME/.pgo/$PGO_OPERATOR_NAMESPACE
path. - Pulls the
pgouser
credentials from thepgouser-admin
secret and saves them in the formatusername:password
in a file calledpgouser
client.crt
,client.key
, andpgouser
are all set to be read/write by the file owner. All other permissions are removed.- Sets the following environmental variables with the following values:
export PGOUSER=$HOME/.pgo/$PGO_OPERATOR_NAMESPACE/pgouser
export PGO_CA_CERT=$HOME/.pgo/$PGO_OPERATOR_NAMESPACE/client.crt
export PGO_CLIENT_CERT=$HOME/.pgo/$PGO_OPERATOR_NAMESPACE/client.crt
export PGO_CLIENT_KEY=$HOME/.pgo/$PGO_OPERATOR_NAMESPACE/client.key
For convenience, after the script has finished, you can permanently add these environmental variables to your environment:
cat <<EOF >> ~/.bashrc
export PATH="$HOME/.pgo/$PGO_OPERATOR_NAMESPACE:$PATH"
export PGOUSER="$HOME/.pgo/$PGO_OPERATOR_NAMESPACE/pgouser"
export PGO_CA_CERT="$HOME/.pgo/$PGO_OPERATOR_NAMESPACE/client.crt"
export PGO_CLIENT_CERT="$HOME/.pgo/$PGO_OPERATOR_NAMESPACE/client.crt"
export PGO_CLIENT_KEY="$HOME/.pgo/$PGO_OPERATOR_NAMESPACE/client.key"
EOF
By default, the client-setup.sh
script targets the user that is stored in the
pgouser-admin
secret in the pgo
($PGO_OPERATOR_NAMESPACE
) Namespace. If
you wish to use a different Secret, you can set the PGO_USER_ADMIN
environmental variable.
For more detailed information about installing the pgo
client,
please see Installing the pgo
client.
Verify the Installation
One way to verify the installation was successful is to execute the
pgo version
command.
In a new console window, run the following command to set up a port forward:
kubectl -n pgo port-forward svc/postgres-operator 8443:8443
In another console window, run the pgo version
command:
pgo version
If successful, you should see output similar to this:
pgo client version 4.6.1
pgo-apiserver version 4.6.1
Upgrade and Uninstall
Once install has be completed using Helm, it will also be used to upgrade and uninstall your PostgreSQL Operator.
name
and namespace
in the following sections should match the options
provided at install.Upgrade
To make changes to your deployment of the PostgreSQL Operator you will use the
helm upgrade
command. Once the configuration changes have been made to you
values.yaml
file, you can run the following command to implement them in the
deployment:
helm upgrade <name> -n <namespace> /path/to/updated_chart
Uninstall
To uninstall the PostgreSQL Operator you will use the helm uninstall
command.
This will uninstall the operator and clean up resources used by the pgo-deployer
.
helm uninstall <name> -n <namespace>
Debugging
When the pgo-deployer
job does not complete successfully, the resources that
are created and normally cleaned up by Helm will be left in your
Kubernetes cluster. This will allow you to use the failed job and its logs to
debug the issue. The following command will show the logs for the pgo-deployer
job:
kubectl logs -n <namespace> job.batch/pgo-deploy
You can also view the logs as the job is running by using the kubectl -f
follow flag:
kubectl logs -n <namespace> job.batch/pgo-deploy -f
These logs will provide feedback if there are any misconfigurations in your install. Once you have finished debugging the failed job and fixed any configuration issues, you can take steps to re-run your install, upgrade, or uninstall. By running another command the resources from the failed install will be cleaned up so that a successfull install can run.