From 3c8a5ef4ecd14061d15a4868c9aa24b7e3b0a1d8 Mon Sep 17 00:00:00 2001 From: Anastasia Alexadrova Date: Mon, 27 Apr 2026 12:01:31 +0200 Subject: [PATCH 1/4] K8SPXC-1768 Updated the custom installation documentation Added how to override Helm release names --- docs/custom-install.md | 158 ++++++++++++++++++++++++++++++----------- 1 file changed, 116 insertions(+), 42 deletions(-) diff --git a/docs/custom-install.md b/docs/custom-install.md index 025fe7c..c4b9dc0 100644 --- a/docs/custom-install.md +++ b/docs/custom-install.md @@ -1,8 +1,22 @@ # Install Percona XtraDB Cluster with customized parameters -You can customize the configuration of Percona XtraDB Cluster and install it with customized parameters. +You can adjust the configuration of the Operator Deployment and/or Percona XtraDB Cluster and install them with customized parameters. -To check available configuration options, see [`deploy/cr.yaml` :octicons-link-external-16:](https://raw.githubusercontent.com/percona/percona-xtradb-cluster-operator/v{{ release }}/deploy/cr.yaml) and [Custom Resource Options](operator.md). +To check available configuration options, see the following manifests: + +* [`deploy/bundle.yaml` :octicons-link-external-16:](https://raw.githubusercontent.com/percona/percona-xtradb-cluster-operator/v{{ release }}/deploy/bundle.yaml) +* [`deploy/cr.yaml` :octicons-link-external-16:](https://raw.githubusercontent.com/percona/percona-xtradb-cluster-operator/v{{ release }}/deploy/cr.yaml). + +Also check the following documentation sections: + +* [Configure Operator environment variables](env-vars-operator.md) +* [Custom Resource Options](operator.md) reference. + +!!! tip + + If you have installed the Operator and wish to update its configuration, you can do so by modifying and applying the [`deploy/operator.yaml` :octicons-link-external-16:](https://raw.githubusercontent.com/percona/percona-xtradb-cluster-operator/v{{ release }}/deploy/operator.yaml) manifest. + +Select how you wish to install the Operator and the database cluster: === "`kubectl`" @@ -14,60 +28,120 @@ To check available configuration options, see [`deploy/cr.yaml` :octicons-link-e git clone -b v{{ release }} https://github.com/percona/percona-xtradb-cluster-operator ``` - 2. Edit the required options and apply the modified `deploy/cr.yaml` file as follows: + 2. To customize the Operator Deployment, edit the required environment variables and apply the modified `deploy/bundle.yaml` file as follows: ```bash - kubectl apply -f deploy/cr.yaml + kubectl apply --server-side -f deploy/bundle.yaml -n + ``` + + 3. To customize Percona XtraDB Cluster, edit the required options in the `deploy/cr.yaml` file and apply it as follows: + + ```bash + kubectl apply -f deploy/cr.yaml -n ``` - === "Helm" - To install Percona XtraDB Cluster with custom parameters, use the following command: + You can install the Operator deployment and the Percona XtraDB 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/pxc-operator#installing-the-chart) and the [Percona Server for MySQL chart documentation :octicons-link-external-16:](https://github.com/percona/percona-helm-charts/tree/main/charts/pxc-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. + + **Using `--set` flags** + + To pass a custom parameter to Helm, use the `--set key=value` flag with the `helm install` command as follows: ```bash helm install --set key=value ``` + + For example, to install Percona XtraDB Cluster in the + `pxc` namespace with disabled backups and 20 Gi storage, run: + + ```bash + helm install my-db percona/pxc-db --version {{ release }} --namespace pxc \ + --set pxc.volumeSpec.resources.requests.storage=20Gi \ + --set backup.enabled=false + ``` + + **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/ps-db --version {{ release }} --namespace -f values.yaml + ``` - You can pass any of the Operator’s [Custom Resource options :octicons-link-external-16:](https://github.com/percona/percona-helm-charts/tree/main/charts/pxc-db#installing-the-chart) as a - `--set key=value[,key=value]` argument. + Example `values.yaml`: - The following example deploys a Percona XtraDB Cluster in the - `pxc` namespace, with disabled backups and 20 Gi storage: + ``` yaml title="values.yaml" + allowUnsafeConfigurations: true + sharding: + enabled: false + pxc: + size: 3 + volumeSpec: + pvc: + resources: + requests: + storage: 2Gi + backup: + enabled: false + ``` - === "Command line" + ## Naming conventions for Helm resources - ```bash - helm install my-db percona/pxc-db --version {{ release }} --namespace pxc \ - --set pxc.volumeSpec.resources.requests.storage=20Gi \ - --set backup.enabled=false - ``` - - === "YAML file" - - You can specify customized options in a YAML file instead of using separate command line parameters. The resulting - file similar to the following example looks as follows: - - ``` yaml title="values.yaml" - allowUnsafeConfigurations: true - sharding: - enabled: false - pxc: - size: 3 - volumeSpec: - pvc: - resources: - requests: - storage: 2Gi - backup: - enabled: false - ``` - - Apply the resulting YAML file as follows: + 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`. - ```bash - helm install my-db percona/pxc-db --namespace pxc -f values.yaml - ``` + 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-op percona/pxc-operator --namespace my-namespace \ + --set nameOverride=pxc-operator + ``` + + Deployment name: `my-op-pxc-operator`. + + ```bash + helm install cluster1 percona/pxc-db -n my-namespace \ + --set nameOverride=pxc + ``` + + Cluster name: `cluster1-pxc`. + + *Using `fullnameOverride`* — replaces the full resource name: + + ```bash + helm install my-op percona/pxc-operator --namespace my-namespace \ + --set fullnameOverride=percona-xtradb-cluster-operator + ``` + + Deployment name: `percona-xtradb-cluster-operator`. + + ```bash + helm install cluster1 percona/pxc-db -n my-namespace \ + --set fullnameOverride=my-pxc-db + ``` + + Cluster name: `my-pxc-db`. + + !!! note "Cluster naming" + + Use names that satisfy [Kubernetes naming rules :octicons-link-external-16:](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) for resources and DNS labels. If you use long release names together with `nameOverride` or `fullnameOverride`, ensure the resulting names stay within length limits your environment allows. + + ## 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` | [pxc-operator](https://github.com/percona/percona-helm-charts/blob/main/charts/pxc-operator/values.yaml), [pxc-db](https://github.com/percona/percona-helm-charts/blob/main/charts/pxc-db/values.yaml) | Replaces the chart name in generated resource names | + | `fullnameOverride` | [pxc-operator](https://github.com/percona/percona-helm-charts/blob/main/charts/pxc-operator/values.yaml), [pxc-db](https://github.com/percona/percona-helm-charts/blob/main/charts/pxc-db/values.yaml) | Replaces the entire generated resource name | + | `watchAllNamespaces` | [pxc-operator](https://github.com/percona/percona-helm-charts/blob/main/charts/pxc-operator/values.yaml) | Deploy the Operator in cluster-wide mode to watch all namespaces | + | `disableTelemetry` | [pxc-operator](https://github.com/percona/percona-helm-charts/blob/main/charts/pxc-operator/values.yaml) | Disable telemetry collection. See [Telemetry](telemetry.md) for details | From 15f06df5e43c2ae023856b491690a0d2f9963eb5 Mon Sep 17 00:00:00 2001 From: Anastasia Alexandrova Date: Mon, 27 Apr 2026 12:09:15 +0200 Subject: [PATCH 2/4] 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 c4b9dc0..950610a 100644 --- a/docs/custom-install.md +++ b/docs/custom-install.md @@ -51,7 +51,7 @@ Select how you wish to install the Operator and the database cluster: To pass a custom parameter to Helm, use the `--set key=value` flag with the `helm install` command as follows: ```bash - helm install --set key=value + helm install --set key=value ``` For example, to install Percona XtraDB Cluster in the From a67cbb9ccb7d24b52fd8288a2bc07c29fafe2656 Mon Sep 17 00:00:00 2001 From: Anastasia Alexandrova Date: Mon, 27 Apr 2026 12:09:26 +0200 Subject: [PATCH 3/4] 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 950610a..1380979 100644 --- a/docs/custom-install.md +++ b/docs/custom-install.md @@ -42,7 +42,7 @@ Select how you wish to install the Operator and the database cluster: === "Helm" - You can install the Operator deployment and the Percona XtraDB 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/pxc-operator#installing-the-chart) and the [Percona Server for MySQL chart documentation :octicons-link-external-16:](https://github.com/percona/percona-helm-charts/tree/main/charts/pxc-db#installing-the-chart). + You can install the Operator deployment and the Percona XtraDB 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/pxc-operator#installing-the-chart) and the [Percona XtraDB Cluster chart documentation :octicons-link-external-16:](https://github.com/percona/percona-helm-charts/tree/main/charts/pxc-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. From 250272bf3f977eea1fd00ff06756a304b8d1f7a3 Mon Sep 17 00:00:00 2001 From: Anastasia Alexandrova Date: Mon, 27 Apr 2026 12:09:33 +0200 Subject: [PATCH 4/4] Update docs/custom-install.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/custom-install.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/docs/custom-install.md b/docs/custom-install.md index 1380979..a93772f 100644 --- a/docs/custom-install.md +++ b/docs/custom-install.md @@ -55,11 +55,11 @@ Select how you wish to install the Operator and the database cluster: ``` For example, to install Percona XtraDB Cluster in the - `pxc` namespace with disabled backups and 20 Gi storage, run: + `pxc` namespace with 20 Gi storage, run: ```bash helm install my-db percona/pxc-db --version {{ release }} --namespace pxc \ - --set pxc.volumeSpec.resources.requests.storage=20Gi \ + --set pxc.volumeSpec.persistentVolumeClaim.resources.requests.storage=20Gi \ --set backup.enabled=false ``` @@ -68,24 +68,19 @@ Select how you wish to install the Operator and the database cluster: 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/ps-db --version {{ release }} --namespace -f values.yaml + helm install my-db percona/pxc-db --version {{ release }} --namespace -f values.yaml ``` Example `values.yaml`: ``` yaml title="values.yaml" - allowUnsafeConfigurations: true - sharding: - enabled: false pxc: size: 3 volumeSpec: - pvc: + persistentVolumeClaim: resources: requests: storage: 2Gi - backup: - enabled: false ``` ## Naming conventions for Helm resources