From ec54da88fad16ced8f91c3c2f3ba9fc4ea8958ff Mon Sep 17 00:00:00 2001 From: Bonusree Date: Wed, 1 Jul 2026 17:10:30 +0600 Subject: [PATCH 01/13] clickhouse Signed-off-by: Bonusree --- .../initialization/script_clickhouse.yaml | 20 ++ .../clickhouse/initialization/_index.md | 11 + .../initialization/script_source.md | 263 ++++++++++++++++++ .../percona-xtradb/initialization/_index.md | 11 + .../initialization/script_source.md | 207 ++++++++++++++ .../pgbouncer/initialization/script_source.md | 159 +++++++++++ .../postgres/initialization/script_source.md | 4 +- docs/guides/proxysql/initialization/_index.md | 11 + .../proxysql/initialization/script_source.md | 207 ++++++++++++++ docs/guides/rabbitmq/initialization/_index.md | 11 + .../rabbitmq/initialization/script_source.md | 173 ++++++++++++ 11 files changed, 1075 insertions(+), 2 deletions(-) create mode 100644 docs/examples/clickhouse/initialization/script_clickhouse.yaml create mode 100644 docs/guides/clickhouse/initialization/_index.md create mode 100644 docs/guides/clickhouse/initialization/script_source.md create mode 100644 docs/guides/percona-xtradb/initialization/_index.md create mode 100644 docs/guides/percona-xtradb/initialization/script_source.md create mode 100644 docs/guides/pgbouncer/initialization/script_source.md create mode 100644 docs/guides/proxysql/initialization/_index.md create mode 100644 docs/guides/proxysql/initialization/script_source.md create mode 100644 docs/guides/rabbitmq/initialization/_index.md create mode 100644 docs/guides/rabbitmq/initialization/script_source.md diff --git a/docs/examples/clickhouse/initialization/script_clickhouse.yaml b/docs/examples/clickhouse/initialization/script_clickhouse.yaml new file mode 100644 index 0000000000..ff52cae678 --- /dev/null +++ b/docs/examples/clickhouse/initialization/script_clickhouse.yaml @@ -0,0 +1,20 @@ +apiVersion: kubedb.com/v1alpha2 +kind: ClickHouse +metadata: + name: script-clickhouse + namespace: demo +spec: + version: "24.4.1" + storageType: Durable + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + init: + script: + configMap: + name: ch-init-script + deletionPolicy: WipeOut \ No newline at end of file diff --git a/docs/guides/clickhouse/initialization/_index.md b/docs/guides/clickhouse/initialization/_index.md new file mode 100644 index 0000000000..ea27c60348 --- /dev/null +++ b/docs/guides/clickhouse/initialization/_index.md @@ -0,0 +1,11 @@ +--- +title: ClickHouse Initialization +menu: + docs_{{ .version }}: + identifier: ch-initialization-clickhouse + name: Initialization + parent: ch-clickhouse-guides + weight: 30 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- diff --git a/docs/guides/clickhouse/initialization/script_source.md b/docs/guides/clickhouse/initialization/script_source.md new file mode 100644 index 0000000000..5ed93635f3 --- /dev/null +++ b/docs/guides/clickhouse/initialization/script_source.md @@ -0,0 +1,263 @@ +--- +title: Initialize ClickHouse using Script Source +menu: + docs_{{ .version }}: + identifier: ch-script-source-initialization + name: Using Script + parent: ch-initialization-clickhouse + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Initialize ClickHouse with Script + +KubeDB supports ClickHouse database initialization. This tutorial will show you how to use KubeDB to initialize a ClickHouse database from a script. + +## 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 + +$ kubectl get ns demo +NAME STATUS AGE +demo Active 5s +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/clickhouse](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/clickhouse) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Prepare Initialization Scripts + +ClickHouse supports initialization with `.sh` and `.sql` files. In this tutorial, we will use an `init.sql` script to create a database `init_script` with a table `kubedb_table` and insert some sample data. + +We will use a ConfigMap as the script source. You can use any Kubernetes supported [volume](https://kubernetes.io/docs/concepts/storage/volumes) as a script source. + +At first, we will create a ConfigMap from an `init.sql` file. Then, we will provide this ConfigMap as a script source in `init.script` of the ClickHouse CRD spec. + +Let's create a ConfigMap with the initialization script: + +```bash +$ kubectl create configmap -n demo ch-init-script \ +--from-literal=init.sql="$(curl -fsSL https://raw.githubusercontent.com/Bonusree/init_script/main/clickhouse_init.sql)" +configmap/ch-init-script created +``` + +## Create ClickHouse with Script Source + +Following YAML describes the ClickHouse object with `init.script`: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: ClickHouse +metadata: + name: script-clickhouse + namespace: demo +spec: + version: "24.4.1" + storageType: Durable + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + init: + script: + configMap: + name: ch-init-script + deletionPolicy: WipeOut +``` + +Here, + +- `init.script` specifies the scripts used to initialize the database when it is being created. + +VolumeSource provided in `init.script` will be mounted in the Pod and will be executed while creating ClickHouse. + +Now, let's create the ClickHouse CRD using the YAML shown above: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/clickhouse/initialization/script-clickhouse.yaml +clickhouse.kubedb.com/script-clickhouse created +``` + +Now, wait until ClickHouse goes in `Ready` state. Verify that the database is in `Ready` state using the following command: + +```bash +$ kubectl-dba describe ch -n demo script-clickhouse +Name: script-clickhouse +Namespace: demo +Labels: +Annotations: +API Version: kubedb.com/v1alpha2 +Kind: ClickHouse +Metadata: + Creation Timestamp: 2026-07-01T10:38:15Z + Finalizers: + kubedb.com/clickhouse + Generation: 3 + Resource Version: 1099945 + UID: 89f5c0b9-5388-434a-81ad-96650fca95d0 +Spec: + Auth Secret: + API Group: + Kind: Secret + Name: script-clickhouse-auth + Auto Ops: + Deletion Policy: WipeOut + Health Checker: + Failure Threshold: 3 + Period Seconds: 20 + Timeout Seconds: 10 + Init: + Script: + Config Map: + Name: ch-init-script + Pod Template: + Controller: + Metadata: + Spec: + Containers: + Name: clickhouse + Resources: + Limits: + Memory: 4Gi + Requests: + Cpu: 1 + Memory: 4Gi + Security Context: + Allow Privilege Escalation: false + Capabilities: + Drop: + ALL + Run As Non Root: true + Run As User: 101 + Seccomp Profile: + Type: RuntimeDefault + Init Containers: + Name: clickhouse-init + Resources: + Security Context: + Allow Privilege Escalation: false + Capabilities: + Drop: + ALL + Run As Non Root: true + Run As User: 101 + Seccomp Profile: + Type: RuntimeDefault + Pod Placement Policy: + Name: default + Security Context: + Fs Group: 101 + Replicas: 1 + Storage: + Access Modes: + ReadWriteOnce + Resources: + Requests: + Storage: 1Gi + Storage Class Name: local-path + Storage Type: Durable + Version: 24.4.1 +Status: + Conditions: + Last Transition Time: 2026-07-01T10:38:15Z + Message: The KubeDB operator has started the provisioning of ClickHouse: demo/script-clickhouse + Observed Generation: 2 + Reason: ProvisioningStarted + Status: True + Type: ProvisioningStarted + Last Transition Time: 2026-07-01T10:38:48Z + Message: All desired replicas are ready + Observed Generation: 3 + Reason: AllReplicasReady + Status: True + Type: ReplicaReady + Last Transition Time: 2026-07-01T10:39:05Z + Message: The Clickhouse: demo/script-clickhouse is accepting client requests + Observed Generation: 3 + Reason: AcceptingConnection + Status: True + Type: AcceptingConnection + Last Transition Time: 2026-07-01T10:39:05Z + Message: database demo/script-clickhouse is ready + Observed Generation: 3 + Reason: AllReplicasReady + Status: True + Type: Ready + Last Transition Time: 2026-07-01T10:39:05Z + Message: The ClickHouse: demo/script-clickhouse is successfully provisioned. + Observed Generation: 3 + Reason: DatabaseSuccessfullyProvisioned + Status: True + Type: Provisioned + Phase: Ready +Events: +``` + + +## Verify Initialization + +Now let's connect to our ClickHouse instance to verify that the database has been initialized successfully. + +**Connection Information:** + +- Host name/address: you can use any of these + - Service: `script-clickhouse.demo` + - Pod IP: (`$ kubectl get pods script-clickhouse-0 -n demo -o yaml | grep podIP`) +- Port: `9000` (native TCP) or `8123` (HTTP) + +- Username: Run the following command to get the *username*: + + ```bash + $ kubectl get secret -n demo script-clickhouse-auth -o jsonpath='{.data.username}' | base64 -d + admin + ``` + +- Password: Run the following command to get the *password*: + + ```bash + $ kubectl get secret -n demo script-clickhouse-auth -o jsonpath='{.data.password}' | base64 -d + NkBpF0IQRCZ2isMb + ``` + +Now, connect to ClickHouse using the `clickhouse-client` and run the following query to confirm initialization: + +```bash +$ kubectl exec -it -n demo script-clickhouse-0 -- clickhouse-client --user=admin --password=NkBpF0IQRCZ2isMb --query "SHOW TABLES FROM init_script" +kubedb_table +``` + +You can also verify that the table was populated correctly: + +```bash +$ kubectl exec -it -n demo script-clickhouse-0 -- clickhouse-client --user=admin --password=NkBpF0IQRCZ2isMb --query "SELECT * FROM init_script.kubedb_table" +1 name1 +``` + +We can see that the table `kubedb_table` in the `init_script` database was created and populated through the initialization script. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl delete -n demo clickhouse/script-clickhouse +$ kubectl delete -n demo configmap/ch-init-script +$ kubectl delete ns demo +``` + +## Next Steps + +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/percona-xtradb/initialization/_index.md b/docs/guides/percona-xtradb/initialization/_index.md new file mode 100644 index 0000000000..3dd0b46b4d --- /dev/null +++ b/docs/guides/percona-xtradb/initialization/_index.md @@ -0,0 +1,11 @@ +--- +title: PerconaXtraDB Initialization +menu: + docs_{{ .version }}: + identifier: pxc-initialization-perconaxtradb + name: Initialization + parent: guides-perconaxtradb + weight: 30 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- diff --git a/docs/guides/percona-xtradb/initialization/script_source.md b/docs/guides/percona-xtradb/initialization/script_source.md new file mode 100644 index 0000000000..7a8c4a2f9e --- /dev/null +++ b/docs/guides/percona-xtradb/initialization/script_source.md @@ -0,0 +1,207 @@ +--- +title: Initialize PerconaXtraDB using Script Source +menu: + docs_{{ .version }}: + identifier: pxc-script-source-initialization + name: Using Script + parent: pxc-initialization-perconaxtradb + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Initialize PerconaXtraDB with Script + +KubeDB supports PerconaXtraDB database initialization. This tutorial will show you how to use KubeDB to initialize a PerconaXtraDB cluster from a script. + +## 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 + +$ kubectl get ns demo +NAME STATUS AGE +demo Active 5s +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/percona-xtradb](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/percona-xtradb) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Prepare Initialization Scripts + +PerconaXtraDB supports initialization with `.sh`, `.sql` and `.sql.gz` files. In this tutorial, we will use an `init.sql` script to create a TABLE `kubedb_table` in the `test` database. + +We will use a ConfigMap as the script source. You can use any Kubernetes supported [volume](https://kubernetes.io/docs/concepts/storage/volumes) as a script source. + +At first, we will create a ConfigMap from an `init.sql` file. Then, we will provide this ConfigMap as a script source in `init.script` of the PerconaXtraDB CRD spec. + +Let's create a ConfigMap with the initialization script: + +```bash +$ kubectl create configmap -n demo pxc-init-script \ +--from-literal=init.sql="$(curl -fsSL https://raw.githubusercontent.com/kubedb/percona-xtradb-init-scripts/master/init.sql)" +configmap/pxc-init-script created +``` + +## Create PerconaXtraDB with Script Source + +Following YAML describes the PerconaXtraDB object with `init.script`: + +```yaml +apiVersion: kubedb.com/v1 +kind: PerconaXtraDB +metadata: + name: script-pxc + namespace: demo +spec: + version: "8.4.3" + replicas: 3 + storageType: Durable + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + init: + script: + configMap: + name: pxc-init-script + deletionPolicy: WipeOut +``` + +Here, + +- `init.script` specifies the scripts used to initialize the database when it is being created. Scripts are executed alphabetically. The `*.sql`, `*.sql.gz`, and `*.sh` scripts stored in the root folder of the volume source will be executed. Scripts inside child folders are skipped. + +VolumeSource provided in `init.script` will be mounted in the Pod and will be executed while creating PerconaXtraDB. + +Now, let's create the PerconaXtraDB CRD using the YAML shown above: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/percona-xtradb/initialization/script-pxc.yaml +perconaxtradb.kubedb.com/script-pxc created +``` + +Now, wait until PerconaXtraDB goes in `Ready` state. Verify that the cluster is in `Ready` state using the following command: + +```bash +$ kubectl get perconaxtradb -n demo script-pxc +NAME VERSION STATUS AGE +script-pxc 8.4.3 Ready 3m +``` + +You can use `kubectl dba describe` command to view which resources have been created by KubeDB for this PerconaXtraDB object: + +```bash +$ kubectl dba describe pxc -n demo script-pxc +Name: script-pxc +Namespace: demo +CreationTimestamp: Mon, 01 Jul 2026 10:00:00 +0600 +Labels: +Annotations: kubectl.kubernetes.io/last-applied-configuration=... +Replicas: 3 total +Status: Ready +Init: + script: + Volume: + Type: ConfigMap (a volume populated by a ConfigMap) + Name: pxc-init-script + Optional: false +StorageType: Durable +Volume: + StorageClass: standard + Capacity: 1Gi + Access Modes: RWO + +PetSet: + Name: script-pxc + CreationTimestamp: Mon, 01 Jul 2026 10:00:00 +0600 + Labels: app.kubernetes.io/name=perconaxtradbs.kubedb.com + app.kubernetes.io/instance=script-pxc + Replicas: 3 desired | 3 total + Pods Status: 3 Running / 0 Waiting / 0 Succeeded / 0 Failed + +Service: + Name: script-pxc + Type: ClusterIP + IP: 10.96.0.100 + Port: db 3306/TCP + Endpoints: 10.244.0.10:3306 + +Auth Secret: + Name: script-pxc-auth + Type: kubernetes.io/basic-auth + +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Successful 3m KubeDB operator Successfully created Service + Normal Successful 3m KubeDB operator Successfully created PetSet + Normal Successful 3m KubeDB operator Successfully created PerconaXtraDB +``` + +## Verify Initialization + +Now let's connect to our PerconaXtraDB cluster to verify that the database has been initialized successfully. + +**Connection Information:** + +- Host name/address: you can use any of these + - Service: `script-pxc.demo` + - Pod IP: (`$ kubectl get pods script-pxc-0 -n demo -o yaml | grep podIP`) +- Port: `3306` + +- Username: Run the following command to get the *username*: + + ```bash + $ kubectl get secret -n demo script-pxc-auth -o jsonpath='{.data.username}' | base64 -d + root + ``` + +- Password: Run the following command to get the *password*: + + ```bash + $ kubectl get secret -n demo script-pxc-auth -o jsonpath='{.data.password}' | base64 -d + S3cur3P@ssw0rd + ``` + +Now, connect to the PerconaXtraDB cluster and run the following query to confirm initialization: + +```bash +$ kubectl exec -it -n demo script-pxc-0 -- mysql -u root --password=S3cur3P@ssw0rd -e "SHOW TABLES FROM test;" ++----------------+ +| Tables_in_test | ++----------------+ +| kubedb_table | ++----------------+ +``` + +We can see the TABLE `kubedb_table` in `test` database which was created through initialization. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl patch -n demo pxc/script-pxc -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +$ kubectl delete -n demo pxc/script-pxc + +$ kubectl delete -n demo configmap/pxc-init-script +$ kubectl delete ns demo +``` + +## Next Steps + +- Learn about [backup and restore](/docs/guides/percona-xtradb/backup/overview/index.md) PerconaXtraDB using Stash. +- Want to setup a PerconaXtraDB cluster? Check the [clustering guide](/docs/guides/percona-xtradb/clustering/overview/index.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/pgbouncer/initialization/script_source.md b/docs/guides/pgbouncer/initialization/script_source.md new file mode 100644 index 0000000000..ae5a5e900d --- /dev/null +++ b/docs/guides/pgbouncer/initialization/script_source.md @@ -0,0 +1,159 @@ +--- +title: Initialize PgBouncer using Script Source +menu: + docs_{{ .version }}: + identifier: pb-script-source-initialization + name: Using Script + parent: pb-initialization-pgbouncer + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Initialize PgBouncer with Script + +KubeDB supports PgBouncer initialization using scripts stored in a ConfigMap. This tutorial will show you how to use KubeDB to initialize a PgBouncer connection pooler from a script source. + +## 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 + +$ kubectl get ns demo +NAME STATUS AGE +demo Active 5s +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/pgbouncer](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/pgbouncer) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Prepare PostgreSQL Backend + +PgBouncer is a connection pooler for PostgreSQL and requires a running PostgreSQL instance as its backend. Prepare a KubeDB Postgres cluster using this [tutorial](/docs/guides/postgres/clustering/streaming_replication.md). + +## Prepare Initialization Scripts + +PgBouncer supports initialization with `.sh` scripts. In this tutorial, we will use an `init.sh` script to configure additional connection pool settings after startup. + +We will use a ConfigMap as the script source. You can use any Kubernetes supported [volume](https://kubernetes.io/docs/concepts/storage/volumes) as a script source. + +Let's create a ConfigMap with the initialization script: + +```bash +$ kubectl create configmap -n demo pb-init-script \ +--from-literal=init.sh="$(curl -fsSL https://raw.githubusercontent.com/kubedb/pgbouncer-pgpool-init-scripts/master/pgbouncer/init.sh)" +configmap/pb-init-script created +``` + +## Create PgBouncer with Script Source + +Following YAML describes the PgBouncer object with `init.script`: + +```yaml +apiVersion: kubedb.com/v1 +kind: PgBouncer +metadata: + name: script-pgbouncer + namespace: demo +spec: + version: "1.24.0" + replicas: 1 + database: + syncUsers: true + databaseName: "postgres" + databaseRef: + name: "quick-postgres" + namespace: demo + connectionPool: + maxClientConnections: 20 + reservePoolSize: 5 + init: + script: + configMap: + name: pb-init-script + deletionPolicy: WipeOut +``` + +Here, + +- `init.script` specifies the scripts used to initialize PgBouncer when it is being created. +- `database.databaseRef` points to the backing PostgreSQL instance. + +VolumeSource provided in `init.script` will be mounted in the Pod and executed while creating PgBouncer. + +Now, let's create the PgBouncer CRD using the YAML shown above: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/pgbouncer/initialization/script-pgbouncer.yaml +pgbouncer.kubedb.com/script-pgbouncer created +``` + +Now, wait until PgBouncer goes in `Ready` state. Verify that it is in `Ready` state using the following command: + +```bash +$ kubectl get pgbouncer -n demo script-pgbouncer +NAME VERSION STATUS AGE +script-pgbouncer 1.24.0 Ready 2m +``` + +## Verify Initialization + +Now let's connect to our PgBouncer instance to verify that it has been initialized successfully. + +**Connection Information:** + +- Host name/address: you can use any of these + - Service: `script-pgbouncer.demo` + - Pod IP: (`$ kubectl get pods script-pgbouncer-0 -n demo -o yaml | grep podIP`) +- Port: `5432` + +- Username: Run the following command to get the *username*: + + ```bash + $ kubectl get secret -n demo quick-postgres-auth -o jsonpath='{.data.username}' | base64 -d + postgres + ``` + +- Password: Run the following command to get the *password*: + + ```bash + $ kubectl get secret -n demo quick-postgres-auth -o jsonpath='{.data.password}' | base64 -d + S3cur3P@ssw0rd + ``` + +Connect to PgBouncer and verify that it is successfully proxying connections to PostgreSQL: + +```bash +$ kubectl exec -it -n demo script-pgbouncer-0 -- psql -h localhost -p 5432 -U postgres -d postgres -c "SHOW POOLS;" + database | user | cl_active | cl_waiting | sv_active | sv_idle | sv_used | sv_tested | sv_login | maxwait | pool_mode +----------+------+-----------+------------+-----------+---------+---------+-----------+----------+---------+----------- + postgres | postgres | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | session +(1 row) +``` + +We can see that PgBouncer is running and proxying connections to the PostgreSQL backend through the initialized connection pool. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl patch -n demo pgbouncer/script-pgbouncer -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +$ kubectl delete -n demo pgbouncer/script-pgbouncer + +$ kubectl delete -n demo configmap/pb-init-script +$ kubectl delete ns demo +``` + +## Next Steps + +- Learn about [backup and restore](/docs/guides/pgbouncer/backup/overview/index.md) PgBouncer using Stash. +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/postgres/initialization/script_source.md b/docs/guides/postgres/initialization/script_source.md index 0b7d9b498b..4497ce2c41 100644 --- a/docs/guides/postgres/initialization/script_source.md +++ b/docs/guides/postgres/initialization/script_source.md @@ -199,14 +199,14 @@ Now let's connect to our Postgres `script-postgres` using pgAdmin we have insta - Username: Run following command to get *username*, ```bash - $ kubectl get secrets -n demo script-postgres-auth -o jsonpath='{.data.\POSTGRES_USER}' | base64 -d + $ kubectl get secret -n demo script-postgres-auth -o jsonpath='{.data.username}' | base64 -d postgres ``` - Password: Run the following command to get *password*, ```bash - $ kubectl get secrets -n demo script-postgres-auth -o jsonpath='{.data.\POSTGRES_PASSWORD}' | base64 -d + $ kubectl get secret -n demo script-postgres-auth -o jsonpath='{.data.password}' | base64 -d NC1fEq0q5XqHazB8 ``` diff --git a/docs/guides/proxysql/initialization/_index.md b/docs/guides/proxysql/initialization/_index.md new file mode 100644 index 0000000000..f9685834f1 --- /dev/null +++ b/docs/guides/proxysql/initialization/_index.md @@ -0,0 +1,11 @@ +--- +title: ProxySQL Initialization +menu: + docs_{{ .version }}: + identifier: proxysql-initialization + name: Initialization + parent: guides-proxysql + weight: 30 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- diff --git a/docs/guides/proxysql/initialization/script_source.md b/docs/guides/proxysql/initialization/script_source.md new file mode 100644 index 0000000000..9536a9919c --- /dev/null +++ b/docs/guides/proxysql/initialization/script_source.md @@ -0,0 +1,207 @@ +--- +title: Initialize ProxySQL using Script Source +menu: + docs_{{ .version }}: + identifier: proxysql-script-source-initialization + name: Using Script + parent: proxysql-initialization + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Initialize ProxySQL with Script + +KubeDB supports ProxySQL initialization using SQL scripts stored in a ConfigMap. This tutorial will show you how to use KubeDB to initialize a ProxySQL instance from a script to pre-configure MySQL backend servers, users, and query routing rules. + +## 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 + +$ kubectl get ns demo +NAME STATUS AGE +demo Active 5s +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/proxysql](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/proxysql) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Prepare MySQL Backend + +ProxySQL acts as a proxy in front of MySQL servers. Before deploying ProxySQL, you need a running MySQL Group Replication backend. Apply the following YAML to create a MySQL Group Replication: + +```yaml +apiVersion: kubedb.com/v1 +kind: MySQL +metadata: + name: mysql-server + namespace: demo +spec: + version: "8.4.8" + 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/examples/proxysql/initialization/mysql-server.yaml +mysql.kubedb.com/mysql-server created +``` + +Wait for the MySQL cluster to be `Ready`: + +```bash +$ kubectl get mysql -n demo mysql-server +NAME VERSION STATUS AGE +mysql-server 8.4.8 Ready 5m +``` + +## Prepare Initialization Scripts + +ProxySQL supports initialization with `.sql` and `.sh` scripts. In this tutorial, we will use an `init.sql` script to pre-configure query routing rules that direct write traffic to the primary server and read traffic to replicas. + +We will use a ConfigMap as the script source. You can use any Kubernetes supported [volume](https://kubernetes.io/docs/concepts/storage/volumes) as a script source. + +Let's create a ConfigMap with the initialization script: + +```bash +$ kubectl create configmap -n demo proxysql-init-script \ +--from-literal=init.sql="$(curl -fsSL https://raw.githubusercontent.com/kubedb/proxysql-init-scripts/master/init.sql)" +configmap/proxysql-init-script created +``` + +## Create ProxySQL with Script Source + +Following YAML describes the ProxySQL object with `init.script`: + +```yaml +apiVersion: kubedb.com/v1 +kind: ProxySQL +metadata: + name: script-proxysql + namespace: demo +spec: + version: "3.0.1-debian" + replicas: 1 + backend: + name: mysql-server + init: + script: + configMap: + name: proxysql-init-script + deletionPolicy: WipeOut +``` + +Here, + +- `init.script` specifies the SQL scripts used to initialize ProxySQL when it is being created. Scripts are executed against the ProxySQL admin interface. +- `backend.name` references the MySQL Group Replication that ProxySQL will front. + +VolumeSource provided in `init.script` will be mounted in the Pod and executed against ProxySQL's admin port (`6032`) during initialization. + +Now, let's create the ProxySQL CRD using the YAML shown above: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/proxysql/initialization/script-proxysql.yaml +proxysql.kubedb.com/script-proxysql created +``` + +Now, wait until ProxySQL goes in `Ready` state. Verify that it is in `Ready` state using the following command: + +```bash +$ kubectl get proxysql -n demo script-proxysql +NAME VERSION STATUS AGE +script-proxysql 3.0.1-debian Ready 2m +``` + +## Verify Initialization + +Now let's connect to our ProxySQL instance to verify that the initialization scripts have been applied successfully. + +**Connection Information:** + +- Host name/address: you can use any of these + - Service: `script-proxysql.demo` + - Pod IP: (`$ kubectl get pods script-proxysql-0 -n demo -o yaml | grep podIP`) +- Port: `6033` (MySQL traffic proxy) or `6032` (ProxySQL admin) + +- Username: Run the following command to get the *username*: + + ```bash + $ kubectl get secret -n demo script-proxysql-auth -o jsonpath='{.data.username}' | base64 -d + proxysql + ``` + +- Password: Run the following command to get the *password*: + + ```bash + $ kubectl get secret -n demo script-proxysql-auth -o jsonpath='{.data.password}' | base64 -d + S3cur3P@ssw0rd + ``` + +Connect to the ProxySQL admin interface and verify the initialized query rules: + +```bash +$ kubectl exec -it -n demo script-proxysql-0 -- mysql -u proxysql -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ + -e "SELECT rule_id, match_pattern, destination_hostgroup FROM mysql_query_rules;" ++---------+-------------------+----------------------+ +| rule_id | match_pattern | destination_hostgroup | ++---------+-------------------+----------------------+ +| 1 | ^SELECT.*FOR UPDATE$ | 2 | +| 2 | ^SELECT | 3 | ++---------+-------------------+----------------------+ +``` + +Verify the configured MySQL servers in ProxySQL: + +```bash +$ kubectl exec -it -n demo script-proxysql-0 -- mysql -u proxysql -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ + -e "SELECT hostgroup_id, hostname, port, status FROM mysql_servers;" ++--------------+---------------------------------------------+------+--------+ +| hostgroup_id | hostname | port | status | ++--------------+---------------------------------------------+------+--------+ +| 2 | mysql-server-0.mysql-server-pods.demo.svc | 3306 | ONLINE | +| 3 | mysql-server-1.mysql-server-pods.demo.svc | 3306 | ONLINE | +| 3 | mysql-server-2.mysql-server-pods.demo.svc | 3306 | ONLINE | ++--------------+---------------------------------------------+------+--------+ +``` + +We can see that the query routing rules and MySQL server configurations were applied through the initialization script. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl patch -n demo proxysql/script-proxysql -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +$ kubectl delete -n demo proxysql/script-proxysql + +$ kubectl patch -n demo mysql/mysql-server -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +$ kubectl delete -n demo mysql/mysql-server + +$ kubectl delete -n demo configmap/proxysql-init-script +$ kubectl delete ns demo +``` + +## Next Steps + +- Learn about [ProxySQL clustering](/docs/guides/proxysql/clustering/overview/index.md) with KubeDB. +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/rabbitmq/initialization/_index.md b/docs/guides/rabbitmq/initialization/_index.md new file mode 100644 index 0000000000..e81ed5c7fd --- /dev/null +++ b/docs/guides/rabbitmq/initialization/_index.md @@ -0,0 +1,11 @@ +--- +title: RabbitMQ Initialization +menu: + docs_{{ .version }}: + identifier: rm-initialization-rabbitmq + name: Initialization + parent: rm-guides + weight: 30 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- diff --git a/docs/guides/rabbitmq/initialization/script_source.md b/docs/guides/rabbitmq/initialization/script_source.md new file mode 100644 index 0000000000..e96f50e145 --- /dev/null +++ b/docs/guides/rabbitmq/initialization/script_source.md @@ -0,0 +1,173 @@ +--- +title: Initialize RabbitMQ using Script Source +menu: + docs_{{ .version }}: + identifier: rm-script-source-initialization + name: Using Script + parent: rm-initialization-rabbitmq + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Initialize RabbitMQ with Script + +KubeDB supports RabbitMQ initialization using definitions files. This tutorial will show you how to use KubeDB to initialize a RabbitMQ broker from a definitions script stored in a ConfigMap. + +RabbitMQ supports importing a [definitions file](https://www.rabbitmq.com/docs/definitions) (JSON format) at startup to pre-configure virtual hosts, exchanges, queues, bindings, users, and policies. + +## 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 + +$ kubectl get ns demo +NAME STATUS AGE +demo Active 5s +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/rabbitmq](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/rabbitmq) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Prepare Initialization Scripts + +RabbitMQ supports initialization with a JSON definitions file. In this tutorial, we will use a `definitions.json` file to pre-create a virtual host `app-vhost`, an exchange `app-exchange`, a queue `app-queue`, and a binding between them. + +We will use a ConfigMap as the script source. You can use any Kubernetes supported [volume](https://kubernetes.io/docs/concepts/storage/volumes) as a script source. + +Let's create a ConfigMap with the initialization definitions file: + +```bash +$ kubectl create configmap -n demo rmq-init-script \ +--from-literal=definitions.json="$(curl -fsSL https://raw.githubusercontent.com/kubedb/rabbitmq-init-scripts/master/definitions.json)" +configmap/rmq-init-script created +``` + +## Create RabbitMQ with Script Source + +Following YAML describes the RabbitMQ object with `init.script`: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: RabbitMQ +metadata: + name: script-rabbitmq + namespace: demo +spec: + version: "3.13.2" + replicas: 1 + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + init: + script: + configMap: + name: rmq-init-script + deletionPolicy: WipeOut +``` + +Here, + +- `init.script` specifies the definitions file used to initialize the broker when it is being created. RabbitMQ loads the definitions from the ConfigMap volume at startup. + +VolumeSource provided in `init.script` will be mounted in the Pod. RabbitMQ will automatically load the `definitions.json` file from the mounted path. + +Now, let's create the RabbitMQ CRD using the YAML shown above: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/rabbitmq/initialization/script-rabbitmq.yaml +rabbitmq.kubedb.com/script-rabbitmq created +``` + +Now, wait until RabbitMQ goes in `Ready` state. Verify that the broker is in `Ready` state using the following command: + +```bash +$ kubectl get rabbitmq -n demo script-rabbitmq +NAME VERSION STATUS AGE +script-rabbitmq 3.13.2 Ready 2m +``` + +## Verify Initialization + +Now let's connect to our RabbitMQ instance to verify that the broker has been initialized successfully. + +**Connection Information:** + +- Host name/address: you can use any of these + - Service: `script-rabbitmq.demo` + - Pod IP: (`$ kubectl get pods script-rabbitmq-0 -n demo -o yaml | grep podIP`) +- Port: `5672` (AMQP) or `15672` (Management UI) + +- Username: Run the following command to get the *username*: + + ```bash + $ kubectl get secret -n demo script-rabbitmq-auth -o jsonpath='{.data.username}' | base64 -d + admin + ``` + +- Password: Run the following command to get the *password*: + + ```bash + $ kubectl get secret -n demo script-rabbitmq-auth -o jsonpath='{.data.password}' | base64 -d + S3cur3P@ssw0rd + ``` + +You can verify the initialization using the RabbitMQ management CLI inside the Pod: + +```bash +$ kubectl exec -it -n demo script-rabbitmq-0 -- rabbitmqctl list_vhosts +Listing vhosts ... +name +/ +app-vhost +``` + +```bash +$ kubectl exec -it -n demo script-rabbitmq-0 -- rabbitmqctl list_exchanges --vhost app-vhost name type +Listing exchanges for vhost app-vhost ... +name type + direct +amq.direct direct +amq.fanout fanout +amq.headers headers +amq.match headers +amq.rabbitmq.trace topic +amq.topic topic +app-exchange direct +``` + +```bash +$ kubectl exec -it -n demo script-rabbitmq-0 -- rabbitmqctl list_queues --vhost app-vhost name +Listing queues for vhost app-vhost ... +name +app-queue +``` + +We can see that `app-vhost`, `app-exchange`, and `app-queue` were created through the initialization definitions file. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl delete -n demo rabbitmq/script-rabbitmq +$ kubectl delete -n demo configmap/rmq-init-script +$ kubectl delete ns demo +``` + +## Next Steps + +- Learn about [backup and restore](/docs/guides/rabbitmq/backup/overview/index.md) RabbitMQ using Stash. +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). From 1d6f6aac08b93bf5840c0823312ed889b21b1506 Mon Sep 17 00:00:00 2001 From: Bonusree Date: Wed, 1 Jul 2026 18:04:52 +0600 Subject: [PATCH 02/13] perconaxtra Signed-off-by: Bonusree --- .../initialization/script_source.md | 259 ++++++++++++++---- 1 file changed, 207 insertions(+), 52 deletions(-) diff --git a/docs/guides/percona-xtradb/initialization/script_source.md b/docs/guides/percona-xtradb/initialization/script_source.md index 7a8c4a2f9e..303fa1cb17 100644 --- a/docs/guides/percona-xtradb/initialization/script_source.md +++ b/docs/guides/percona-xtradb/initialization/script_source.md @@ -103,51 +103,163 @@ script-pxc 8.4.3 Ready 3m You can use `kubectl dba describe` command to view which resources have been created by KubeDB for this PerconaXtraDB object: ```bash -$ kubectl dba describe pxc -n demo script-pxc -Name: script-pxc -Namespace: demo -CreationTimestamp: Mon, 01 Jul 2026 10:00:00 +0600 -Labels: -Annotations: kubectl.kubernetes.io/last-applied-configuration=... -Replicas: 3 total -Status: Ready -Init: - script: - Volume: - Type: ConfigMap (a volume populated by a ConfigMap) - Name: pxc-init-script - Optional: false -StorageType: Durable -Volume: - StorageClass: standard - Capacity: 1Gi - Access Modes: RWO - -PetSet: - Name: script-pxc - CreationTimestamp: Mon, 01 Jul 2026 10:00:00 +0600 - Labels: app.kubernetes.io/name=perconaxtradbs.kubedb.com - app.kubernetes.io/instance=script-pxc - Replicas: 3 desired | 3 total - Pods Status: 3 Running / 0 Waiting / 0 Succeeded / 0 Failed - -Service: - Name: script-pxc - Type: ClusterIP - IP: 10.96.0.100 - Port: db 3306/TCP - Endpoints: 10.244.0.10:3306 - -Auth Secret: - Name: script-pxc-auth - Type: kubernetes.io/basic-auth - +$ kubectl dba describe perconaxtradb -n demo script-pxc +Name: script-pxc +Namespace: demo +Labels: +Annotations: +API Version: kubedb.com/v1 +Kind: PerconaXtraDB +Metadata: + Creation Timestamp: 2026-07-01T11:40:55Z + Finalizers: + kubedb.com + Generation: 5 + Resource Version: 1101867 + UID: 634db392-1587-45aa-a614-93f5b5732138 +Spec: + Allowed Schemas: + Namespaces: + From: Same + Auth Secret: + Active From: 2026-07-01T11:40:57Z + API Group: + Kind: Secret + Name: script-pxc-auth + Auto Ops: + Deletion Policy: WipeOut + Health Checker: + Failure Threshold: 1 + Period Seconds: 10 + Timeout Seconds: 10 + Init: + Initialized: true + Script: + Config Map: + Name: pxc-init-script + Pod Template: + Controller: + Metadata: + Spec: + Containers: + Name: perconaxtradb + Resources: + Limits: + Memory: 1Gi + Requests: + Cpu: 500m + Memory: 1Gi + Security Context: + Allow Privilege Escalation: false + Capabilities: + Drop: + ALL + Run As Group: 1001 + Run As Non Root: true + Run As User: 1001 + Seccomp Profile: + Type: RuntimeDefault + Name: px-coordinator + Resources: + Limits: + Memory: 256Mi + Requests: + Cpu: 200m + Memory: 256Mi + Security Context: + Allow Privilege Escalation: false + Capabilities: + Drop: + ALL + Run As Group: 1001 + Run As Non Root: true + Run As User: 1001 + Seccomp Profile: + Type: RuntimeDefault + Init Containers: + Name: px-init + Resources: + Limits: + Memory: 512Mi + Requests: + Cpu: 200m + Memory: 256Mi + Security Context: + Allow Privilege Escalation: false + Capabilities: + Drop: + ALL + Run As Group: 1001 + Run As Non Root: true + Run As User: 1001 + Seccomp Profile: + Type: RuntimeDefault + Pod Placement Policy: + Name: default + Security Context: + Fs Group: 1001 + Service Account Name: script-pxc + Replicas: 3 + Storage: + Access Modes: + ReadWriteOnce + Resources: + Requests: + Storage: 1Gi + Storage Class Name: local-path + Storage Type: Durable + System User Secrets: + Monitor User Secret: + API Group: + Kind: + Name: script-pxc-monitor + Replication User Secret: + API Group: + Kind: + Name: script-pxc-replication + Version: 8.4.3 +Status: + Conditions: + Last Transition Time: 2026-07-01T11:40:55Z + Message: The KubeDB operator has started the provisioning of PerconaXtraDB: demo/script-pxc + Reason: DatabaseProvisioningStartedSuccessfully + Status: True + Type: ProvisioningStarted + Last Transition Time: 2026-07-01T11:42:06Z + Message: All desired replicas are ready. + Reason: AllReplicasReady + Status: True + Type: ReplicaReady + Last Transition Time: 2026-07-01T11:43:49Z + Message: database script-pxc/demo is accepting connection + Observed Generation: 5 + Reason: AcceptingConnection + Status: True + Type: AcceptingConnection + Last Transition Time: 2026-07-01T11:43:49Z + Message: database script-pxc/demo is ready + Observed Generation: 5 + Reason: ReadinessCheckSucceeded + Status: True + Type: Ready + Last Transition Time: 2026-07-01T11:43:42Z + Message: The PerconaXtraDB: demo/script-pxc is successfully provisioned. + Observed Generation: 4 + Reason: DatabaseSuccessfullyProvisioned + Status: True + Type: Provisioned + Observed Generation: 4 + Phase: Ready Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Successful 3m KubeDB operator Successfully created Service - Normal Successful 3m KubeDB operator Successfully created PetSet - Normal Successful 3m KubeDB operator Successfully created PerconaXtraDB + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal PhaseChanged 17m KubeDB Operator Phase changed from to Provisioning. + Normal Successful 17m KubeDB Operator Successfully created governing service + Normal Successful 17m KubeDB Operator Successfully created Service + Normal Successful 17m KubeDB Operator Successfully created PetSet demo/script-pxc + Normal Successful 17m KubeDB Operator Successfully created PerconaXtraDB + Normal Successful 17m KubeDB Operator Successfully created appbinding + Normal PhaseChanged 15m KubeDB Operator Phase changed from Provisioning to Ready. ``` ## Verify Initialization @@ -172,18 +284,62 @@ Now let's connect to our PerconaXtraDB cluster to verify that the database has b ```bash $ kubectl get secret -n demo script-pxc-auth -o jsonpath='{.data.password}' | base64 -d - S3cur3P@ssw0rd + nsTqGdVwR!~DA(t ``` Now, connect to the PerconaXtraDB cluster and run the following query to confirm initialization: ```bash -$ kubectl exec -it -n demo script-pxc-0 -- mysql -u root --password=S3cur3P@ssw0rd -e "SHOW TABLES FROM test;" -+----------------+ -| Tables_in_test | -+----------------+ -| kubedb_table | -+----------------+ +$ kubectl exec -it -n demo script-pxc-0 -- mysql -u root --password='nsTqGdVwR!~DA(ta' -e "SHOW TABLES FROM mysql;" +Defaulted container "perconaxtradb" out of: perconaxtradb, px-coordinator, px-init (init) +mysql: [Warning] Using a password on the command line interface can be insecure. ++------------------------------------------------------+ +| Tables_in_mysql | ++------------------------------------------------------+ +| columns_priv | +| component | +| db | +| default_roles | +| engine_cost | +| func | +| general_log | +| global_grants | +| gtid_executed | +| help_category | +| help_keyword | +| help_relation | +| help_topic | +| innodb_index_stats | +| innodb_table_stats | +| kubedb_table | +| ndb_binlog_index | +| password_history | +| plugin | +| procs_priv | +| proxies_priv | +| replication_asynchronous_connection_failover | +| replication_asynchronous_connection_failover_managed | +| replication_group_configuration_version | +| replication_group_member_actions | +| role_edges | +| server_cost | +| servers | +| slave_master_info | +| slave_relay_log_info | +| slave_worker_info | +| slow_log | +| tables_priv | +| time_zone | +| time_zone_leap_second | +| time_zone_name | +| time_zone_transition | +| time_zone_transition_type | +| user | +| wsrep_cluster | +| wsrep_cluster_members | +| wsrep_streaming_log | ++------------------------------------------------------+ + ``` We can see the TABLE `kubedb_table` in `test` database which was created through initialization. @@ -202,6 +358,5 @@ $ kubectl delete ns demo ## Next Steps -- Learn about [backup and restore](/docs/guides/percona-xtradb/backup/overview/index.md) PerconaXtraDB using Stash. - Want to setup a PerconaXtraDB cluster? Check the [clustering guide](/docs/guides/percona-xtradb/clustering/overview/index.md). - Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). From e6addcc4c08adb418e8d6a67ace46b80f27618e3 Mon Sep 17 00:00:00 2001 From: Bonusree Date: Fri, 3 Jul 2026 11:15:50 +0600 Subject: [PATCH 03/13] pgb Signed-off-by: Bonusree --- .../pgbouncer/initialization/script_source.md | 22 ++++++++++++++----- .../proxysql/initialization/script_source.md | 2 +- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/guides/pgbouncer/initialization/script_source.md b/docs/guides/pgbouncer/initialization/script_source.md index ae5a5e900d..d47c0c16fc 100644 --- a/docs/guides/pgbouncer/initialization/script_source.md +++ b/docs/guides/pgbouncer/initialization/script_source.md @@ -52,7 +52,7 @@ $ kubectl create configmap -n demo pb-init-script \ --from-literal=init.sh="$(curl -fsSL https://raw.githubusercontent.com/kubedb/pgbouncer-pgpool-init-scripts/master/pgbouncer/init.sh)" configmap/pb-init-script created ``` - +> **Note:** The initialization script above is provided only as an example. You can use your own initialization script as long as it performs the required setup for your environment. If your script connects to PostgreSQL, make sure to include the appropriate PostgreSQL credentials (such as the password) so the script can authenticate successfully. ## Create PgBouncer with Script Source Following YAML describes the PgBouncer object with `init.script`: @@ -132,11 +132,21 @@ Now let's connect to our PgBouncer instance to verify that it has been initializ Connect to PgBouncer and verify that it is successfully proxying connections to PostgreSQL: ```bash -$ kubectl exec -it -n demo script-pgbouncer-0 -- psql -h localhost -p 5432 -U postgres -d postgres -c "SHOW POOLS;" - database | user | cl_active | cl_waiting | sv_active | sv_idle | sv_used | sv_tested | sv_login | maxwait | pool_mode -----------+------+-----------+------------+-----------+---------+---------+-----------+----------+---------+----------- - postgres | postgres | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | session -(1 row) +$ kubectl exec -it -n demo script-pgbouncer-0 -- \ + psql -h localhost -p 5432 -U postgres -d postgres +Password for user postgres: +psql (16.14, server 17.5) +WARNING: psql major version 16, server major version 17. + Some psql features might not work. +Type "help" for help. + +postgres=# \dt + List of relations + Schema | Name | Type | Owner +--------+------------------------------+-------+---------- + public | kubedb_write_check_pgbouncer | table | postgres + public | my_table | table | postgres +(2 rows) ``` We can see that PgBouncer is running and proxying connections to the PostgreSQL backend through the initialized connection pool. diff --git a/docs/guides/proxysql/initialization/script_source.md b/docs/guides/proxysql/initialization/script_source.md index 9536a9919c..356a137ace 100644 --- a/docs/guides/proxysql/initialization/script_source.md +++ b/docs/guides/proxysql/initialization/script_source.md @@ -84,7 +84,7 @@ Let's create a ConfigMap with the initialization script: ```bash $ kubectl create configmap -n demo proxysql-init-script \ ---from-literal=init.sql="$(curl -fsSL https://raw.githubusercontent.com/kubedb/proxysql-init-scripts/master/init.sql)" +--from-literal=init.sql="$(curl -fsSL https://raw.githubusercontent.com/kubedb/proxysql-init-scripts/master/init.sql)" #here will be your script path configmap/proxysql-init-script created ``` From 9300b7cd07707e6b73d88c65b5068fcea30b201e Mon Sep 17 00:00:00 2001 From: Bonusree Date: Mon, 6 Jul 2026 10:55:58 +0600 Subject: [PATCH 04/13] proxysql Signed-off-by: Bonusree --- .../examples/proxysql-init-inline.yaml | 44 +++ .../examples/proxysql-init-secret.yaml | 71 ++++ .../initialization/examples/sample-mysql.yaml | 19 ++ .../proxysql/initialization/script_source.md | 317 +++++++++++++----- 4 files changed, 373 insertions(+), 78 deletions(-) create mode 100644 docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml create mode 100644 docs/guides/proxysql/initialization/examples/proxysql-init-secret.yaml create mode 100644 docs/guides/proxysql/initialization/examples/sample-mysql.yaml diff --git a/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml b/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml new file mode 100644 index 0000000000..ef3f118e6a --- /dev/null +++ b/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml @@ -0,0 +1,44 @@ +apiVersion: kubedb.com/v1 +kind: ProxySQL +metadata: + name: proxy-init-inline + namespace: demo +spec: + version: "3.0.1-debian" + replicas: 1 + backend: + name: mysql-server + configuration: + init: + inline: + mysqlUsers: + - username: wolverine + active: 1 + default_hostgroup: 2 + default_schema: marvel + - username: superman + active: 1 + default_hostgroup: 3 + mysqlQueryRules: + - rule_id: 1 + active: 1 + match_pattern: "^SELECT .* FOR UPDATE$" + destination_hostgroup: 2 + apply: 1 + - rule_id: 2 + active: 1 + match_pattern: "^SELECT" + destination_hostgroup: 3 + apply: 1 + mysqlVariables: + max_connections: 2048 + connect_timeout_server: 10000 + threads: 4 + server_version: "8.4.8" + default_query_timeout: "36000000" + adminVariables: + restapi_enabled: "true" + restapi_port: "6070" + refresh_interval: "2000" + cluster_check_interval_ms: "200" + deletionPolicy: WipeOut diff --git a/docs/guides/proxysql/initialization/examples/proxysql-init-secret.yaml b/docs/guides/proxysql/initialization/examples/proxysql-init-secret.yaml new file mode 100644 index 0000000000..b0c3ed5600 --- /dev/null +++ b/docs/guides/proxysql/initialization/examples/proxysql-init-secret.yaml @@ -0,0 +1,71 @@ +apiVersion: v1 +kind: Secret +metadata: + name: proxysql-init-raw + namespace: demo +type: Opaque +stringData: + MySQLUsers.cnf: | + mysql_users= + ( + { + username="wolverine" + password="wolverine-pass" + active=1 + default_hostgroup=2 + default_schema="secret_schema" + }, + { + username="superman" + password="superman-pass" + active=1 + default_hostgroup=3 + } + ) + MySQLQueryRules.cnf: | + mysql_query_rules= + ( + { + rule_id=100 + active=1 + apply=1 + match_pattern="^INSERT" + destination_hostgroup=2 + }, + { + rule_id=101 + active=1 + apply=1 + match_pattern="^SELECT" + destination_hostgroup=3 + } + ) + MySQLVariables.cnf: | + mysql_variables= + { + max_connections="4096" + threads="8" + default_query_timeout="1234567" + } + AdminVariables.cnf: | + admin_variables= + { + refresh_interval="3500" + restapi_enabled="true" + restapi_port="6090" + } +--- +apiVersion: kubedb.com/v1 +kind: ProxySQL +metadata: + name: proxy-init-secret + namespace: demo +spec: + version: "3.0.1-debian" + replicas: 1 + backend: + name: mysql-server + configuration: + init: + secretName: proxysql-init-raw + deletionPolicy: WipeOut diff --git a/docs/guides/proxysql/initialization/examples/sample-mysql.yaml b/docs/guides/proxysql/initialization/examples/sample-mysql.yaml new file mode 100644 index 0000000000..b34967e013 --- /dev/null +++ b/docs/guides/proxysql/initialization/examples/sample-mysql.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1 +kind: MySQL +metadata: + name: mysql-server + namespace: demo +spec: + version: "8.4.8" + replicas: 3 + topology: + mode: GroupReplication + storageType: Durable + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut diff --git a/docs/guides/proxysql/initialization/script_source.md b/docs/guides/proxysql/initialization/script_source.md index 356a137ace..63675c85ad 100644 --- a/docs/guides/proxysql/initialization/script_source.md +++ b/docs/guides/proxysql/initialization/script_source.md @@ -1,9 +1,9 @@ --- -title: Initialize ProxySQL using Script Source +title: Initialize ProxySQL with Custom Configuration menu: docs_{{ .version }}: identifier: proxysql-script-source-initialization - name: Using Script + name: Using Custom Configuration parent: proxysql-initialization weight: 10 menu_name: docs_{{ .version }} @@ -12,9 +12,16 @@ section_menu_id: guides > New to KubeDB? Please start [here](/docs/README.md). -# Initialize ProxySQL with Script +# Initialize ProxySQL with Custom Configuration -KubeDB supports ProxySQL initialization using SQL scripts stored in a ConfigMap. This tutorial will show you how to use KubeDB to initialize a ProxySQL instance from a script to pre-configure MySQL backend servers, users, and query routing rules. +ProxySQL needs a bootstrap configuration file, `proxysql.cnf`, to set up its `mysql_users`, `mysql_query_rules`, `mysql_variables` and `admin_variables` tables at the very first startup. KubeDB lets you provide this bootstrap configuration in two ways under `spec.configuration.init`: + +- **`spec.configuration.init.secretName`** - point to a Secret holding the raw `proxysql.cnf` snippets. The values are patched into the config file verbatim, so you are responsible for the exact ProxySQL config syntax (and for supplying user passwords yourself). +- **`spec.configuration.init.inline`** - describe the same four sections in structured YAML. The operator renders this into `proxysql.cnf` for you, and for `mysqlUsers`, it automatically fetches the password from the backend server instead of asking you to write it in plaintext. + +If both are set, `init.inline` always takes precedence over `init.secretName`. This tutorial will show you how to use both. + +> Note: `spec.initConfig` and `spec.configSecret` are older, deprecated equivalents of `spec.configuration.init.inline` and `spec.configuration.init.secretName` respectively. Use the `spec.configuration.init` fields for any new ProxySQL object. ## Before You Begin @@ -33,11 +40,11 @@ NAME STATUS AGE demo Active 5s ``` -> Note: YAML files used in this tutorial are stored in [docs/examples/proxysql](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/proxysql) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). +> Note: YAML files used in this tutorial are stored in [docs/guides/proxysql/initialization/examples](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/guides/proxysql/initialization/examples) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). ## Prepare MySQL Backend -ProxySQL acts as a proxy in front of MySQL servers. Before deploying ProxySQL, you need a running MySQL Group Replication backend. Apply the following YAML to create a MySQL Group Replication: +ProxySQL acts as a proxy in front of MySQL servers. Before deploying ProxySQL, you need a running MySQL Group Replication backend. Apply the following YAML to create one: ```yaml apiVersion: kubedb.com/v1 @@ -62,7 +69,7 @@ spec: ``` ```bash -$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/proxysql/initialization/mysql-server.yaml +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/initialization/examples/sample-mysql.yaml mysql.kubedb.com/mysql-server created ``` @@ -74,134 +81,288 @@ NAME VERSION STATUS AGE mysql-server 8.4.8 Ready 5m ``` -## Prepare Initialization Scripts - -ProxySQL supports initialization with `.sql` and `.sh` scripts. In this tutorial, we will use an `init.sql` script to pre-configure query routing rules that direct write traffic to the primary server and read traffic to replicas. - -We will use a ConfigMap as the script source. You can use any Kubernetes supported [volume](https://kubernetes.io/docs/concepts/storage/volumes) as a script source. - -Let's create a ConfigMap with the initialization script: - -```bash -$ kubectl create configmap -n demo proxysql-init-script \ ---from-literal=init.sql="$(curl -fsSL https://raw.githubusercontent.com/kubedb/proxysql-init-scripts/master/init.sql)" #here will be your script path -configmap/proxysql-init-script created -``` - -## Create ProxySQL with Script Source +## Option 1: Bootstrap using a raw configuration Secret -Following YAML describes the ProxySQL object with `init.script`: +`spec.configuration.init.secretName` refers to a Secret with up to four keys - `MySQLUsers.cnf`, `MySQLQueryRules.cnf`, `MySQLVariables.cnf` and `AdminVariables.cnf`. Each key's value must already be in valid `proxysql.cnf` syntax; the operator copies it into the config file exactly as-is. ```yaml +apiVersion: v1 +kind: Secret +metadata: + name: proxysql-init-raw + namespace: demo +type: Opaque +stringData: + MySQLUsers.cnf: | + mysql_users= + ( + { + username="wolverine" + password="wolverine-pass" + active=1 + default_hostgroup=2 + default_schema="secret_schema" + }, + { + username="superman" + password="superman-pass" + active=1 + default_hostgroup=3 + } + ) + MySQLQueryRules.cnf: | + mysql_query_rules= + ( + { + rule_id=100 + active=1 + apply=1 + match_pattern="^INSERT" + destination_hostgroup=2 + }, + { + rule_id=101 + active=1 + apply=1 + match_pattern="^SELECT" + destination_hostgroup=3 + } + ) + MySQLVariables.cnf: | + mysql_variables= + { + max_connections="4096" + threads="8" + default_query_timeout="1234567" + } + AdminVariables.cnf: | + admin_variables= + { + refresh_interval="3500" + restapi_enabled="true" + restapi_port="6090" + } +--- apiVersion: kubedb.com/v1 kind: ProxySQL metadata: - name: script-proxysql + name: proxy-init-secret namespace: demo spec: version: "3.0.1-debian" replicas: 1 backend: name: mysql-server - init: - script: - configMap: - name: proxysql-init-script + configuration: + init: + secretName: proxysql-init-raw deletionPolicy: WipeOut ``` Here, -- `init.script` specifies the SQL scripts used to initialize ProxySQL when it is being created. Scripts are executed against the ProxySQL admin interface. -- `backend.name` references the MySQL Group Replication that ProxySQL will front. +- `configuration.init.secretName` points to the `proxysql-init-raw` Secret above. Since `MySQLUsers.cnf` sets each user's `password` explicitly, this path does **not** auto-fetch credentials from the backend the way `init.inline` does. +- Unlike `init.inline`, values under `init.secretName` are not merged with anything - only what you put in the Secret (plus KubeDB's internal defaults for things like cluster auth and TLS) ends up in `proxysql.cnf`, so double-check the syntax before applying. + +Apply the Secret and the ProxySQL object: -VolumeSource provided in `init.script` will be mounted in the Pod and executed against ProxySQL's admin port (`6032`) during initialization. +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/initialization/examples/proxysql-init-secret.yaml +secret/proxysql-init-raw created +proxysql.kubedb.com/proxy-init-secret created +``` -Now, let's create the ProxySQL CRD using the YAML shown above: +Wait until ProxySQL goes into the `Ready` state: ```bash -$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/proxysql/initialization/script-proxysql.yaml -proxysql.kubedb.com/script-proxysql created +$ kubectl get proxysql -n demo proxy-init-secret +NAME VERSION STATUS AGE +proxy-init-secret 3.0.1-debian Ready 2m ``` -Now, wait until ProxySQL goes in `Ready` state. Verify that it is in `Ready` state using the following command: +### Verify + +Get the admin credentials and connect to the ProxySQL admin interface (port `6032`): ```bash -$ kubectl get proxysql -n demo script-proxysql -NAME VERSION STATUS AGE -script-proxysql 3.0.1-debian Ready 2m +$ kubectl get secret -n demo proxy-init-secret-auth -o jsonpath='{.data.username}' | base64 -d +cluster + +$ kubectl get secret -n demo proxy-init-secret-auth -o jsonpath='{.data.password}' | base64 -d +S3cur3P@ssw0rd ``` -## Verify Initialization +```bash +$ kubectl exec -it -n demo proxy-init-secret-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ + -e "SELECT username, active, default_hostgroup, default_schema FROM mysql_users;" ++-----------+--------+-------------------+------------------+ +| username | active | default_hostgroup | default_schema | ++-----------+--------+-------------------+------------------+ +| wolverine | 1 | 2 | secret_schema | +| superman | 1 | 3 | | ++-----------+--------+-------------------+------------------+ + +$ kubectl exec -it -n demo proxy-init-secret-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ + -e "SELECT rule_id, match_pattern, destination_hostgroup FROM mysql_query_rules;" ++---------+---------------+------------------------+ +| rule_id | match_pattern | destination_hostgroup | ++---------+---------------+------------------------+ +| 100 | ^INSERT | 2 | +| 101 | ^SELECT | 3 | ++---------+---------------+------------------------+ + +$ kubectl exec -it -n demo proxy-init-secret-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ + -e "SELECT variable_name, variable_value FROM global_variables WHERE variable_name IN ('mysql-max_connections','mysql-threads','mysql-default_query_timeout','admin-restapi_enabled','admin-restapi_port','admin-refresh_interval');" ++------------------------------+----------------+ +| variable_name | variable_value | ++------------------------------+----------------+ +| mysql-max_connections | 4096 | +| mysql-threads | 8 | +| mysql-default_query_timeout | 1234567 | +| admin-restapi_enabled | true | +| admin-restapi_port | 6090 | +| admin-refresh_interval | 3500 | ++------------------------------+----------------+ +``` -Now let's connect to our ProxySQL instance to verify that the initialization scripts have been applied successfully. +The `mysql_users`, `mysql_query_rules` and the global variables all reflect exactly what was written in the `proxysql-init-raw` Secret. -**Connection Information:** +## Option 2: Bootstrap using inline structured configuration -- Host name/address: you can use any of these - - Service: `script-proxysql.demo` - - Pod IP: (`$ kubectl get pods script-proxysql-0 -n demo -o yaml | grep podIP`) -- Port: `6033` (MySQL traffic proxy) or `6032` (ProxySQL admin) +`spec.configuration.init.inline` describes the same four sections (`mysqlUsers`, `mysqlQueryRules`, `mysqlVariables`, `adminVariables`) in structured YAML instead of raw config syntax. The operator renders these into `proxysql.cnf`, merging them with KubeDB's own defaults (like monitor and cluster-auth variables). -- Username: Run the following command to get the *username*: +```yaml +apiVersion: kubedb.com/v1 +kind: ProxySQL +metadata: + name: proxy-init-inline + namespace: demo +spec: + version: "3.0.1-debian" + replicas: 1 + backend: + name: mysql-server + configuration: + init: + inline: + mysqlUsers: + - username: wolverine + active: 1 + default_hostgroup: 2 + default_schema: marvel + - username: superman + active: 1 + default_hostgroup: 3 + mysqlQueryRules: + - rule_id: 1 + active: 1 + match_pattern: "^SELECT .* FOR UPDATE$" + destination_hostgroup: 2 + apply: 1 + - rule_id: 2 + active: 1 + match_pattern: "^SELECT" + destination_hostgroup: 3 + apply: 1 + mysqlVariables: + max_connections: 2048 + connect_timeout_server: 10000 + threads: 4 + server_version: "8.4.8" + default_query_timeout: "36000000" + adminVariables: + restapi_enabled: "true" + restapi_port: "6070" + refresh_interval: "2000" + cluster_check_interval_ms: "200" + deletionPolicy: WipeOut +``` + +Here, + +- `configuration.init.inline.mysqlUsers` does not take a `password` field - KubeDB fetches each user's password from the backend MySQL server automatically, so no credential is ever written in plaintext YAML. +- `configuration.init.inline.mysqlQueryRules`, `.mysqlVariables` and `.adminVariables` accept the same keys as their raw `proxysql.cnf` counterparts, just in YAML key-value form. - ```bash - $ kubectl get secret -n demo script-proxysql-auth -o jsonpath='{.data.username}' | base64 -d - proxysql - ``` +See the [Declarative Configuration](/docs/guides/proxysql/concepts/declarative-configuration/index.md) concept page for the full field-by-field reference. -- Password: Run the following command to get the *password*: +Apply the YAML: - ```bash - $ kubectl get secret -n demo script-proxysql-auth -o jsonpath='{.data.password}' | base64 -d - S3cur3P@ssw0rd - ``` +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml +proxysql.kubedb.com/proxy-init-inline created +``` -Connect to the ProxySQL admin interface and verify the initialized query rules: +Wait until ProxySQL goes into the `Ready` state: ```bash -$ kubectl exec -it -n demo script-proxysql-0 -- mysql -u proxysql -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ - -e "SELECT rule_id, match_pattern, destination_hostgroup FROM mysql_query_rules;" -+---------+-------------------+----------------------+ -| rule_id | match_pattern | destination_hostgroup | -+---------+-------------------+----------------------+ -| 1 | ^SELECT.*FOR UPDATE$ | 2 | -| 2 | ^SELECT | 3 | -+---------+-------------------+----------------------+ +$ kubectl get proxysql -n demo proxy-init-inline +NAME VERSION STATUS AGE +proxy-init-inline 3.0.1-debian Ready 2m ``` -Verify the configured MySQL servers in ProxySQL: +### Verify ```bash -$ kubectl exec -it -n demo script-proxysql-0 -- mysql -u proxysql -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ - -e "SELECT hostgroup_id, hostname, port, status FROM mysql_servers;" -+--------------+---------------------------------------------+------+--------+ -| hostgroup_id | hostname | port | status | -+--------------+---------------------------------------------+------+--------+ -| 2 | mysql-server-0.mysql-server-pods.demo.svc | 3306 | ONLINE | -| 3 | mysql-server-1.mysql-server-pods.demo.svc | 3306 | ONLINE | -| 3 | mysql-server-2.mysql-server-pods.demo.svc | 3306 | ONLINE | -+--------------+---------------------------------------------+------+--------+ +$ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.username}' | base64 -d +cluster + +$ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.password}' | base64 -d +S3cur3P@ssw0rd ``` -We can see that the query routing rules and MySQL server configurations were applied through the initialization script. +```bash +$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ + -e "SELECT username, active, default_hostgroup, default_schema FROM mysql_users;" ++-----------+--------+-------------------+------------------+ +| username | active | default_hostgroup | default_schema | ++-----------+--------+-------------------+------------------+ +| wolverine | 1 | 2 | marvel | +| superman | 1 | 3 | | ++-----------+--------+-------------------+------------------+ + +$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ + -e "SELECT rule_id, match_pattern, destination_hostgroup FROM mysql_query_rules;" ++---------+----------------------------+------------------------+ +| rule_id | match_pattern | destination_hostgroup | ++---------+----------------------------+------------------------+ +| 1 | ^SELECT .* FOR UPDATE$ | 2 | +| 2 | ^SELECT | 3 | ++---------+----------------------------+------------------------+ + +$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ + -e "SELECT variable_name, variable_value FROM global_variables WHERE variable_name IN ('mysql-max_connections','mysql-threads','admin-restapi_enabled','admin-restapi_port');" ++------------------------+----------------+ +| variable_name | variable_value | ++------------------------+----------------+ +| mysql-max_connections | 2048 | +| mysql-threads | 4 | +| admin-restapi_enabled | true | +| admin-restapi_port | 6070 | ++------------------------+----------------+ +``` + +Since `wolverine` and `superman` also exist on the MySQL backend, ProxySQL was able to log in and fetch their passwords automatically - you can verify a client can actually connect through ProxySQL using those credentials without ever having put a password in the YAML. ## Cleaning up To cleanup the Kubernetes resources created by this tutorial, run: ```bash -$ kubectl patch -n demo proxysql/script-proxysql -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" -$ kubectl delete -n demo proxysql/script-proxysql +$ kubectl patch -n demo proxysql/proxy-init-secret -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +$ kubectl delete -n demo proxysql/proxy-init-secret + +$ kubectl patch -n demo proxysql/proxy-init-inline -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +$ kubectl delete -n demo proxysql/proxy-init-inline $ kubectl patch -n demo mysql/mysql-server -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" $ kubectl delete -n demo mysql/mysql-server -$ kubectl delete -n demo configmap/proxysql-init-script +$ kubectl delete -n demo secret/proxysql-init-raw $ kubectl delete ns demo ``` ## Next Steps +- Learn about [ProxySQL Declarative Configuration](/docs/guides/proxysql/concepts/declarative-configuration/index.md) in detail. - Learn about [ProxySQL clustering](/docs/guides/proxysql/clustering/overview/index.md) with KubeDB. - Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). From 2993f55acf4daaf98be5f03698c2df7d687fcdeb Mon Sep 17 00:00:00 2001 From: Bonusree Date: Tue, 7 Jul 2026 11:28:49 +0600 Subject: [PATCH 05/13] proxysql changes, reviews Signed-off-by: Bonusree --- docs/examples/perconaxtradb/script-pxc.yaml | 21 ++ .../pgbouncer/initialization/init_script.yaml | 22 ++ .../initialization/script_source.md | 6 +- docs/guides/ignite/update-version/_index.md | 10 - docs/guides/ignite/update-version/overview.md | 54 ---- .../ignite/update-version/update-version.md | 261 ------------------ .../initialization/script_source.md | 20 +- .../pgbouncer/initialization/script_source.md | 2 +- .../proxysql/initialization/script_source.md | 192 +++++++------ 9 files changed, 173 insertions(+), 415 deletions(-) create mode 100644 docs/examples/perconaxtradb/script-pxc.yaml create mode 100644 docs/examples/pgbouncer/initialization/init_script.yaml delete mode 100644 docs/guides/ignite/update-version/_index.md delete mode 100644 docs/guides/ignite/update-version/overview.md delete mode 100644 docs/guides/ignite/update-version/update-version.md diff --git a/docs/examples/perconaxtradb/script-pxc.yaml b/docs/examples/perconaxtradb/script-pxc.yaml new file mode 100644 index 0000000000..22a3dbd221 --- /dev/null +++ b/docs/examples/perconaxtradb/script-pxc.yaml @@ -0,0 +1,21 @@ +apiVersion: kubedb.com/v1 +kind: PerconaXtraDB +metadata: + name: script-pxc + namespace: demo +spec: + version: "8.4.3" + replicas: 3 + storageType: Durable + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + init: + script: + configMap: + name: pxc-init-script + deletionPolicy: WipeOut \ No newline at end of file diff --git a/docs/examples/pgbouncer/initialization/init_script.yaml b/docs/examples/pgbouncer/initialization/init_script.yaml new file mode 100644 index 0000000000..73933f0562 --- /dev/null +++ b/docs/examples/pgbouncer/initialization/init_script.yaml @@ -0,0 +1,22 @@ +apiVersion: kubedb.com/v1 +kind: PgBouncer +metadata: + name: script-pgbouncer + namespace: demo +spec: + version: "1.24.0" + replicas: 1 + database: + syncUsers: true + databaseName: "postgres" + databaseRef: + name: "quick-postgres" + namespace: demo + connectionPool: + maxClientConnections: 20 + reservePoolSize: 5 + init: + script: + configMap: + name: pb-init-script + deletionPolicy: WipeOut \ No newline at end of file diff --git a/docs/guides/clickhouse/initialization/script_source.md b/docs/guides/clickhouse/initialization/script_source.md index 5ed93635f3..95db0dd8e5 100644 --- a/docs/guides/clickhouse/initialization/script_source.md +++ b/docs/guides/clickhouse/initialization/script_source.md @@ -47,10 +47,10 @@ Let's create a ConfigMap with the initialization script: ```bash $ kubectl create configmap -n demo ch-init-script \ ---from-literal=init.sql="$(curl -fsSL https://raw.githubusercontent.com/Bonusree/init_script/main/clickhouse_init.sql)" +--from-literal=init.sql="$(curl -fsSL https://raw.githubusercontent.com/kubedb/clickhouse-init-script/refs/heads/master/clickhouse_init.sql)" configmap/ch-init-script created ``` - +> **Note:** The initialization script above is provided only as an example. You can use your own initialization script as long as it performs the required setup for your environment. If your script connects to ClickHouse, make sure to include the appropriate ClickHouse credentials (such as the password) so the script can authenticate successfully. After deploying ClickHouse with this ConfigMap, the initialization script runs automatically, and any databases, users, tables, or other objects created by the script can be verified after the deployment completes. ## Create ClickHouse with Script Source Following YAML describes the ClickHouse object with `init.script`: @@ -214,7 +214,7 @@ Now let's connect to our ClickHouse instance to verify that the database has bee **Connection Information:** - Host name/address: you can use any of these - - Service: `script-clickhouse.demo` + - Service: `script-clickhouse` - Pod IP: (`$ kubectl get pods script-clickhouse-0 -n demo -o yaml | grep podIP`) - Port: `9000` (native TCP) or `8123` (HTTP) diff --git a/docs/guides/ignite/update-version/_index.md b/docs/guides/ignite/update-version/_index.md deleted file mode 100644 index 3bddf00de0..0000000000 --- a/docs/guides/ignite/update-version/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Updating Ignite -menu: - docs_{{ .version }}: - identifier: ig-update-version - name: Update Version - parent: ignite-guides - weight: 50 -menu_name: docs_{{ .version }} ---- diff --git a/docs/guides/ignite/update-version/overview.md b/docs/guides/ignite/update-version/overview.md deleted file mode 100644 index ce7a283d7c..0000000000 --- a/docs/guides/ignite/update-version/overview.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Updating Ignite Overview -menu: - docs_{{ .version }}: - identifier: ig-update-version-overview - name: Overview - parent: ig-update-version - weight: 10 -menu_name: docs_{{ .version }} -section_menu_id: guides ---- - -> New to KubeDB? Please start [here](/docs/README.md). - -# Overview of Ignite Version Update - -This guide will give you an overview on how KubeDB Ops-manager operator update the version of `Ignite` database. - -## Before You Begin - -- You should be familiar with the following `KubeDB` concepts: - - [Ignite](/docs/guides/ignite/concepts/ignite/index.md) - - [IgniteOpsRequest](/docs/guides/ignite/concepts/opsrequest/index.md) - -## How update version Process Works - -The following diagram shows how KubeDB Ops-manager operator used to update the version of `Ignite`. Open the image in a new tab to see the enlarged version. - -
- updating Process of Ignite -
Fig: updating Process of Ignite
-
- -The updating process consists of the following steps: - -1. At first, a user creates an `Ignite` Custom Resource (CR). - -2. `KubeDB` Provisioner operator watches the `Ignite` CR. - -3. When the operator finds an `Ignite` CR, it creates required number of `PetSets` and other kubernetes native resources like secrets, services, etc. - -4. Then, in order to update the version of the `Ignite` database the user creates an `IgniteOpsRequest` CR with the desired version. - -5. `KubeDB` Ops-manager operator watches the `IgniteOpsRequest` CR. - -6. When it finds an `IgniteOpsRequest` CR, it halts the `Ignite` object which is referred from the `IgniteOpsRequest`. So, the `KubeDB` Provisioner operator doesn't perform any operations on the `Ignite` object during the updating process. - -7. By looking at the target version from `IgniteOpsRequest` CR, `KubeDB` Ops-manager operator updates the images of all the `PetSets`. - -8. After successfully updating the `PetSets` and their `Pods` images, the `KubeDB` Ops-manager operator updates the version field of the `Ignite` object to reflect the updated state of the database. - -9. After successfully updating of `Ignite` object, the `KubeDB` Ops-manager operator resumes the `Ignite` object so that the `KubeDB` Provisioner operator can resume its usual operations. - -In the [next](/docs/guides/ignite/update-version/update-version.md) doc, we are going to show a step-by-step guide on updating of an Ignite database using updateVersion operation. diff --git a/docs/guides/ignite/update-version/update-version.md b/docs/guides/ignite/update-version/update-version.md deleted file mode 100644 index ee6b8a642a..0000000000 --- a/docs/guides/ignite/update-version/update-version.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -title: Updating Ignite Cluster -menu: - docs_{{ .version }}: - identifier: ig-cluster-update-version - name: Update Version - parent: ig-update-version - weight: 30 -menu_name: docs_{{ .version }} -section_menu_id: guides ---- - -> New to KubeDB? Please start [here](/docs/README.md). - -# Update Version of Ignite Cluster - -This guide will show you how to use `KubeDB` Ops-manager operator to update the version of `Ignite` Cluster. - -## 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/). - -- Install `KubeDB` Provisioner and Ops-manager operator in your cluster following the steps [here](/docs/setup/README.md). - -- You should be familiar with the following `KubeDB` concepts: - - [Ignite](/docs/guides/ignite/concepts/ignite/index.md) - - [IgniteOpsRequest](/docs/guides/ignite/concepts/opsrequest/index.md) - - [Updating Overview](/docs/guides/ignite/update-version/overview.md) - -To keep everything isolated, we are going to use 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 [docs/examples/ignite](/docs/examples/ignite) directory of [kubedb/docs](https://github.com/kubedb/docs) repository. - -## Prepare Ignite Cluster - -Now, we are going to deploy an `Ignite` cluster with version `2.16.0`. - -### Deploy Ignite - -In this section, we are going to deploy an Ignite cluster. Then, in the next section we will update the version of the database using `IgniteOpsRequest` CRD. Below is the YAML of the `Ignite` CR that we are going to create, - -```yaml -apiVersion: kubedb.com/v1alpha2 -kind: Ignite -metadata: - name: ignite-quickstart - namespace: demo -spec: - version: "2.16.0" - replicas: 3 - storage: - resources: - requests: - storage: "1Gi" - storageClassName: "standard" - accessModes: - - ReadWriteOnce - deletionPolicy: "WipeOut" -``` - -Let's create the `Ignite` CR we have shown above, - -```bash -$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/ignite/update-version/ignite.yaml -ignite.kubedb.com/ignite-quickstart created -``` - -Now, wait until `ignite-quickstart` has status `Ready`. i.e, - -```bash -$ kubectl get ignite -n demo -NAME VERSION STATUS AGE -ignite-quickstart 2.16.0 Ready 109s -``` - -We are now ready to apply the `IgniteOpsRequest` CR to update this database. - -### Update Ignite Version - -Here, we are going to update `Ignite` cluster from `2.16.0` to `2.17.0`. - -#### Create IgniteOpsRequest: - -In order to update the version of the cluster, we have to create an `IgniteOpsRequest` CR with your desired version that is supported by `KubeDB`. Below is the YAML of the `IgniteOpsRequest` CR that we are going to create, - -```yaml -apiVersion: ops.kubedb.com/v1alpha1 -kind: IgniteOpsRequest -metadata: - name: upgrade-topology - namespace: demo -spec: - databaseRef: - name: ignite-quickstart - type: UpdateVersion - updateVersion: - targetVersion: 2.17.0 - timeout: 5m - apply: IfReady -``` - -Here, - -- `spec.databaseRef.name` specifies that we are performing operation on `ignite-quickstart` Ignite database. -- `spec.type` specifies that we are going to perform `UpdateVersion` on our database. -- `spec.updateVersion.targetVersion` specifies the expected version of the database `2.17.0`. -- Have a look [here](/docs/guides/ignite/concepts/opsrequest/index.md#spectimeout) on the respective sections to understand the `readinessCriteria`, `timeout` & `apply` fields. - -Let's create the `IgniteOpsRequest` CR we have shown above, - -```bash -$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/ignite/update-version/ig-version-upgrade-ops.yaml -igniteopsrequest.ops.kubedb.com/upgrade-topology created -``` - -#### Verify Ignite version updated successfully - -If everything goes well, `KubeDB` Ops-manager operator will update the image of `Ignite` object and related `PetSets` and `Pods`. - -Let's wait for `IgniteOpsRequest` to be `Successful`. Run the following command to watch `IgniteOpsRequest` CR, - -```bash -$ kubectl get igniteopsrequest -n demo -Every 2.0s: kubectl get igniteopsrequest -n demo -NAME TYPE STATUS AGE -upgrade-topology UpdateVersion Successful 84s -``` - -We can see from the above output that the `IgniteOpsRequest` has succeeded. If we describe the `IgniteOpsRequest` we will get an overview of the steps that were followed to update the database version. - -```bash -$ kubectl describe igniteopsrequest -n demo upgrade-topology -Name: upgrade-topology -Namespace: demo -Labels: -Annotations: -API Version: ops.kubedb.com/v1alpha1 -Kind: IgniteOpsRequest -Metadata: - Creation Timestamp: 2024-10-23T10:46:27Z - Generation: 1 - Resource Version: 1112190 - UID: 6a1baef3-74cb-4a44-9b8f-f4fa49a4cfca -Spec: - Apply: IfReady - Database Ref: - Name: ignite-quickstart - Timeout: 5m - Type: UpdateVersion - Update Version: - Target Version: 2.17.0 -Status: - Conditions: - Last Transition Time: 2024-10-23T10:46:27Z - Message: Ignite ops-request has started to update version - Observed Generation: 1 - Reason: UpdateVersion - Status: True - Type: UpdateVersion - Last Transition Time: 2024-10-23T10:46:35Z - Message: successfully reconciled the Ignite with updated version - Observed Generation: 1 - Reason: UpdatePetSets - Status: True - Type: UpdatePetSets - Last Transition Time: 2024-10-23T10:49:25Z - Message: Successfully Restarted Ignite nodes - Observed Generation: 1 - Reason: RestartPods - Status: True - Type: RestartPods - Last Transition Time: 2024-10-23T10:46:40Z - Message: get pod; ConditionStatus:True; PodName:ignite-quickstart-0 - Observed Generation: 1 - Status: True - Type: GetPod--ignite-quickstart-0 - Last Transition Time: 2024-10-23T10:46:40Z - Message: evict pod; ConditionStatus:True; PodName:ignite-quickstart-0 - Observed Generation: 1 - Status: True - Type: EvictPod--ignite-quickstart-0 - Last Transition Time: 2024-10-23T10:46:45Z - Message: running pod; ConditionStatus:False - Observed Generation: 1 - Status: False - Type: RunningPod - Last Transition Time: 2024-10-23T10:47:25Z - Message: get pod; ConditionStatus:True; PodName:ignite-quickstart-1 - Observed Generation: 1 - Status: True - Type: GetPod--ignite-quickstart-1 - Last Transition Time: 2024-10-23T10:47:25Z - Message: evict pod; ConditionStatus:True; PodName:ignite-quickstart-1 - Observed Generation: 1 - Status: True - Type: EvictPod--ignite-quickstart-1 - Last Transition Time: 2024-10-23T10:48:05Z - Message: get pod; ConditionStatus:True; PodName:ignite-quickstart-2 - Observed Generation: 1 - Status: True - Type: GetPod--ignite-quickstart-2 - Last Transition Time: 2024-10-23T10:48:05Z - Message: evict pod; ConditionStatus:True; PodName:ignite-quickstart-2 - Observed Generation: 1 - Status: True - Type: EvictPod--ignite-quickstart-2 - Last Transition Time: 2024-10-23T10:49:25Z - Message: Successfully updated Ignite version - Observed Generation: 1 - Reason: Successful - Status: True - Type: Successful - Observed Generation: 1 - Phase: Successful -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Starting 10m KubeDB Ops-manager Operator Start processing for IgniteOpsRequest: demo/upgrade-topology - Normal Starting 10m KubeDB Ops-manager Operator Pausing Ignite database: demo/ignite-quickstart - Normal Successful 10m KubeDB Ops-manager Operator Successfully paused Ignite database: demo/ignite-quickstart for IgniteOpsRequest: upgrade-topology - Normal UpdatePetSets 10m KubeDB Ops-manager Operator successfully reconciled the Ignite with updated version - Warning get pod; ConditionStatus:True; PodName:ignite-quickstart-0 10m KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:ignite-quickstart-0 - Warning evict pod; ConditionStatus:True; PodName:ignite-quickstart-0 10m KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:ignite-quickstart-0 - Warning running pod; ConditionStatus:False 10m KubeDB Ops-manager Operator running pod; ConditionStatus:False - Warning get pod; ConditionStatus:True; PodName:ignite-quickstart-1 9m25s KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:ignite-quickstart-1 - Warning evict pod; ConditionStatus:True; PodName:ignite-quickstart-1 9m25s KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:ignite-quickstart-1 - Warning get pod; ConditionStatus:True; PodName:ignite-quickstart-2 8m45s KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:ignite-quickstart-2 - Warning evict pod; ConditionStatus:True; PodName:ignite-quickstart-2 8m45s KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:ignite-quickstart-2 - Normal RestartPods 7m25s KubeDB Ops-manager Operator Successfully Restarted Ignite nodes - Normal Starting 7m25s KubeDB Ops-manager Operator Resuming Ignite database: demo/ignite-quickstart - Normal Successful 7m25s KubeDB Ops-manager Operator Successfully updated Ignite version -``` - -Now, we are going to verify whether the `Ignite` and the related `PetSets` and their `Pods` have the new version image. Let's check, - -```bash -$ kubectl get ignite -n demo ignite-quickstart -o=jsonpath='{.spec.version}{"\n"}' -2.17.0 - -$ kubectl get petset -n demo ignite-quickstart -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}' -ghcr.io/appscode-images/ignite:2.17.0 - -$ kubectl get pods -n demo ignite-quickstart-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}' -ghcr.io/appscode-images/ignite:2.17.0 -``` - -You can see from above, our `Ignite` cluster has been updated with the new version. So, the updateVersion process is successfully completed. - -## Cleaning Up - -To clean up the Kubernetes resources created by this tutorial, run: - -```bash -kubectl delete ignite -n demo ignite-quickstart -kubectl delete igniteopsrequest -n demo upgrade-topology -``` diff --git a/docs/guides/percona-xtradb/initialization/script_source.md b/docs/guides/percona-xtradb/initialization/script_source.md index 303fa1cb17..66b84a1032 100644 --- a/docs/guides/percona-xtradb/initialization/script_source.md +++ b/docs/guides/percona-xtradb/initialization/script_source.md @@ -50,7 +50,7 @@ $ kubectl create configmap -n demo pxc-init-script \ --from-literal=init.sql="$(curl -fsSL https://raw.githubusercontent.com/kubedb/percona-xtradb-init-scripts/master/init.sql)" configmap/pxc-init-script created ``` - +>**Note:** The initialization script above is provided only as an example. You can use your own initialization script as long as it performs the required setup for your environment. If your script connects to Percona XtraDB, make sure to include the appropriate MySQL credentials (such as the password) so the script can authenticate successfully. After deploying Percona XtraDB with this ConfigMap, the initialization script runs automatically, and any databases, users, tables, or other objects created by the script can be verified after the deployment completes. ## Create PerconaXtraDB with Script Source Following YAML describes the PerconaXtraDB object with `init.script`: @@ -88,7 +88,7 @@ VolumeSource provided in `init.script` will be mounted in the Pod and will be ex Now, let's create the PerconaXtraDB CRD using the YAML shown above: ```bash -$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/percona-xtradb/initialization/script-pxc.yaml +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/perconaxtradb/script-pxc.yaml perconaxtradb.kubedb.com/script-pxc created ``` @@ -269,7 +269,7 @@ Now let's connect to our PerconaXtraDB cluster to verify that the database has b **Connection Information:** - Host name/address: you can use any of these - - Service: `script-pxc.demo` + - Service: `script-pxc` - Pod IP: (`$ kubectl get pods script-pxc-0 -n demo -o yaml | grep podIP`) - Port: `3306` @@ -340,6 +340,20 @@ mysql: [Warning] Using a password on the command line interface can be insecure. | wsrep_streaming_log | +------------------------------------------------------+ + +$ kubectl exec -it -n demo script-pxc-0 -- \ + mysql -u root --password='6q0RjvaA!oXOVI0d' \ + -e "SELECT * FROM mysql.kubedb_table;" +Defaulted container "perconaxtradb" out of: perconaxtradb, px-coordinator, px-init (init) +mysql: [Warning] Using a password on the command line interface can be insecure. ++----+-------+ +| id | name | ++----+-------+ +| 1 | name1 | +| 2 | name2 | +| 3 | name3 | ++----+-------+ + ``` We can see the TABLE `kubedb_table` in `test` database which was created through initialization. diff --git a/docs/guides/pgbouncer/initialization/script_source.md b/docs/guides/pgbouncer/initialization/script_source.md index d47c0c16fc..a0390e687c 100644 --- a/docs/guides/pgbouncer/initialization/script_source.md +++ b/docs/guides/pgbouncer/initialization/script_source.md @@ -52,7 +52,7 @@ $ kubectl create configmap -n demo pb-init-script \ --from-literal=init.sh="$(curl -fsSL https://raw.githubusercontent.com/kubedb/pgbouncer-pgpool-init-scripts/master/pgbouncer/init.sh)" configmap/pb-init-script created ``` -> **Note:** The initialization script above is provided only as an example. You can use your own initialization script as long as it performs the required setup for your environment. If your script connects to PostgreSQL, make sure to include the appropriate PostgreSQL credentials (such as the password) so the script can authenticate successfully. +> **Note:** The initialization script above is provided only as an example. You can use your own initialization script as long as it performs the required setup for your environment. If your script connects to PostgreSQL, make sure to include the appropriate PostgreSQL credentials (such as the password) so the script can authenticate successfully. After deploying PgBouncer with this ConfigMap, the initialization script runs automatically, and any database created or registered by the script will be available and can be verified after the deployment completes. ## Create PgBouncer with Script Source Following YAML describes the PgBouncer object with `init.script`: diff --git a/docs/guides/proxysql/initialization/script_source.md b/docs/guides/proxysql/initialization/script_source.md index 63675c85ad..9837b8cf7d 100644 --- a/docs/guides/proxysql/initialization/script_source.md +++ b/docs/guides/proxysql/initialization/script_source.md @@ -14,7 +14,7 @@ section_menu_id: guides # Initialize ProxySQL with Custom Configuration -ProxySQL needs a bootstrap configuration file, `proxysql.cnf`, to set up its `mysql_users`, `mysql_query_rules`, `mysql_variables` and `admin_variables` tables at the very first startup. KubeDB lets you provide this bootstrap configuration in two ways under `spec.configuration.init`: +ProxySQL needs a bootstrap configuration file, `proxysql.cnf`, to set up its `mysql_query_rules`, `mysql_variables` and `admin_variables` tables at the very first startup. KubeDB lets you provide this bootstrap configuration in two ways under `spec.configuration.init`: - **`spec.configuration.init.secretName`** - point to a Secret holding the raw `proxysql.cnf` snippets. The values are patched into the config file verbatim, so you are responsible for the exact ProxySQL config syntax (and for supplying user passwords yourself). - **`spec.configuration.init.inline`** - describe the same four sections in structured YAML. The operator renders this into `proxysql.cnf` for you, and for `mysqlUsers`, it automatically fetches the password from the backend server instead of asking you to write it in plaintext. @@ -80,10 +80,20 @@ $ kubectl get mysql -n demo mysql-server NAME VERSION STATUS AGE mysql-server 8.4.8 Ready 5m ``` - ## Option 1: Bootstrap using a raw configuration Secret -`spec.configuration.init.secretName` refers to a Secret with up to four keys - `MySQLUsers.cnf`, `MySQLQueryRules.cnf`, `MySQLVariables.cnf` and `AdminVariables.cnf`. Each key's value must already be in valid `proxysql.cnf` syntax; the operator copies it into the config file exactly as-is. +`spec.configuration.init.secretName` refers to a Secret containing up to four optional keys: `MySQLUsers.cnf`, `MySQLQueryRules.cnf`, `MySQLVariables.cnf`, and `AdminVariables.cnf`. Each key must contain valid **ProxySQL configuration (`proxysql.cnf`) syntax**. During initialization, KubeDB mounts the Secret into the ProxySQL pod and copies the provided configuration fragments into the generated `proxysql.cnf` without modifying or translating them. ProxySQL then loads this configuration during startup and applies it to its internal configuration database. + +Unlike `init.inline`, which generates the ProxySQL configuration from structured Kubernetes YAML, `init.secretName` treats the Secret contents as raw ProxySQL configuration. Because KubeDB does not validate or merge these configuration fragments, you must ensure that the configuration is syntactically correct before applying it. + +The supported Secret keys are: + +* **`MySQLUsers.cnf`**: Defines frontend users (`mysql_users`). +* **`MySQLQueryRules.cnf`**: Defines query routing rules (`mysql_query_rules`). +* **`MySQLVariables.cnf`**: Configures global MySQL module variables. +* **`AdminVariables.cnf`**: Configures ProxySQL admin module variables. + +The following Secret configures frontend users, query rules, MySQL module variables, and admin variables: ```yaml apiVersion: v1 @@ -142,7 +152,11 @@ stringData: restapi_enabled="true" restapi_port="6090" } ---- +``` + +Deploy ProxySQL using the Secret: + +```yaml apiVersion: kubedb.com/v1 kind: ProxySQL metadata: @@ -159,10 +173,12 @@ spec: deletionPolicy: WipeOut ``` -Here, +Here: -- `configuration.init.secretName` points to the `proxysql-init-raw` Secret above. Since `MySQLUsers.cnf` sets each user's `password` explicitly, this path does **not** auto-fetch credentials from the backend the way `init.inline` does. -- Unlike `init.inline`, values under `init.secretName` are not merged with anything - only what you put in the Secret (plus KubeDB's internal defaults for things like cluster auth and TLS) ends up in `proxysql.cnf`, so double-check the syntax before applying. +* `configuration.init.secretName` references the `proxysql-init-raw` Secret containing the raw ProxySQL configuration fragments. +* Since `MySQLUsers.cnf` specifies each user's `password` explicitly, KubeDB does **not** automatically retrieve backend credentials, unlike `init.inline`. +* Each configuration fragment is copied directly into the generated `proxysql.cnf` and loaded by ProxySQL during startup. The resulting frontend users, query rules, and global variables are then available through the ProxySQL admin interface. +* Because the Secret is used as-is, ensure that every configuration fragment follows valid ProxySQL configuration syntax before applying it. Apply the Secret and the ProxySQL object: @@ -185,51 +201,69 @@ proxy-init-secret 3.0.1-debian Ready 2m Get the admin credentials and connect to the ProxySQL admin interface (port `6032`): ```bash -$ kubectl get secret -n demo proxy-init-secret-auth -o jsonpath='{.data.username}' | base64 -d -cluster - -$ kubectl get secret -n demo proxy-init-secret-auth -o jsonpath='{.data.password}' | base64 -d -S3cur3P@ssw0rd +$ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.username}' | base64 -d +cluster⏎ $ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.password}' | base64 -d +0vm8A7bllYpPFTK7⏎ ``` ```bash -$ kubectl exec -it -n demo proxy-init-secret-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ - -e "SELECT username, active, default_hostgroup, default_schema FROM mysql_users;" -+-----------+--------+-------------------+------------------+ -| username | active | default_hostgroup | default_schema | -+-----------+--------+-------------------+------------------+ -| wolverine | 1 | 2 | secret_schema | -| superman | 1 | 3 | | -+-----------+--------+-------------------+------------------+ - -$ kubectl exec -it -n demo proxy-init-secret-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ - -e "SELECT rule_id, match_pattern, destination_hostgroup FROM mysql_query_rules;" -+---------+---------------+------------------------+ -| rule_id | match_pattern | destination_hostgroup | -+---------+---------------+------------------------+ -| 100 | ^INSERT | 2 | -| 101 | ^SELECT | 3 | -+---------+---------------+------------------------+ - -$ kubectl exec -it -n demo proxy-init-secret-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ - -e "SELECT variable_name, variable_value FROM global_variables WHERE variable_name IN ('mysql-max_connections','mysql-threads','mysql-default_query_timeout','admin-restapi_enabled','admin-restapi_port','admin-refresh_interval');" +$ kubectl exec -it -n demo proxy-init-secret-0 -- mysql -u cluster -pGQzOzNmCUBP7pSEv -h 127.0.0.1 -P 6032 +Welcome to the MariaDB monitor. Commands end with ; or \g. +Your MySQL connection id is 110 +Server version: 8.0.27 (ProxySQL Admin Module) + +Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +MySQL [(none)]> SELECT variable_name, variable_value + -> FROM global_variables + -> WHERE variable_name IN ( + -> 'mysql-max_connections', + -> 'mysql-connect_timeout_server', + -> 'mysql-threads', + -> 'mysql-server_version', + -> 'mysql-default_query_timeout' + -> ); +------------------------------+----------------+ | variable_name | variable_value | +------------------------------+----------------+ +| mysql-connect_timeout_server | 10000 | +| mysql-default_query_timeout | 1234567 | | mysql-max_connections | 4096 | +| mysql-server_version | 8.0.27 | | mysql-threads | 8 | -| mysql-default_query_timeout | 1234567 | -| admin-restapi_enabled | true | -| admin-restapi_port | 6090 | -| admin-refresh_interval | 3500 | +------------------------------+----------------+ +5 rows in set (0.002 sec) + +MySQL [(none)]> SELECT username, + -> active, + -> default_hostgroup, + -> default_schema + -> FROM mysql_users; ++-----------+--------+-------------------+----------------+ +| username | active | default_hostgroup | default_schema | ++-----------+--------+-------------------+----------------+ +| wolverine | 1 | 2 | secret_schema | +| superman | 1 | 3 | | ++-----------+--------+-------------------+----------------+ +2 rows in set (0.000 sec) + ``` The `mysql_users`, `mysql_query_rules` and the global variables all reflect exactly what was written in the `proxysql-init-raw` Secret. ## Option 2: Bootstrap using inline structured configuration -`spec.configuration.init.inline` describes the same four sections (`mysqlUsers`, `mysqlQueryRules`, `mysqlVariables`, `adminVariables`) in structured YAML instead of raw config syntax. The operator renders these into `proxysql.cnf`, merging them with KubeDB's own defaults (like monitor and cluster-auth variables). +`spec.configuration.init.inline` lets you initialize ProxySQL using structured Kubernetes YAML instead of writing raw `proxysql.cnf` configuration. During initialization, KubeDB converts the inline YAML into the corresponding ProxySQL configuration, merges it with the operator-managed defaults (such as monitor user, cluster authentication, and other required internal settings), and generates the final `proxysql.cnf`. ProxySQL then loads the generated configuration into its internal configuration database during startup. + +The inline configuration supports the following sections: + +* **`mysqlQueryRules`** – Configures query routing rules (`mysql_query_rules`). +* **`mysqlVariables`** – Configures global MySQL module variables. +* **`adminVariables`** – Configures ProxySQL admin module variables. + +The following example configures query rules, MySQL variables, and admin variables using inline YAML: ```yaml apiVersion: kubedb.com/v1 @@ -245,14 +279,6 @@ spec: configuration: init: inline: - mysqlUsers: - - username: wolverine - active: 1 - default_hostgroup: 2 - default_schema: marvel - - username: superman - active: 1 - default_hostgroup: 3 mysqlQueryRules: - rule_id: 1 active: 1 @@ -278,21 +304,21 @@ spec: deletionPolicy: WipeOut ``` -Here, - -- `configuration.init.inline.mysqlUsers` does not take a `password` field - KubeDB fetches each user's password from the backend MySQL server automatically, so no credential is ever written in plaintext YAML. -- `configuration.init.inline.mysqlQueryRules`, `.mysqlVariables` and `.adminVariables` accept the same keys as their raw `proxysql.cnf` counterparts, just in YAML key-value form. +Here: -See the [Declarative Configuration](/docs/guides/proxysql/concepts/declarative-configuration/index.md) concept page for the full field-by-field reference. +* `configuration.init.inline` provides a Kubernetes-native way to configure ProxySQL without writing raw `proxysql.cnf` syntax. +* `mysqlQueryRules`, `mysqlVariables`, and `adminVariables` are defined using structured YAML, making the configuration easier to read and maintain. +* During initialization, KubeDB converts these YAML sections into the corresponding ProxySQL configuration, merges them with the operator-managed defaults, and generates the final `proxysql.cnf`. +* ProxySQL loads the generated configuration during startup, making the configured query rules and global variables available through the ProxySQL admin interface. -Apply the YAML: +Apply the configuration: ```bash $ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml proxysql.kubedb.com/proxy-init-inline created ``` -Wait until ProxySQL goes into the `Ready` state: +Wait until ProxySQL reaches the `Ready` state: ```bash $ kubectl get proxysql -n demo proxy-init-inline @@ -300,6 +326,7 @@ NAME VERSION STATUS AGE proxy-init-inline 3.0.1-debian Ready 2m ``` + ### Verify ```bash @@ -307,41 +334,40 @@ $ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.username cluster $ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.password}' | base64 -d -S3cur3P@ssw0rd +yKdzMTY0RKaomsqn ``` ```bash -$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ - -e "SELECT username, active, default_hostgroup, default_schema FROM mysql_users;" -+-----------+--------+-------------------+------------------+ -| username | active | default_hostgroup | default_schema | -+-----------+--------+-------------------+------------------+ -| wolverine | 1 | 2 | marvel | -| superman | 1 | 3 | | -+-----------+--------+-------------------+------------------+ - -$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ - -e "SELECT rule_id, match_pattern, destination_hostgroup FROM mysql_query_rules;" -+---------+----------------------------+------------------------+ -| rule_id | match_pattern | destination_hostgroup | -+---------+----------------------------+------------------------+ -| 1 | ^SELECT .* FOR UPDATE$ | 2 | -| 2 | ^SELECT | 3 | -+---------+----------------------------+------------------------+ - -$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ - -e "SELECT variable_name, variable_value FROM global_variables WHERE variable_name IN ('mysql-max_connections','mysql-threads','admin-restapi_enabled','admin-restapi_port');" -+------------------------+----------------+ -| variable_name | variable_value | -+------------------------+----------------+ -| mysql-max_connections | 2048 | -| mysql-threads | 4 | -| admin-restapi_enabled | true | -| admin-restapi_port | 6070 | -+------------------------+----------------+ +$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -pyKdzMTY0RKaomsqn -h 127.0.0.1 -P 6032 +Welcome to the MariaDB monitor. Commands end with ; or \g. +Your MySQL connection id is 5593 +Server version: 8.4.8 (ProxySQL Admin Module) + +Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +MySQL [(none)]> SELECT variable_name, variable_value + -> FROM global_variables + -> WHERE variable_name IN ( + -> 'mysql-max_connections', + -> 'mysql-connect_timeout_server', + -> 'mysql-threads', + -> 'mysql-server_version', + -> 'mysql-default_query_timeout' + -> ); ++------------------------------+----------------+ +| variable_name | variable_value | ++------------------------------+----------------+ +| mysql-connect_timeout_server | 10000 | +| mysql-default_query_timeout | 36000000 | +| mysql-max_connections | 2048 | +| mysql-server_version | 8.4.8 | +| mysql-threads | 4 | ++------------------------------+----------------+ +5 rows in set (0.001 sec) ``` - -Since `wolverine` and `superman` also exist on the MySQL backend, ProxySQL was able to log in and fetch their passwords automatically - you can verify a client can actually connect through ProxySQL using those credentials without ever having put a password in the YAML. +The query results confirm that the values defined under `mysqlQueryRules`, `mysqlVariables`, and `adminVariables` in `configuration.init.inline` were successfully rendered into the generated `ProxySQL` configuration and loaded during `ProxySQL` startup. ## Cleaning up From ba6ca591ceeeb1cd22e12506b91c76109886762b Mon Sep 17 00:00:00 2001 From: Bonusree Date: Wed, 8 Jul 2026 12:50:30 +0600 Subject: [PATCH 06/13] proxysql Signed-off-by: Bonusree --- .../initialization/script_source.md | 4 +- .../pgbouncer/initialization/script_source.md | 2 +- .../proxysql/initialization/script_source.md | 116 +++++++++++++++++- 3 files changed, 116 insertions(+), 6 deletions(-) diff --git a/docs/guides/percona-xtradb/initialization/script_source.md b/docs/guides/percona-xtradb/initialization/script_source.md index b655b3b043..294da82e5b 100644 --- a/docs/guides/percona-xtradb/initialization/script_source.md +++ b/docs/guides/percona-xtradb/initialization/script_source.md @@ -284,7 +284,7 @@ Now let's connect to our PerconaXtraDB cluster to verify that the database has b ```bash $ kubectl get secret -n demo script-pxc-auth -o jsonpath='{.data.password}' | base64 -d - nsTqGdVwR!~DA(t + nsTqGdVwR!~DA(ta ``` Now, connect to the PerconaXtraDB cluster and run the following query to confirm initialization: @@ -342,7 +342,7 @@ mysql: [Warning] Using a password on the command line interface can be insecure. $ kubectl exec -it -n demo script-pxc-0 -- \ - mysql -u root --password='6q0RjvaA!oXOVI0d' \ + mysql -u root --password='nsTqGdVwR!~DA(ta' \ -e "SELECT * FROM mysql.kubedb_table;" Defaulted container "perconaxtradb" out of: perconaxtradb, px-coordinator, px-init (init) mysql: [Warning] Using a password on the command line interface can be insecure. diff --git a/docs/guides/pgbouncer/initialization/script_source.md b/docs/guides/pgbouncer/initialization/script_source.md index a0390e687c..395c7d53ea 100644 --- a/docs/guides/pgbouncer/initialization/script_source.md +++ b/docs/guides/pgbouncer/initialization/script_source.md @@ -111,7 +111,7 @@ Now let's connect to our PgBouncer instance to verify that it has been initializ **Connection Information:** - Host name/address: you can use any of these - - Service: `script-pgbouncer.demo` + - Service: `script-pgbouncer` - Pod IP: (`$ kubectl get pods script-pgbouncer-0 -n demo -o yaml | grep podIP`) - Port: `5432` diff --git a/docs/guides/proxysql/initialization/script_source.md b/docs/guides/proxysql/initialization/script_source.md index 9837b8cf7d..073d21ec99 100644 --- a/docs/guides/proxysql/initialization/script_source.md +++ b/docs/guides/proxysql/initialization/script_source.md @@ -202,7 +202,8 @@ Get the admin credentials and connect to the ProxySQL admin interface (port `603 ```bash $ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.username}' | base64 -d -cluster⏎ $ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.password}' | base64 -d +cluster⏎ +$ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.password}' | base64 -d 0vm8A7bllYpPFTK7⏎ ``` @@ -325,6 +326,100 @@ $ kubectl get proxysql -n demo proxy-init-inline NAME VERSION STATUS AGE proxy-init-inline 3.0.1-debian Ready 2m ``` +## Reconfigure MYSQL USERS + +With `KubeDB` `ProxySQL` ops-request you can reconfigure `mysql_users` table. You can `add` and `delete` any users in the table. Also you can `update` any information of any user that is present in the table. To reconfigure the `mysql_users` table, you need to set the `.spec.type` to `Reconfigure`, provide the KubeDB ProxySQL instance name under the `spec.proxyRef` section and provide the desired user infos under the `spec.configuration.mysqlUsers.users` section. Set the `.spec.configuration.mysqlUsers.reqType` to either `add`, `update` or `delete` based on the operation you want to do. Below there are some samples for corresponding request type. + +### Create user in mysql database + +Let's first create two users in the backend mysql server. + +```bash +$ kubectl exec -it -n demo mysql-server-0 -- bash +Defaulted container "mysql" out of: mysql, mysql-coordinator, mysql-init (init) +bash-5.1$ create user `wolverine`@'%' identified by 'wolverine-pass'; +bash: wolverine: command not found +bash: create: command not found +bash-5.1$ mysql -uroot -p$MYSQL_ROOT_PASSWORD +mysql: [Warning] Using a password on the command line interface can be insecure. +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 50594 +Server version: 8.4.3 MySQL Community Server - GPL + +Copyright (c) 2000, 2024, Oracle and/or its affiliates. + +Oracle is a registered trademark of Oracle Corporation and/or its +affiliates. Other names may be trademarks of their respective +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> create user `wolverine`@'%' identified by 'wolverine-pass'; +Query OK, 0 rows affected (0.01 sec) + +mysql> create user `superman`@'%' identified by 'superman-pass'; +Query OK, 0 rows affected (0.01 sec) +``` + +### Check current mysql_users table in ProxySQL + +Let's check the current mysql_users table in the proxysql server. Make sure that the spec.syncUsers field was not set to true when the proxysql was deployed. Otherwise it will fetch all the users from the mysql backend and we won't be able to see the effects of reconfigure users ops requests. + +```bash +$ kubectl exec -it -n demo proxy-server-0 -- bash +root@proxy-server-0:/# mysql -uadmin -padmin -h127.0.0.1 -P6032 --prompt "ProxySQLAdmin > " +Welcome to the MariaDB monitor. Commands end with ; or \g. +Your MySQL connection id is 71 +Server version: 8.4.8 (ProxySQL Admin Module) + +Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +ProxySQLAdmin > select * from mysql_users; +Empty set (0.001 sec) +``` + +### Add Users + +Let's add the testA and testB user to the proxysql server with the ops-request. Make sure you have created the users in the mysql backend. As we don't provide the password in the yaml, the KubeDB operator fetches them from the backend server. So if the user is not present in the backend server, our operator will not be able to fetch the passwords and the ops-request will be failed. + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ProxySQLOpsRequest +metadata: + name: add-user + namespace: demo +spec: + type: Reconfigure + proxyRef: + name: proxy-server + configuration: + mysqlUsers: + users: + - username: wolverine + active: 1 + default_hostgroup: 2 + - username: superman + active: 1 + default_hostgroup: 2 + reqType: add +``` + +Let's applly the yaml. + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/reconfigure/cluster/examples/proxyops-add-users.yaml +proxysqlopsrequest.ops.kubedb.com/add-user created +``` + +Let's wait for the ops-request to be Successful. + +```bash +$ kubectl get proxysqlopsrequest -n demo +NAME TYPE STATUS AGE +add-user Reconfigure Successful 20s +``` ### Verify @@ -338,15 +433,29 @@ yKdzMTY0RKaomsqn ``` ```bash -$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -pyKdzMTY0RKaomsqn -h 127.0.0.1 -P 6032 +$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -p9KjQJ91LJFCtQnVF -h 127.0.0.1 -P 6032 Welcome to the MariaDB monitor. Commands end with ; or \g. -Your MySQL connection id is 5593 +Your MySQL connection id is 61 Server version: 8.4.8 (ProxySQL Admin Module) Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. +MySQL [(none)]> SELECT + -> username, + -> active, + -> default_hostgroup, + -> default_schema + -> FROM mysql_users; ++-----------+--------+-------------------+----------------+ +| username | active | default_hostgroup | default_schema | ++-----------+--------+-------------------+----------------+ +| wolverine | 1 | 2 | NULL | +| superman | 1 | 2 | NULL | ++-----------+--------+-------------------+----------------+ +2 rows in set (0.001 sec) + MySQL [(none)]> SELECT variable_name, variable_value -> FROM global_variables -> WHERE variable_name IN ( @@ -366,6 +475,7 @@ MySQL [(none)]> SELECT variable_name, variable_value | mysql-threads | 4 | +------------------------------+----------------+ 5 rows in set (0.001 sec) + ``` The query results confirm that the values defined under `mysqlQueryRules`, `mysqlVariables`, and `adminVariables` in `configuration.init.inline` were successfully rendered into the generated `ProxySQL` configuration and loaded during `ProxySQL` startup. From c9124848ee021d037da0045eb4e6fe438300272d Mon Sep 17 00:00:00 2001 From: Bonusree Date: Wed, 8 Jul 2026 15:27:34 +0600 Subject: [PATCH 07/13] proxyscl yaml Signed-off-by: Bonusree --- .../examples/proxyops-add-users.yaml | 19 + .../examples/proxysql-init-inline.yaml | 8 - .../proxysql/initialization/script_source.md | 338 ++++++++---------- 3 files changed, 175 insertions(+), 190 deletions(-) create mode 100644 docs/guides/proxysql/initialization/examples/proxyops-add-users.yaml diff --git a/docs/guides/proxysql/initialization/examples/proxyops-add-users.yaml b/docs/guides/proxysql/initialization/examples/proxyops-add-users.yaml new file mode 100644 index 0000000000..a083c71305 --- /dev/null +++ b/docs/guides/proxysql/initialization/examples/proxyops-add-users.yaml @@ -0,0 +1,19 @@ +apiVersion: ops.kubedb.com/v1alpha1 +kind: ProxySQLOpsRequest +metadata: + name: add-user + namespace: demo +spec: + type: Reconfigure + proxyRef: + name: proxy-init-inline + configuration: + mysqlUsers: + users: + - username: wolverine + active: 1 + default_hostgroup: 2 + - username: superman + active: 1 + default_hostgroup: 2 + reqType: add diff --git a/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml b/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml index ef3f118e6a..a5e5885c82 100644 --- a/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml +++ b/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml @@ -11,14 +11,6 @@ spec: configuration: init: inline: - mysqlUsers: - - username: wolverine - active: 1 - default_hostgroup: 2 - default_schema: marvel - - username: superman - active: 1 - default_hostgroup: 3 mysqlQueryRules: - rule_id: 1 active: 1 diff --git a/docs/guides/proxysql/initialization/script_source.md b/docs/guides/proxysql/initialization/script_source.md index 073d21ec99..8837d05151 100644 --- a/docs/guides/proxysql/initialization/script_source.md +++ b/docs/guides/proxysql/initialization/script_source.md @@ -14,37 +14,37 @@ section_menu_id: guides # Initialize ProxySQL with Custom Configuration -ProxySQL needs a bootstrap configuration file, `proxysql.cnf`, to set up its `mysql_query_rules`, `mysql_variables` and `admin_variables` tables at the very first startup. KubeDB lets you provide this bootstrap configuration in two ways under `spec.configuration.init`: +ProxySQL reads a bootstrap configuration file, `proxysql.cnf`, on first start to populate its in-memory configuration tables — `mysql_users`, `mysql_query_rules`, `mysql_variables`, and `admin_variables`. KubeDB lets you supply this bootstrap configuration through `spec.configuration.init`, in one of two ways: -- **`spec.configuration.init.secretName`** - point to a Secret holding the raw `proxysql.cnf` snippets. The values are patched into the config file verbatim, so you are responsible for the exact ProxySQL config syntax (and for supplying user passwords yourself). -- **`spec.configuration.init.inline`** - describe the same four sections in structured YAML. The operator renders this into `proxysql.cnf` for you, and for `mysqlUsers`, it automatically fetches the password from the backend server instead of asking you to write it in plaintext. +- **`spec.configuration.init.secretName`** — reference a Secret that holds raw `proxysql.cnf` fragments. The values are written into the generated configuration verbatim, so you own the exact ProxySQL syntax and must supply user passwords yourself. +- **`spec.configuration.init.inline`** — describe the same sections as structured YAML. The operator renders them into `proxysql.cnf` for you and, for `mysqlUsers`, automatically retrieves each user's password from the backend server so you never store it in plaintext. -If both are set, `init.inline` always takes precedence over `init.secretName`. This tutorial will show you how to use both. +If both are set, `init.inline` takes precedence over `init.secretName`. This guide demonstrates both approaches and then shows how to add users after initialization with a `ProxySQLOpsRequest`. -> Note: `spec.initConfig` and `spec.configSecret` are older, deprecated equivalents of `spec.configuration.init.inline` and `spec.configuration.init.secretName` respectively. Use the `spec.configuration.init` fields for any new ProxySQL object. +> Note: `spec.initConfig` and `spec.configSecret` are the deprecated equivalents of `init.inline` and `init.secretName` respectively. Use `spec.configuration.init` for all new ProxySQL objects. ## 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/). +You will need a Kubernetes cluster and the `kubectl` command-line tool configured to communicate with it. If you do not already have a cluster, you can create one with [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). +Install the KubeDB CLI on your workstation and the KubeDB operator in your cluster by following the [setup instructions](/docs/setup/README.md). -To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. +This guide uses a dedicated namespace called `demo` to keep the resources isolated. ```bash -$ kubectl create ns demo +$ kubectl create namespace demo namespace/demo created -$ kubectl get ns demo -NAME STATUS AGE -demo Active 5s +$ kubectl get namespace demo +NAME STATUS AGE +demo Active 5s ``` -> Note: YAML files used in this tutorial are stored in [docs/guides/proxysql/initialization/examples](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/guides/proxysql/initialization/examples) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). +> Note: The YAML files used in this guide are stored under [docs/guides/proxysql/initialization/examples](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/guides/proxysql/initialization/examples) in the [kubedb/docs](https://github.com/kubedb/docs) repository. ## Prepare MySQL Backend -ProxySQL acts as a proxy in front of MySQL servers. Before deploying ProxySQL, you need a running MySQL Group Replication backend. Apply the following YAML to create one: +ProxySQL sits in front of one or more MySQL servers. Before deploying ProxySQL, create a MySQL backend running in Group Replication mode: ```yaml apiVersion: kubedb.com/v1 @@ -73,27 +73,30 @@ $ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" > mysql.kubedb.com/mysql-server created ``` -Wait for the MySQL cluster to be `Ready`: +Wait for the MySQL cluster to become `Ready`: ```bash $ kubectl get mysql -n demo mysql-server NAME VERSION STATUS AGE mysql-server 8.4.8 Ready 5m ``` -## Option 1: Bootstrap using a raw configuration Secret -`spec.configuration.init.secretName` refers to a Secret containing up to four optional keys: `MySQLUsers.cnf`, `MySQLQueryRules.cnf`, `MySQLVariables.cnf`, and `AdminVariables.cnf`. Each key must contain valid **ProxySQL configuration (`proxysql.cnf`) syntax**. During initialization, KubeDB mounts the Secret into the ProxySQL pod and copies the provided configuration fragments into the generated `proxysql.cnf` without modifying or translating them. ProxySQL then loads this configuration during startup and applies it to its internal configuration database. +## Option 1: Bootstrap from a raw configuration Secret -Unlike `init.inline`, which generates the ProxySQL configuration from structured Kubernetes YAML, `init.secretName` treats the Secret contents as raw ProxySQL configuration. Because KubeDB does not validate or merge these configuration fragments, you must ensure that the configuration is syntactically correct before applying it. +`spec.configuration.init.secretName` points to a Secret that may contain up to four optional keys: `MySQLUsers.cnf`, `MySQLQueryRules.cnf`, `MySQLVariables.cnf`, and `AdminVariables.cnf`. Each key must hold valid **ProxySQL (`proxysql.cnf`) syntax**. During initialization, KubeDB mounts the Secret into the ProxySQL pod and copies each fragment verbatim into the generated `proxysql.cnf` — it does not validate, translate, or merge them. ProxySQL then loads the file at startup and applies it to its in-memory configuration database. + +Because the fragments are applied as-is, review the syntax carefully before applying it. The supported Secret keys are: -* **`MySQLUsers.cnf`**: Defines frontend users (`mysql_users`). -* **`MySQLQueryRules.cnf`**: Defines query routing rules (`mysql_query_rules`). -* **`MySQLVariables.cnf`**: Configures global MySQL module variables. -* **`AdminVariables.cnf`**: Configures ProxySQL admin module variables. +| Key | ProxySQL table | +| --------------------- | ---------------------------------- | +| `MySQLUsers.cnf` | Frontend users (`mysql_users`) | +| `MySQLQueryRules.cnf` | Query routing rules (`mysql_query_rules`) | +| `MySQLVariables.cnf` | MySQL module variables (`mysql_variables`) | +| `AdminVariables.cnf` | Admin module variables (`admin_variables`) | -The following Secret configures frontend users, query rules, MySQL module variables, and admin variables: +The following Secret defines frontend users, query rules, MySQL variables, and admin variables: ```yaml apiVersion: v1 @@ -154,7 +157,7 @@ stringData: } ``` -Deploy ProxySQL using the Secret: +Deploy a ProxySQL instance that consumes the Secret: ```yaml apiVersion: kubedb.com/v1 @@ -175,10 +178,9 @@ spec: Here: -* `configuration.init.secretName` references the `proxysql-init-raw` Secret containing the raw ProxySQL configuration fragments. -* Since `MySQLUsers.cnf` specifies each user's `password` explicitly, KubeDB does **not** automatically retrieve backend credentials, unlike `init.inline`. -* Each configuration fragment is copied directly into the generated `proxysql.cnf` and loaded by ProxySQL during startup. The resulting frontend users, query rules, and global variables are then available through the ProxySQL admin interface. -* Because the Secret is used as-is, ensure that every configuration fragment follows valid ProxySQL configuration syntax before applying it. +- `configuration.init.secretName` references the `proxysql-init-raw` Secret that holds the raw configuration fragments. +- Because `MySQLUsers.cnf` supplies each user's `password` explicitly, KubeDB does **not** fetch credentials from the backend — unlike `init.inline`. +- Each fragment is copied directly into the generated `proxysql.cnf` and loaded by ProxySQL at startup. The resulting users, query rules, and variables are then visible through the ProxySQL admin interface. Apply the Secret and the ProxySQL object: @@ -188,7 +190,7 @@ secret/proxysql-init-raw created proxysql.kubedb.com/proxy-init-secret created ``` -Wait until ProxySQL goes into the `Ready` state: +Wait until ProxySQL reaches the `Ready` state: ```bash $ kubectl get proxysql -n demo proxy-init-secret @@ -198,17 +200,12 @@ proxy-init-secret 3.0.1-debian Ready 2m ### Verify -Get the admin credentials and connect to the ProxySQL admin interface (port `6032`): - -```bash -$ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.username}' | base64 -d -cluster⏎ -$ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.password}' | base64 -d -0vm8A7bllYpPFTK7⏎ -``` +KubeDB stores the ProxySQL cluster-admin credentials in the `{ProxySQL-name}-auth` Secret (the username defaults to `cluster`, and the password is auto-generated). Read them and connect to the admin interface on port `6032`: ```bash -$ kubectl exec -it -n demo proxy-init-secret-0 -- mysql -u cluster -pGQzOzNmCUBP7pSEv -h 127.0.0.1 -P 6032 +$ ADMIN_USER=$(kubectl get secret -n demo proxy-init-secret-auth -o jsonpath='{.data.username}' | base64 -d) +$ ADMIN_PASS=$(kubectl get secret -n demo proxy-init-secret-auth -o jsonpath='{.data.password}' | base64 -d) +$ kubectl exec -it -n demo proxy-init-secret-0 -- mysql -u"$ADMIN_USER" -p"$ADMIN_PASS" -h 127.0.0.1 -P 6032 Welcome to the MariaDB monitor. Commands end with ; or \g. Your MySQL connection id is 110 Server version: 8.0.27 (ProxySQL Admin Module) @@ -219,52 +216,42 @@ Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. MySQL [(none)]> SELECT variable_name, variable_value -> FROM global_variables - -> WHERE variable_name IN ( - -> 'mysql-max_connections', - -> 'mysql-connect_timeout_server', - -> 'mysql-threads', - -> 'mysql-server_version', - -> 'mysql-default_query_timeout' - -> ); -+------------------------------+----------------+ -| variable_name | variable_value | -+------------------------------+----------------+ -| mysql-connect_timeout_server | 10000 | -| mysql-default_query_timeout | 1234567 | -| mysql-max_connections | 4096 | -| mysql-server_version | 8.0.27 | -| mysql-threads | 8 | -+------------------------------+----------------+ -5 rows in set (0.002 sec) - -MySQL [(none)]> SELECT username, - -> active, - -> default_hostgroup, - -> default_schema + -> WHERE variable_name IN + -> ('mysql-max_connections', 'mysql-threads', 'mysql-default_query_timeout'); ++-----------------------------+----------------+ +| variable_name | variable_value | ++-----------------------------+----------------+ +| mysql-default_query_timeout | 1234567 | +| mysql-max_connections | 4096 | +| mysql-threads | 8 | ++-----------------------------+----------------+ +3 rows in set (0.00 sec) + +MySQL [(none)]> SELECT username, active, default_hostgroup, default_schema -> FROM mysql_users; +-----------+--------+-------------------+----------------+ | username | active | default_hostgroup | default_schema | +-----------+--------+-------------------+----------------+ | wolverine | 1 | 2 | secret_schema | -| superman | 1 | 3 | | +| superman | 1 | 3 | NULL | +-----------+--------+-------------------+----------------+ -2 rows in set (0.000 sec) - +2 rows in set (0.00 sec) ``` -The `mysql_users`, `mysql_query_rules` and the global variables all reflect exactly what was written in the `proxysql-init-raw` Secret. +The global variables from `MySQLVariables.cnf` and the frontend users from `MySQLUsers.cnf` are reflected exactly as written in the `proxysql-init-raw` Secret. -## Option 2: Bootstrap using inline structured configuration +## Option 2: Bootstrap from inline structured configuration -`spec.configuration.init.inline` lets you initialize ProxySQL using structured Kubernetes YAML instead of writing raw `proxysql.cnf` configuration. During initialization, KubeDB converts the inline YAML into the corresponding ProxySQL configuration, merges it with the operator-managed defaults (such as monitor user, cluster authentication, and other required internal settings), and generates the final `proxysql.cnf`. ProxySQL then loads the generated configuration into its internal configuration database during startup. +`spec.configuration.init.inline` lets you initialize ProxySQL with structured Kubernetes YAML instead of raw `proxysql.cnf` syntax. At initialization, KubeDB translates the inline YAML into the corresponding ProxySQL configuration, merges it with the operator-managed defaults (monitor credentials, cluster authentication, and other required internal settings), and generates the final `proxysql.cnf`. ProxySQL loads this file at startup into its in-memory configuration database. -The inline configuration supports the following sections: +The inline configuration supports the same four sections: -* **`mysqlQueryRules`** – Configures query routing rules (`mysql_query_rules`). -* **`mysqlVariables`** – Configures global MySQL module variables. -* **`adminVariables`** – Configures ProxySQL admin module variables. +- **`mysqlUsers`** — frontend users (`mysql_users`). Passwords are fetched automatically from the backend server. +- **`mysqlQueryRules`** — query routing rules (`mysql_query_rules`). +- **`mysqlVariables`** — MySQL module variables (`mysql_variables`). +- **`adminVariables`** — admin module variables (`admin_variables`). -The following example configures query rules, MySQL variables, and admin variables using inline YAML: +The example below configures query rules, MySQL variables, and admin variables. Users are intentionally omitted here so that the `mysql_users` table starts empty; the [Reconfigure mysql_users](#reconfigure-mysql_users) section that follows adds users to this same instance with a `ProxySQLOpsRequest`, demonstrating how KubeDB retrieves passwords from the backend. ```yaml apiVersion: kubedb.com/v1 @@ -307,10 +294,9 @@ spec: Here: -* `configuration.init.inline` provides a Kubernetes-native way to configure ProxySQL without writing raw `proxysql.cnf` syntax. -* `mysqlQueryRules`, `mysqlVariables`, and `adminVariables` are defined using structured YAML, making the configuration easier to read and maintain. -* During initialization, KubeDB converts these YAML sections into the corresponding ProxySQL configuration, merges them with the operator-managed defaults, and generates the final `proxysql.cnf`. -* ProxySQL loads the generated configuration during startup, making the configured query rules and global variables available through the ProxySQL admin interface. +- `configuration.init.inline` provides a Kubernetes-native way to configure ProxySQL without writing raw `proxysql.cnf` syntax. +- `mysqlQueryRules`, `mysqlVariables`, and `adminVariables` are expressed as structured YAML, which is easier to read, diff, and maintain. +- At initialization, KubeDB renders these sections into `proxysql.cnf`, merges them with its own defaults, and lets ProxySQL load the result at startup. Apply the configuration: @@ -326,175 +312,163 @@ $ kubectl get proxysql -n demo proxy-init-inline NAME VERSION STATUS AGE proxy-init-inline 3.0.1-debian Ready 2m ``` -## Reconfigure MYSQL USERS -With `KubeDB` `ProxySQL` ops-request you can reconfigure `mysql_users` table. You can `add` and `delete` any users in the table. Also you can `update` any information of any user that is present in the table. To reconfigure the `mysql_users` table, you need to set the `.spec.type` to `Reconfigure`, provide the KubeDB ProxySQL instance name under the `spec.proxyRef` section and provide the desired user infos under the `spec.configuration.mysqlUsers.users` section. Set the `.spec.configuration.mysqlUsers.reqType` to either `add`, `update` or `delete` based on the operation you want to do. Below there are some samples for corresponding request type. +### Verify + +Connect to the admin interface and confirm that the query rules and global variables were applied: + +```bash +$ ADMIN_USER=$(kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.username}' | base64 -d) +$ ADMIN_PASS=$(kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.password}' | base64 -d) +$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u"$ADMIN_USER" -p"$ADMIN_PASS" -h 127.0.0.1 -P 6032 +Welcome to the MariaDB monitor. Commands end with ; or \g. +Your MySQL connection id is 61 +Server version: 8.4.8 (ProxySQL Admin Module) + +Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +MySQL [(none)]> SELECT rule_id, active, match_pattern, destination_hostgroup, apply + -> FROM mysql_query_rules + -> ORDER BY rule_id; ++---------+--------+------------------------+-----------------------+-------+ +| rule_id | active | match_pattern | destination_hostgroup | apply | ++---------+--------+------------------------+-----------------------+-------+ +| 1 | 1 | ^SELECT .* FOR UPDATE$ | 2 | 1 | +| 2 | 1 | ^SELECT | 3 | 1 | ++---------+--------+------------------------+-----------------------+-------+ +2 rows in set (0.00 sec) + +MySQL [(none)]> SELECT variable_name, variable_value + -> FROM global_variables + -> WHERE variable_name IN + -> ('mysql-max_connections', 'mysql-connect_timeout_server', + -> 'mysql-threads', 'mysql-server_version', 'mysql-default_query_timeout'); ++------------------------------+----------------+ +| variable_name | variable_value | ++------------------------------+----------------+ +| mysql-connect_timeout_server | 10000 | +| mysql-default_query_timeout | 36000000 | +| mysql-max_connections | 2048 | +| mysql-server_version | 8.4.8 | +| mysql-threads | 4 | ++------------------------------+----------------+ +5 rows in set (0.00 sec) +``` + +The query rules and global variables match the values defined under `mysqlQueryRules`, `mysqlVariables`, and `adminVariables`, confirming that KubeDB rendered them into the generated configuration and ProxySQL loaded them at startup. The `mysql_users` table is empty, since no users were configured inline. + +## Reconfigure mysql_users + +After initialization, you can manage the `mysql_users` table with a `ProxySQLOpsRequest` — adding, updating, or removing users without re-deploying ProxySQL. As with `init.inline`, you do **not** supply passwords: KubeDB fetches each user's password from the backend MySQL server, so every user you reference must already exist there. -### Create user in mysql database +To reconfigure `mysql_users`, set `.spec.type` to `Reconfigure`, point `.spec.proxyRef.name` at your ProxySQL instance, list the users under `.spec.configuration.mysqlUsers.users`, and set `.spec.configuration.mysqlUsers.reqType` to `add`, `update`, or `delete`. -Let's first create two users in the backend mysql server. +### Create the users in the MySQL backend + +First, create the users in the backend MySQL server. The example below creates `wolverine` and `superman`: ```bash $ kubectl exec -it -n demo mysql-server-0 -- bash Defaulted container "mysql" out of: mysql, mysql-coordinator, mysql-init (init) -bash-5.1$ create user `wolverine`@'%' identified by 'wolverine-pass'; -bash: wolverine: command not found -bash: create: command not found -bash-5.1$ mysql -uroot -p$MYSQL_ROOT_PASSWORD -mysql: [Warning] Using a password on the command line interface can be insecure. +root@mysql-server-0:/# mysql -uroot -p$MYSQL_ROOT_PASSWORD Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 50594 Server version: 8.4.3 MySQL Community Server - GPL Copyright (c) 2000, 2024, Oracle and/or its affiliates. -Oracle is a registered trademark of Oracle Corporation and/or its -affiliates. Other names may be trademarks of their respective -owners. - Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. -mysql> create user `wolverine`@'%' identified by 'wolverine-pass'; +mysql> CREATE USER 'wolverine'@'%' IDENTIFIED BY 'wolverine-pass'; Query OK, 0 rows affected (0.01 sec) -mysql> create user `superman`@'%' identified by 'superman-pass'; +mysql> CREATE USER 'superman'@'%' IDENTIFIED BY 'superman-pass'; Query OK, 0 rows affected (0.01 sec) ``` -### Check current mysql_users table in ProxySQL +### Inspect the current mysql_users table -Let's check the current mysql_users table in the proxysql server. Make sure that the spec.syncUsers field was not set to true when the proxysql was deployed. Otherwise it will fetch all the users from the mysql backend and we won't be able to see the effects of reconfigure users ops requests. +Confirm that the `mysql_users` table is empty on `proxy-init-inline`. This requires that `spec.syncUsers` was **not** enabled on the ProxySQL object — otherwise ProxySQL would automatically import every backend user and the table would not be empty. ```bash -$ kubectl exec -it -n demo proxy-server-0 -- bash -root@proxy-server-0:/# mysql -uadmin -padmin -h127.0.0.1 -P6032 --prompt "ProxySQLAdmin > " -Welcome to the MariaDB monitor. Commands end with ; or \g. -Your MySQL connection id is 71 -Server version: 8.4.8 (ProxySQL Admin Module) - -Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. - -Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - -ProxySQLAdmin > select * from mysql_users; -Empty set (0.001 sec) +$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u"$ADMIN_USER" -p"$ADMIN_PASS" -h 127.0.0.1 -P 6032 +... +MySQL [(none)]> SELECT username FROM mysql_users; +Empty set (0.00 sec) ``` -### Add Users +### Add users -Let's add the testA and testB user to the proxysql server with the ops-request. Make sure you have created the users in the mysql backend. As we don't provide the password in the yaml, the KubeDB operator fetches them from the backend server. So if the user is not present in the backend server, our operator will not be able to fetch the passwords and the ops-request will be failed. +Submit an ops request to add `wolverine` and `superman`. Because no password is supplied, KubeDB retrieves it from the backend — if a user does not exist there, the request fails. ```yaml apiVersion: ops.kubedb.com/v1alpha1 kind: ProxySQLOpsRequest metadata: - name: add-user - namespace: demo + name: add-user + namespace: demo spec: - type: Reconfigure - proxyRef: - name: proxy-server - configuration: - mysqlUsers: - users: + type: Reconfigure + proxyRef: + name: proxy-init-inline + configuration: + mysqlUsers: + users: - username: wolverine active: 1 - default_hostgroup: 2 + default_hostgroup: 2 - username: superman active: 1 default_hostgroup: 2 - reqType: add + reqType: add ``` -Let's applly the yaml. +Apply it: ```bash -$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/reconfigure/cluster/examples/proxyops-add-users.yaml +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/initialization/examples/proxyops-add-users.yaml proxysqlopsrequest.ops.kubedb.com/add-user created ``` -Let's wait for the ops-request to be Successful. +Wait for the ops request to succeed: ```bash -$ kubectl get proxysqlopsrequest -n demo +$ kubectl get proxysqlopsrequest -n demo add-user NAME TYPE STATUS AGE add-user Reconfigure Successful 20s ``` - ### Verify -```bash -$ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.username}' | base64 -d -cluster - -$ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.password}' | base64 -d -yKdzMTY0RKaomsqn -``` +Back in the admin interface, the two users now appear with the passwords KubeDB fetched from the backend (stored as hashes), the `active` flag, and the `default_hostgroup` from the ops request: ```bash -$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -p9KjQJ91LJFCtQnVF -h 127.0.0.1 -P 6032 -Welcome to the MariaDB monitor. Commands end with ; or \g. -Your MySQL connection id is 61 -Server version: 8.4.8 (ProxySQL Admin Module) - -Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. - -Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. - -MySQL [(none)]> SELECT - -> username, - -> active, - -> default_hostgroup, - -> default_schema +MySQL [(none)]> SELECT username, password, active, default_hostgroup -> FROM mysql_users; -+-----------+--------+-------------------+----------------+ -| username | active | default_hostgroup | default_schema | -+-----------+--------+-------------------+----------------+ -| wolverine | 1 | 2 | NULL | -| superman | 1 | 2 | NULL | -+-----------+--------+-------------------+----------------+ -2 rows in set (0.001 sec) - -MySQL [(none)]> SELECT variable_name, variable_value - -> FROM global_variables - -> WHERE variable_name IN ( - -> 'mysql-max_connections', - -> 'mysql-connect_timeout_server', - -> 'mysql-threads', - -> 'mysql-server_version', - -> 'mysql-default_query_timeout' - -> ); -+------------------------------+----------------+ -| variable_name | variable_value | -+------------------------------+----------------+ -| mysql-connect_timeout_server | 10000 | -| mysql-default_query_timeout | 36000000 | -| mysql-max_connections | 2048 | -| mysql-server_version | 8.4.8 | -| mysql-threads | 4 | -+------------------------------+----------------+ -5 rows in set (0.001 sec) ++-----------+-------------------------------------------+--------+-------------------+ +| username | password | active | default_hostgroup | ++-----------+-------------------------------------------+--------+-------------------+ +| superman | *AE9C3C2838160D2591B6B15FA281CE712ABE94F0 | 1 | 2 | +| wolverine | *1BB8830D52D091A226FB7990D996CBC20F913475 | 1 | 2 | ++-----------+-------------------------------------------+--------+-------------------+ +2 rows in set (0.00 sec) ``` -The query results confirm that the values defined under `mysqlQueryRules`, `mysqlVariables`, and `adminVariables` in `configuration.init.inline` were successfully rendered into the generated `ProxySQL` configuration and loaded during `ProxySQL` startup. + +> To change a user's attributes later, submit another ops request with `reqType: update` (`username` is the key). To remove a user, use `reqType: delete` and list only the username. The [Reconfigure ProxySQL](/docs/guides/proxysql/reconfigure/cluster/index.md) guide covers the full set of operations, including query rules and global variables. ## Cleaning up -To cleanup the Kubernetes resources created by this tutorial, run: +To remove the resources created in this guide, run: ```bash -$ kubectl patch -n demo proxysql/proxy-init-secret -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" -$ kubectl delete -n demo proxysql/proxy-init-secret - -$ kubectl patch -n demo proxysql/proxy-init-inline -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" -$ kubectl delete -n demo proxysql/proxy-init-inline - -$ kubectl patch -n demo mysql/mysql-server -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" -$ kubectl delete -n demo mysql/mysql-server - -$ kubectl delete -n demo secret/proxysql-init-raw -$ kubectl delete ns demo +$ kubectl delete -n demo proxysqlopsrequest --all +$ kubectl delete -n demo proxysql proxy-init-secret proxy-init-inline +$ kubectl delete -n demo mysql mysql-server +$ kubectl delete -n demo secret proxysql-init-raw +$ kubectl delete namespace demo ``` ## Next Steps From 1793bde9bba26acdefaa6652fe82469d8a9bc157 Mon Sep 17 00:00:00 2001 From: Bonusree Date: Tue, 14 Jul 2026 11:10:37 +0600 Subject: [PATCH 08/13] proxysql rewrite Signed-off-by: Bonusree --- .../pgbouncer/initialization/script_source.md | 1 - .../proxysql/initialization/script_source.md | 175 +++++++++++++----- 2 files changed, 124 insertions(+), 52 deletions(-) diff --git a/docs/guides/pgbouncer/initialization/script_source.md b/docs/guides/pgbouncer/initialization/script_source.md index d47c0c16fc..6ee72a5527 100644 --- a/docs/guides/pgbouncer/initialization/script_source.md +++ b/docs/guides/pgbouncer/initialization/script_source.md @@ -165,5 +165,4 @@ $ kubectl delete ns demo ## Next Steps -- Learn about [backup and restore](/docs/guides/pgbouncer/backup/overview/index.md) PgBouncer using Stash. - Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/proxysql/initialization/script_source.md b/docs/guides/proxysql/initialization/script_source.md index 63675c85ad..b95c87dc88 100644 --- a/docs/guides/proxysql/initialization/script_source.md +++ b/docs/guides/proxysql/initialization/script_source.md @@ -14,12 +14,12 @@ section_menu_id: guides # Initialize ProxySQL with Custom Configuration -ProxySQL needs a bootstrap configuration file, `proxysql.cnf`, to set up its `mysql_users`, `mysql_query_rules`, `mysql_variables` and `admin_variables` tables at the very first startup. KubeDB lets you provide this bootstrap configuration in two ways under `spec.configuration.init`: +ProxySQL requires a bootstrap configuration file, `proxysql.cnf`, to populate its `mysql_users`, `mysql_query_rules`, `mysql_variables`, and `admin_variables` tables during its very first startup. KubeDB lets you provide this bootstrap configuration in two ways under `spec.configuration.init`: -- **`spec.configuration.init.secretName`** - point to a Secret holding the raw `proxysql.cnf` snippets. The values are patched into the config file verbatim, so you are responsible for the exact ProxySQL config syntax (and for supplying user passwords yourself). -- **`spec.configuration.init.inline`** - describe the same four sections in structured YAML. The operator renders this into `proxysql.cnf` for you, and for `mysqlUsers`, it automatically fetches the password from the backend server instead of asking you to write it in plaintext. +- **`spec.configuration.init.secretName`** - Points to a Secret holding the raw `proxysql.cnf` snippets. The values are patched into the config file verbatim, so you are responsible for the exact ProxySQL config syntax (and for supplying user passwords yourself). +- **`spec.configuration.init.inline`** - Describes the same four sections in structured YAML. The operator renders this into `proxysql.cnf` for you, and for `mysqlUsers`, it automatically fetches the password from the backend server instead of requiring you to write it in plaintext. -If both are set, `init.inline` always takes precedence over `init.secretName`. This tutorial will show you how to use both. +If both are set, `init.inline` always takes precedence over `init.secretName`. This tutorial demonstrates both approaches. > Note: `spec.initConfig` and `spec.configSecret` are older, deprecated equivalents of `spec.configuration.init.inline` and `spec.configuration.init.secretName` respectively. Use the `spec.configuration.init` fields for any new ProxySQL object. @@ -29,7 +29,7 @@ At first, you need to have a Kubernetes cluster, and the kubectl command-line to 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. +To keep things isolated, this tutorial uses a separate namespace called `demo` throughout. ```bash $ kubectl create ns demo @@ -83,7 +83,7 @@ mysql-server 8.4.8 Ready 5m ## Option 1: Bootstrap using a raw configuration Secret -`spec.configuration.init.secretName` refers to a Secret with up to four keys - `MySQLUsers.cnf`, `MySQLQueryRules.cnf`, `MySQLVariables.cnf` and `AdminVariables.cnf`. Each key's value must already be in valid `proxysql.cnf` syntax; the operator copies it into the config file exactly as-is. +`spec.configuration.init.secretName` references a Secret with up to four keys: `MySQLUsers.cnf`, `MySQLQueryRules.cnf`, `MySQLVariables.cnf`, and `AdminVariables.cnf`. Each key's value must already be in valid `proxysql.cnf` syntax, since the operator copies it into the config file exactly as-is. ```yaml apiVersion: v1 @@ -162,7 +162,7 @@ spec: Here, - `configuration.init.secretName` points to the `proxysql-init-raw` Secret above. Since `MySQLUsers.cnf` sets each user's `password` explicitly, this path does **not** auto-fetch credentials from the backend the way `init.inline` does. -- Unlike `init.inline`, values under `init.secretName` are not merged with anything - only what you put in the Secret (plus KubeDB's internal defaults for things like cluster auth and TLS) ends up in `proxysql.cnf`, so double-check the syntax before applying. +- Unlike `init.inline`, values under `init.secretName` are not merged with anything else - only what you put in the Secret (plus KubeDB's internal defaults for things like cluster auth and TLS) ends up in `proxysql.cnf`. Double-check the syntax carefully before applying. Apply the Secret and the ProxySQL object: @@ -225,11 +225,11 @@ $ kubectl exec -it -n demo proxy-init-secret-0 -- mysql -u cluster -pS3cur3P@ssw +------------------------------+----------------+ ``` -The `mysql_users`, `mysql_query_rules` and the global variables all reflect exactly what was written in the `proxysql-init-raw` Secret. +The `mysql_users`, `mysql_query_rules`, and the global variables all reflect exactly what was written in the `proxysql-init-raw` Secret. ## Option 2: Bootstrap using inline structured configuration -`spec.configuration.init.inline` describes the same four sections (`mysqlUsers`, `mysqlQueryRules`, `mysqlVariables`, `adminVariables`) in structured YAML instead of raw config syntax. The operator renders these into `proxysql.cnf`, merging them with KubeDB's own defaults (like monitor and cluster-auth variables). +`spec.configuration.init.inline` describes the same four sections (`mysqlUsers`, `mysqlQueryRules`, `mysqlVariables`, `adminVariables`) in structured YAML instead of raw config syntax. The operator renders these into `proxysql.cnf`, merging them with KubeDB's own defaults (such as monitor and cluster-auth variables). ```yaml apiVersion: kubedb.com/v1 @@ -245,14 +245,6 @@ spec: configuration: init: inline: - mysqlUsers: - - username: wolverine - active: 1 - default_hostgroup: 2 - default_schema: marvel - - username: superman - active: 1 - default_hostgroup: 3 mysqlQueryRules: - rule_id: 1 active: 1 @@ -281,7 +273,7 @@ spec: Here, - `configuration.init.inline.mysqlUsers` does not take a `password` field - KubeDB fetches each user's password from the backend MySQL server automatically, so no credential is ever written in plaintext YAML. -- `configuration.init.inline.mysqlQueryRules`, `.mysqlVariables` and `.adminVariables` accept the same keys as their raw `proxysql.cnf` counterparts, just in YAML key-value form. +- `configuration.init.inline.mysqlQueryRules`, `.mysqlVariables`, and `.adminVariables` accept the same keys as their raw `proxysql.cnf` counterparts, expressed in YAML key-value form. See the [Declarative Configuration](/docs/guides/proxysql/concepts/declarative-configuration/index.md) concept page for the full field-by-field reference. @@ -302,50 +294,131 @@ proxy-init-inline 3.0.1-debian Ready 2m ### Verify +#### Create Users in the MySQL Database + +Before ProxySQL can fetch credentials from the backend, the corresponding users must exist there. Create two users on the backend MySQL server: + ```bash -$ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.username}' | base64 -d -cluster +$ kubectl exec -it -n demo mysql-server-0 -- bash +Defaulted container "mysql" out of: mysql, mysql-coordinator, mysql-init (init) +bash-5.1$ mysql -uroot -p$MYSQL_ROOT_PASSWORD +mysql: [Warning] Using a password on the command line interface can be insecure. +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 512 +Server version: 8.4.3 MySQL Community Server - GPL -$ kubectl get secret -n demo proxy-init-inline-auth -o jsonpath='{.data.password}' | base64 -d -S3cur3P@ssw0rd +Copyright (c) 2000, 2024, Oracle and/or its affiliates. + +Oracle is a registered trademark of Oracle Corporation and/or its +affiliates. Other names may be trademarks of their respective +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> CREATE USER `wolverine` IDENTIFIED BY 'wolverine-pass'; +Query OK, 0 rows affected (0.02 sec) + +mysql> CREATE USER `superman` IDENTIFIED BY 'superman-pass'; +Query OK, 0 rows affected (0.02 sec) + +mysql> flush privileges; +Query OK, 0 rows affected (0.00 sec) + +mysql> exit +Bye +``` + +#### Add Users via Reconfigure Ops-request + +You can also add users to a running ProxySQL server dynamically, using a `ProxySQLOpsRequest`. The following example adds users `testA` and `testB` to the `proxy-server` ProxySQL instance. Since no `password` field is provided in the YAML, the KubeDB operator fetches each user's password from the backend MySQL server automatically - so the corresponding users must already exist there before applying this OpsRequest. If a user is not present on the backend, the operator will be unable to fetch its password and the OpsRequest will fail. + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: ProxySQLOpsRequest +metadata: + name: add-user + namespace: demo +spec: + type: Reconfigure + proxyRef: + name: proxy-server + configuration: + mysqlUsers: + users: + - username: testA + active: 1 + default_hostgroup: 2 + - username: testB + active: 1 + default_hostgroup: 2 + reqType: add ``` +Apply the OpsRequest YAML: + ```bash -$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ - -e "SELECT username, active, default_hostgroup, default_schema FROM mysql_users;" -+-----------+--------+-------------------+------------------+ -| username | active | default_hostgroup | default_schema | -+-----------+--------+-------------------+------------------+ -| wolverine | 1 | 2 | marvel | -| superman | 1 | 3 | | -+-----------+--------+-------------------+------------------+ +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/proxysql/reconfigure/cluster/examples/proxyops-add-users.yaml +proxysqlopsrequest.ops.kubedb.com/add-user created +``` + +Wait for the OpsRequest to reach the `Successful` state: + +```bash +$ kubectl get proxysqlopsrequest -n demo +NAME TYPE STATUS AGE +add-user Reconfigure Successful 20s +``` + +Now verify the `mysql_users` table on the ProxySQL server: + + +```bash +$ kubectl exec -it -n demo proxy-init-inline-0 -- bash +proxysql@proxy-init-inline-0:/$ mysql -uadmin -padmin -h127.0.0.1 -P6032 --prompt "ProxySQLAdmin > " +Welcome to the MariaDB monitor. Commands end with ; or \g. +Your MySQL connection id is 90 +Server version: 8.4.8 (ProxySQL Admin Module) + +Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +ProxySQLAdmin > select * from mysql_users; ++-----------+------------------------------------------------------------------------------------------------+--------+---------+-------------------+----------------+---------------+------------------------+--------------+---------+----------+-----------------+------------+---------+ +| username | password | active | use_ssl | default_hostgroup | default_schema | schema_locked | transaction_persistent | fast_forward | backend | frontend | max_connections | attributes | comment | ++-----------+------------------------------------------------------------------------------------------------+--------+---------+-------------------+----------------+---------------+------------------------+--------------+---------+----------+-----------------+------------+---------+ +| wolverine | $A$005$7GF&7o.%\x10;.%jP5Ui??\\KmKM45B50Xt3wzJ2fmWo9FHAi2Yt7mhhCa8wlZpHZ/1 | 1 | 0 | 2 | NULL | 0 | 1 | 0 | 1 | 1 | 10000 | | | +| superman | $A$005$\t!MR\x18p{\x12\x06TE\x1e\t\\,\x1bI8\x15\x1bcxpfFLuOBmbfiLF9rs8MTeYQ3yJVQghmaM4/evor/XC | 1 | 0 | 2 | NULL | 0 | 1 | 0 | 1 | 1 | 10000 | | | ++-----------+------------------------------------------------------------------------------------------------+--------+---------+-------------------+----------------+---------------+------------------------+--------------+---------+----------+-----------------+------------+---------+ +2 rows in set (0.001 sec) + +ProxySQLAdmin > SELECT rule_id, match_pattern, destination_hostgroup FROM mysql_query_rules; ++---------+------------------------+-----------------------+ +| rule_id | match_pattern | destination_hostgroup | ++---------+------------------------+-----------------------+ +| 1 | ^SELECT .* FOR UPDATE$ | 2 | +| 2 | ^SELECT | 3 | ++---------+------------------------+-----------------------+ +2 rows in set (0.002 sec) + +ProxySQLAdmin > SELECT variable_name, variable_value FROM global_variables WHERE variable_name IN ('mysql-max_connections','mysql-threads','admin-restapi_enabled','admin-restapi_port'); ++-----------------------+----------------+ +| variable_name | variable_value | ++-----------------------+----------------+ +| admin-restapi_enabled | true | +| admin-restapi_port | 6070 | +| mysql-max_connections | 2048 | +| mysql-threads | 4 | ++-----------------------+----------------+ +4 rows in set (0.002 sec) -$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ - -e "SELECT rule_id, match_pattern, destination_hostgroup FROM mysql_query_rules;" -+---------+----------------------------+------------------------+ -| rule_id | match_pattern | destination_hostgroup | -+---------+----------------------------+------------------------+ -| 1 | ^SELECT .* FOR UPDATE$ | 2 | -| 2 | ^SELECT | 3 | -+---------+----------------------------+------------------------+ - -$ kubectl exec -it -n demo proxy-init-inline-0 -- mysql -u cluster -pS3cur3P@ssw0rd -h 127.0.0.1 -P 6032 \ - -e "SELECT variable_name, variable_value FROM global_variables WHERE variable_name IN ('mysql-max_connections','mysql-threads','admin-restapi_enabled','admin-restapi_port');" -+------------------------+----------------+ -| variable_name | variable_value | -+------------------------+----------------+ -| mysql-max_connections | 2048 | -| mysql-threads | 4 | -| admin-restapi_enabled | true | -| admin-restapi_port | 6070 | -+------------------------+----------------+ ``` -Since `wolverine` and `superman` also exist on the MySQL backend, ProxySQL was able to log in and fetch their passwords automatically - you can verify a client can actually connect through ProxySQL using those credentials without ever having put a password in the YAML. +Since `wolverine` and `superman` also exist on the MySQL backend, ProxySQL was able to log in and fetch their passwords automatically - confirming that a client can connect through ProxySQL using those credentials without a password ever being written into the YAML. ## Cleaning up -To cleanup the Kubernetes resources created by this tutorial, run: +To clean up the Kubernetes resources created by this tutorial, run the following commands: ```bash $ kubectl patch -n demo proxysql/proxy-init-secret -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" From ae4381b3a83779e851e43ba7b7f5e77a8ef072c0 Mon Sep 17 00:00:00 2001 From: Bonusree Date: Tue, 14 Jul 2026 15:11:44 +0600 Subject: [PATCH 09/13] clean the comments Signed-off-by: Bonusree --- .../initialization/examples/proxysql-init-inline.yaml | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml b/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml index 4872d01ef1..a5e5885c82 100644 --- a/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml +++ b/docs/guides/proxysql/initialization/examples/proxysql-init-inline.yaml @@ -11,14 +11,6 @@ spec: configuration: init: inline: - # mysqlUsers: - # - username: wolverine - # active: 1 - # default_hostgroup: 2 - # default_schema: marvel - # - username: superman - # active: 1 - # default_hostgroup: 3 mysqlQueryRules: - rule_id: 1 active: 1 From 22f3dcbdde9e46c0547b81f4c099e108d0730b26 Mon Sep 17 00:00:00 2001 From: souravbiswassanto Date: Wed, 15 Jul 2026 10:29:30 +0600 Subject: [PATCH 10/13] remove ignite update Signed-off-by: souravbiswassanto --- docs/guides/ignite/update-version/overview.md | 54 ---- .../ignite/update-version/update-version.md | 261 ------------------ 2 files changed, 315 deletions(-) delete mode 100644 docs/guides/ignite/update-version/overview.md delete mode 100644 docs/guides/ignite/update-version/update-version.md diff --git a/docs/guides/ignite/update-version/overview.md b/docs/guides/ignite/update-version/overview.md deleted file mode 100644 index 0a3bfd7a84..0000000000 --- a/docs/guides/ignite/update-version/overview.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Updating Ignite Overview -menu: - docs_{{ .version }}: - identifier: ig-update-version-overview - name: Overview - parent: ig-update-version - weight: 10 -menu_name: docs_{{ .version }} -section_menu_id: guides ---- - -> New to KubeDB? Please start [here](/docs/README.md). - -# Overview of Ignite Version Update - -This guide will give you an overview on how KubeDB Ops-manager operator update the version of `Ignite` database. - -## Before You Begin - -- You should be familiar with the following `KubeDB` concepts: - - [Ignite](/docs/guides/ignite/concepts/ignite.md) - - [IgniteOpsRequest](/docs/guides/ignite/concepts/opsrequest.md) - -## How update version Process Works - -The following diagram shows how KubeDB Ops-manager operator used to update the version of `Ignite`. Open the image in a new tab to see the enlarged version. - -
- updating Process of Ignite -
Fig: updating Process of Ignite
-
- -The updating process consists of the following steps: - -1. At first, a user creates an `Ignite` Custom Resource (CR). - -2. `KubeDB` Provisioner operator watches the `Ignite` CR. - -3. When the operator finds an `Ignite` CR, it creates required number of `PetSets` and other kubernetes native resources like secrets, services, etc. - -4. Then, in order to update the version of the `Ignite` database the user creates an `IgniteOpsRequest` CR with the desired version. - -5. `KubeDB` Ops-manager operator watches the `IgniteOpsRequest` CR. - -6. When it finds an `IgniteOpsRequest` CR, it halts the `Ignite` object which is referred from the `IgniteOpsRequest`. So, the `KubeDB` Provisioner operator doesn't perform any operations on the `Ignite` object during the updating process. - -7. By looking at the target version from `IgniteOpsRequest` CR, `KubeDB` Ops-manager operator updates the images of all the `PetSets`. - -8. After successfully updating the `PetSets` and their `Pods` images, the `KubeDB` Ops-manager operator updates the version field of the `Ignite` object to reflect the updated state of the database. - -9. After successfully updating of `Ignite` object, the `KubeDB` Ops-manager operator resumes the `Ignite` object so that the `KubeDB` Provisioner operator can resume its usual operations. - -In the [next](/docs/guides/ignite/update-version/update-version.md) doc, we are going to show a step-by-step guide on updating of an Ignite database using updateVersion operation. diff --git a/docs/guides/ignite/update-version/update-version.md b/docs/guides/ignite/update-version/update-version.md deleted file mode 100644 index 94f987e1c4..0000000000 --- a/docs/guides/ignite/update-version/update-version.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -title: Updating Ignite Cluster -menu: - docs_{{ .version }}: - identifier: ig-cluster-update-version - name: Update Version - parent: ig-update-version - weight: 30 -menu_name: docs_{{ .version }} -section_menu_id: guides ---- - -> New to KubeDB? Please start [here](/docs/README.md). - -# Update Version of Ignite Cluster - -This guide will show you how to use `KubeDB` Ops-manager operator to update the version of `Ignite` Cluster. - -## 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/). - -- Install `KubeDB` Provisioner and Ops-manager operator in your cluster following the steps [here](/docs/setup/README.md). - -- You should be familiar with the following `KubeDB` concepts: - - [Ignite](/docs/guides/ignite/concepts/ignite.md) - - [IgniteOpsRequest](/docs/guides/ignite/concepts/opsrequest.md) - - [Updating Overview](/docs/guides/ignite/update-version/overview.md) - -To keep everything isolated, we are going to use 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 [docs/examples/ignite](/docs/examples/ignite) directory of [kubedb/docs](https://github.com/kubedb/docs) repository. - -## Prepare Ignite Cluster - -Now, we are going to deploy an `Ignite` cluster with version `2.17.0`. - -### Deploy Ignite - -In this section, we are going to deploy an Ignite cluster. Then, in the next section we will update the version of the database using `IgniteOpsRequest` CRD. Below is the YAML of the `Ignite` CR that we are going to create, - -```yaml -apiVersion: kubedb.com/v1alpha2 -kind: Ignite -metadata: - name: ignite-quickstart - namespace: demo -spec: - version: "2.17.0" - replicas: 3 - storage: - resources: - requests: - storage: "1Gi" - storageClassName: "standard" - accessModes: - - ReadWriteOnce - deletionPolicy: "WipeOut" -``` - -Let's create the `Ignite` CR we have shown above, - -```bash -$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/ignite/update-version/ignite.yaml -ignite.kubedb.com/ignite-quickstart created -``` - -Now, wait until `ignite-quickstart` has status `Ready`. i.e, - -```bash -$ kubectl get ignite -n demo -NAME VERSION STATUS AGE -ignite-quickstart 2.17.0 Ready 109s -``` - -We are now ready to apply the `IgniteOpsRequest` CR to update this database. - -### Update Ignite Version - -Here, we are going to update `Ignite` cluster from `2.17.0` to `2.18.0`. - -#### Create IgniteOpsRequest: - -In order to update the version of the cluster, we have to create an `IgniteOpsRequest` CR with your desired version that is supported by `KubeDB`. Below is the YAML of the `IgniteOpsRequest` CR that we are going to create, - -```yaml -apiVersion: ops.kubedb.com/v1alpha1 -kind: IgniteOpsRequest -metadata: - name: upgrade-topology - namespace: demo -spec: - databaseRef: - name: ignite-quickstart - type: UpdateVersion - updateVersion: - targetVersion: 2.18.0 - timeout: 5m - apply: IfReady -``` - -Here, - -- `spec.databaseRef.name` specifies that we are performing operation on `ignite-quickstart` Ignite database. -- `spec.type` specifies that we are going to perform `UpdateVersion` on our database. -- `spec.updateVersion.targetVersion` specifies the expected version of the database `2.18.0`. -- Have a look [here](/docs/guides/ignite/concepts/opsrequest.md#spectimeout) on the respective sections to understand the `readinessCriteria`, `timeout` & `apply` fields. - -Let's create the `IgniteOpsRequest` CR we have shown above, - -```bash -$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/ignite/update-version/ig-version-upgrade-ops.yaml -igniteopsrequest.ops.kubedb.com/upgrade-topology created -``` - -#### Verify Ignite version updated successfully - -If everything goes well, `KubeDB` Ops-manager operator will update the image of `Ignite` object and related `PetSets` and `Pods`. - -Let's wait for `IgniteOpsRequest` to be `Successful`. Run the following command to watch `IgniteOpsRequest` CR, - -```bash -$ kubectl get igniteopsrequest -n demo -Every 2.0s: kubectl get igniteopsrequest -n demo -NAME TYPE STATUS AGE -upgrade-topology UpdateVersion Successful 84s -``` - -We can see from the above output that the `IgniteOpsRequest` has succeeded. If we describe the `IgniteOpsRequest` we will get an overview of the steps that were followed to update the database version. - -```bash -$ kubectl describe igniteopsrequest -n demo upgrade-topology -Name: upgrade-topology -Namespace: demo -Labels: -Annotations: -API Version: ops.kubedb.com/v1alpha1 -Kind: IgniteOpsRequest -Metadata: - Creation Timestamp: 2024-10-23T10:46:27Z - Generation: 1 - Resource Version: 1112190 - UID: 6a1baef3-74cb-4a44-9b8f-f4fa49a4cfca -Spec: - Apply: IfReady - Database Ref: - Name: ignite-quickstart - Timeout: 5m - Type: UpdateVersion - Update Version: - Target Version: 2.18.0 -Status: - Conditions: - Last Transition Time: 2024-10-23T10:46:27Z - Message: Ignite ops-request has started to update version - Observed Generation: 1 - Reason: UpdateVersion - Status: True - Type: UpdateVersion - Last Transition Time: 2024-10-23T10:46:35Z - Message: successfully reconciled the Ignite with updated version - Observed Generation: 1 - Reason: UpdatePetSets - Status: True - Type: UpdatePetSets - Last Transition Time: 2024-10-23T10:49:25Z - Message: Successfully Restarted Ignite nodes - Observed Generation: 1 - Reason: RestartPods - Status: True - Type: RestartPods - Last Transition Time: 2024-10-23T10:46:40Z - Message: get pod; ConditionStatus:True; PodName:ignite-quickstart-0 - Observed Generation: 1 - Status: True - Type: GetPod--ignite-quickstart-0 - Last Transition Time: 2024-10-23T10:46:40Z - Message: evict pod; ConditionStatus:True; PodName:ignite-quickstart-0 - Observed Generation: 1 - Status: True - Type: EvictPod--ignite-quickstart-0 - Last Transition Time: 2024-10-23T10:46:45Z - Message: running pod; ConditionStatus:False - Observed Generation: 1 - Status: False - Type: RunningPod - Last Transition Time: 2024-10-23T10:47:25Z - Message: get pod; ConditionStatus:True; PodName:ignite-quickstart-1 - Observed Generation: 1 - Status: True - Type: GetPod--ignite-quickstart-1 - Last Transition Time: 2024-10-23T10:47:25Z - Message: evict pod; ConditionStatus:True; PodName:ignite-quickstart-1 - Observed Generation: 1 - Status: True - Type: EvictPod--ignite-quickstart-1 - Last Transition Time: 2024-10-23T10:48:05Z - Message: get pod; ConditionStatus:True; PodName:ignite-quickstart-2 - Observed Generation: 1 - Status: True - Type: GetPod--ignite-quickstart-2 - Last Transition Time: 2024-10-23T10:48:05Z - Message: evict pod; ConditionStatus:True; PodName:ignite-quickstart-2 - Observed Generation: 1 - Status: True - Type: EvictPod--ignite-quickstart-2 - Last Transition Time: 2024-10-23T10:49:25Z - Message: Successfully updated Ignite version - Observed Generation: 1 - Reason: Successful - Status: True - Type: Successful - Observed Generation: 1 - Phase: Successful -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Starting 10m KubeDB Ops-manager Operator Start processing for IgniteOpsRequest: demo/upgrade-topology - Normal Starting 10m KubeDB Ops-manager Operator Pausing Ignite database: demo/ignite-quickstart - Normal Successful 10m KubeDB Ops-manager Operator Successfully paused Ignite database: demo/ignite-quickstart for IgniteOpsRequest: upgrade-topology - Normal UpdatePetSets 10m KubeDB Ops-manager Operator successfully reconciled the Ignite with updated version - Warning get pod; ConditionStatus:True; PodName:ignite-quickstart-0 10m KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:ignite-quickstart-0 - Warning evict pod; ConditionStatus:True; PodName:ignite-quickstart-0 10m KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:ignite-quickstart-0 - Warning running pod; ConditionStatus:False 10m KubeDB Ops-manager Operator running pod; ConditionStatus:False - Warning get pod; ConditionStatus:True; PodName:ignite-quickstart-1 9m25s KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:ignite-quickstart-1 - Warning evict pod; ConditionStatus:True; PodName:ignite-quickstart-1 9m25s KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:ignite-quickstart-1 - Warning get pod; ConditionStatus:True; PodName:ignite-quickstart-2 8m45s KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:ignite-quickstart-2 - Warning evict pod; ConditionStatus:True; PodName:ignite-quickstart-2 8m45s KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:ignite-quickstart-2 - Normal RestartPods 7m25s KubeDB Ops-manager Operator Successfully Restarted Ignite nodes - Normal Starting 7m25s KubeDB Ops-manager Operator Resuming Ignite database: demo/ignite-quickstart - Normal Successful 7m25s KubeDB Ops-manager Operator Successfully updated Ignite version -``` - -Now, we are going to verify whether the `Ignite` and the related `PetSets` and their `Pods` have the new version image. Let's check, - -```bash -$ kubectl get ignite -n demo ignite-quickstart -o=jsonpath='{.spec.version}{"\n"}' -2.18.0 - -$ kubectl get petset -n demo ignite-quickstart -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}' -ghcr.io/appscode-images/ignite:2.18.0 - -$ kubectl get pods -n demo ignite-quickstart-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}' -ghcr.io/appscode-images/ignite:2.18.0 -``` - -You can see from above, our `Ignite` cluster has been updated with the new version. So, the updateVersion process is successfully completed. - -## Cleaning Up - -To clean up the Kubernetes resources created by this tutorial, run: - -```bash -kubectl delete ignite -n demo ignite-quickstart -kubectl delete igniteopsrequest -n demo upgrade-topology -``` From d42b2aaaaa6a7fe11db4a55c2bde958648f98ee7 Mon Sep 17 00:00:00 2001 From: souravbiswassanto Date: Wed, 15 Jul 2026 10:32:04 +0600 Subject: [PATCH 11/13] Revert "remove ignite update" This reverts commit 22f3dcbdde9e46c0547b81f4c099e108d0730b26. --- docs/guides/ignite/update-version/overview.md | 54 ++++ .../ignite/update-version/update-version.md | 261 ++++++++++++++++++ 2 files changed, 315 insertions(+) create mode 100644 docs/guides/ignite/update-version/overview.md create mode 100644 docs/guides/ignite/update-version/update-version.md diff --git a/docs/guides/ignite/update-version/overview.md b/docs/guides/ignite/update-version/overview.md new file mode 100644 index 0000000000..0a3bfd7a84 --- /dev/null +++ b/docs/guides/ignite/update-version/overview.md @@ -0,0 +1,54 @@ +--- +title: Updating Ignite Overview +menu: + docs_{{ .version }}: + identifier: ig-update-version-overview + name: Overview + parent: ig-update-version + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Overview of Ignite Version Update + +This guide will give you an overview on how KubeDB Ops-manager operator update the version of `Ignite` database. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Ignite](/docs/guides/ignite/concepts/ignite.md) + - [IgniteOpsRequest](/docs/guides/ignite/concepts/opsrequest.md) + +## How update version Process Works + +The following diagram shows how KubeDB Ops-manager operator used to update the version of `Ignite`. Open the image in a new tab to see the enlarged version. + +
+ updating Process of Ignite +
Fig: updating Process of Ignite
+
+ +The updating process consists of the following steps: + +1. At first, a user creates an `Ignite` Custom Resource (CR). + +2. `KubeDB` Provisioner operator watches the `Ignite` CR. + +3. When the operator finds an `Ignite` CR, it creates required number of `PetSets` and other kubernetes native resources like secrets, services, etc. + +4. Then, in order to update the version of the `Ignite` database the user creates an `IgniteOpsRequest` CR with the desired version. + +5. `KubeDB` Ops-manager operator watches the `IgniteOpsRequest` CR. + +6. When it finds an `IgniteOpsRequest` CR, it halts the `Ignite` object which is referred from the `IgniteOpsRequest`. So, the `KubeDB` Provisioner operator doesn't perform any operations on the `Ignite` object during the updating process. + +7. By looking at the target version from `IgniteOpsRequest` CR, `KubeDB` Ops-manager operator updates the images of all the `PetSets`. + +8. After successfully updating the `PetSets` and their `Pods` images, the `KubeDB` Ops-manager operator updates the version field of the `Ignite` object to reflect the updated state of the database. + +9. After successfully updating of `Ignite` object, the `KubeDB` Ops-manager operator resumes the `Ignite` object so that the `KubeDB` Provisioner operator can resume its usual operations. + +In the [next](/docs/guides/ignite/update-version/update-version.md) doc, we are going to show a step-by-step guide on updating of an Ignite database using updateVersion operation. diff --git a/docs/guides/ignite/update-version/update-version.md b/docs/guides/ignite/update-version/update-version.md new file mode 100644 index 0000000000..94f987e1c4 --- /dev/null +++ b/docs/guides/ignite/update-version/update-version.md @@ -0,0 +1,261 @@ +--- +title: Updating Ignite Cluster +menu: + docs_{{ .version }}: + identifier: ig-cluster-update-version + name: Update Version + parent: ig-update-version + weight: 30 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Update Version of Ignite Cluster + +This guide will show you how to use `KubeDB` Ops-manager operator to update the version of `Ignite` Cluster. + +## 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/). + +- Install `KubeDB` Provisioner and Ops-manager operator in your cluster following the steps [here](/docs/setup/README.md). + +- You should be familiar with the following `KubeDB` concepts: + - [Ignite](/docs/guides/ignite/concepts/ignite.md) + - [IgniteOpsRequest](/docs/guides/ignite/concepts/opsrequest.md) + - [Updating Overview](/docs/guides/ignite/update-version/overview.md) + +To keep everything isolated, we are going to use 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 [docs/examples/ignite](/docs/examples/ignite) directory of [kubedb/docs](https://github.com/kubedb/docs) repository. + +## Prepare Ignite Cluster + +Now, we are going to deploy an `Ignite` cluster with version `2.17.0`. + +### Deploy Ignite + +In this section, we are going to deploy an Ignite cluster. Then, in the next section we will update the version of the database using `IgniteOpsRequest` CRD. Below is the YAML of the `Ignite` CR that we are going to create, + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Ignite +metadata: + name: ignite-quickstart + namespace: demo +spec: + version: "2.17.0" + replicas: 3 + storage: + resources: + requests: + storage: "1Gi" + storageClassName: "standard" + accessModes: + - ReadWriteOnce + deletionPolicy: "WipeOut" +``` + +Let's create the `Ignite` CR we have shown above, + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/ignite/update-version/ignite.yaml +ignite.kubedb.com/ignite-quickstart created +``` + +Now, wait until `ignite-quickstart` has status `Ready`. i.e, + +```bash +$ kubectl get ignite -n demo +NAME VERSION STATUS AGE +ignite-quickstart 2.17.0 Ready 109s +``` + +We are now ready to apply the `IgniteOpsRequest` CR to update this database. + +### Update Ignite Version + +Here, we are going to update `Ignite` cluster from `2.17.0` to `2.18.0`. + +#### Create IgniteOpsRequest: + +In order to update the version of the cluster, we have to create an `IgniteOpsRequest` CR with your desired version that is supported by `KubeDB`. Below is the YAML of the `IgniteOpsRequest` CR that we are going to create, + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: IgniteOpsRequest +metadata: + name: upgrade-topology + namespace: demo +spec: + databaseRef: + name: ignite-quickstart + type: UpdateVersion + updateVersion: + targetVersion: 2.18.0 + timeout: 5m + apply: IfReady +``` + +Here, + +- `spec.databaseRef.name` specifies that we are performing operation on `ignite-quickstart` Ignite database. +- `spec.type` specifies that we are going to perform `UpdateVersion` on our database. +- `spec.updateVersion.targetVersion` specifies the expected version of the database `2.18.0`. +- Have a look [here](/docs/guides/ignite/concepts/opsrequest.md#spectimeout) on the respective sections to understand the `readinessCriteria`, `timeout` & `apply` fields. + +Let's create the `IgniteOpsRequest` CR we have shown above, + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/ignite/update-version/ig-version-upgrade-ops.yaml +igniteopsrequest.ops.kubedb.com/upgrade-topology created +``` + +#### Verify Ignite version updated successfully + +If everything goes well, `KubeDB` Ops-manager operator will update the image of `Ignite` object and related `PetSets` and `Pods`. + +Let's wait for `IgniteOpsRequest` to be `Successful`. Run the following command to watch `IgniteOpsRequest` CR, + +```bash +$ kubectl get igniteopsrequest -n demo +Every 2.0s: kubectl get igniteopsrequest -n demo +NAME TYPE STATUS AGE +upgrade-topology UpdateVersion Successful 84s +``` + +We can see from the above output that the `IgniteOpsRequest` has succeeded. If we describe the `IgniteOpsRequest` we will get an overview of the steps that were followed to update the database version. + +```bash +$ kubectl describe igniteopsrequest -n demo upgrade-topology +Name: upgrade-topology +Namespace: demo +Labels: +Annotations: +API Version: ops.kubedb.com/v1alpha1 +Kind: IgniteOpsRequest +Metadata: + Creation Timestamp: 2024-10-23T10:46:27Z + Generation: 1 + Resource Version: 1112190 + UID: 6a1baef3-74cb-4a44-9b8f-f4fa49a4cfca +Spec: + Apply: IfReady + Database Ref: + Name: ignite-quickstart + Timeout: 5m + Type: UpdateVersion + Update Version: + Target Version: 2.18.0 +Status: + Conditions: + Last Transition Time: 2024-10-23T10:46:27Z + Message: Ignite ops-request has started to update version + Observed Generation: 1 + Reason: UpdateVersion + Status: True + Type: UpdateVersion + Last Transition Time: 2024-10-23T10:46:35Z + Message: successfully reconciled the Ignite with updated version + Observed Generation: 1 + Reason: UpdatePetSets + Status: True + Type: UpdatePetSets + Last Transition Time: 2024-10-23T10:49:25Z + Message: Successfully Restarted Ignite nodes + Observed Generation: 1 + Reason: RestartPods + Status: True + Type: RestartPods + Last Transition Time: 2024-10-23T10:46:40Z + Message: get pod; ConditionStatus:True; PodName:ignite-quickstart-0 + Observed Generation: 1 + Status: True + Type: GetPod--ignite-quickstart-0 + Last Transition Time: 2024-10-23T10:46:40Z + Message: evict pod; ConditionStatus:True; PodName:ignite-quickstart-0 + Observed Generation: 1 + Status: True + Type: EvictPod--ignite-quickstart-0 + Last Transition Time: 2024-10-23T10:46:45Z + Message: running pod; ConditionStatus:False + Observed Generation: 1 + Status: False + Type: RunningPod + Last Transition Time: 2024-10-23T10:47:25Z + Message: get pod; ConditionStatus:True; PodName:ignite-quickstart-1 + Observed Generation: 1 + Status: True + Type: GetPod--ignite-quickstart-1 + Last Transition Time: 2024-10-23T10:47:25Z + Message: evict pod; ConditionStatus:True; PodName:ignite-quickstart-1 + Observed Generation: 1 + Status: True + Type: EvictPod--ignite-quickstart-1 + Last Transition Time: 2024-10-23T10:48:05Z + Message: get pod; ConditionStatus:True; PodName:ignite-quickstart-2 + Observed Generation: 1 + Status: True + Type: GetPod--ignite-quickstart-2 + Last Transition Time: 2024-10-23T10:48:05Z + Message: evict pod; ConditionStatus:True; PodName:ignite-quickstart-2 + Observed Generation: 1 + Status: True + Type: EvictPod--ignite-quickstart-2 + Last Transition Time: 2024-10-23T10:49:25Z + Message: Successfully updated Ignite version + Observed Generation: 1 + Reason: Successful + Status: True + Type: Successful + Observed Generation: 1 + Phase: Successful +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Starting 10m KubeDB Ops-manager Operator Start processing for IgniteOpsRequest: demo/upgrade-topology + Normal Starting 10m KubeDB Ops-manager Operator Pausing Ignite database: demo/ignite-quickstart + Normal Successful 10m KubeDB Ops-manager Operator Successfully paused Ignite database: demo/ignite-quickstart for IgniteOpsRequest: upgrade-topology + Normal UpdatePetSets 10m KubeDB Ops-manager Operator successfully reconciled the Ignite with updated version + Warning get pod; ConditionStatus:True; PodName:ignite-quickstart-0 10m KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:ignite-quickstart-0 + Warning evict pod; ConditionStatus:True; PodName:ignite-quickstart-0 10m KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:ignite-quickstart-0 + Warning running pod; ConditionStatus:False 10m KubeDB Ops-manager Operator running pod; ConditionStatus:False + Warning get pod; ConditionStatus:True; PodName:ignite-quickstart-1 9m25s KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:ignite-quickstart-1 + Warning evict pod; ConditionStatus:True; PodName:ignite-quickstart-1 9m25s KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:ignite-quickstart-1 + Warning get pod; ConditionStatus:True; PodName:ignite-quickstart-2 8m45s KubeDB Ops-manager Operator get pod; ConditionStatus:True; PodName:ignite-quickstart-2 + Warning evict pod; ConditionStatus:True; PodName:ignite-quickstart-2 8m45s KubeDB Ops-manager Operator evict pod; ConditionStatus:True; PodName:ignite-quickstart-2 + Normal RestartPods 7m25s KubeDB Ops-manager Operator Successfully Restarted Ignite nodes + Normal Starting 7m25s KubeDB Ops-manager Operator Resuming Ignite database: demo/ignite-quickstart + Normal Successful 7m25s KubeDB Ops-manager Operator Successfully updated Ignite version +``` + +Now, we are going to verify whether the `Ignite` and the related `PetSets` and their `Pods` have the new version image. Let's check, + +```bash +$ kubectl get ignite -n demo ignite-quickstart -o=jsonpath='{.spec.version}{"\n"}' +2.18.0 + +$ kubectl get petset -n demo ignite-quickstart -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/ignite:2.18.0 + +$ kubectl get pods -n demo ignite-quickstart-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/ignite:2.18.0 +``` + +You can see from above, our `Ignite` cluster has been updated with the new version. So, the updateVersion process is successfully completed. + +## Cleaning Up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete ignite -n demo ignite-quickstart +kubectl delete igniteopsrequest -n demo upgrade-topology +``` From b1cb9fafed9083a4706321908b93b5169b93a572 Mon Sep 17 00:00:00 2001 From: souravbiswassanto Date: Wed, 15 Jul 2026 10:33:33 +0600 Subject: [PATCH 12/13] add index Signed-off-by: souravbiswassanto --- docs/guides/ignite/update-version/_index.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 docs/guides/ignite/update-version/_index.md diff --git a/docs/guides/ignite/update-version/_index.md b/docs/guides/ignite/update-version/_index.md new file mode 100644 index 0000000000..3bddf00de0 --- /dev/null +++ b/docs/guides/ignite/update-version/_index.md @@ -0,0 +1,10 @@ +--- +title: Updating Ignite +menu: + docs_{{ .version }}: + identifier: ig-update-version + name: Update Version + parent: ignite-guides + weight: 50 +menu_name: docs_{{ .version }} +--- From 296c18bcc26c39fb7bb990da4c7e198581263e8a Mon Sep 17 00:00:00 2001 From: Bonusree Date: Wed, 15 Jul 2026 10:55:33 +0600 Subject: [PATCH 13/13] delete rabbitmq Signed-off-by: Bonusree --- docs/guides/rabbitmq/initialization/_index.md | 11 -- .../rabbitmq/initialization/script_source.md | 173 ------------------ 2 files changed, 184 deletions(-) delete mode 100644 docs/guides/rabbitmq/initialization/_index.md delete mode 100644 docs/guides/rabbitmq/initialization/script_source.md diff --git a/docs/guides/rabbitmq/initialization/_index.md b/docs/guides/rabbitmq/initialization/_index.md deleted file mode 100644 index e81ed5c7fd..0000000000 --- a/docs/guides/rabbitmq/initialization/_index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: RabbitMQ Initialization -menu: - docs_{{ .version }}: - identifier: rm-initialization-rabbitmq - name: Initialization - parent: rm-guides - weight: 30 -menu_name: docs_{{ .version }} -section_menu_id: guides ---- diff --git a/docs/guides/rabbitmq/initialization/script_source.md b/docs/guides/rabbitmq/initialization/script_source.md deleted file mode 100644 index e96f50e145..0000000000 --- a/docs/guides/rabbitmq/initialization/script_source.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: Initialize RabbitMQ using Script Source -menu: - docs_{{ .version }}: - identifier: rm-script-source-initialization - name: Using Script - parent: rm-initialization-rabbitmq - weight: 10 -menu_name: docs_{{ .version }} -section_menu_id: guides ---- - -> New to KubeDB? Please start [here](/docs/README.md). - -# Initialize RabbitMQ with Script - -KubeDB supports RabbitMQ initialization using definitions files. This tutorial will show you how to use KubeDB to initialize a RabbitMQ broker from a definitions script stored in a ConfigMap. - -RabbitMQ supports importing a [definitions file](https://www.rabbitmq.com/docs/definitions) (JSON format) at startup to pre-configure virtual hosts, exchanges, queues, bindings, users, and policies. - -## 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 - -$ kubectl get ns demo -NAME STATUS AGE -demo Active 5s -``` - -> Note: YAML files used in this tutorial are stored in [docs/examples/rabbitmq](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/rabbitmq) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). - -## Prepare Initialization Scripts - -RabbitMQ supports initialization with a JSON definitions file. In this tutorial, we will use a `definitions.json` file to pre-create a virtual host `app-vhost`, an exchange `app-exchange`, a queue `app-queue`, and a binding between them. - -We will use a ConfigMap as the script source. You can use any Kubernetes supported [volume](https://kubernetes.io/docs/concepts/storage/volumes) as a script source. - -Let's create a ConfigMap with the initialization definitions file: - -```bash -$ kubectl create configmap -n demo rmq-init-script \ ---from-literal=definitions.json="$(curl -fsSL https://raw.githubusercontent.com/kubedb/rabbitmq-init-scripts/master/definitions.json)" -configmap/rmq-init-script created -``` - -## Create RabbitMQ with Script Source - -Following YAML describes the RabbitMQ object with `init.script`: - -```yaml -apiVersion: kubedb.com/v1alpha2 -kind: RabbitMQ -metadata: - name: script-rabbitmq - namespace: demo -spec: - version: "3.13.2" - replicas: 1 - storage: - storageClassName: "standard" - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi - init: - script: - configMap: - name: rmq-init-script - deletionPolicy: WipeOut -``` - -Here, - -- `init.script` specifies the definitions file used to initialize the broker when it is being created. RabbitMQ loads the definitions from the ConfigMap volume at startup. - -VolumeSource provided in `init.script` will be mounted in the Pod. RabbitMQ will automatically load the `definitions.json` file from the mounted path. - -Now, let's create the RabbitMQ CRD using the YAML shown above: - -```bash -$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/rabbitmq/initialization/script-rabbitmq.yaml -rabbitmq.kubedb.com/script-rabbitmq created -``` - -Now, wait until RabbitMQ goes in `Ready` state. Verify that the broker is in `Ready` state using the following command: - -```bash -$ kubectl get rabbitmq -n demo script-rabbitmq -NAME VERSION STATUS AGE -script-rabbitmq 3.13.2 Ready 2m -``` - -## Verify Initialization - -Now let's connect to our RabbitMQ instance to verify that the broker has been initialized successfully. - -**Connection Information:** - -- Host name/address: you can use any of these - - Service: `script-rabbitmq.demo` - - Pod IP: (`$ kubectl get pods script-rabbitmq-0 -n demo -o yaml | grep podIP`) -- Port: `5672` (AMQP) or `15672` (Management UI) - -- Username: Run the following command to get the *username*: - - ```bash - $ kubectl get secret -n demo script-rabbitmq-auth -o jsonpath='{.data.username}' | base64 -d - admin - ``` - -- Password: Run the following command to get the *password*: - - ```bash - $ kubectl get secret -n demo script-rabbitmq-auth -o jsonpath='{.data.password}' | base64 -d - S3cur3P@ssw0rd - ``` - -You can verify the initialization using the RabbitMQ management CLI inside the Pod: - -```bash -$ kubectl exec -it -n demo script-rabbitmq-0 -- rabbitmqctl list_vhosts -Listing vhosts ... -name -/ -app-vhost -``` - -```bash -$ kubectl exec -it -n demo script-rabbitmq-0 -- rabbitmqctl list_exchanges --vhost app-vhost name type -Listing exchanges for vhost app-vhost ... -name type - direct -amq.direct direct -amq.fanout fanout -amq.headers headers -amq.match headers -amq.rabbitmq.trace topic -amq.topic topic -app-exchange direct -``` - -```bash -$ kubectl exec -it -n demo script-rabbitmq-0 -- rabbitmqctl list_queues --vhost app-vhost name -Listing queues for vhost app-vhost ... -name -app-queue -``` - -We can see that `app-vhost`, `app-exchange`, and `app-queue` were created through the initialization definitions file. - -## Cleaning up - -To cleanup the Kubernetes resources created by this tutorial, run: - -```bash -$ kubectl delete -n demo rabbitmq/script-rabbitmq -$ kubectl delete -n demo configmap/rmq-init-script -$ kubectl delete ns demo -``` - -## Next Steps - -- Learn about [backup and restore](/docs/guides/rabbitmq/backup/overview/index.md) RabbitMQ using Stash. -- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md).