K8SPG-914 Documented naming conventions for Helm resources.

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) 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 PostgreSQL servers, Services and Secrets. 
+
+The default Percona Distribution for PostgreSQL configuration includes:
+
+* 3 PostgreSQL servers, one Primary and two replicas. 
+* 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.

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 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
+
+    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 |

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
 

docs/kubectl.md

@@ -1,16 +1,16 @@
-# 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, 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:
+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/).
 

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 \