Add Pgpool quickstart (#636)

* Add Pgpool Quickstart

Signed-off-by: MobarakHsn <[email protected]>

docs/examples/pgpool/quickstart/quick-pgpool.yaml

@@ -0,0 +1,15 @@
+apiVersion: kubedb.com/v1alpha2
+kind: Pgpool
+metadata:
+  name: quick-pgpool
+  namespace: pool
+spec:
+  version: "4.5.0"
+  replicas: 1
+  postgresRef:
+    name: quick-postgres
+    namespace: demo
+  sslMode: disable
+  clientAuthMode: md5
+  syncUsers: true
+  terminationPolicy: WipeOut

docs/examples/pgpool/quickstart/quick-postgres.yaml

@@ -0,0 +1,19 @@
+apiVersion: kubedb.com/v1alpha2
+kind: Postgres
+metadata:
+  name: quick-postgres
+  namespace: demo
+spec:
+  replicas: 3
+  version: "13.13"
+  configSecret:
+    name: pg-configuration
+  storageType: Durable
+  storage:
+    storageClassName: "standard"
+    accessModes:
+      - ReadWriteOnce
+    resources:
+      requests:
+        storage: 50Mi
+  terminationPolicy: WipeOut

docs/examples/pgpool/quickstart/user.conf

@@ -0,0 +1 @@
+max_connections=400

docs/guides/README.md

@@ -24,6 +24,7 @@ Guides to show you how to perform tasks with KubeDB:
 - [MySQL](/docs/guides/mysql/README.md). Shows how to manage MySQL using KubeDB.
 - [Percona XtraDB](/docs/guides/percona-xtradb/README.md). Shows how to manage Percona XtraDB using KubeDB.
 - [PgBouncer](/docs/guides/pgbouncer/README.md). Shows how to manage PgBouncer using KubeDB.
+- [Pgpool](/docs/guides/pgpool/README.md). Shows how to manage Pgpool using KubeDB.
 - [PostgreSQL](/docs/guides/postgres/README.md). Shows how to manage PostgreSQL using KubeDB.
 - [ProxySQL](/docs/guides/proxysql/README.md). Shows how to manage ProxySQL using KubeDB.
 - [Redis](/docs/guides/redis/README.md). Shows how to manage Redis using KubeDB.

docs/guides/druid/quickstart/overview/index.md

@@ -24,7 +24,7 @@ This tutorial will show you how to use KubeDB to run an [Apache Druid](https://d
 
 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) and make sure install with helm command including the flags `--set global.featureGates.Druid=true` to ensure **Druid CRD** and `--set global.featureGates.Zookeeper=true` to ensure **ZooKeeper CRD** as Druid depends on ZooKeeper for external dependency.
+Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md) and make sure install with helm command including the flags `--set global.featureGates.Druid=true` to ensure **Druid CRD** and `--set global.featureGates.ZooKeeper=true` to ensure **ZooKeeper CRD** as Druid depends on ZooKeeper for external dependency.
 
 To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial.
 

docs/guides/pgbouncer/custom-versions/setup.md

@@ -6,7 +6,7 @@ menu:
     name: Overview
     parent: pb-custom-versions-pgbouncer
     weight: 10
-menu_name: docs_{{ .version }}s
+menu_name: docs_{{ .version }}
 section_menu_id: guides
 ---
 

docs/guides/pgpool/README.md

@@ -0,0 +1,61 @@
+---
+title: Pgpool
+menu:
+  docs_{{ .version }}:
+    identifier: pp-readme-pgpool
+    name: Pgpool
+    parent: pp-pgpool-guides
+    weight: 10
+menu_name: docs_{{ .version }}
+section_menu_id: guides
+url: /docs/{{ .version }}/guides/pgpool/
+aliases:
+  - /docs/{{ .version }}/guides/pgpool/README/
+---
+
+> New to KubeDB? Please start [here](/docs/README.md).
+
+# Overview
+
+[Pgpool](https://pgpool.net/) is a versatile proxy solution positioned between PostgreSQL servers and database clients. It offers essential functionalities such as Connection Pooling, Load Balancing, In-Memory Query Cache and many more. Pgpool enhances the performance, scalability, and reliability of PostgreSQL database systems.
+
+KubeDB operator now comes bundled with Pgpool crd to manage all the essential features of Pgpool. 
+
+## Supported Pgpool Features
+
+| Features                                                    | Availability |
+|-------------------------------------------------------------| :----------: |
+| Clustering                                                  |   ✓   |
+| Multiple Pgpool Versions                                    |   ✓   |
+| Custom Configuration                                        |   ✓   |
+| Externally manageable Auth Secret                           |   ✓   |
+| Reconfigurable Health Checker                               |   ✓   |
+| Integrate with externally managed PostgreSQL                |   ✓   |
+| Sync Postgres Users to Pgpool                               |   ✓   |
+| Custom docker images                                        |   ✓   |
+| TLS: Add ( [Cert Manager]((https://cert-manager.io/docs/))) |   ✓   |
+| Monitoring with Prometheus & Grafana                        |   ✓   |
+| Builtin Prometheus Discovery                                |   ✓   |
+| Using Prometheus operator                                   |   ✓   |
+| Alert Dashboard                                             |   ✓   |
+| Grafana Dashboard                                           |   ✓   |
+
+## Supported Pgpool Versions
+
+KubeDB supports the following Pgpool versions:
+- `4.4.5`
+- `4.5.0`
+
+> The listed PgpoolVersions are tested and provided as a part of the installation process (ie. catalog chart), but you are open to create your own [PgpoolVersion](/docs/guides/pgpool/concepts/catalog.md) object with your custom pgpool image.
+
+## Lifecycle of Pgpool Object
+
+<p align="center">
+  <img alt="lifecycle"  src="/docs/images/pgpool/quickstart/lifecycle.png">
+</p>
+
+## User Guide
+
+- [Quickstart Pgpool](/docs/guides/pgpool/quickstart/quickstart.md) with KubeDB Operator.
+- Detail concepts of [Pgpool object](/docs/guides/pgpool/concepts/pgpool.md).
+- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md).

docs/guides/pgpool/_index.md

@@ -0,0 +1,10 @@
+---
+title: Pgpool
+menu:
+  docs_{{ .version }}:
+    identifier: pp-pgpool-guides
+    name: Pgpool
+    parent: guides
+    weight: 10
+menu_name: docs_{{ .version }}
+---

docs/guides/pgpool/concepts/_index.md

@@ -0,0 +1,10 @@
+---
+title: Pgpool Concepts
+menu:
+  docs_{{ .version }}:
+    identifier: pp-concepts-pgpool
+    name: Concepts
+    parent: pp-pgpool-guides
+    weight: 20
+menu_name: docs_{{ .version }}
+---

docs/guides/pgpool/concepts/appbinding.md

@@ -0,0 +1,147 @@
+---
+title: AppBinding CRD
+menu:
+  docs_{{ .version }}:
+    identifier: pp-appbinding-concepts
+    name: AppBinding
+    parent: pp-concepts-pgpool
+    weight: 20
+menu_name: docs_{{ .version }}
+section_menu_id: guides
+---
+
+> New to KubeDB? Please start [here](/docs/README.md).
+
+# AppBinding
+
+## What is AppBinding
+
+An `AppBinding` is a Kubernetes `CustomResourceDefinition`(CRD) which points to an application using either its URL (usually for a non-Kubernetes resident service instance) or a Kubernetes service object (if self-hosted in a Kubernetes cluster), some optional parameters and a credential secret. To learn more about AppBinding and the problems it solves, please read this blog post: [The case for AppBinding](https://appscode.com/blog/post/the-case-for-appbinding).
+
+If you deploy a database using [KubeDB](https://kubedb.com/docs/0.11.0/concepts/), `AppBinding` object will be created automatically for it. Otherwise, you have to create an `AppBinding` object manually pointing to your desired database.
+
+KubeDB uses [Stash](https://appscode.com/products/stash/) to perform backup/recovery of databases. Stash needs to know how to connect with a target database and the credentials necessary to access it. This is done via an `AppBinding`.
+
+## AppBinding CRD Specification
+
+Like any official Kubernetes resource, an `AppBinding` has `TypeMeta`, `ObjectMeta` and `Spec` sections. However, unlike other Kubernetes resources, it does not have a `Status` section.
+
+An `AppBinding` object created by `KubeDB` for PostgreSQL database is shown below,
+
+```yaml
+apiVersion: appcatalog.appscode.com/v1alpha1
+kind: AppBinding
+metadata:
+  labels:
+    app.kubernetes.io/component: database
+    app.kubernetes.io/instance: quick-postgres
+    app.kubernetes.io/managed-by: kubedb.com
+    app.kubernetes.io/name: postgreses.kubedb.com
+  name: quick-postgres
+  namespace: demo
+spec:
+  appRef:
+    apiGroup: kubedb.com
+    kind: Postgres
+    name: quick-postgres
+    namespace: demo
+  clientConfig:
+    service:
+      name: quick-postgres
+      path: /
+      port: 5432
+      query: sslmode=disable
+      scheme: postgresql
+  secret:
+    name: quick-postgres-auth
+  type: kubedb.com/postgres
+  version: "13.13"
+```
+
+Here, we are going to describe the sections of an `AppBinding` crd.
+
+### AppBinding `Spec`
+
+An `AppBinding` object has the following fields in the `spec` section:
+
+#### spec.type
+
+`spec.type` is an optional field that indicates the type of the app that this `AppBinding` is pointing to. Stash uses this field to resolve the values of `TARGET_APP_TYPE`, `TARGET_APP_GROUP` and `TARGET_APP_RESOURCE` variables of [BackupBlueprint](https://appscode.com/products/stash/latest/concepts/crds/backupblueprint/) object.
+
+This field follows the following format: `<app group>/<resource kind>`. The above AppBinding is pointing to a `postgres` resource under `kubedb.com` group.
+
+Here, the variables are parsed as follows:
+
+|       Variable        |                                                               Usage                                                               |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `TARGET_APP_GROUP`    | Represents the application group where the respective app belongs (i.e: `kubedb.com`).                                            |
+| `TARGET_APP_RESOURCE` | Represents the resource under that application group that this appbinding represents (i.e: `postgres`).                           |
+| `TARGET_APP_TYPE`     | Represents the complete type of the application. It's simply `TARGET_APP_GROUP/TARGET_APP_RESOURCE` (i.e: `kubedb.com/postgres`). |
+
+#### spec.secret
+
+`spec.secret` specifies the name of the secret which contains the credentials that are required to access the database. This secret must be in the same namespace as the `AppBinding`.
+
+This secret must contain the following keys:
+
+PostgreSQL :
+
+| Key        | Usage                                          |
+|------------|------------------------------------------------|
+| `username` | Username of the target database.               |
+| `password` | Password for the user specified by `username`. |
+
+MySQL :
+
+| Key        | Usage                                          |
+| ---------- | ---------------------------------------------- |
+| `username` | Username of the target database.               |
+| `password` | Password for the user specified by `username`. |
+
+MongoDB :
+
+| Key        | Usage                                          |
+| ---------- | ---------------------------------------------- |
+| `username` | Username of the target database.               |
+| `password` | Password for the user specified by `username`. |
+
+Elasticsearch:
+
+|       Key        |          Usage          |
+| ---------------- | ----------------------- |
+| `ADMIN_USERNAME` | Admin username          |
+| `ADMIN_PASSWORD` | Password for admin user |
+
+#### spec.clientConfig
+
+`spec.clientConfig` defines how to communicate with the target database. You can use either an URL or a Kubernetes service to connect with the database. You don't have to specify both of them.
+
+You can configure following fields in `spec.clientConfig` section:
+
+- **spec.clientConfig.url**
+
+  `spec.clientConfig.url` gives the location of the database, in standard URL form (i.e. `[scheme://]host:port/[path]`). This is particularly useful when the target database is running outside of the Kubernetes cluster. If your database is running inside the cluster, use `spec.clientConfig.service` section instead.
+
+
+> Note that, attempting to use a user or basic auth (e.g. `user:password@host:port`) is not allowed. Stash will insert them automatically from the respective secret. Fragments ("#...") and query parameters ("?...") are not allowed either.
+
+- **spec.clientConfig.service**
+
+  If you are running the database inside the Kubernetes cluster, you can use Kubernetes service to connect with the database. You have to specify the following fields in `spec.clientConfig.service` section if you manually create an `AppBinding` object.
+
+  - **name :** `name` indicates the name of the service that connects with the target database.
+  - **scheme :** `scheme` specifies the scheme (i.e. http, https) to use to connect with the database.
+  - **port :** `port` specifies the port where the target database is running.
+
+- **spec.clientConfig.insecureSkipTLSVerify**
+
+  `spec.clientConfig.insecureSkipTLSVerify` is used to disable TLS certificate verification while connecting with the database. We strongly discourage to disable TLS verification during backup. You should provide the respective CA bundle through `spec.clientConfig.caBundle` field instead.
+
+- **spec.clientConfig.caBundle**
+
+  `spec.clientConfig.caBundle` is a PEM encoded CA bundle which will be used to validate the serving certificate of the database.
+
+## Next Steps
+
+- Learn how to use KubeDB to manage various databases [here](/docs/guides/README.md).
+- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md).

docs/guides/pgpool/concepts/catalog.md

@@ -0,0 +1,74 @@
+---
+title: PgpoolVersion CRD
+menu:
+  docs_{{ .version }}:
+    identifier: pp-catalog-concepts
+    name: PgpoolVersion
+    parent: pp-concepts-pgpool
+    weight: 15
+menu_name: docs_{{ .version }}
+section_menu_id: guides
+---
+
+> New to KubeDB? Please start [here](/docs/README.md).
+
+# PgpoolVersion
+
+## What is PgpoolVersion
+
+`PgpoolVersion` is a Kubernetes `Custom Resource Definitions` (CRD). It provides a declarative configuration to specify the docker images to be used for [Pgpool](https://pgpool.net/) server deployed with KubeDB in a Kubernetes native way.
+
+When you install KubeDB, a `PgpoolVersion` custom resource will be created automatically for every supported Pgpool release versions. You have to specify the name of `PgpoolVersion` crd in `spec.version` field of [Pgpool](/docs/guides/pgpool/concepts/pgpool.md) crd. Then, KubeDB will use the docker images specified in the `PgpoolVersion` crd to create your expected Pgpool instance.
+
+Using a separate crd for specifying respective docker image names allow us to modify the images independent of KubeDB operator. This will also allow the users to use a custom Pgpool image for their server. For more details about how to use custom image with Pgpool in KubeDB, please visit [here](/docs/guides/pgpool/custom-versions/setup.md).
+
+## PgpoolVersion Specification
+
+As with all other Kubernetes objects, a PgpoolVersion needs `apiVersion`, `kind`, and `metadata` fields. It also needs a `.spec` section.
+
+```yaml
+apiVersion: catalog.kubedb.com/v1alpha1
+kind: PgpoolVersion
+metadata:
+  name: 4.5.0
+spec:
+  exporter:
+    image: ghcr.io/appscode-images/pgpool2_exporter:v1.2.2
+  pgpool:
+    image: ghcr.io/appscode-images/pgpool2:4.5.0
+  version: 4.5.0
+  deprecated: false
+```
+
+### metadata.name
+
+`metadata.name` is a required field that specifies the name of the `PgpoolVersion` crd. You have to specify this name in `spec.version` field of [Pgpool](/docs/guides/pgpool/concepts/pgpool.md) crd.
+
+We follow this convention for naming PgpoolVersion crd:
+
+- Name format: `{Original pgpool image version}-{modification tag}`
+
+We plan to modify original Pgpool docker images to support additional features. Re-tagging the image with v1, v2 etc. modification tag help separating newer iterations from the older ones. An image with higher modification tag will have more features than the images with lower modification tag. Hence, it is recommended to use PgpoolVersion crd with higher modification tag to take advantage of the latest features.
+
+### spec.version
+
+`spec.version` is a required field that specifies the original version of Pgpool that has been used to build the docker image specified in `spec.server.image` field.
+
+### spec.deprecated
+
+`spec.deprecated` is an optional field that specifies whether the docker images specified here is supported by the current KubeDB operator.
+
+The default value of this field is `false`. If `spec.deprecated` is set `true`, KubeDB operator will not create the server and other respective resources for this version.
+
+### spec.pgpool.image
+
+`spec.pgpool.image` is a required field that specifies the docker image which will be used to create PetSet by KubeDB operator to create expected Pgpool server.
+
+### spec.exporter.image
+
+`spec.exporter.image` is a required field that specifies the image which will be used to export Prometheus metrics.
+
+## Next Steps
+
+- Learn about Pgpool crd [here](/docs/guides/pgpool/concepts/catalog.md).
+- Deploy your first Pgpool server with KubeDB by following the guide [here](/docs/guides/pgpool/quickstart/quickstart.md).