Install PGO with Kustomize overlays on Kubernetes

PGO ships with Kustomize overlays that let you install the operator with a single command. The default overlay deploys PGO to the postgres-operator namespace and grants it access to manage PostgresCluster resources across every namespace in your cluster. A single-namespace overlay is also available if you want to restrict the operator to one namespace.

The default installation pulls container images from the Crunchy Data Developer Portal. These images are subject to the Crunchy Data Developer Program terms of use. Register for a free account before proceeding.

Prerequisites

Before you install PGO, make sure you have the following tools available:

kubectl v1.24 or later, configured to talk to your cluster
kustomize v5.0 or later (or kubectl with built-in kustomize support via -k)
Access to a running Kubernetes cluster with permissions to create Namespace, CustomResourceDefinition, and ClusterRole resources

Choose an installation mode

All namespaces (default)
Single namespace

In all-namespaces mode, PGO watches every namespace for PostgresCluster, PGUpgrade, and PGAdmin resources. This is the recommended mode for most installations.The default overlay uses a ClusterRole and ClusterRoleBinding, so the operator service account has cluster-wide access.What gets installed

Resource	Description
`Namespace/postgres-operator`	Namespace that runs the operator pod
`CustomResourceDefinition` (×3)	`postgresclusters`, `pgupgrades`, `pgadmins`
`ClusterRole/postgres-operator`	Cluster-wide RBAC for the operator
`Deployment/pgo`	The operator itself (one replica)

Fork and clone the examples repository

The official install overlays live in the postgres-operator-examples repository. Fork it so you can version-control any customizations.

YOUR_GITHUB_UN="<your GitHub username>"
git clone --depth 1 "git@github.com:${YOUR_GITHUB_UN}/postgres-operator-examples.git"
cd postgres-operator-examples

Create the operator namespace

Apply the namespace overlay first. This creates the postgres-operator namespace before the operator Deployment is created.

kubectl apply -k kustomize/install/namespace

Expected output:

namespace/postgres-operator created

Install PGO

Apply the default overlay. The --server-side flag is required because the CRD manifests exceed the annotation size limit of client-side apply.

kubectl apply --server-side -k kustomize/install/default

Expected output (resources created on first install):

customresourcedefinition.apiextensions.k8s.io/pgadmins.postgres-operator.crunchydata.com serverside-applied
customresourcedefinition.apiextensions.k8s.io/pgupgrades.postgres-operator.crunchydata.com serverside-applied
customresourcedefinition.apiextensions.k8s.io/postgresclusters.postgres-operator.crunchydata.com serverside-applied
serviceaccount/pgo serverside-applied
clusterrole.rbac.authorization.k8s.io/postgres-operator serverside-applied
clusterrolebinding.rbac.authorization.k8s.io/postgres-operator serverside-applied
deployment.apps/pgo serverside-applied

Verify the installation

Wait for the operator pod to reach Running status:

kubectl get pods -n postgres-operator

NAME                   READY   STATUS    RESTARTS   AGE
pgo-5d7b8c9f6d-x4p2k   1/1     Running   0          45s

If the pod is in ImagePullBackOff, confirm that your nodes can reach the Crunchy Data registry and that you have a valid Developer Portal account.

In single-namespace mode, PGO only watches the namespace it is deployed into. The ClusterRole and ClusterRoleBinding from the default overlay are replaced with a Role and RoleBinding scoped to that namespace.This mode is useful when you do not have cluster-admin privileges, or when you want to give each team their own isolated operator instance.How it worksThe config/components/single-namespace Kustomize component patches the RBAC kind from ClusterRole → Role and sets the PGO_TARGET_NAMESPACE environment variable so the operator knows which namespace to watch:

# config/components/single-namespace/kustomization.yaml
kind: Component

patches:
- target:
    kind: ClusterRole
  patch: |-
    - { op: replace, path: /kind, value: Role }
- target:
    kind: ClusterRoleBinding
  patch: |-
    - { op: replace, path: /kind, value: RoleBinding }
    - { op: replace, path: /roleRef/kind, value: Role }
- target:
    kind: Deployment
  patch: |-
    kind: Deployment
    metadata: { name: ignored }
    spec:
      template:
        spec:
          containers:
          - name: operator
            env:
            - name: CPK_TARGET_NAMESPACE
              valueFrom: { fieldRef: { apiVersion: v1, fieldPath: metadata.namespace } }
            - name: PGO_TARGET_NAMESPACE
              value: '$(CPK_TARGET_NAMESPACE)'

Fork and clone the examples repository

YOUR_GITHUB_UN="<your GitHub username>"
git clone --depth 1 "git@github.com:${YOUR_GITHUB_UN}/postgres-operator-examples.git"
cd postgres-operator-examples

Create the operator namespace

kubectl apply -k kustomize/install/namespace

Install PGO in single-namespace mode

Apply the singlenamespace overlay instead of default:

kubectl apply --server-side -k kustomize/install/singlenamespace

The operator will only reconcile resources in the postgres-operator namespace.

Verify the installation

kubectl get pods -n postgres-operator

NAME                   READY   STATUS    RESTARTS   AGE
pgo-7c9d4b8f5d-r2n8m   1/1     Running   0          30s

To watch a namespace other than postgres-operator, add a namespace: field to your own kustomization.yaml overlay before applying.

Customize the installation

You can layer your own kustomization.yaml on top of the upstream overlays without modifying the cloned repository. Create a file such as my-install/kustomization.yaml:

kind: Kustomization

resources:
- ../postgres-operator-examples/kustomize/install/default

# Override the operator image tag
images:
- name: postgres-operator
  newTag: "6.0.1"

# Set a custom feature gate
patches:
- patch: |-
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: pgo
    spec:
      template:
        spec:
          containers:
          - name: operator
            env:
            - name: PGO_FEATURE_GATES
              value: "TablespaceVolumes=true"

Then apply your overlay:

kubectl apply --server-side -k my-install/

Uninstall PGO

Deleting the operator does not delete existing PostgresCluster resources or their data. The clusters continue running until you explicitly delete them. If you also remove the CRDs, Kubernetes will garbage-collect all custom resource objects and the associated PVCs may be lost.

To remove the operator while keeping your Postgres clusters intact:

kubectl delete -k kustomize/install/default

To also remove the CRDs (this deletes all PostgresCluster, PGUpgrade, and PGAdmin objects):

kubectl delete -k kustomize/install/default
kubectl delete crd \
  postgresclusters.postgres-operator.crunchydata.com \
  pgupgrades.postgres-operator.crunchydata.com \
  pgadmins.postgres-operator.crunchydata.com

Next steps

Create your first cluster

Deploy a production-grade Postgres cluster with high availability.

Install with Helm

Prefer Helm? Use the Crunchy Data chart for a values-driven install.

Configure feature gates

Enable alpha and beta features in the operator.

PostgresCluster reference

Full API reference for the PostgresCluster custom resource.

Get Started

Installation

Core Operations

Day-Two Operations

Security

Install PGO with Kustomize overlays on Kubernetes

Prerequisites

Choose an installation mode

Customize the installation

Uninstall PGO

Next steps

Create your first cluster

Install with Helm

Configure feature gates

PostgresCluster reference

​Prerequisites

​Choose an installation mode

​Customize the installation

​Uninstall PGO

​Next steps

Create your first cluster

Install with Helm

Configure feature gates

PostgresCluster reference

Prerequisites

Choose an installation mode

Customize the installation

Uninstall PGO

Next steps