From 177e70c31e055061e14550de9707a492b0428a4f Mon Sep 17 00:00:00 2001 From: Bonusree Date: Tue, 16 Jun 2026 13:26:40 +0600 Subject: [PATCH 1/2] pgbouncer,proxysql customconfig Signed-off-by: Bonusree --- docs/guides/pgbouncer/configuration/_index.md | 10 + .../using-config-file/examples/pb-custom.yaml | 19 ++ .../configuration/using-config-file/index.md | 162 ++++++++++++++++ .../examples/pb-misc-config.yaml | 28 +++ .../configuration/using-pod-template/index.md | 138 +++++++++++++ docs/guides/proxysql/configuration/_index.md | 10 + .../examples/proxysql-custom.yaml | 14 ++ .../configuration/using-config-file/index.md | 181 ++++++++++++++++++ .../examples/proxysql-misc-config.yaml | 22 +++ .../configuration/using-pod-template/index.md | 174 +++++++++++++++++ 10 files changed, 758 insertions(+) create mode 100644 docs/guides/pgbouncer/configuration/_index.md create mode 100644 docs/guides/pgbouncer/configuration/using-config-file/examples/pb-custom.yaml create mode 100644 docs/guides/pgbouncer/configuration/using-config-file/index.md create mode 100644 docs/guides/pgbouncer/configuration/using-pod-template/examples/pb-misc-config.yaml create mode 100644 docs/guides/pgbouncer/configuration/using-pod-template/index.md create mode 100644 docs/guides/proxysql/configuration/_index.md create mode 100644 docs/guides/proxysql/configuration/using-config-file/examples/proxysql-custom.yaml create mode 100644 docs/guides/proxysql/configuration/using-config-file/index.md create mode 100644 docs/guides/proxysql/configuration/using-pod-template/examples/proxysql-misc-config.yaml create mode 100644 docs/guides/proxysql/configuration/using-pod-template/index.md diff --git a/docs/guides/pgbouncer/configuration/_index.md b/docs/guides/pgbouncer/configuration/_index.md new file mode 100644 index 0000000000..3aee0cc301 --- /dev/null +++ b/docs/guides/pgbouncer/configuration/_index.md @@ -0,0 +1,10 @@ +--- +title: Run PgBouncer with Custom Configuration +menu: + docs_{{ .version }}: + identifier: pb-configuration + name: Custom Configuration + parent: pb-pgbouncer-guides + weight: 35 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/pgbouncer/configuration/using-config-file/examples/pb-custom.yaml b/docs/guides/pgbouncer/configuration/using-config-file/examples/pb-custom.yaml new file mode 100644 index 0000000000..a5734e2aa0 --- /dev/null +++ b/docs/guides/pgbouncer/configuration/using-config-file/examples/pb-custom.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1 +kind: PgBouncer +metadata: + name: sample-pgbouncer + namespace: demo +spec: + version: "1.18.0" + replicas: 1 + database: + syncUsers: true + databaseName: "postgres" + databaseRef: + name: "quick-postgres" + namespace: demo + connectionPool: + port: 5432 + configuration: + secretName: pb-configuration + deletionPolicy: WipeOut diff --git a/docs/guides/pgbouncer/configuration/using-config-file/index.md b/docs/guides/pgbouncer/configuration/using-config-file/index.md new file mode 100644 index 0000000000..aec6009782 --- /dev/null +++ b/docs/guides/pgbouncer/configuration/using-config-file/index.md @@ -0,0 +1,162 @@ +--- +title: Run PgBouncer with Custom Configuration File +menu: + docs_{{ .version }}: + identifier: pb-configuration-usingconfigfile + name: Config File + parent: pb-configuration + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Using Custom Configuration File + +KubeDB supports providing custom configuration for PgBouncer. This tutorial will show you how to use KubeDB to run a PgBouncer with custom configuration. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +- You will need a PostgreSQL server for PgBouncer to connect to. You can prepare one by following the [PgBouncer quickstart](/docs/guides/pgbouncer/quickstart/quickstart.md) tutorial. In this tutorial, we will use a Postgres named `quick-postgres` in the `demo` namespace. + +- To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + + ```bash + $ kubectl create ns demo + namespace/demo created + + $ kubectl get ns demo + NAME STATUS AGE + demo Active 5s + ``` + +> Note: YAML files used in this tutorial are stored in [here](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/guides/pgbouncer/configuration/using-config-file/examples) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +PgBouncer is configured via an ini-style configuration file, `pgbouncer.ini`. KubeDB lets you provide a custom `pgbouncer.ini` file through `spec.configuration.secretName`. The operator reads this Secret internally and merges its content with the configuration generated from `spec.connectionPool`; settings from the custom config file take precedence over the generated defaults. + +In this tutorial, we will configure [`auth_type`](https://www.pgbouncer.org/config.html#auth_type) and [`max_client_conn`](https://www.pgbouncer.org/config.html#max_client_conn) via a custom config file. We will use a Secret as the configuration source. + +## Custom Configuration + +At first, let's create `pgbouncer.ini` file setting `auth_type` and `max_client_conn` parameters. + +```bash +cat < pgbouncer.ini +[pgbouncer] +auth_type = scram-sha-256 +max_client_conn = 100 +EOF + +$ cat pgbouncer.ini +[pgbouncer] +auth_type = scram-sha-256 +max_client_conn = 100 +``` + +Now, create a Secret with this configuration file. + +```bash +$ kubectl create secret generic -n demo pb-configuration --from-file=./pgbouncer.ini +secret/pb-configuration created +``` + +Verify the Secret has the configuration file. + +```yaml +$ kubectl get secret -n demo pb-configuration -o yaml +apiVersion: v1 +stringData: + pgbouncer.ini: | + [pgbouncer] + auth_type = scram-sha-256 + max_client_conn = 100 +kind: Secret +metadata: + name: pb-configuration + namespace: demo + ... +``` + +Now, create PgBouncer crd specifying `spec.configuration.secretName` field. + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/pgbouncer/configuration/using-config-file/examples/pb-custom.yaml +pgbouncer.kubedb.com/sample-pgbouncer created +``` + +Below is the YAML for the PgBouncer crd we just created. + +```yaml +apiVersion: kubedb.com/v1 +kind: PgBouncer +metadata: + name: sample-pgbouncer + namespace: demo +spec: + version: "1.18.0" + replicas: 1 + database: + syncUsers: true + databaseName: "postgres" + databaseRef: + name: "quick-postgres" + namespace: demo + connectionPool: + port: 5432 + configuration: + secretName: pb-configuration + deletionPolicy: WipeOut +``` + +Now, wait a few minutes. KubeDB operator will create necessary petset, services, secret etc. If everything goes well, we will see that a pod with the name `sample-pgbouncer-0` has been created. + +Check that the petset's pod is running + +```bash +$ kubectl get pod -n demo +NAME READY STATUS RESTARTS AGE +sample-pgbouncer-0 1/1 Running 0 45s + +$ kubectl get pgbouncer -n demo +NAME TYPE VERSION STATUS AGE +sample-pgbouncer kubedb.com/v1 1.18.0 Ready 71s +``` + +We can see the PgBouncer is in `Ready` phase so it can accept connections. + +Now, we will check if PgBouncer has started with the custom configuration we have provided. + +```bash +$ kubectl exec -it -n demo sample-pgbouncer-0 -- bash +pgbouncer@sample-pgbouncer-0:/$ cat etc/config/pgbouncer.ini +[databases] +postgres = host=quick-postgres.demo.svc port=5432 dbname=postgres + +[pgbouncer] +max_client_conn = 100 +... +auth_type = scram-sha-256 +... +pgbouncer@sample-pgbouncer-0:/$ exit +exit +``` + +We can see that the values of `auth_type` and `max_client_conn` are the same as we provided in the custom config file. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl delete pgbouncer -n demo sample-pgbouncer +pgbouncer.kubedb.com "sample-pgbouncer" deleted +$ kubectl delete ns demo +namespace "demo" deleted +``` diff --git a/docs/guides/pgbouncer/configuration/using-pod-template/examples/pb-misc-config.yaml b/docs/guides/pgbouncer/configuration/using-pod-template/examples/pb-misc-config.yaml new file mode 100644 index 0000000000..2194190913 --- /dev/null +++ b/docs/guides/pgbouncer/configuration/using-pod-template/examples/pb-misc-config.yaml @@ -0,0 +1,28 @@ +apiVersion: kubedb.com/v1 +kind: PgBouncer +metadata: + name: sample-pgbouncer + namespace: demo +spec: + version: "1.18.0" + replicas: 1 + database: + syncUsers: true + databaseName: "postgres" + databaseRef: + name: "quick-postgres" + namespace: demo + connectionPool: + port: 5432 + podTemplate: + metadata: + annotations: + passMe: ToPbPod + spec: + containers: + - name: pgbouncer + resources: + requests: + memory: "256Mi" + cpu: "250m" + deletionPolicy: WipeOut diff --git a/docs/guides/pgbouncer/configuration/using-pod-template/index.md b/docs/guides/pgbouncer/configuration/using-pod-template/index.md new file mode 100644 index 0000000000..8f26352ec7 --- /dev/null +++ b/docs/guides/pgbouncer/configuration/using-pod-template/index.md @@ -0,0 +1,138 @@ +--- +title: Run PgBouncer with Custom PodTemplate +menu: + docs_{{ .version }}: + identifier: pb-configuration-usingpodtemplate + name: Customize PodTemplate + parent: pb-configuration + weight: 15 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Run PgBouncer with Custom PodTemplate + +KubeDB supports providing custom configuration for PgBouncer via [PodTemplate](/docs/guides/pgbouncer/concepts/pgbouncer.md#specpodtemplate). This tutorial will show you how to use KubeDB to run a PgBouncer server with custom configuration using PodTemplate. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +- You will need a PostgreSQL server for PgBouncer to connect to. You can prepare one by following the [PgBouncer quickstart](/docs/guides/pgbouncer/quickstart/quickstart.md) tutorial. In this tutorial, we will use a Postgres named `quick-postgres` in the `demo` namespace. + +- To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + + ```bash + $ kubectl create ns demo + namespace/demo created + ``` + +> Note: YAML files used in this tutorial are stored in [here](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/guides/pgbouncer/configuration/using-pod-template/examples) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +KubeDB allows providing a template for PgBouncer pods through `spec.podTemplate`. KubeDB operator will pass the information provided in `spec.podTemplate` to the PetSet created for the PgBouncer server. + +KubeDB accepts the following fields to set in `spec.podTemplate`: + +- metadata: + - annotations (pod's annotation) +- controller: + - annotations (petset's annotation) +- spec: + - containers + - env + - resources + - initContainers + - imagePullSecrets + - nodeSelector + - schedulerName + - tolerations + - priorityClassName + - priority + - securityContext + +Read about the fields in detail in [PodTemplate concept](/docs/guides/pgbouncer/concepts/pgbouncer.md#specpodtemplate). + +## CRD Configuration + +Below is the YAML for the PgBouncer used in this example. Here, `spec.podTemplate.metadata.annotations` adds a custom annotation to the pod and `spec.podTemplate.spec.containers[].resources` requests compute resources for the `pgbouncer` container. + +```yaml +apiVersion: kubedb.com/v1 +kind: PgBouncer +metadata: + name: sample-pgbouncer + namespace: demo +spec: + version: "1.18.0" + replicas: 1 + database: + syncUsers: true + databaseName: "postgres" + databaseRef: + name: "quick-postgres" + namespace: demo + connectionPool: + port: 5432 + podTemplate: + metadata: + annotations: + passMe: ToPbPod + spec: + containers: + - name: pgbouncer + resources: + requests: + memory: "256Mi" + cpu: "250m" + deletionPolicy: WipeOut +``` + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/pgbouncer/configuration/using-pod-template/examples/pb-misc-config.yaml +pgbouncer.kubedb.com/sample-pgbouncer created +``` + +Now, wait a few minutes. KubeDB operator will create necessary petset, services, secret etc. If everything goes well, we will see that a pod with the name `sample-pgbouncer-0` has been created. + +Check that the petset's pod is running + +```bash +$ kubectl get pod -n demo +NAME READY STATUS RESTARTS AGE +sample-pgbouncer-0 1/1 Running 0 45s +``` + +Now, we will check if the pod has started with the custom configuration we have provided. + +Check that the annotation has been set on the pod. + +```bash +$ kubectl get pod -n demo sample-pgbouncer-0 -o jsonpath='{.metadata.annotations}' +map[passMe:ToPbPod] +``` + +Check that the resource requests have been set on the `pgbouncer` container. + +```bash +$ kubectl get pod -n demo sample-pgbouncer-0 -o jsonpath='{.spec.containers[?(@.name=="pgbouncer")].resources}' +{"requests":{"cpu":"250m","memory":"256Mi"}} +``` + +We can see that both the annotation and the resource requests we provided through `spec.podTemplate` have been applied to the pod. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl delete pgbouncer -n demo sample-pgbouncer +pgbouncer.kubedb.com "sample-pgbouncer" deleted +$ kubectl delete ns demo +namespace "demo" deleted +``` diff --git a/docs/guides/proxysql/configuration/_index.md b/docs/guides/proxysql/configuration/_index.md new file mode 100644 index 0000000000..cb6ac856d8 --- /dev/null +++ b/docs/guides/proxysql/configuration/_index.md @@ -0,0 +1,10 @@ +--- +title: Run ProxySQL with Custom Configuration +menu: + docs_{{ .version }}: + identifier: guides-proxysql-configuration + name: Custom Configuration + parent: guides-proxysql + weight: 35 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/proxysql/configuration/using-config-file/examples/proxysql-custom.yaml b/docs/guides/proxysql/configuration/using-config-file/examples/proxysql-custom.yaml new file mode 100644 index 0000000000..9027ace7bb --- /dev/null +++ b/docs/guides/proxysql/configuration/using-config-file/examples/proxysql-custom.yaml @@ -0,0 +1,14 @@ +apiVersion: kubedb.com/v1 +kind: ProxySQL +metadata: + name: sample-proxysql + namespace: demo +spec: + version: "2.7.3-debian" + replicas: 1 + backend: + name: mysql-server + configuration: + init: + secretName: proxysql-configuration + deletionPolicy: WipeOut diff --git a/docs/guides/proxysql/configuration/using-config-file/index.md b/docs/guides/proxysql/configuration/using-config-file/index.md new file mode 100644 index 0000000000..34c27bffc5 --- /dev/null +++ b/docs/guides/proxysql/configuration/using-config-file/index.md @@ -0,0 +1,181 @@ +--- +title: Run ProxySQL with Custom Configuration File +menu: + docs_{{ .version }}: + identifier: guides-proxysql-configuration-usingconfigfile + name: Config File + parent: guides-proxysql-configuration + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Using Custom Configuration File + +KubeDB supports providing custom bootstrap configuration for ProxySQL. This tutorial will show you how to use KubeDB to run a ProxySQL server with custom configuration. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +- To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + + ```bash + $ kubectl create ns demo + namespace/demo created + ``` + +> Note: YAML files used in this tutorial are stored in [here](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/guides/proxysql/configuration/using-config-file/examples) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +ProxySQL bootstraps itself from a `proxysql.cnf` configuration file built from a few tables: `mysql_users`, `mysql_query_rules`, `mysql_variables` and `admin_variables`. KubeDB lets you provide this bootstrap configuration declaratively through `spec.configuration.init.secretName`. You create a Secret containing one or more of the keys `AdminVariables.cnf`, `MySQLVariables.cnf`, `MySQLUsers.cnf`, `MySQLQueryRules.cnf`, and the operator patches their contents verbatim into `proxysql.cnf` during bootstrap. This configuration is applied only once, when ProxySQL is initialized. + +> Note: `spec.configuration.init.inline` lets you provide the same kind of bootstrap configuration as structured YAML instead of raw `*.cnf` text, and always takes precedence over `secretName`. See the [ProxySQL concept page](/docs/guides/proxysql/concepts/proxysql/index.md#specconfigurationsecretname) for details. + +In this tutorial, we will set [`mysql-max_connections`](https://proxysql.com/documentation/global-variables/mysql-variables/#mysql-max_connections) via a custom config file. + +## Prepare MySQL Backend + +ProxySQL needs a backend server to proxy. We will use a 3 node MySQL Group Replication cluster set up with KubeDB. + +```yaml +apiVersion: kubedb.com/v1 +kind: MySQL +metadata: + name: mysql-server + namespace: demo +spec: + version: "8.4.3" + replicas: 3 + topology: + mode: GroupReplication + storageType: Durable + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/backends/mysqlgrp/examples/sample-mysql.yaml +mysql.kubedb.com/mysql-server created +``` + +Wait for the MySQL cluster to be `Ready`. + +```bash +$ kubectl get my -n demo +NAME VERSION STATUS AGE +mysql-server 8.4.3 Ready 7m6s +``` + +> You can use MariaDB or Percona XtraDB as a backend as well. Have a look at the other [ProxySQL backend examples](/docs/guides/proxysql/backends/). + +## Custom Configuration + +At first, let's create a `MySQLVariables.cnf` file setting `mysql-max_connections`. + +```bash +cat < MySQLVariables.cnf +mysql_variables= +{ + max_connections=2048 +} +EOF + +$ cat MySQLVariables.cnf +mysql_variables= +{ + max_connections=2048 +} +``` + +Now, create a Secret with this configuration file. + +```bash +$ kubectl create secret generic -n demo proxysql-configuration --from-file=./MySQLVariables.cnf +secret/proxysql-configuration created +``` + +Now, create the ProxySQL crd specifying `spec.configuration.init.secretName` field. + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/configuration/using-config-file/examples/proxysql-custom.yaml +proxysql.kubedb.com/sample-proxysql created +``` + +Below is the YAML for the ProxySQL crd we just created. + +```yaml +apiVersion: kubedb.com/v1 +kind: ProxySQL +metadata: + name: sample-proxysql + namespace: demo +spec: + version: "2.7.3-debian" + replicas: 1 + backend: + name: mysql-server + configuration: + init: + secretName: proxysql-configuration + deletionPolicy: WipeOut +``` + +Now, wait a few minutes. KubeDB operator will create necessary petset, services, secret etc. If everything goes well, we will see that a pod with the name `sample-proxysql-0` has been created. + +Check that the petset's pod is running + +```bash +$ kubectl get pod -n demo +NAME READY STATUS RESTARTS AGE +sample-proxysql-0 1/1 Running 0 45s + +$ kubectl get proxysql -n demo +NAME VERSION STATUS AGE +sample-proxysql 2.7.3-debian Ready 71s +``` + +We can see the ProxySQL is in `Ready` phase. Now, we will check if ProxySQL has bootstrapped with the custom configuration we have provided. + +```bash +$ kubectl exec -it -n demo sample-proxysql-0 -- bash +root@sample-proxysql-0:/# mysql -uadmin -padmin -h127.0.0.1 -P6032 --prompt "ProxySQLAdmin > " +ProxySQLAdmin > select * from global_variables where variable_name='mysql-max_connections'; ++------------------------+----------------+ +| variable_name | variable_value | ++------------------------+----------------+ +| mysql-max_connections | 2048 | ++------------------------+----------------+ +1 row in set (0.00 sec) + +ProxySQLAdmin > exit +Bye +root@sample-proxysql-0:/# exit +exit +``` + +We can see that the value of `mysql-max_connections` is the same as we provided in the custom config file. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl delete proxysql -n demo sample-proxysql +proxysql.kubedb.com "sample-proxysql" deleted +$ kubectl delete mysql -n demo mysql-server +mysql.kubedb.com "mysql-server" deleted +$ kubectl delete ns demo +namespace "demo" deleted +``` diff --git a/docs/guides/proxysql/configuration/using-pod-template/examples/proxysql-misc-config.yaml b/docs/guides/proxysql/configuration/using-pod-template/examples/proxysql-misc-config.yaml new file mode 100644 index 0000000000..9f4b6b9143 --- /dev/null +++ b/docs/guides/proxysql/configuration/using-pod-template/examples/proxysql-misc-config.yaml @@ -0,0 +1,22 @@ +apiVersion: kubedb.com/v1 +kind: ProxySQL +metadata: + name: sample-proxysql + namespace: demo +spec: + version: "2.7.3-debian" + replicas: 1 + backend: + name: mysql-server + podTemplate: + metadata: + annotations: + passMe: ToProxySQLPod + spec: + containers: + - name: proxysql + resources: + requests: + memory: "256Mi" + cpu: "250m" + deletionPolicy: WipeOut diff --git a/docs/guides/proxysql/configuration/using-pod-template/index.md b/docs/guides/proxysql/configuration/using-pod-template/index.md new file mode 100644 index 0000000000..6f51672379 --- /dev/null +++ b/docs/guides/proxysql/configuration/using-pod-template/index.md @@ -0,0 +1,174 @@ +--- +title: Run ProxySQL with Custom PodTemplate +menu: + docs_{{ .version }}: + identifier: guides-proxysql-configuration-usingpodtemplate + name: Customize PodTemplate + parent: guides-proxysql-configuration + weight: 15 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Run ProxySQL with Custom PodTemplate + +KubeDB supports providing custom configuration for ProxySQL via [PodTemplate](/docs/guides/proxysql/concepts/proxysql/index.md#specpodtemplate). This tutorial will show you how to use KubeDB to run a ProxySQL server with custom configuration using PodTemplate. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +- To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + + ```bash + $ kubectl create ns demo + namespace/demo created + ``` + +> Note: YAML files used in this tutorial are stored in [here](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/guides/proxysql/configuration/using-pod-template/examples) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Prepare MySQL Backend + +ProxySQL needs a backend server to proxy. We will use a 3 node MySQL Group Replication cluster set up with KubeDB. + +```yaml +apiVersion: kubedb.com/v1 +kind: MySQL +metadata: + name: mysql-server + namespace: demo +spec: + version: "8.4.3" + replicas: 3 + topology: + mode: GroupReplication + storageType: Durable + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/backends/mysqlgrp/examples/sample-mysql.yaml +mysql.kubedb.com/mysql-server created +``` + +Wait for the MySQL cluster to be `Ready`. + +```bash +$ kubectl get my -n demo +NAME VERSION STATUS AGE +mysql-server 8.4.3 Ready 7m6s +``` + +> You can use MariaDB or Percona XtraDB as a backend as well. Have a look at the other [ProxySQL backend examples](/docs/guides/proxysql/backends/). + +## Overview + +KubeDB allows providing a template for the ProxySQL pod through `.spec.podTemplate`. KubeDB operator will pass the information provided in `.spec.podTemplate` to the PetSet created for ProxySQL. + +KubeDB accepts the following fields to set in `.spec.podTemplate`: + +- metadata: + - annotations (pod's annotation) +- controller: + - annotations (petset's annotation) +- spec: + - containers + - env + - resources + - initContainers + - imagePullSecrets + - nodeSelector + - schedulerName + - tolerations + - priorityClassName + - priority + - securityContext + - serviceAccountName + +Read about the fields in detail in [PodTemplate concept](/docs/guides/proxysql/concepts/proxysql/index.md#specpodtemplate). + +## CRD Configuration + +Below is the YAML for the ProxySQL used in this example. Here, `spec.podTemplate.metadata.annotations` adds a custom annotation to the pod and `spec.podTemplate.spec.containers[].resources` requests compute resources for the `proxysql` container. + +```yaml +apiVersion: kubedb.com/v1 +kind: ProxySQL +metadata: + name: sample-proxysql + namespace: demo +spec: + version: "2.7.3-debian" + replicas: 1 + backend: + name: mysql-server + podTemplate: + metadata: + annotations: + passMe: ToProxySQLPod + spec: + containers: + - name: proxysql + resources: + requests: + memory: "256Mi" + cpu: "250m" + deletionPolicy: WipeOut +``` + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/configuration/using-pod-template/examples/proxysql-misc-config.yaml +proxysql.kubedb.com/sample-proxysql created +``` + +Now, wait a few minutes. KubeDB operator will create necessary petset, services, secret etc. If everything goes well, we will see that a pod with the name `sample-proxysql-0` has been created. + +Check that the petset's pod is running + +```bash +$ kubectl get pod -n demo +NAME READY STATUS RESTARTS AGE +sample-proxysql-0 1/1 Running 0 45s +``` + +Now, we will check if the pod has started with the custom configuration we have provided. + +Check that the annotation has been set on the pod. + +```bash +$ kubectl get pod -n demo sample-proxysql-0 -o jsonpath='{.metadata.annotations}' +map[passMe:ToProxySQLPod] +``` + +Check that the resource requests have been set on the `proxysql` container. + +```bash +$ kubectl get pod -n demo sample-proxysql-0 -o jsonpath='{.spec.containers[?(@.name=="proxysql")].resources}' +{"requests":{"cpu":"250m","memory":"256Mi"}} +``` + +We can see that both the annotation and the resource requests we provided through `spec.podTemplate` have been applied to the pod. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl delete proxysql -n demo sample-proxysql +proxysql.kubedb.com "sample-proxysql" deleted +$ kubectl delete mysql -n demo mysql-server +mysql.kubedb.com "mysql-server" deleted +$ kubectl delete ns demo +namespace "demo" deleted +``` From 49363c8eaf537f594b0b8c05289a63ee9e0b1d8e Mon Sep 17 00:00:00 2001 From: Bonusree Date: Tue, 16 Jun 2026 18:02:01 +0600 Subject: [PATCH 2/2] proxysql custom config Signed-off-by: Bonusree --- .../proxysql/configuration/using-config-file/index.md | 7 ------- .../proxysql/configuration/using-pod-template/index.md | 4 ++-- 2 files changed, 2 insertions(+), 9 deletions(-) diff --git a/docs/guides/proxysql/configuration/using-config-file/index.md b/docs/guides/proxysql/configuration/using-config-file/index.md index 34c27bffc5..07add489ea 100644 --- a/docs/guides/proxysql/configuration/using-config-file/index.md +++ b/docs/guides/proxysql/configuration/using-config-file/index.md @@ -85,13 +85,6 @@ mysql-server 8.4.3 Ready 7m6s At first, let's create a `MySQLVariables.cnf` file setting `mysql-max_connections`. ```bash -cat < MySQLVariables.cnf -mysql_variables= -{ - max_connections=2048 -} -EOF - $ cat MySQLVariables.cnf mysql_variables= { diff --git a/docs/guides/proxysql/configuration/using-pod-template/index.md b/docs/guides/proxysql/configuration/using-pod-template/index.md index 6f51672379..7f125be9a5 100644 --- a/docs/guides/proxysql/configuration/using-pod-template/index.md +++ b/docs/guides/proxysql/configuration/using-pod-template/index.md @@ -148,14 +148,14 @@ Check that the annotation has been set on the pod. ```bash $ kubectl get pod -n demo sample-proxysql-0 -o jsonpath='{.metadata.annotations}' -map[passMe:ToProxySQLPod] +{"passMe":"ToProxySQLPod"}⏎ ``` Check that the resource requests have been set on the `proxysql` container. ```bash $ kubectl get pod -n demo sample-proxysql-0 -o jsonpath='{.spec.containers[?(@.name=="proxysql")].resources}' -{"requests":{"cpu":"250m","memory":"256Mi"}} +{"limits":{"memory":"256Mi"},"requests":{"cpu":"250m","memory":"256Mi"}} ``` We can see that both the annotation and the resource requests we provided through `spec.podTemplate` have been applied to the pod.