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..303fa1cb17 --- /dev/null +++ b/docs/guides/percona-xtradb/initialization/script_source.md @@ -0,0 +1,362 @@ +--- +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 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 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 + +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 + 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='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. + +## 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 + +- 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..d47c0c16fc --- /dev/null +++ b/docs/guides/pgbouncer/initialization/script_source.md @@ -0,0 +1,169 @@ +--- +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 +``` +> **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`: + +```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 +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. + +## 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..356a137ace --- /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)" #here will be your script path +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).