From 66cf005253ea8816dae2326425b21764c26acc46 Mon Sep 17 00:00:00 2001 From: Anastasia Alexadrova Date: Tue, 17 Feb 2026 17:49:15 +0100 Subject: [PATCH 1/6] K8SPG-914 Documented naming conventions for Helm resources. Improved Helm install steps, extended custom install page new file: docs/assets/fragments/what-you-install.txt modified: docs/custom-install.md modified: docs/helm.md modified: docs/kubectl.md modified: docs/update-operator.md --- docs/assets/fragments/what-you-install.txt | 18 +++++ docs/custom-install.md | 94 +++++++++++++++++++--- docs/helm.md | 23 ++++-- docs/kubectl.md | 10 +-- docs/update-operator.md | 2 +- 5 files changed, 123 insertions(+), 24 deletions(-) create mode 100644 docs/assets/fragments/what-you-install.txt diff --git a/docs/assets/fragments/what-you-install.txt b/docs/assets/fragments/what-you-install.txt new file mode 100644 index 00000000..674fe834 --- /dev/null +++ b/docs/assets/fragments/what-you-install.txt @@ -0,0 +1,18 @@ +## What you will install + +* The Operator - the custom controller that uses the custom resources to install and manage the lifecycle of your database cluster. It consists of the following components: + + * the Operator Deployment - the controller Pod + * the CustomResourceDefinitions (CRDs) are a way to add new API types (custom resources) to Kubernetes so that it understands and handles them + * Role-based access control (RBAC) is the system that controls who can perform which actions on which resources, using roles and bindings to enforce safe, predictable access. + +* The database cluster - the actual Percona Distribution for PostgreSQL cluster that the Operator creates for you when you apply the Custom Resource or install the Helm chart. It includes StatefulSets for postgres servers, Services and Secrets. + +The default Percona Distribution for PostgreSQL configuration includes: + +* 3 PostgreSQL servers, one Primary and two replicas. +* a pgBouncer instance - a lightweight connection pooler for PostgreSQL that sits between client applications and the database server to manage and reuse connections efficiently. +* a pgBackRest instance - a backup and restore utility for PostgreSQL that provides a way to backup and restore your database. +* a PMM client instance - a monitoring and management tool for PostgreSQL that provides a way to monitor and manage your database. + +Read more about the default components in the [Architecture](architecture.md) section. diff --git a/docs/custom-install.md b/docs/custom-install.md index c670bac5..a647f526 100644 --- a/docs/custom-install.md +++ b/docs/custom-install.md @@ -1,8 +1,8 @@ -# Install Percona Distribution for PostgreSQL with customized parameters +# Install Percona Operator for PostgreSQL with customized parameters You can customize the configuration of Percona Distribution for PostgreSQL and install it with customized parameters. -To check available configuration options, see [deploy/cr.yaml :octicons-link-external-16:](https://raw.githubusercontent.com/percona/percona-postgresql-operator/v{{ release }}/deploy/cr.yaml) and [Custom Resource Options](operator.md). +To check available configuration options, see [deploy/cr.yaml :octicons-link-external-16:](https://raw.githubusercontent.com/percona/percona-postgresql-operator/v{{ release }}/deploy/cr.yaml) and [Custom Resource Options](operator.md). === ":simple-kubernetes: kubectl" @@ -22,20 +22,92 @@ To check available configuration options, see [deploy/cr.yaml :octicons-link-ext === ":simple-helm: Helm" - To install Percona Distribution for PostgreSQL with custom parameters using Helm, use the following command: - - ```bash - helm install --set key=value - ``` + You can install the Operator deployment and the Percona Distribution for PostgreSQL cluster with custom parameters using Helm. Find what options you can customize in the [Operator chart documentation :octicons-link-external-16:](https://github.com/percona/percona-helm-charts/tree/main/charts/pg-operator#installing-the-chart) and the [Percona Distribution for PostgreSQL chart documentation :octicons-link-external-16:](https://github.com/percona/percona-helm-charts/tree/main/charts/pg-db#installing-the-chart). + + You can provide custom parameters to Helm using either the `--set` flag or a `values.yaml` file. The `--set` flag is convenient for overriding a small number of parameters directly in the command line, while a `values.yaml` file is preferable when you want to manage many custom settings in one place. Both methods are fully supported by Helm and can be used as needed for your deployment. - You can pass any of the Operator’s [Custom Resource options](operator.md) as a - `--set key=value[,key=value]` argument. + **Using `--set` flags** - The following example deploys a PostgreSQL {{postgresrecommended}} based cluster - in the `my-namespace` namespace, with enabled [Percona Monitoring and Management (PMM) :octicons-link-external-16:](https://docs.percona.com/percona-monitoring-and-management/2/index.html): + To pass a custom parameter to Helm, use the `--set key=value` flag with the `helm install` command. + + For example, to enable [Percona Monitoring and Management (PMM) :octicons-link-external-16:](https://docs.percona.com/percona-monitoring-and-management/2/index.html) for the database cluster, run: ```bash helm install my-db percona/pg-db --version {{ release }} --namespace my-namespace \ --set postgresVersion={{postgresrecommended}} \ --set pmm.enabled=true ``` + + **Using a `values.yaml` file** + + Create a `values.yaml` file with your custom parameters and pass it to `helm install` with the `-f` or `--values` flag: + + ```bash + helm install my-db percona/pg-db --version {{ release }} --namespace my-namespace -f values.yaml + ``` + + Example `values.yaml`: + + ```yaml + postgresVersion: {{ postgresrecommended }} + pmm: + enabled: true + ``` + + ## Naming conventions for Helm resources + + When you install a chart, Helm creates a release and uses the release name and chart name to generate resource names. By default, resources are named `release-name-chart-name`. + + You can override the default naming with the `nameOverride` or `fullnameOverride` options. Pass them using the `--set` flag or in your `values.yaml` file. + + | Option | Effect | Example | + | ------ | ------ | ------- | + | `nameOverride` | Replaces the chart name but keeps the release name in the generated name | `release-name-name-override` | + | `fullnameOverride` | Replaces the entire generated name with the specified value | `fullname-override` | + + *Using `nameOverride`* — replaces the chart name but keeps the release name: + + ```bash + helm install my-operator percona/pg-operator --namespace my-namespace \ + --set nameOverride=postgres-operator + ``` + + Deployment name: `my-operator-postgres-operator`. + + ```bash + helm install cluster1 percona/pg-db -n my-namespace \ + --set nameOverride=postgres + ``` + + Cluster name: `cluster1-postgres`. + + *Using `fullnameOverride`* — replaces the full resource name: + + ```bash + helm install my-operator percona/pg-operator --namespace my-namespace \ + --set fullnameOverride=percona-postgresql-operator + ``` + + Deployment name: `percona-postgresql-operator`. + + ```bash + helm install cluster1 percona/pg-db -n my-namespace \ + --set fullnameOverride=my-db + ``` + + Cluster name: `my-db`. + + !!! note "Cluster name length" + + For the pg-db chart, the cluster name is limited to 21 characters, must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character. Keep this in mind when using `fullnameOverride` or long release names. + + ## Common Helm values reference + + The following table lists commonly used values for the Operator and database charts. For the full list of options, see the chart values files. + + | Value | Charts | Description | + | ----- | ------ | ----------- | + | `nameOverride` | [pg-operator](https://github.com/percona/percona-helm-charts/blob/main/charts/pg-operator/values.yaml), [pg-db](https://github.com/percona/percona-helm-charts/blob/main/charts/pg-db/values.yaml) | Replaces the chart name in generated resource names | + | `fullnameOverride` | [pg-operator](https://github.com/percona/percona-helm-charts/blob/main/charts/pg-operator/values.yaml), [pg-db](https://github.com/percona/percona-helm-charts/blob/main/charts/pg-db/values.yaml) | Replaces the entire generated resource name | + | `watchAllNamespaces` | [pg-operator](https://github.com/percona/percona-helm-charts/blob/main/charts/pg-operator/values.yaml) | Deploy the Operator in cluster-wide mode to watch all namespaces | + | `disableTelemetry` | [pg-operator](https://github.com/percona/percona-helm-charts/blob/main/charts/pg-operator/values.yaml) | Disable telemetry collection. See [Telemetry](telemetry.md) for details | diff --git a/docs/helm.md b/docs/helm.md index de9cb26e..dbff39df 100644 --- a/docs/helm.md +++ b/docs/helm.md @@ -1,15 +1,24 @@ -# Install Percona Distribution for PostgreSQL using Helm +# Install Percona Operator for PostgreSQL using Helm [Helm :octicons-link-external-16:](https://github.com/helm/helm) is the package manager for Kubernetes. -A Helm [chart :octicons-link-external-16:](https://helm.sh/docs/topics/charts/) is a package that contains all the necessary resources to deploy an application to a Kubernetes cluster. +A Helm [chart :octicons-link-external-16:](https://helm.sh/docs/topics/charts/) is a package that contains all the necessary files to deploy resources or an application to a Kubernetes cluster. -You can find Percona Helm charts in [percona/percona-helm-charts :octicons-link-external-16:](https://github.com/percona/percona-helm-charts) repository in Github. +Helm charts for Percona Operator for PostgreSQL include: + +* [Percona Operator for PostgreSQL Deployment :octicons-link-external-16:](https://github.com/percona/percona-helm-charts/tree/main/charts/pg-operator) +* [Percona Distribution for PostgreSQL :octicons-link-external-16:](https://github.com/percona/percona-helm-charts/tree/main/charts/pg-db) + +You need to install both of them. First you install the Operator Deployment and then you use that to install Percona Distribution for PostgreSQL cluster. + +This guide walks you through installing Percona Operator for PostgreSQL with default parameters and names. + +To install the Operator with custom parameters or custom resource names, refer to [Install Percona Operator for PostgreSQL with customized parameters](custom-install.md). ## Prerequisites To install and deploy the Operator, you need the following: -1. [Helm v3 :octicons-link-external-16:](https://docs.helm.sh/using_helm/#installing-helm). +1. [Helm v3 :octicons-link-external-16:](https://docs.helm.sh/using_helm/#installing-helm). Run `helm version` to check the version 2. [kubectl :octicons-link-external-16:](https://kubernetes.io/docs/tasks/tools/) command line utility. 3. A Kubernetes environment. You can deploy it locally on [Minikube :octicons-link-external-16:](https://github.com/kubernetes/minikube) for testing purposes or using any cloud provider of your choice. Check the list of our [officially supported platforms](System-Requirements.md#supported-platforms). @@ -19,6 +28,8 @@ To install and deploy the Operator, you need the following: * [Create and configure the GKE cluster](gke.md#create-and-configure-the-gke-cluster) * [Set up Amazon Elastic Kubernetes Service](eks.md#software-installation) +4. Privileges to create Custom Resource Definitions (CRDs), RBAC resources, and deploy the Operator + ## Installation Here's a sequence of steps to follow: @@ -75,9 +86,7 @@ Here's a sequence of steps to follow: cluster1 cluster1-pgbouncer.postgres-operator.svc ready 3 3 143m ``` -You have successfully installed and deployed the Operator with default parameters. You can check them in the [Custom Resource options reference](operator.md). - -You can find in the documentation for the charts which [Operator :octicons-link-external-16:](https://github.com/percona/percona-helm-charts/tree/main/charts/pg-operator#installing-the-chart) and [database :octicons-link-external-16:](https://github.com/percona/percona-helm-charts/tree/main/charts/pg-db#installing-the-chart) parameters can be customized during installation. +You have successfully installed and deployed the Operator with default parameters. ## Next steps diff --git a/docs/kubectl.md b/docs/kubectl.md index 2b1d0192..05364888 100644 --- a/docs/kubectl.md +++ b/docs/kubectl.md @@ -1,13 +1,13 @@ -# Install Percona Distribution for PostgreSQL using kubectl +# Install Percona Operator for PostgreSQL using kubectl -A Kubernetes Operator is a special type of controller introduced to simplify complex deployments. The Operator extends the Kubernetes API with custom resources. +Percona Operator for PostgreSQL is a custom controller that will manage your PostgreSQL clusters inside Kubernetes. The Operator will automatically deploy, maintain, and monitor PostgreSQL databases automatically, so you don't have to manage these tasks manually. -The [Percona Operator for PostgreSQL](compare.md) is based on best practices for configuration and setup of a Percona Distribution for PostgreSQL cluster in a Kubernetes-based environment on-premises or in the cloud. - -We recommend installing the Operator with the [kubectl :octicons-link-external-16:](https://kubernetes.io/docs/tasks/tools/) command line utility. It is the universal way to interact with Kubernetes. Alternatively, you can install it using the [Helm :octicons-link-external-16:](https://github.com/helm/helm) package manager. +We recommend installing the Operator with the [kubectl :octicons-link-external-16:](https://kubernetes.io/docs/tasks/tools/) command line utility. It is the universal way to interact with Kubernetes. Alternatively, you can install the Operator using the [Helm :octicons-link-external-16:](https://github.com/helm/helm) package manager. [:simple-kubernetes: Install with kubectl :material-arrow-down:](#prerequisites){.md-button} [:simple-helm: Install with Helm :material-arrow-right:](helm.md){.md-button} +--8<-- "what-you-install.txt" + ## Prerequisites To install Percona Distribution for PostgreSQL, you need the following: diff --git a/docs/update-operator.md b/docs/update-operator.md index ea4f0847..6aae63e7 100644 --- a/docs/update-operator.md +++ b/docs/update-operator.md @@ -73,7 +73,7 @@ You can upgrade the Operator and CRD as follows, considering the Operator uses In case of [cluster-wide installation](cluster-wide.md), use `deploy/cw-rbac.yaml` instead of `deploy/rbac.yaml`. -2. Next, update the Percona Distribution for PostgreSQL Operator Deployment in Kubernetes by changing the container image of the Operator Pod to the latest version. Find the image name for the current Operator release [in the list of certified images](images.md). Use the following command to update the Operator to the `{{ release }}` version: +2. Next, update the Percona Operator for PostgreSQL Deployment in Kubernetes by changing the container image of the Operator Pod to the latest version. Find the image name for the current Operator release [in the list of certified images](images.md). Use the following command to update the Operator to the `{{ release }}` version: ```bash kubectl -n postgres-operator patch deployment percona-postgresql-operator \ From d03ba55b03b84454ec5efe9527c8f45d8e21d681 Mon Sep 17 00:00:00 2001 From: Anastasia Alexandrova Date: Wed, 18 Feb 2026 11:26:29 +0100 Subject: [PATCH 2/6] Update docs/kubectl.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/kubectl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/kubectl.md b/docs/kubectl.md index 05364888..fad12100 100644 --- a/docs/kubectl.md +++ b/docs/kubectl.md @@ -1,6 +1,6 @@ # Install Percona Operator for PostgreSQL using kubectl -Percona Operator for PostgreSQL is a custom controller that will manage your PostgreSQL clusters inside Kubernetes. The Operator will automatically deploy, maintain, and monitor PostgreSQL databases automatically, so you don't have to manage these tasks manually. +Percona Operator for PostgreSQL is a custom controller that will manage your PostgreSQL clusters inside Kubernetes. The Operator will automatically deploy, maintain, and monitor PostgreSQL databases, so you don't have to manage these tasks manually. We recommend installing the Operator with the [kubectl :octicons-link-external-16:](https://kubernetes.io/docs/tasks/tools/) command line utility. It is the universal way to interact with Kubernetes. Alternatively, you can install the Operator using the [Helm :octicons-link-external-16:](https://github.com/helm/helm) package manager. From 99ac2e59d92cf7da1632bd477d61d345ce988f3b Mon Sep 17 00:00:00 2001 From: Anastasia Alexandrova Date: Wed, 18 Feb 2026 11:26:42 +0100 Subject: [PATCH 3/6] Update docs/update-operator.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/update-operator.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/update-operator.md b/docs/update-operator.md index 6aae63e7..86dbc8d8 100644 --- a/docs/update-operator.md +++ b/docs/update-operator.md @@ -73,7 +73,7 @@ You can upgrade the Operator and CRD as follows, considering the Operator uses In case of [cluster-wide installation](cluster-wide.md), use `deploy/cw-rbac.yaml` instead of `deploy/rbac.yaml`. -2. Next, update the Percona Operator for PostgreSQL Deployment in Kubernetes by changing the container image of the Operator Pod to the latest version. Find the image name for the current Operator release [in the list of certified images](images.md). Use the following command to update the Operator to the `{{ release }}` version: + 2. Next, update the Percona Operator for PostgreSQL Deployment in Kubernetes by changing the container image of the Operator Pod to the latest version. Find the image name for the current Operator release [in the list of certified images](images.md). Use the following command to update the Operator to the `{{ release }}` version: ```bash kubectl -n postgres-operator patch deployment percona-postgresql-operator \ From d30482ceb286573a32c1fbbb067b8dfc72087ffe Mon Sep 17 00:00:00 2001 From: Anastasia Alexandrova Date: Wed, 18 Feb 2026 11:26:53 +0100 Subject: [PATCH 4/6] Update docs/assets/fragments/what-you-install.txt Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/assets/fragments/what-you-install.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/assets/fragments/what-you-install.txt b/docs/assets/fragments/what-you-install.txt index 674fe834..3f997762 100644 --- a/docs/assets/fragments/what-you-install.txt +++ b/docs/assets/fragments/what-you-install.txt @@ -3,10 +3,10 @@ * The Operator - the custom controller that uses the custom resources to install and manage the lifecycle of your database cluster. It consists of the following components: * the Operator Deployment - the controller Pod - * the CustomResourceDefinitions (CRDs) are a way to add new API types (custom resources) to Kubernetes so that it understands and handles them + * The CustomResourceDefinitions (CRDs) add new API types (custom resources) to Kubernetes so that it can understand and manage them * Role-based access control (RBAC) is the system that controls who can perform which actions on which resources, using roles and bindings to enforce safe, predictable access. -* The database cluster - the actual Percona Distribution for PostgreSQL cluster that the Operator creates for you when you apply the Custom Resource or install the Helm chart. It includes StatefulSets for postgres servers, Services and Secrets. +* The database cluster - the actual Percona Distribution for PostgreSQL cluster that the Operator creates for you when you apply the Custom Resource or install the Helm chart. It includes StatefulSets for PostgreSQL servers, Services and Secrets. The default Percona Distribution for PostgreSQL configuration includes: From 5c5157ae56caf00da1159ec22d1a43923ad28011 Mon Sep 17 00:00:00 2001 From: Anastasia Alexandrova Date: Wed, 18 Feb 2026 11:27:03 +0100 Subject: [PATCH 5/6] Update docs/custom-install.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/custom-install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/custom-install.md b/docs/custom-install.md index a647f526..e79f22e9 100644 --- a/docs/custom-install.md +++ b/docs/custom-install.md @@ -99,7 +99,7 @@ To check available configuration options, see [deploy/cr.yaml :octicons-link-ext !!! note "Cluster name length" - For the pg-db chart, the cluster name is limited to 21 characters, must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character. Keep this in mind when using `fullnameOverride` or long release names. + For the pg-db chart, the cluster name is limited to 21 characters, must consist of lowercase alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character. Keep this in mind when using `fullnameOverride` or long release names. ## Common Helm values reference From eeb5a2da31243f34ef488fc35744a85703408cd4 Mon Sep 17 00:00:00 2001 From: Anastasia Alexadrova Date: Wed, 18 Feb 2026 12:35:21 +0100 Subject: [PATCH 6/6] Updated after the review --- docs/assets/fragments/what-you-install.txt | 6 +++--- docs/kubectl.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/assets/fragments/what-you-install.txt b/docs/assets/fragments/what-you-install.txt index 3f997762..0a0c04ce 100644 --- a/docs/assets/fragments/what-you-install.txt +++ b/docs/assets/fragments/what-you-install.txt @@ -11,8 +11,8 @@ The default Percona Distribution for PostgreSQL configuration includes: * 3 PostgreSQL servers, one Primary and two replicas. -* a pgBouncer instance - a lightweight connection pooler for PostgreSQL that sits between client applications and the database server to manage and reuse connections efficiently. -* a pgBackRest instance - a backup and restore utility for PostgreSQL that provides a way to backup and restore your database. -* a PMM client instance - a monitoring and management tool for PostgreSQL that provides a way to monitor and manage your database. +* 3 pgBouncer instances - a lightweight connection pooler for PostgreSQL that sits between client applications and the database server to manage and reuse connections efficiently. +* a pgBackRest repository host instance – a dedicated instance in your cluster that stores filesystem backups made with pgBackRest - a backup and restore utility. +* a PMM client instance - a monitoring and management tool for PostgreSQL that provides a way to monitor and manage your database. It runs as a sidecar container in the database Pods. Read more about the default components in the [Architecture](architecture.md) section. diff --git a/docs/kubectl.md b/docs/kubectl.md index fad12100..d1a41b40 100644 --- a/docs/kubectl.md +++ b/docs/kubectl.md @@ -10,7 +10,7 @@ We recommend installing the Operator with the [kubectl :octicons-link-external-1 ## Prerequisites -To install Percona Distribution for PostgreSQL, you need the following: +To install Percona Operator for PostgreSQL, you need the following: 1. The **kubectl** tool to manage and deploy applications on Kubernetes, included in most Kubernetes distributions. Install not already installed, [follow its official installation instructions :octicons-link-external-16:](https://kubernetes.io/docs/tasks/tools/install-kubectl/).