diff --git a/docs/guides/elasticsearch/gitops/_index.md b/docs/guides/elasticsearch/gitops/_index.md new file mode 100644 index 000000000..cc82b5f6b --- /dev/null +++ b/docs/guides/elasticsearch/gitops/_index.md @@ -0,0 +1,10 @@ +--- +title: Elasticsearch Gitops +menu: + docs_{{ .version }}: + identifier: es-gitops + name: Elasticsearch Gitops + parent: es-elasticsearch-guides + weight: 70 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/elasticsearch/gitops/gitops.md b/docs/guides/elasticsearch/gitops/gitops.md new file mode 100644 index 000000000..e3a2e57d2 --- /dev/null +++ b/docs/guides/elasticsearch/gitops/gitops.md @@ -0,0 +1,765 @@ +--- +title: Elasticsearch Gitops Overview +description: Elasticsearch Gitops Overview +menu: + docs_{{ .version }}: + identifier: es-gitops-overview + name: Overview + parent: es-gitops + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + + + +> New to KubeDB? Please start [here](/docs/README.md). + +# GitOps Elasticsearch using KubeDB GitOps Operator + +This guide will show you how to use `KubeDB` GitOps operator to create Elasticsearch database and manage updates using GitOps woreslow. + +## 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` operator in your cluster following the steps [here](/docs/setup/README.md). Pass `--set kubedb-crd-manager.installGitOpsCRDs=true` in the kubedb installation +process to enable `GitOps` operator. + +- You need to install GitOps tools like `ArgoCD` or `FluxCD` and configure with your Git Repository to monitor the Git repository and synchronize the state of the Kubernetes +cluster with the desired state defined in Git. + + ```bash + $ kubectl create ns monitoring + namespace/monitoring created + + $ kubectl create ns demo + namespace/demo created + ``` +> Note: YAML files used in this tutorial are stored in [docs/examples/elasticsearch](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/elasticsearch) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +We are going to use `ArgoCD` in this tutorial. You can install `ArgoCD` in your cluster by following the steps [here](https://argo-cd.readthedocs.io/en/stable/getting_started/). Also, you need to install `argocd` CLI in your local machine. You can install `argocd` CLI by following the steps [here](https://argo-cd.readthedocs.io/en/stable/cli_installation/). + +## Creating Apps via CLI + +### For Public Repository +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace +``` + +### For Private Repository +#### Using HTTPS +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace --username --password +``` + +#### Using SSH +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace --ssh-private-key-path ~/.ssh/id_rsa +``` + +## Create Elasticsearch Database using GitOps + +### Create a Elasticsearch GitOps CR +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: es-gitops + namespace: demo +spec: + version: xpack-8.2.3 + enableSSL: true + replicas: 2 + storageType: Durable + storage: + storageClassName: longhorn + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Create a directory like below, +```bash +$ tree . +├── kubedb + └── Elasticsearch.yaml +1 directories, 1 files +``` + +Now commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is created in your cluster. + +Our `gitops` operator will create an actual `Elasticsearch` database CR in the cluster. List the resources created by `gitops` operator in the `demo` namespace. + + +```bash +$ kubectl get Elasticsearch.gitops.kubedb.com,Elasticsearch.kubedb.com -n demo +NAME AGE +elasticsearch.gitops.kubedb.com/es-gitops 20m + +NAME VERSION STATUS AGE +elasticsearch.kubedb.com/es-gitops xpack-8.2.3 Ready 20m +``` + +List the resources created by `kubedb` operator created for `kubedb.com/v1` Elasticsearch. + +```bash +$ kubectl get petset,pod,secret,service,appbinding -n demo -l 'app.kubernetes.io/instance=es-gitops' +NAME AGE +petset.apps.k8s.appscode.com/es-gitops 20m + +NAME READY STATUS RESTARTS AGE +pod/es-gitops-0 1/1 Running 0 20m +pod/es-gitops-1 1/1 Running 0 19m + +NAME TYPE DATA AGE +secret/es-gitops-a1d7d4 Opaque 1 13m +secret/es-gitops-apm-system-cred kubernetes.io/basic-auth 2 20m +secret/es-gitops-auth kubernetes.io/basic-auth 2 20m +secret/es-gitops-beats-system-cred kubernetes.io/basic-auth 2 20m +secret/es-gitops-ca-cert kubernetes.io/tls 2 20m +secret/es-gitops-client-cert kubernetes.io/tls 3 20m +secret/es-gitops-config Opaque 1 20m +secret/es-gitops-http-cert kubernetes.io/tls 3 20m +secret/es-gitops-kibana-system-cred kubernetes.io/basic-auth 2 20m +secret/es-gitops-logstash-system-cred kubernetes.io/basic-auth 2 20m +secret/es-gitops-remote-monitoring-user-cred kubernetes.io/basic-auth 2 20m +secret/es-gitops-transport-cert kubernetes.io/tls 3 20m + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/es-gitops ClusterIP 10.43.235.79 9200/TCP 20m +service/es-gitops-master ClusterIP None 9300/TCP 20m +service/es-gitops-pods ClusterIP None 9200/TCP 20m + +NAME TYPE VERSION AGE +appbinding.appcatalog.appscode.com/es-gitops kubedb.com/elasticsearch 8.2.3 20m +``` + +## Update Elasticsearch Database using GitOps +### Scale Elasticsearch Replicas +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: es-gitops + namespace: demo +spec: + version: xpack-8.2.3 + enableSSL: true + replicas: 3 + storageType: Durable + storage: + storageClassName: longhorn + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Update the `replicas` to `3`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. +Now, `gitops` operator will detect the replica changes and create a `HorizontalScaling` ElasticsearchOpsRequest to update the `Elasticsearch` database replicas. List the +resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get es,esops -n demo +NAME VERSION STATUS AGE +elasticsearch.kubedb.com/es-gitops xpack-8.2.3 Ready 64m + +NAME TYPE STATUS AGE +elasticsearchopsrequest.ops.kubedb.com/es-gitops-horizontalscaling-32p116 HorizontalScaling Successful 39m +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the number of pods, +```bash +$ kubectl get pod -n demo -l 'app.kubernetes.io/instance=es-gitops' +NAME READY STATUS RESTARTS AGE +es-gitops-0 1/1 Running 0 36m +es-gitops-1 1/1 Running 0 16m +es-gitops-2 1/1 Running 0 15m +``` + + +We can also scale down the replicas by updating the `replicas` fields. +### Scale Elasticsearch Database Resources + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: es-gitops + namespace: demo +spec: + version: xpack-8.2.3 + enableSSL: true + replicas: 3 + podTemplate: + spec: + containers: + - name: elasticsearch + resources: + limits: + cpu: 500m + memory: 1Gi + requests: + cpu: 100m + memory: 1Gi + storageType: Durable + storage: + storageClassName: longhorn + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut + ``` + +Resource Requests and Limits are updated to `500m` CPU and `1Gi` Memory. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the resource changes and create a `ElasticsearchOpsRequest` to update the `Elasticsearch` database. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get es,esops -n demo +NAME VERSION STATUS AGE +elasticsearch.kubedb.com/es-gitops xpack-8.2.3 Ready 64m + +NAME TYPE STATUS AGE +elasticsearchopsrequest.ops.kubedb.com/es-gitops-horizontalscaling-injx1l HorizontalScaling Successful 15m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-verticalscaling-x5mfy0 VerticalScaling Successful 39m + +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the one of the pod, +```bash +$ kubectl get pod -n demo es-gitops-0 -o json | jq '.spec.containers[0].resources' +{ + "limits": { + "cpu": "500m", + "memory": "1Gi" + }, + "requests": { + "cpu": "100m", + "memory": "1Gi" + } +} + +``` + + +### Expand Elasticsearch Volume + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: es-gitops + namespace: demo +spec: + version: xpack-8.2.3 + enableSSL: true + replicas: 3 + podTemplate: + spec: + containers: + - name: elasticsearch + resources: + limits: + cpu: 500m + memory: 1Gi + requests: + cpu: 100m + memory: 1Gi + storageType: Durable + storage: + storageClassName: longhorn + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + deletionPolicy: WipeOut +``` + +Update the `storage.resources.requests.storage` to `2Gi`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the volume changes and create a `VolumeExpansion` ElasticsearchOpsRequest to update the `Elasticsearch` database volume. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get es,esops -n demo +NAME VERSION STATUS AGE +elasticsearch.kubedb.com/es-gitops xpack-8.2.3 Ready 3h1m + +NAME TYPE STATUS AGE +elasticsearchopsrequest.ops.kubedb.com/es-gitops-horizontalscaling-32p116 HorizontalScaling Successful 157m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-verticalscaling-x5mfy0 VerticalScaling Successful 157m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-volumeexpansion-sata37 VolumeExpansion Successful 38m + +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the pvc size, +```bash +$ kubectl get pod -n demo -l 'app.kubernetes.io/instance=es-gitops' +NAME READY STATUS RESTARTS AGE +es-gitops-0 1/1 Running 0 36m +es-gitops-1 1/1 Running 0 16m +es-gitops-2 1/1 Running 0 15m +``` + +## Reconfigure Elasticsearch + +At first, we will create a secret containing `user.conf` file with required configuration settings. +To know more about this configuration file, check [here](/docs/guides/elasticsearch/configuration/combined-cluster/index.md) +```yaml +apiVersion: v1 +stringData: + user.conf: | + max_connections=200 + shared_buffers=256MB +kind: Secret +metadata: + name: es-configuration + namespace: demo +type: Opaque +``` + +Now, we will add this file to `kubedb /es-configuration.yaml`. + +```bash +$ tree . +├── kubedb +│ ├── es-configuration.yaml +│ └── Elasticsearch.yaml +1 directories, 2 files +``` + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: es-gitops + namespace: demo +spec: + version: xpack-8.2.3 + enableSSL: true + replicas: 3 + configuration: + secretName: es-configuration + podTemplate: + spec: + containers: + - name: elasticsearch + resources: + limits: + cpu: 500m + memory: 1Gi + requests: + cpu: 100m + memory: 1Gi + storageType: Durable + storage: + storageClassName: longhorn + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + deletionPolicy: WipeOut +``` + +Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the configuration changes and create a `Reconfigure` ElasticsearchOpsRequest to update the `Elasticsearch` database configuration. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get es,esops -n demo +NAME VERSION STATUS AGE +elasticsearch.kubedb.com/es-gitops xpack-8.2.3 Ready 3h53m + +NAME TYPE STATUS AGE +elasticsearchopsrequest.ops.kubedb.com/es-gitops-horizontalscaling-32p116 HorizontalScaling Successful 3h29m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-reconfigure-wj5qyx Reconfigure Successful 3m42s +elasticsearchopsrequest.ops.kubedb.com/es-gitops-verticalscaling-lvh38k VerticalScaling Successful 99m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-volumeexpansion-sata37 VolumeExpansion Successful 90m +``` + + + +### Rotate Elasticsearch Auth + +To do that, create a `kubernetes.io/basic-auth` type k8s secret with the new username and password. + +We will generate a secret named `es-rotate-auth` with the following content, + +```bash +$ kubectl create secret generic es-rotate-auth -n demo \ + --type=kubernetes.io/basic-auth \ + --from-literal=username=elastic \ + --from-literal=password=elasticsearch-secret +secret/es-rotate-auth created + +``` + + + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: es-gitops + namespace: demo +spec: + version: xpack-8.2.3 + enableSSL: true + replicas: 3 + authSecret: + kind: Secret + name: es-rotate-auth + configuration: + secretName: es-configuration + podTemplate: + spec: + containers: + - name: elasticsearch + resources: + limits: + cpu: 500m + memory: 1Gi + requests: + cpu: 100m + memory: 1Gi + storageType: Durable + storage: + storageClassName: longhorn + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + deletionPolicy: WipeOut +``` + +Change the `authSecret` field to `es-rotate-auth`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the auth changes and create a `RotateAuth` ElasticsearchOpsRequest to update the `Elasticsearch` database auth. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get es,esops -n demo +NAME VERSION STATUS AGE +elasticsearch.kubedb.com/es-gitops xpack-9.1.9 Ready 18m + +NAME TYPE STATUS AGE +elasticsearchopsrequest.ops.kubedb.com/es-gitops-horizontalscaling-wiezxp HorizontalScaling Successful 13m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-reconfigure-i9puam Reconfigure Successful 13m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-rotate-auth-xisot8 RotateAuth Successful 4m38s +elasticsearchopsrequest.ops.kubedb.com/es-gitops-verticalscaling-7dyz6e VerticalScaling Successful 13m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-volumeexpansion-pptef3 VolumeExpansion Successful 13m +``` + + +### TLS configuration + +We can add, rotate or remove TLS configuration using `gitops`. + +To add tls, we are going to create an example `Issuer` that will be used to enable SSL/TLS in Elasticsearch. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. + +- Start off by generating a ca certificates using openssl. + +```bash +$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=ca/O=kubedb" +Generating a RSA private key +................+++++ +........................+++++ +writing new private key to './ca.key' +----- +``` + +- Now we are going to create a ca-secret using the certificate files that we have just generated. + +```bash +$ kubectl create secret tls Elasticsearch-ca \ + --cert=ca.crt \ + --key=ca.key \ + --namespace=demo +secret/Elasticsearch-ca created +``` + +Now, Let's create an `Issuer` using the `Elasticsearch-ca` secret that we have just created. The `YAML` file looks like this: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: es-issuer + namespace: demo +spec: + ca: + secretName: Elasticsearch-ca +``` + +Let's add that to our `kubedb /es-issuer.yaml` file. File structure will look like this, +```bash +$ tree . +├── kubedb +│ ├── es-configuration.yaml +│ ├── es-issuer.yaml +│ └── Elasticsearch.yaml +1 directories, 4 files +``` + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: es-gitops + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Add `sslMode` and `tls` fields in the spec. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the tls changes and create a `ReconfigureTLS` ElasticsearchOpsRequest to update the `Elasticsearch` database tls. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get es,Elasticsearch,esops,pods -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/es-gitops kubedb.com/v1 3.9.0 Ready 41m + +NAME AGE +Elasticsearch.gitops.kubedb.com/es-gitops 75m + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/es-gitops-reconfigure-ukj41o Reconfigure Successful 5d18h +Elasticsearchopsrequest.ops.kubedb.com/es-gitops-reconfiguretls-r4mx7v ReconfigureTLS Successful 9m18s +Elasticsearchopsrequest.ops.kubedb.com/es-gitops-rotate-auth-43ris8 RotateAuth Successful 5d1h +Elasticsearchopsrequest.ops.kubedb.com/es-gitops-volumeexpansion-41xthr VolumeExpansion Successful 5d19h + +``` + + +> We can also rotate the certificates updating `.spec.tls.certificates` field. Also you can remove the `.spec.tls` field to remove tls for Elasticsearch. + +### Update Version + +List Elasticsearch versions using `kubectl get Elasticsearchversion` and choose desired version that is compatible for upgrade from current version. Check the version constraints and ops request [here](/docs/guides/elasticsearch/update-version/update-version.md). + +Let's choose `4.0.0` in this example. + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: es-gitops + namespace: demo +spec: + version: xpack-9.2.3 + replicas: 3 + authSecret: + kind: Secret + name: es-rotate-auth + configuration: + secretName: es-configuration + podTemplate: + spec: + containers: + - name: elasticsearch + resources: + limits: + cpu: 500m + memory: 1Gi + requests: + cpu: 100m + memory: 1Gi + storageType: Durable + storage: + storageClassName: longhorn + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + deletionPolicy: WipeOut +``` + +Update the `version` field to `17.4`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the version changes and create a `VersionUpdate` ElasticsearchOpsRequest to update the `Elasticsearch` database version. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get es,Elasticsearch,esops -n demo +NAME VERSION STATUS AGE +elasticsearch.kubedb.com/es-gitops xpack-9.2.3 Ready 64m + +NAME AGE +elasticsearch.gitops.kubedb.com/es-gitops 64m + +NAME TYPE STATUS AGE +elasticsearchopsrequest.ops.kubedb.com/es-gitops-horizontalscaling-os8fon HorizontalScaling Successful 58m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-reconfigure-hrbrs1 Reconfigure Successful 58m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-rotate-auth-s0tkka RotateAuth Successful 58m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-versionupdate-bn3rk4 UpdateVersion Successful 31m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-verticalscaling-vhzkxl VerticalScaling Successful 58m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-volumeexpansion-bzqd4r VolumeExpansion Successful 58m + +``` + + +Now, we are going to verify whether the `Elasticsearch`, `PetSet` and it's `Pod` have updated with new image. Let's check, + +```bash +$ kubectl get Elasticsearch -n demo es-gitops -o=jsonpath='{.spec.version}{"\n"}' +xpack-9.2.3 + +$ kubectl get petset -n demo es-gitops -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/elastic:9.2.3@sha256:714f35c53d333fef7e673079d05ce80440caf2c20ca3dc9b3e366728527760bb + +$ kubectl get pod -n demo es-gitops-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/elastic:9.2.3@sha256:714f35c53d333fef7e673079d05ce80440caf2c20ca3dc9b3e366728527760bb +``` + +### Enable Monitoring + +If you already don't have a Prometheus server running, deploy one following tutorial from [here](https://github.com/appscode/third-party-tools/blob/master/monitoring/prometheus/operator/README.md#deploy-prometheus-server). + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: es-gitops + namespace: demo +spec: + version: xpack-9.2.3 + replicas: 3 + authSecret: + kind: Secret + name: es-rotate-auth + configuration: + secretName: es-configuration + podTemplate: + spec: + containers: + - name: elasticsearch + resources: + limits: + cpu: 500m + memory: 1Gi + requests: + cpu: 100m + memory: 1Gi + storageType: Durable + storage: + storageClassName: longhorn + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + deletionPolicy: WipeOut + monitor: + agent: prometheus.io/operator + prometheus: + serviceMonitor: + labels: + release: prometheus + interval: 10s +``` + +Add `monitor` field in the spec. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the monitoring changes and create a `Restart` ElasticsearchOpsRequest to add the `Elasticsearch` database monitoring. List the resources created by `gitops` operator in the `demo` namespace. +```bash +$ kubectl get Elasticsearches.gitops.kubedb.com,Elasticsearches.kubedb.com,Elasticsearchopsrequest -n demo +NAME AGE +elasticsearch.gitops.kubedb.com/es-gitops 106m + +NAME VERSION STATUS AGE +elasticsearch.kubedb.com/es-gitops xpack-9.2.3 Ready 106m + +NAME TYPE STATUS AGE +elasticsearchopsrequest.ops.kubedb.com/es-gitops-horizontalscaling-os8fon HorizontalScaling Successful 101m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-reconfigure-hrbrs1 Reconfigure Successful 101m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-restart-7v0e29 Restart Successful 15m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-rotate-auth-s0tkka RotateAuth Successful 101m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-versionupdate-bn3rk4 UpdateVersion Successful 73m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-verticalscaling-vhzkxl VerticalScaling Successful 101m +elasticsearchopsrequest.ops.kubedb.com/es-gitops-volumeexpansion-bzqd4r VolumeExpansion Successful 101m + +``` + +Verify the monitoring is enabled by checking the prometheus targets. + +There are some other fields that will trigger `Restart` ops request. +- `.spec.monitor` +- `.spec.spec.archiver` +- `.spec.remoteReplica` +- `spec.replication` +- `.spec.standbyMode` +- `.spec.streamingMode` +- `.spec.enforceGroup` +- `.spec.sslMode` etc. + + +## Next Steps + +[//]: # (- Learn Elasticsearch [GitOps](/docs/guides/elasticsearch/concepts/Elasticsearch-gitops.md)) +- Learn Elasticsearch Scaling + - [Horizontal Scaling](/docs/guides/elasticsearch/scaling/horizontal/combined.md) + - [Vertical Scaling](/docs/guides/elasticsearch/scaling/vertical/combined.md) +- Learn Version Update Ops Request and Constraints [here](/docs/guides/elasticsearch/update-version/overview.md) +- Monitor your ElasticsearchQL database with KubeDB using [built-in Prometheus](/docs/guides/elasticsearch/monitoring/using-builtin-prometheus.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md) \ No newline at end of file diff --git a/docs/guides/elasticsearch/gitops/overview.md b/docs/guides/elasticsearch/gitops/overview.md new file mode 100644 index 000000000..bfa01c2ff --- /dev/null +++ b/docs/guides/elasticsearch/gitops/overview.md @@ -0,0 +1,50 @@ +--- +title: Elasticsearch Gitops Overview +description: Elasticsearch Gitops Overview +menu: + docs_{{ .version }}: + identifier: es-gitops-overview + name: Overview + parent: es-gitops + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# GitOps Overview for Elasticsearch + +This guide will give you an overview of how KubeDB `gitops` operator works with Elasticsearch databases using the `gitops.kubedb.com/v1alpha1` API. It will help you understand the GitOps workflow for +managing Elasticsearch databases in Kubernetes. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Elasticsearch](/docs/guides/elasticsearch/concepts/elasticsearch/index.md) + - [ElasticsearchOpsRequest](/docs/guides/elasticsearch/concepts/elasticsearch-ops-request/index.md) + + + +## Workflow GitOps with Elasticsearch + +The following diagram shows how the `KubeDB` GitOps Operator used to sync with your database. Open the image in a new tab to see the enlarged version. + + +
+ + GitOps Flow + +
Fig: GitOps process of Elasticsearch
+ +
+ +1. **Define GitOps Elasticsearch**: Create Custom Resource (CR) of kind `Elasticsearch` using the `gitops.kubedb.com/v1alpha1` API. +2. **Store in Git**: Push the CR to a Git repository. +3. **Automated Deployment**: Use a GitOps tool (like `ArgoCD` or `FluxCD`) to monitor the Git repository and synchronize the state of the Kubernetes cluster with the desired state defined in Git. +4. **Create Database**: The GitOps operator creates a corresponding KubeDB Elasticsearch CR in the Kubernetes cluster to deploy the database. +5. **Handle Updates**: When you update the ElasticsearchGitOps CR, the operator generates an Ops Request to safely apply the update(e.g. `VerticalScaling`, `HorizontalScaling`, `VolumeExapnsion`, `Reconfigure`, `RotateAuth`, `ReconfigureTLS`, `VersionUpdate`, ans `Restart`. + +This flow makes managing Elasticsearch databases efficient, reliable, and fully integrated with GitOps practices. + +In the next doc, we are going to show a step by step guide on running Elasticsearch using GitOps. diff --git a/docs/guides/kafka/autoscaler/_index.md b/docs/guides/kafka/autoscaler/_index.md index 22a1e3830..c6d7e89ab 100644 --- a/docs/guides/kafka/autoscaler/_index.md +++ b/docs/guides/kafka/autoscaler/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-auto-scaling name: Autoscaling parent: kf-kafka-guides - weight: 46 + weight: 90 menu_name: docs_{{ .version }} --- \ No newline at end of file diff --git a/docs/guides/kafka/cli/_index.md b/docs/guides/kafka/cli/_index.md index 155f42086..e879f4f43 100755 --- a/docs/guides/kafka/cli/_index.md +++ b/docs/guides/kafka/cli/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-cli-kafka name: CLI parent: kf-kafka-guides - weight: 100 + weight: 95 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/clustering/_index.md b/docs/guides/kafka/clustering/_index.md index 21b81a743..6cab222d4 100755 --- a/docs/guides/kafka/clustering/_index.md +++ b/docs/guides/kafka/clustering/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-clustering name: Clustering parent: kf-kafka-guides - weight: 20 + weight: 25 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/configuration/_index.md b/docs/guides/kafka/configuration/_index.md index 81167c2af..1ef769c0d 100644 --- a/docs/guides/kafka/configuration/_index.md +++ b/docs/guides/kafka/configuration/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-configuration name: Custom Configuration parent: kf-kafka-guides - weight: 30 + weight: 35 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/connectcluster/_index.md b/docs/guides/kafka/connectcluster/_index.md index 7d833caaa..44991d14d 100644 --- a/docs/guides/kafka/connectcluster/_index.md +++ b/docs/guides/kafka/connectcluster/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-connectcluster-guides name: ConnectCluster parent: kf-kafka-guides - weight: 25 + weight: 40 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/gitops/_index.md b/docs/guides/kafka/gitops/_index.md new file mode 100644 index 000000000..098093afa --- /dev/null +++ b/docs/guides/kafka/gitops/_index.md @@ -0,0 +1,10 @@ +--- +title: Gitops Kafka +menu: + docs_{{ .version }}: + identifier: kf-gitops + name: Gitops + parent: kf-kafka-guides + weight: 30 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/kafka/gitops/gitops.md b/docs/guides/kafka/gitops/gitops.md new file mode 100644 index 000000000..881efb1dd --- /dev/null +++ b/docs/guides/kafka/gitops/gitops.md @@ -0,0 +1,908 @@ +--- +title: Kafka GitOps Guides +menu: + docs_{{ .version }}: + identifier: kf-gitops-guides + name: Gitops Kafka + parent: kf-gitops-kafka + weight: 20 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + + +> New to KubeDB? Please start [here](/docs/README.md). + +# GitOps Kafka using KubeDB GitOps Operator + +This guide will show you how to use `KubeDB` GitOps operator to create Kafka database and manage updates using GitOps workflow. + +## 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` operator in your cluster following the steps [here](/docs/setup/README.md). Pass `--set kubedb-crd-manager.installGitOpsCRDs=true` in the kubedb installation process to enable `GitOps` operator. + +- You need to install GitOps tools like `ArgoCD` or `FluxCD` and configure with your Git Repository to monitor the Git repository and synchronize the state of the Kubernetes cluster with the desired state defined in Git. + + ```bash + $ kubectl create ns monitoring + namespace/monitoring created + + $ kubectl create ns demo + namespace/demo created + ``` +> Note: YAML files used in this tutorial are stored in [docs/examples/kafka](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/kafka) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +We are going to use `ArgoCD` in this tutorial. You can install `ArgoCD` in your cluster by following the steps [here](https://argo-cd.readthedocs.io/en/stable/getting_started/). Also, you need to install `argocd` CLI in your local machine. You can install `argocd` CLI by following the steps [here](https://argo-cd.readthedocs.io/en/stable/cli_installation/). + +## Creating Apps via CLI + +### For Public Repository +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace +``` + +### For Private Repository +#### Using HTTPS +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace --username --password +``` + +#### Using SSH +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace --ssh-private-key-path ~/.ssh/id_rsa +``` + +## Create Kafka Database using GitOps + +### Create a Kafka GitOps CR +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Kafka +metadata: + name: kafka-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: Standard + controller: + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Create a directory like below, +```bash +$ tree . +├── kubedb + └── Kafka.yaml +1 directories, 1 files +``` + +Now commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Kafka` CR is created in your cluster. + +Our `gitops` operator will create an actual `Kafka` database CR in the cluster. List the resources created by `gitops` operator in the `demo` namespace. + + +```bash +$ kubectl get kafka.gitops.kubedb.com,kafka.kubedb.com -n demo +NAME AGE +kafka.gitops.kubedb.com/kafka-prod 2m56s + +NAME TYPE VERSION STATUS AGE +kafka.kubedb.com/kafka-prod kubedb.com/v1 3.9.0 Ready 2m56s +``` + +List the resources created by `kubedb` operator created for `kubedb.com/v1` Kafka. + +```bash +$ kubectl get petset,pod,secret,service,appbinding -n demo -l 'app.kubernetes.io/instance=kafka-prod' +NAME AGE +petset.apps.k8s.appscode.com/kafka-prod-broker 4m49s +petset.apps.k8s.appscode.com/kafka-prod-controller 4m47s + +NAME READY STATUS RESTARTS AGE +pod/kafka-prod-broker-0 1/1 Running 0 4m48s +pod/kafka-prod-broker-1 1/1 Running 0 4m42s +pod/kafka-prod-controller-0 1/1 Running 0 4m47s +pod/kafka-prod-controller-1 1/1 Running 0 4m40s + +NAME TYPE DATA AGE +secret/kafka-prod-auth kubernetes.io/basic-auth 2 4m51s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/kafka-prod-pods ClusterIP None 9092/TCP,9093/TCP,29092/TCP 4m51s + +NAME TYPE VERSION AGE +appbinding.appcatalog.appscode.com/kafka-prod kubedb.com/kafka 3.9.0 4m47s +``` + +## Update Kafka Database using GitOps + +### Scale Kafka Database Resources + +Update the `Kafka.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Kafka +metadata: + name: kafka-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + controller: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + storageType: Durable + deletionPolicy: WipeOut + ``` + +Resource Requests and Limits are updated to `700m` CPU and `2Gi` Memory. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Kafka` CR is updated in your cluster. + +Now, `gitops` operator will detect the resource changes and create a `KafkaOpsRequest` to update the `Kafka` database. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ $ kubectl get kf,kafka,kfops -n demo +NAME TYPE VERSION STATUS AGE +kafka.kubedb.com/kafka-prod kubedb.com/v1 3.9.0 Ready 22h + +NAME AGE +kafka.gitops.kubedb.com/kafka-prod 22h + +NAME TYPE STATUS AGE +Kafkaopsrequest.ops.kubedb.com/kafka-prod-verticalscaling-i0kr1l VerticalScaling Successful 2s +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the one of the pod, +```bash +$ kubectl get pod -n demo Kafka-prod-broker-0 -o json | jq '.spec.containers[0].resources' +{ + "limits": { + "memory": "1536Mi" + }, + "requests": { + "cpu": "500m", + "memory": "1536Mi" + } +} +``` + +### Scale Kafka Replicas +Update the `Kafka.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Kafka +metadata: + name: kafka-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + controller: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `replicas` to `3`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Kafka` CR is updated in your cluster. +Now, `gitops` operator will detect the replica changes and create a `HorizontalScaling` KafkaOpsRequest to update the `Kafka` database replicas. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,kafka,kfops -n demo +NAME TYPE VERSION STATUS AGE +kafka.kubedb.com/kafka-prod kubedb.com/v1 3.9.0 Ready 22h + +NAME AGE +kafka.gitops.kubedb.com/kafka-prod 22h + +NAME TYPE STATUS AGE +kafkaopsrequest.ops.kubedb.com/kafka-prod-horizontalscaling-j0wni6 HorizontalScaling Successful 13m +kafkaopsrequest.ops.kubedb.com/kafka-prod-verticalscaling-tfkvi8 VerticalScaling Successful 8m29s +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the number of pods, +```bash +$ kubectl get pod -n demo -l 'app.kubernetes.io/instance=kafka-prod' +NAME READY STATUS RESTARTS AGE +kafka-prod-broker-0 1/1 Running 0 34m +kafka-prod-broker-1 1/1 Running 0 33m +kafka-prod-broker-2 1/1 Running 0 33m +kafka-prod-controller-0 1/1 Running 0 32m +kafka-prod-controller-1 1/1 Running 0 31m +kafka-prod-controller-2 1/1 Running 0 31m +``` + +We can also scale down the replicas by updating the `replicas` fields. + +### Expand Kafka Volume + +Update the `Kafka.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Kafka +metadata: + name: kafka-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `storage.resources.requests.storage` to `2Gi`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Kafka` CR is updated in your cluster. + +Now, `gitops` operator will detect the volume changes and create a `VolumeExpansion` KafkaOpsRequest to update the `Kafka` database volume. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,kafka,kfops -n demo +NAME TYPE VERSION STATUS AGE +kafka.kubedb.com/kafka-prod kubedb.com/v1 3.9.0 Ready 23m + +NAME AGE +kafka.gitops.kubedb.com/kafka-prod 23m + +NAME TYPE STATUS AGE +kafkaopsrequest.ops.kubedb.com/kafka-prod-horizontalscaling-j0wni6 HorizontalScaling Successful 13m +kafkaopsrequest.ops.kubedb.com/kafka-prod-verticalscaling-tfkvi8 VerticalScaling Successful 8m29s +kafkaopsrequest.ops.kubedb.com/kafka-prod-volumeexpansion-41xthr VolumeExpansion Successful 19m +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the pvc size, +```bash +$ kubectl get pvc -n demo -l 'app.kubernetes.io/instance=kafka-prod' +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE +kafka-prod-data-kafka-prod-broker-0 Bound pvc-2afd4835-5686-492b-be93-c6e040e0a6c6 2Gi RWO Standard 3h39m +kafka-prod-data-kafka-prod-broker-1 Bound pvc-aaf994cc-6b04-4c37-80d5-5e966dad8487 2Gi RWO Standard 3h39m +kafka-prod-data-kafka-prod-controller-0 Bound pvc-82d2b233-203d-4df2-a0fd-ecedbc0825b7 2Gi RWO Standard 3h39m +kafka-prod-data-kafka-prod-controller-1 Bound pvc-91852c29-ab1a-48ad-9255-a0b15d5a7515 2Gi RWO Standard 3h39m + +``` + +## Reconfigure Kafka + +At first, we will create a secret containing `user.conf` file with required configuration settings. +To know more about this configuration file, check [here](/docs/guides/kafka/configuration/kafka-combined.md) +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: new-kf-combined-custom-config + namespace: demo +stringData: + server.properties: |- + log.retention.hours=125 +``` + +Now, we will add this file to `kubedb /kf-configuration.yaml`. + +```bash +$ tree . +├── kubedb +│ ├── kf-configuration.yaml +│ └── Kafka.yaml +1 directories, 2 files +``` + +Update the `Kafka.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Kafka +metadata: + name: kafka-prod + namespace: demo +spec: + configSecret: + name: new-kf-combined-custom-config + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Kafka` CR is updated in your cluster. + +Now, `gitops` operator will detect the configuration changes and create a `Reconfigure` KafkaOpsRequest to update the `Kafka` database configuration. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,kafka,kfops -n demo +NAME TYPE VERSION STATUS AGE +kafka.kubedb.com/kafka-prod kubedb.com/v1 3.9.0 Ready 74m + +NAME AGE +kafka.gitops.kubedb.com/kafka-prod 74m + +NAME TYPE STATUS AGE +kafkaopsrequest.ops.kubedb.com/kafka-prod-reconfigure-ukj41o Reconfigure Successful 24m +kafkaopsrequest.ops.kubedb.com/kafka-prod-volumeexpansion-41xthr VolumeExpansion Successful 70m + +``` + + + +> We can also reconfigure the parameters creating another secret and reference the secret in the `configSecret` field. Also you can remove the `configSecret` field to use the default parameters. + +### Rotate Kafka Auth + +To do that, create a `kubernetes.io/basic-auth` type k8s secret with the new username and password. + +We will create a secret named `kf-rotate-auth ` with the following content, + +```bash +kubectl create secret generic kf-rotate-auth -n demo \ +--type=kubernetes.io/basic-auth \ +--from-literal=username=kafka \ +--from-literal=password=kafka-secret +secret/kf-rotate-auth created + +``` + + + +Update the `Kafka.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Kafka +metadata: + name: kafka-prod + namespace: demo +spec: + authSecret: + kind: Secret + name: kf-rotate-auth + configuration: + secretName: new-kf-combined-custom-config + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Change the `authSecret` field to `kf-rotate-auth`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Kafka` CR is updated in your cluster. + +Now, `gitops` operator will detect the auth changes and create a `RotateAuth` KafkaOpsRequest to update the `Kafka` database auth. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,kafka,kfops -n demo +NAME TYPE VERSION STATUS AGE +kafka.kubedb.com/kafka-prod kubedb.com/v1 3.9.0 Ready 7m11s + +NAME AGE +kafka.gitops.kubedb.com/kafka-prod 7m11s + +NAME TYPE STATUS AGE +kafkaopsrequest.ops.kubedb.com/kafka-prod-reconfigure-ukj41o Reconfigure Successful 17h +kafkaopsrequest.ops.kubedb.com/kafka-prod-rotate-auth-43ris8 RotateAuth Successful 28m +kafkaopsrequest.ops.kubedb.com/kafka-prod-volumeexpansion-41xthr VolumeExpansion Successful 17h + +``` + + +### TLS configuration + +We can add, rotate or remove TLS configuration using `gitops`. + +To add tls, we are going to create an example `Issuer` that will be used to enable SSL/TLS in Kafka. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. + +- Start off by generating a ca certificates using openssl. + +```bash +$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=ca/O=kubedb" +Generating a RSA private key +................+++++ +........................+++++ +writing new private key to './ca.key' +----- +``` + +- Now we are going to create a ca-secret using the certificate files that we have just generated. + +```bash +$ kubectl create secret tls kafka-ca \ + --cert=ca.crt \ + --key=ca.key \ + --namespace=demo +secret/Kafka-ca created +``` + +Now, Let's create an `Issuer` using the `Kafka-ca` secret that we have just created. The `YAML` file looks like this: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: kf-issuer + namespace: demo +spec: + ca: + secretName: kafka-ca +``` + +Let's add that to our `kubedb /kf-issuer.yaml` file. File structure will look like this, +```bash +$ tree . +├── kubedb +│ ├── kf-configuration.yaml +│ ├── kf-issuer.yaml +│ └── Kafka.yaml +1 directories, 4 files +``` + +Update the `Kafka.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Kafka +metadata: + name: kafka-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Add `sslMode` and `tls` fields in the spec. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Kafka` CR is updated in your cluster. + +Now, `gitops` operator will detect the tls changes and create a `ReconfigureTLS` KafkaOpsRequest to update the `Kafka` database tls. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,kafka,kfops,pods -n demo +NAME TYPE VERSION STATUS AGE +kafka.kubedb.com/kafka-prod kubedb.com/v1 3.9.0 Ready 41m + +NAME AGE +kafka.gitops.kubedb.com/kafka-prod 75m + +NAME TYPE STATUS AGE +kafkaopsrequest.ops.kubedb.com/kafka-prod-reconfigure-ukj41o Reconfigure Successful 5d18h +kafkaopsrequest.ops.kubedb.com/kafka-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 9m18s +kafkaopsrequest.ops.kubedb.com/kafka-prod-rotate-auth-43ris8 RotateAuth Successful 5d1h +kafkaopsrequest.ops.kubedb.com/kafka-prod-volumeexpansion-41xthr VolumeExpansion Successful 5d19h + +``` + + +> We can also rotate the certificates updating `.spec.tls.certificates` field. Also you can remove the `.spec.tls` field to remove tls for Kafka. + +### Update Version + +List Kafka versions using `kubectl get Kafkaversion` and choose desired version that is compatible for upgrade from current version. Check the version constraints and ops request [here](/docs/guides/kafka/update-version/update-version.md). + +Let's choose `4.0.0` in this example. + +Update the `Kafka.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Kafka +metadata: + name: kafka-prod + namespace: demo +spec: + version: 4.0.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `version` field to `17.4`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Kafka` CR is updated in your cluster. + +Now, `gitops` operator will detect the version changes and create a `VersionUpdate` KafkaOpsRequest to update the `Kafka` database version. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,kafka,kfops -n demo +NAME TYPE VERSION STATUS AGE +kafka.kubedb.com/kafka-prod kubedb.com/v1 4.0.0 Ready 3h47m + +NAME AGE +kafka.gitops.kubedb.com/kafka-prod 3h47m + +NAME TYPE STATUS AGE +kafkaopsrequest.ops.kubedb.com/kafka-prod-reconfigure-ukj41o Reconfigure Successful 5d22h +kafkaopsrequest.ops.kubedb.com/kafka-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 4h16m +kafkaopsrequest.ops.kubedb.com/kafka-prod-rotate-auth-43ris8 RotateAuth Successful 5d6h +kafkaopsrequest.ops.kubedb.com/kafka-prod-versionupdate-wyn2dp UpdateVersion Successful 3h51m +kafkaopsrequest.ops.kubedb.com/kafka-prod-volumeexpansion-41xthr VolumeExpansion Successful 5d23h +``` + + +Now, we are going to verify whether the `Kafka`, `PetSet` and it's `Pod` have updated with new image. Let's check, + +```bash +$ kubectl get Kafka -n demo kafka-prod -o=jsonpath='{.spec.version}{"\n"}' +4.0.0 + +$ kubectl get petset -n demo kafka-prod-broker -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/kafka:4.0.0@sha256:42a79fe8f14b00b1c76d135bbbaf7605b8c66f45cf3eb749c59138f6df288b31 + +$ kubectl get pod -n demo kafka-prod-broker-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/kafka:4.0.0@sha256:42a79fe8f14b00b1c76d135bbbaf7605b8c66f45cf3eb749c59138f6df288b31 +``` + +### Enable Monitoring + +If you already don't have a Prometheus server running, deploy one following tutorial from [here](https://github.com/appscode/third-party-tools/blob/master/monitoring/prometheus/operator/README.md#deploy-prometheus-server). + +Update the `Kafka.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Kafka +metadata: + name: kafka-prod + namespace: demo +spec: + version: 4.0.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: kafka + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + monitor: + agent: prometheus.io/operator + prometheus: + exporter: + port: 9091 + serviceMonitor: + labels: + release: prometheus + interval: 10s + deletionPolicy: WipeOut +``` + +Add `monitor` field in the spec. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Kafka` CR is updated in your cluster. + +Now, `gitops` operator will detect the monitoring changes and create a `Restart` KafkaOpsRequest to add the `Kafka` database monitoring. List the resources created by `gitops` operator in the `demo` namespace. +```bash +$ kubectl get Kafkaes.gitops.kubedb.com,Kafkaes.kubedb.com,Kafkaopsrequest -n demo +NAME TYPE VERSION STATUS AGE +kafka.kubedb.com/kafka-prod kubedb.com/v1 4.0.0 Ready 5h12m + +NAME AGE +kafka.gitops.kubedb.com/kafka-prod 5h12m + +NAME TYPE STATUS AGE +kafkaopsrequest.ops.kubedb.com/kafka-prod-reconfigure-ukj41o Reconfigure Successful 6d +kafkaopsrequest.ops.kubedb.com/kafka-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 5h42m +kafkaopsrequest.ops.kubedb.com/kafka-prod-restart-ljpqih Restart Successful 3m51s +kafkaopsrequest.ops.kubedb.com/kafka-prod-rotate-auth-43ris8 RotateAuth Successful 5d7h +kafkaopsrequest.ops.kubedb.com/kafka-prod-versionupdate-wyn2dp UpdateVersion Successful 5h16m +kafkaopsrequest.ops.kubedb.com/kafka-prod-volumeexpansion-41xthr VolumeExpansion Successful 6d + +``` + +Verify the monitoring is enabled by checking the prometheus targets. + +There are some other fields that will trigger `Restart` ops request. +- `.spec.monitor` +- `.spec.spec.archiver` +- `.spec.remoteReplica` +- `spec.replication` +- `.spec.standbyMode` +- `.spec.streamingMode` +- `.spec.enforceGroup` +- `.spec.sslMode` etc. + + +## Next Steps + +[//]: # (- Learn Kafka [GitOps](/docs/guides/kafka/concepts/Kafka-gitops.md)) +- Learn Kafka Scaling + - [Horizontal Scaling](/docs/guides/kafka/scaling/horizontal-scaling/combined.md) + - [Vertical Scaling](/docs/guides/kafka/scaling/vertical-scaling/combined.md) +- Learn Version Update Ops Request and Constraints [here](/docs/guides/kafka/update-version/overview.md) +- Monitor your KafkaQL database with KubeDB using [built-in Prometheus](/docs/guides/kafka/monitoring/using-builtin-prometheus.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/kafka/gitops/overview.md b/docs/guides/kafka/gitops/overview.md new file mode 100644 index 000000000..cf959a479 --- /dev/null +++ b/docs/guides/kafka/gitops/overview.md @@ -0,0 +1,50 @@ +--- +title: Kafka Gitops Overview +description: Kafka Gitops Overview +menu: + docs_{{ .version }}: + identifier: kf-gitops-overview + name: Overview + parent: kf-gitops + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# GitOps Overview for Kafka + +This guide will give you an overview of how KubeDB `gitops` operator works with Kafka databases using the `gitops.kubedb.com/v1alpha1` API. It will help you understand the GitOps workflow for +managing Kafka databases in Kubernetes. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Kafka](/docs/guides/kafka/concepts/kafka.md) + - [KafkaOpsRequest](/docs/guides/kafka/concepts/kafkaopsrequest.md) + + + +## Workflow GitOps with Kafka + +The following diagram shows how the `KubeDB` GitOps Operator used to sync with your database. Open the image in a new tab to see the enlarged version. + + +
+ + GitOps Flow + +
Fig: GitOps process of Kafka
+ +
+ +1. **Define GitOps Kafka**: Create Custom Resource (CR) of kind `Kafka` using the `gitops.kubedb.com/v1alpha1` API. +2. **Store in Git**: Push the CR to a Git repository. +3. **Automated Deployment**: Use a GitOps tool (like `ArgoCD` or `FluxCD`) to monitor the Git repository and synchronize the state of the Kubernetes cluster with the desired state defined in Git. +4. **Create Database**: The GitOps operator creates a corresponding KubeDB Kafka CR in the Kubernetes cluster to deploy the database. +5. **Handle Updates**: When you update the KafkaGitOps CR, the operator generates an Ops Request to safely apply the update(e.g. `VerticalScaling`, `HorizontalScaling`, `VolumeExapnsion`, `Reconfigure`, `RotateAuth`, `ReconfigureTLS`, `VersionUpdate`, ans `Restart`. + +This flow makes managing Kafka databases efficient, reliable, and fully integrated with GitOps practices. + +In the next doc, we are going to show a step by step guide on running Kafka using GitOps. diff --git a/docs/guides/kafka/migration/_index.md b/docs/guides/kafka/migration/_index.md index 0f8b4d2e1..84e319492 100644 --- a/docs/guides/kafka/migration/_index.md +++ b/docs/guides/kafka/migration/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-migration-kafka name: Migration parent: kf-kafka-guides - weight: 27 + weight: 60 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/monitoring/_index.md b/docs/guides/kafka/monitoring/_index.md index 05429b728..16cc76ef2 100755 --- a/docs/guides/kafka/monitoring/_index.md +++ b/docs/guides/kafka/monitoring/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-monitoring-kafka name: Monitoring parent: kf-kafka-guides - weight: 50 + weight: 60 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/reconfigure-tls/_index.md b/docs/guides/kafka/reconfigure-tls/_index.md index 5b2552a6d..e4f77b489 100644 --- a/docs/guides/kafka/reconfigure-tls/_index.md +++ b/docs/guides/kafka/reconfigure-tls/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-reconfigure-tls name: Reconfigure TLS/SSL parent: kf-kafka-guides - weight: 46 + weight: 55 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/reconfigure/_index.md b/docs/guides/kafka/reconfigure/_index.md index 86d8888b6..7a9181a21 100644 --- a/docs/guides/kafka/reconfigure/_index.md +++ b/docs/guides/kafka/reconfigure/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-reconfigure name: Reconfigure parent: kf-kafka-guides - weight: 46 + weight: 45 menu_name: docs_{{ .version }} --- \ No newline at end of file diff --git a/docs/guides/kafka/restart/_index.md b/docs/guides/kafka/restart/_index.md index d0d4240b4..1199fe4ae 100644 --- a/docs/guides/kafka/restart/_index.md +++ b/docs/guides/kafka/restart/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-restart name: Restart parent: kf-kafka-guides - weight: 46 + weight: 75 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/restproxy/_index.md b/docs/guides/kafka/restproxy/_index.md index b02df6b52..1e1e16820 100644 --- a/docs/guides/kafka/restproxy/_index.md +++ b/docs/guides/kafka/restproxy/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-rest-proxy-guides name: RestProxy parent: kf-kafka-guides - weight: 25 + weight: 60 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/rotate-auth/_index.md b/docs/guides/kafka/rotate-auth/_index.md index 840907389..ed2cf8a38 100644 --- a/docs/guides/kafka/rotate-auth/_index.md +++ b/docs/guides/kafka/rotate-auth/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-rotate-auth name: Rotate Authentication parent: kf-kafka-guides - weight: 45 + weight: 85 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/scaling/_index.md b/docs/guides/kafka/scaling/_index.md index 98b83c710..48781a47d 100644 --- a/docs/guides/kafka/scaling/_index.md +++ b/docs/guides/kafka/scaling/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-scaling name: Scaling parent: kf-kafka-guides - weight: 43 + weight: 70 menu_name: docs_{{ .version }} --- \ No newline at end of file diff --git a/docs/guides/kafka/schemaregistry/_index.md b/docs/guides/kafka/schemaregistry/_index.md index 31f884753..64a121265 100644 --- a/docs/guides/kafka/schemaregistry/_index.md +++ b/docs/guides/kafka/schemaregistry/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-schema-registry-guides name: SchemaRegistry parent: kf-kafka-guides - weight: 25 + weight: 60 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/tls/_index.md b/docs/guides/kafka/tls/_index.md index 1b5fe9d94..d92320672 100755 --- a/docs/guides/kafka/tls/_index.md +++ b/docs/guides/kafka/tls/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-tls name: TLS/SSL Encryption parent: kf-kafka-guides - weight: 45 + weight: 50 menu_name: docs_{{ .version }} --- diff --git a/docs/guides/kafka/update-version/_index.md b/docs/guides/kafka/update-version/_index.md index 08f8af5d4..2581cfd25 100644 --- a/docs/guides/kafka/update-version/_index.md +++ b/docs/guides/kafka/update-version/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-update-version name: UpdateVersion parent: kf-kafka-guides - weight: 42 + weight: 65 menu_name: docs_{{ .version }} --- \ No newline at end of file diff --git a/docs/guides/kafka/volume-expansion/_index.md b/docs/guides/kafka/volume-expansion/_index.md index 27c8e1f8b..dddfb1563 100644 --- a/docs/guides/kafka/volume-expansion/_index.md +++ b/docs/guides/kafka/volume-expansion/_index.md @@ -5,6 +5,6 @@ menu: identifier: kf-volume-expansion name: Volume Expansion parent: kf-kafka-guides - weight: 44 + weight: 80 menu_name: docs_{{ .version }} --- \ No newline at end of file diff --git a/docs/guides/mariadb/gitops/_index.md b/docs/guides/mariadb/gitops/_index.md new file mode 100644 index 000000000..cc82b5f6b --- /dev/null +++ b/docs/guides/mariadb/gitops/_index.md @@ -0,0 +1,10 @@ +--- +title: Elasticsearch Gitops +menu: + docs_{{ .version }}: + identifier: es-gitops + name: Elasticsearch Gitops + parent: es-elasticsearch-guides + weight: 70 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/mariadb/gitops/gitops.md b/docs/guides/mariadb/gitops/gitops.md new file mode 100644 index 000000000..ec2fdd8f5 --- /dev/null +++ b/docs/guides/mariadb/gitops/gitops.md @@ -0,0 +1,910 @@ +--- +title: MariaDB Gitops Overview +description: MariaDB Gitops Overview +menu: + docs_{{ .version }}: + identifier: es-gitops-overview + name: Overview + parent: es-gitops + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + + + +> New to KubeDB? Please start [here](/docs/README.md). + +# GitOps MariaDB using KubeDB GitOps Operator + +This guide will show you how to use `KubeDB` GitOps operator to create MariaDB database and manage updates using GitOps workflow. + +## 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` operator in your cluster following the steps [here](/docs/setup/README.md). Pass `--set kubedb-crd-manager.installGitOpsCRDs=true` in the kubedb installation process to enable `GitOps` operator. + +- You need to install GitOps tools like `ArgoCD` or `FluxCD` and configure with your Git Repository to monitor the Git repository and synchronize the state of the Kubernetes cluster with the desired state defined in Git. + + ```bash + $ kubectl create ns monitoring + namespace/monitoring created + + $ kubectl create ns demo + namespace/demo created + ``` +> Note: YAML files used in this tutorial are stored in [docs/examples/MariaDB](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/MariaDB) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +We are going to use `ArgoCD` in this tutorial. You can install `ArgoCD` in your cluster by following the steps [here](https://argo-cd.readthedocs.io/en/stable/getting_started/). Also, you need to install `argocd` CLI in your local machine. You can install `argocd` CLI by following the steps [here](https://argo-cd.readthedocs.io/en/stable/cli_installation/). + +## Creating Apps via CLI + +### For Public Repository +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace +``` + +### For Private Repository +#### Using HTTPS +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace --username --password +``` + +#### Using SSH +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace --ssh-private-key-path ~/.ssh/id_rsa +``` + +## Create MariaDB Database using GitOps + +### Create a MariaDB GitOps CR +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: MariaDB +metadata: + name: mariadb-gitops + namespace: demo +spec: + version: "10.5.23" + storageType: Durable + storage: + storageClassName: longhorn + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Create a directory like below, +```bash +$ tree . +├── kubedb + └── MariaDB.yaml +1 directories, 1 files +``` + +Now commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `MariaDB` CR is created in your cluster. + +Our `gitops` operator will create an actual `MariaDB` database CR in the cluster. List the resources created by `gitops` operator in the `demo` namespace. + + +```bash +$ kubectl get MariaDB.gitops.kubedb.com,MariaDB.kubedb.com -n demo +NAME AGE +mariadb.gitops.kubedb.com/mariadb-gitops 2m + +NAME VERSION STATUS AGE +mariadb.kubedb.com/mariadb-gitops 10.5.23 Ready 2m + +``` + +List the resources created by `kubedb` operator created for `kubedb.com/v1` MariaDB. + +```bash +$ kubectl get petset,pod,secret,service,appbinding -n demo -l 'app.kubernetes.io/instance=mariadb-gitops' +NAME AGE +petset.apps.k8s.appscode.com/mariadb-gitops 2m45s + +NAME READY STATUS RESTARTS AGE +pod/mariadb-gitops-0 1/1 Running 0 2m45s + +NAME TYPE DATA AGE +secret/mariadb-gitops-auth kubernetes.io/basic-auth 2 2m47s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/mariadb-gitops ClusterIP 10.43.132.16 3306/TCP 2m47s +service/mariadb-gitops-pods ClusterIP None 3306/TCP 2m47s + +NAME TYPE VERSION AGE +appbinding.appcatalog.appscode.com/mariadb-gitops kubedb.com/mariadb 10.5.23 2m45s + +``` + +## Update MariaDB Database using GitOps + +### Scale MariaDB Database Resources + +```shell +$ kubectl get pod -n demo mariadb-gitops-0 -o json | jq '.spec.containers[].resources' +{ + "limits": { + "memory": "1Gi" + }, + "requests": { + "cpu": "500m", + "memory": "1Gi" + } +} + +``` +Update the `MariaDB.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: MariaDB +metadata: + name: MariaDB-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + controller: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + storageType: Durable + deletionPolicy: WipeOut + ``` + +Resource Requests and Limits are updated to `700m` CPU and `2Gi` Memory. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `MariaDB` CR is updated in your cluster. + +Now, `gitops` operator will detect the resource changes and create a `MariaDBOpsRequest` to update the `MariaDB` database. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ $ kubectl get kf,MariaDB,kfops -n demo +NAME TYPE VERSION STATUS AGE +MariaDB.kubedb.com/MariaDB-prod kubedb.com/v1 3.9.0 Ready 22h + +NAME AGE +MariaDB.gitops.kubedb.com/MariaDB-prod 22h + +NAME TYPE STATUS AGE +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-verticalscaling-i0kr1l VerticalScaling Successful 2s +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the one of the pod, +```bash +$ kubectl get pod -n demo MariaDB-prod-broker-0 -o json | jq '.spec.containers[0].resources' +{ + "limits": { + "memory": "1536Mi" + }, + "requests": { + "cpu": "500m", + "memory": "1536Mi" + } +} +``` + +### Scale MariaDB Replicas +Update the `MariaDB.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: MariaDB +metadata: + name: MariaDB-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + controller: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `replicas` to `3`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `MariaDB` CR is updated in your cluster. +Now, `gitops` operator will detect the replica changes and create a `HorizontalScaling` MariaDBOpsRequest to update the `MariaDB` database replicas. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,MariaDB,kfops -n demo +NAME TYPE VERSION STATUS AGE +MariaDB.kubedb.com/MariaDB-prod kubedb.com/v1 3.9.0 Ready 22h + +NAME AGE +MariaDB.gitops.kubedb.com/MariaDB-prod 22h + +NAME TYPE STATUS AGE +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-horizontalscaling-j0wni6 HorizontalScaling Successful 13m +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-verticalscaling-tfkvi8 VerticalScaling Successful 8m29s +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the number of pods, +```bash +$ kubectl get pod -n demo -l 'app.kubernetes.io/instance=MariaDB-prod' +NAME READY STATUS RESTARTS AGE +MariaDB-prod-broker-0 1/1 Running 0 34m +MariaDB-prod-broker-1 1/1 Running 0 33m +MariaDB-prod-broker-2 1/1 Running 0 33m +MariaDB-prod-controller-0 1/1 Running 0 32m +MariaDB-prod-controller-1 1/1 Running 0 31m +MariaDB-prod-controller-2 1/1 Running 0 31m +``` + +We can also scale down the replicas by updating the `replicas` fields. + +### Expand MariaDB Volume + +Update the `MariaDB.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: MariaDB +metadata: + name: MariaDB-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `storage.resources.requests.storage` to `2Gi`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `MariaDB` CR is updated in your cluster. + +Now, `gitops` operator will detect the volume changes and create a `VolumeExpansion` MariaDBOpsRequest to update the `MariaDB` database volume. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,MariaDB,kfops -n demo +NAME TYPE VERSION STATUS AGE +MariaDB.kubedb.com/MariaDB-prod kubedb.com/v1 3.9.0 Ready 23m + +NAME AGE +MariaDB.gitops.kubedb.com/MariaDB-prod 23m + +NAME TYPE STATUS AGE +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-horizontalscaling-j0wni6 HorizontalScaling Successful 13m +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-verticalscaling-tfkvi8 VerticalScaling Successful 8m29s +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-volumeexpansion-41xthr VolumeExpansion Successful 19m +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the pvc size, +```bash +$ kubectl get pvc -n demo -l 'app.kubernetes.io/instance=MariaDB-prod' +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE +MariaDB-prod-data-MariaDB-prod-broker-0 Bound pvc-2afd4835-5686-492b-be93-c6e040e0a6c6 2Gi RWO Standard 3h39m +MariaDB-prod-data-MariaDB-prod-broker-1 Bound pvc-aaf994cc-6b04-4c37-80d5-5e966dad8487 2Gi RWO Standard 3h39m +MariaDB-prod-data-MariaDB-prod-controller-0 Bound pvc-82d2b233-203d-4df2-a0fd-ecedbc0825b7 2Gi RWO Standard 3h39m +MariaDB-prod-data-MariaDB-prod-controller-1 Bound pvc-91852c29-ab1a-48ad-9255-a0b15d5a7515 2Gi RWO Standard 3h39m + +``` + +## Reconfigure MariaDB + +At first, we will create a secret containing `user.conf` file with required configuration settings. +To know more about this configuration file, check [here](/docs/guides/MariaDB/configuration/MariaDB-combined.md) +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: new-kf-combined-custom-config + namespace: demo +stringData: + server.properties: |- + log.retention.hours=125 +``` + +Now, we will add this file to `kubedb /kf-configuration.yaml`. + +```bash +$ tree . +├── kubedb +│ ├── kf-configuration.yaml +│ └── MariaDB.yaml +1 directories, 2 files +``` + +Update the `MariaDB.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: MariaDB +metadata: + name: MariaDB-prod + namespace: demo +spec: + configSecret: + name: new-kf-combined-custom-config + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `MariaDB` CR is updated in your cluster. + +Now, `gitops` operator will detect the configuration changes and create a `Reconfigure` MariaDBOpsRequest to update the `MariaDB` database configuration. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,MariaDB,kfops -n demo +NAME TYPE VERSION STATUS AGE +MariaDB.kubedb.com/MariaDB-prod kubedb.com/v1 3.9.0 Ready 74m + +NAME AGE +MariaDB.gitops.kubedb.com/MariaDB-prod 74m + +NAME TYPE STATUS AGE +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-reconfigure-ukj41o Reconfigure Successful 24m +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-volumeexpansion-41xthr VolumeExpansion Successful 70m + +``` + + + +> We can also reconfigure the parameters creating another secret and reference the secret in the `configSecret` field. Also you can remove the `configSecret` field to use the default parameters. + +### Rotate MariaDB Auth + +To do that, create a `kubernetes.io/basic-auth` type k8s secret with the new username and password. + +We will do that using gitops, create the file `kubedb /kf-auth.yaml` with the following content, + +```bash +kubectl create secret generic kf-rotate-auth -n demo \ +--type=kubernetes.io/basic-auth \ +--from-literal=username=MariaDB \ +--from-literal=password=MariaDB-secret +secret/kf-rotate-auth created + +``` + + + +Update the `MariaDB.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: MariaDB +metadata: + name: MariaDB-prod + namespace: demo +spec: + authSecret: + kind: Secret + name: kf-rotate-auth + configSecret: + name: new-kf-combined-custom-config + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Change the `authSecret` field to `kf-rotate-auth`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `MariaDB` CR is updated in your cluster. + +Now, `gitops` operator will detect the auth changes and create a `RotateAuth` MariaDBOpsRequest to update the `MariaDB` database auth. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,MariaDB,kfops -n demo +NAME TYPE VERSION STATUS AGE +MariaDB.kubedb.com/MariaDB-prod kubedb.com/v1 3.9.0 Ready 7m11s + +NAME AGE +MariaDB.gitops.kubedb.com/MariaDB-prod 7m11s + +NAME TYPE STATUS AGE +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-reconfigure-ukj41o Reconfigure Successful 17h +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-rotate-auth-43ris8 RotateAuth Successful 28m +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-volumeexpansion-41xthr VolumeExpansion Successful 17h + +``` + + +### TLS configuration + +We can add, rotate or remove TLS configuration using `gitops`. + +To add tls, we are going to create an example `Issuer` that will be used to enable SSL/TLS in MariaDB. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. + +- Start off by generating a ca certificates using openssl. + +```bash +$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=ca/O=kubedb" +Generating a RSA private key +................+++++ +........................+++++ +writing new private key to './ca.key' +----- +``` + +- Now we are going to create a ca-secret using the certificate files that we have just generated. + +```bash +$ kubectl create secret tls MariaDB-ca \ + --cert=ca.crt \ + --key=ca.key \ + --namespace=demo +secret/MariaDB-ca created +``` + +Now, Let's create an `Issuer` using the `MariaDB-ca` secret that we have just created. The `YAML` file looks like this: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: kf-issuer + namespace: demo +spec: + ca: + secretName: MariaDB-ca +``` + +Let's add that to our `kubedb /kf-issuer.yaml` file. File structure will look like this, +```bash +$ tree . +├── kubedb +│ ├── kf-configuration.yaml +│ ├── kf-issuer.yaml +│ └── MariaDB.yaml +1 directories, 4 files +``` + +Update the `MariaDB.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: MariaDB +metadata: + name: MariaDB-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Add `sslMode` and `tls` fields in the spec. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `MariaDB` CR is updated in your cluster. + +Now, `gitops` operator will detect the tls changes and create a `ReconfigureTLS` MariaDBOpsRequest to update the `MariaDB` database tls. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,MariaDB,kfops,pods -n demo +NAME TYPE VERSION STATUS AGE +MariaDB.kubedb.com/MariaDB-prod kubedb.com/v1 3.9.0 Ready 41m + +NAME AGE +MariaDB.gitops.kubedb.com/MariaDB-prod 75m + +NAME TYPE STATUS AGE +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-reconfigure-ukj41o Reconfigure Successful 5d18h +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 9m18s +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-rotate-auth-43ris8 RotateAuth Successful 5d1h +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-volumeexpansion-41xthr VolumeExpansion Successful 5d19h + +``` + + +> We can also rotate the certificates updating `.spec.tls.certificates` field. Also you can remove the `.spec.tls` field to remove tls for MariaDB. + +### Update Version + +List MariaDB versions using `kubectl get MariaDBversion` and choose desired version that is compatible for upgrade from current version. Check the version constraints and ops request [here](/docs/guides/MariaDB/update-version/update-version.md). + +Let's choose `4.0.0` in this example. + +Update the `MariaDB.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: MariaDB +metadata: + name: MariaDB-prod + namespace: demo +spec: + version: 4.0.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `version` field to `17.4`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `MariaDB` CR is updated in your cluster. + +Now, `gitops` operator will detect the version changes and create a `VersionUpdate` MariaDBOpsRequest to update the `MariaDB` database version. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,MariaDB,kfops -n demo +NAME TYPE VERSION STATUS AGE +MariaDB.kubedb.com/MariaDB-prod kubedb.com/v1 4.0.0 Ready 3h47m + +NAME AGE +MariaDB.gitops.kubedb.com/MariaDB-prod 3h47m + +NAME TYPE STATUS AGE +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-reconfigure-ukj41o Reconfigure Successful 5d22h +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 4h16m +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-rotate-auth-43ris8 RotateAuth Successful 5d6h +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-versionupdate-wyn2dp UpdateVersion Successful 3h51m +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-volumeexpansion-41xthr VolumeExpansion Successful 5d23h +``` + + +Now, we are going to verify whether the `MariaDB`, `PetSet` and it's `Pod` have updated with new image. Let's check, + +```bash +$ kubectl get MariaDB -n demo MariaDB-prod -o=jsonpath='{.spec.version}{"\n"}' +4.0.0 + +$ kubectl get petset -n demo MariaDB-prod-broker -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/MariaDB:4.0.0@sha256:42a79fe8f14b00b1c76d135bbbaf7605b8c66f45cf3eb749c59138f6df288b31 + +$ kubectl get pod -n demo MariaDB-prod-broker-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/MariaDB:4.0.0@sha256:42a79fe8f14b00b1c76d135bbbaf7605b8c66f45cf3eb749c59138f6df288b31 +``` + +### Enable Monitoring + +If you already don't have a Prometheus server running, deploy one following tutorial from [here](https://github.com/appscode/third-party-tools/blob/master/monitoring/prometheus/operator/README.md#deploy-prometheus-server). + +Update the `MariaDB.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: MariaDB +metadata: + name: MariaDB-prod + namespace: demo +spec: + version: 4.0.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: MariaDB + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + monitor: + agent: prometheus.io/operator + prometheus: + exporter: + port: 9091 + serviceMonitor: + labels: + release: prometheus + interval: 10s + deletionPolicy: WipeOut +``` + +Add `monitor` field in the spec. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `MariaDB` CR is updated in your cluster. + +Now, `gitops` operator will detect the monitoring changes and create a `Restart` MariaDBOpsRequest to add the `MariaDB` database monitoring. List the resources created by `gitops` operator in the `demo` namespace. +```bash +$ kubectl get MariaDBes.gitops.kubedb.com,MariaDBes.kubedb.com,MariaDBopsrequest -n demo +NAME TYPE VERSION STATUS AGE +MariaDB.kubedb.com/MariaDB-prod kubedb.com/v1 4.0.0 Ready 5h12m + +NAME AGE +MariaDB.gitops.kubedb.com/MariaDB-prod 5h12m + +NAME TYPE STATUS AGE +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-reconfigure-ukj41o Reconfigure Successful 6d +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 5h42m +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-restart-ljpqih Restart Successful 3m51s +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-rotate-auth-43ris8 RotateAuth Successful 5d7h +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-versionupdate-wyn2dp UpdateVersion Successful 5h16m +MariaDBopsrequest.ops.kubedb.com/MariaDB-prod-volumeexpansion-41xthr VolumeExpansion Successful 6d + +``` + +Verify the monitoring is enabled by checking the prometheus targets. + +There are some other fields that will trigger `Restart` ops request. +- `.spec.monitor` +- `.spec.spec.archiver` +- `.spec.remoteReplica` +- `spec.replication` +- `.spec.standbyMode` +- `.spec.streamingMode` +- `.spec.enforceGroup` +- `.spec.sslMode` etc. + + +## Next Steps + +[//]: # (- Learn MariaDB [GitOps](/docs/guides/MariaDB/concepts/MariaDB-gitops.md)) +- Learn MariaDB Scaling + - [Horizontal Scaling](/docs/guides/MariaDB/scaling/horizontal-scaling/combined.md) + - [Vertical Scaling](/docs/guides/MariaDB/scaling/vertical-scaling/combined.md) +- Learn Version Update Ops Request and Constraints [here](/docs/guides/MariaDB/update-version/overview.md) +- Monitor your MariaDBQL database with KubeDB using [built-in Prometheus](/docs/guides/MariaDB/monitoring/using-builtin-prometheus.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/mariadb/gitops/overview.md b/docs/guides/mariadb/gitops/overview.md new file mode 100644 index 000000000..80ab6a2fc --- /dev/null +++ b/docs/guides/mariadb/gitops/overview.md @@ -0,0 +1,50 @@ +--- +title: MariaDB Gitops Overview +description: MariaDB Gitops Overview +menu: + docs_{{ .version }}: + identifier: es-gitops-overview + name: Overview + parent: es-gitops + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# GitOps Overview for MariaDB + +This guide will give you an overview of how KubeDB `gitops` operator works with MariaDB databases using the `gitops.kubedb.com/v1alpha1` API. It will help you understand the GitOps workflow for +managing MariaDB databases in Kubernetes. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [MariaDB](/docs/guides/mariadb/concepts/mariadb/index.md) + - [MariaDBOpsRequest](/docs/guides/mariadb/concepts/opsrequest/index.md) + + + +## Workflow GitOps with MariaDB + +The following diagram shows how the `KubeDB` GitOps Operator used to sync with your database. Open the image in a new tab to see the enlarged version. + + +
+ + GitOps Flow + +
Fig: GitOps process of MariaDB
+ +
+ +1. **Define GitOps MariaDB**: Create Custom Resource (CR) of kind `MariaDB` using the `gitops.kubedb.com/v1alpha1` API. +2. **Store in Git**: Push the CR to a Git repository. +3. **Automated Deployment**: Use a GitOps tool (like `ArgoCD` or `FluxCD`) to monitor the Git repository and synchronize the state of the Kubernetes cluster with the desired state defined in Git. +4. **Create Database**: The GitOps operator creates a corresponding KubeDB MariaDB CR in the Kubernetes cluster to deploy the database. +5. **Handle Updates**: When you update the MariaDBGitOps CR, the operator generates an Ops Request to safely apply the update(e.g. `VerticalScaling`, `HorizontalScaling`, `VolumeExapnsion`, `Reconfigure`, `RotateAuth`, `ReconfigureTLS`, `VersionUpdate`, ans `Restart`. + +This flow makes managing MariaDB databases efficient, reliable, and fully integrated with GitOps practices. + +In the next doc, we are going to show a step by step guide on running MariaDB using GitOps. diff --git a/docs/guides/mongodb/gitops/_index.md b/docs/guides/mongodb/gitops/_index.md new file mode 100644 index 000000000..cc82b5f6b --- /dev/null +++ b/docs/guides/mongodb/gitops/_index.md @@ -0,0 +1,10 @@ +--- +title: Elasticsearch Gitops +menu: + docs_{{ .version }}: + identifier: es-gitops + name: Elasticsearch Gitops + parent: es-elasticsearch-guides + weight: 70 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/mongodb/gitops/gitops.md b/docs/guides/mongodb/gitops/gitops.md new file mode 100644 index 000000000..332c4f29d --- /dev/null +++ b/docs/guides/mongodb/gitops/gitops.md @@ -0,0 +1,900 @@ +--- +title: Elasticsearch Gitops Overview +description: Elasticsearch Gitops Overview +menu: + docs_{{ .version }}: + identifier: es-gitops-overview + name: Overview + parent: es-gitops + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + + + +> New to KubeDB? Please start [here](/docs/README.md). + +# GitOps Elasticsearch using KubeDB GitOps Operator + +This guide will show you how to use `KubeDB` GitOps operator to create Elasticsearch database and manage updates using GitOps workflow. + +## 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` operator in your cluster following the steps [here](/docs/setup/README.md). Pass `--set kubedb-crd-manager.installGitOpsCRDs=true` in the kubedb installation process to enable `GitOps` operator. + +- You need to install GitOps tools like `ArgoCD` or `FluxCD` and configure with your Git Repository to monitor the Git repository and synchronize the state of the Kubernetes cluster with the desired state defined in Git. + + ```bash + $ kubectl create ns monitoring + namespace/monitoring created + + $ kubectl create ns demo + namespace/demo created + ``` +> Note: YAML files used in this tutorial are stored in [docs/examples/Elasticsearch](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/Elasticsearch) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +We are going to use `ArgoCD` in this tutorial. You can install `ArgoCD` in your cluster by following the steps [here](https://argo-cd.readthedocs.io/en/stable/getting_started/). Also, you need to install `argocd` CLI in your local machine. You can install `argocd` CLI by following the steps [here](https://argo-cd.readthedocs.io/en/stable/cli_installation/). + +## Creating Apps via CLI + +### For Public Repository +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace +``` + +### For Private Repository +#### Using HTTPS +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace --username --password +``` + +#### Using SSH +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace --ssh-private-key-path ~/.ssh/id_rsa +``` + +## Create Elasticsearch Database using GitOps + +### Create a Elasticsearch GitOps CR +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: es-gitops + namespace: demo +spec: + version: xpack-8.2.3 + enableSSL: true + replicas: 2 + storageType: Durable + storage: + storageClassName: longhorn + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Create a directory like below, +```bash +$ tree . +├── kubedb + └── Elasticsearch.yaml +1 directories, 1 files +``` + +Now commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is created in your cluster. + +Our `gitops` operator will create an actual `Elasticsearch` database CR in the cluster. List the resources created by `gitops` operator in the `demo` namespace. + + +```bash +$ kubectl get Elasticsearch.gitops.kubedb.com,Elasticsearch.kubedb.com -n demo +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 2m56s + +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 2m56s +``` + +List the resources created by `kubedb` operator created for `kubedb.com/v1` Elasticsearch. + +```bash +$ kubectl get petset,pod,secret,service,appbinding -n demo -l 'app.kubernetes.io/instance=Elasticsearch-prod' +NAME AGE +petset.apps.k8s.appscode.com/Elasticsearch-prod-broker 4m49s +petset.apps.k8s.appscode.com/Elasticsearch-prod-controller 4m47s + +NAME READY STATUS RESTARTS AGE +pod/Elasticsearch-prod-broker-0 1/1 Running 0 4m48s +pod/Elasticsearch-prod-broker-1 1/1 Running 0 4m42s +pod/Elasticsearch-prod-controller-0 1/1 Running 0 4m47s +pod/Elasticsearch-prod-controller-1 1/1 Running 0 4m40s + +NAME TYPE DATA AGE +secret/Elasticsearch-prod-auth kubernetes.io/basic-auth 2 4m51s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/Elasticsearch-prod-pods ClusterIP None 9092/TCP,9093/TCP,29092/TCP 4m51s + +NAME TYPE VERSION AGE +appbinding.appcatalog.appscode.com/Elasticsearch-prod kubedb.com/Elasticsearch 3.9.0 4m47s +``` + +## Update Elasticsearch Database using GitOps + +### Scale Elasticsearch Database Resources + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + storageType: Durable + deletionPolicy: WipeOut + ``` + +Resource Requests and Limits are updated to `700m` CPU and `2Gi` Memory. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the resource changes and create a `ElasticsearchOpsRequest` to update the `Elasticsearch` database. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ $ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 22h + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 22h + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-verticalscaling-i0kr1l VerticalScaling Successful 2s +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the one of the pod, +```bash +$ kubectl get pod -n demo Elasticsearch-prod-broker-0 -o json | jq '.spec.containers[0].resources' +{ + "limits": { + "memory": "1536Mi" + }, + "requests": { + "cpu": "500m", + "memory": "1536Mi" + } +} +``` + +### Scale Elasticsearch Replicas +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `replicas` to `3`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. +Now, `gitops` operator will detect the replica changes and create a `HorizontalScaling` ElasticsearchOpsRequest to update the `Elasticsearch` database replicas. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 22h + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 22h + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-horizontalscaling-j0wni6 HorizontalScaling Successful 13m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-verticalscaling-tfkvi8 VerticalScaling Successful 8m29s +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the number of pods, +```bash +$ kubectl get pod -n demo -l 'app.kubernetes.io/instance=Elasticsearch-prod' +NAME READY STATUS RESTARTS AGE +Elasticsearch-prod-broker-0 1/1 Running 0 34m +Elasticsearch-prod-broker-1 1/1 Running 0 33m +Elasticsearch-prod-broker-2 1/1 Running 0 33m +Elasticsearch-prod-controller-0 1/1 Running 0 32m +Elasticsearch-prod-controller-1 1/1 Running 0 31m +Elasticsearch-prod-controller-2 1/1 Running 0 31m +``` + +We can also scale down the replicas by updating the `replicas` fields. + +### Expand Elasticsearch Volume + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `storage.resources.requests.storage` to `2Gi`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the volume changes and create a `VolumeExpansion` ElasticsearchOpsRequest to update the `Elasticsearch` database volume. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 23m + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 23m + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-horizontalscaling-j0wni6 HorizontalScaling Successful 13m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-verticalscaling-tfkvi8 VerticalScaling Successful 8m29s +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 19m +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the pvc size, +```bash +$ kubectl get pvc -n demo -l 'app.kubernetes.io/instance=Elasticsearch-prod' +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE +Elasticsearch-prod-data-Elasticsearch-prod-broker-0 Bound pvc-2afd4835-5686-492b-be93-c6e040e0a6c6 2Gi RWO Standard 3h39m +Elasticsearch-prod-data-Elasticsearch-prod-broker-1 Bound pvc-aaf994cc-6b04-4c37-80d5-5e966dad8487 2Gi RWO Standard 3h39m +Elasticsearch-prod-data-Elasticsearch-prod-controller-0 Bound pvc-82d2b233-203d-4df2-a0fd-ecedbc0825b7 2Gi RWO Standard 3h39m +Elasticsearch-prod-data-Elasticsearch-prod-controller-1 Bound pvc-91852c29-ab1a-48ad-9255-a0b15d5a7515 2Gi RWO Standard 3h39m + +``` + +## Reconfigure Elasticsearch + +At first, we will create a secret containing `user.conf` file with required configuration settings. +To know more about this configuration file, check [here](/docs/guides/Elasticsearch/configuration/Elasticsearch-combined.md) +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: new-kf-combined-custom-config + namespace: demo +stringData: + server.properties: |- + log.retention.hours=125 +``` + +Now, we will add this file to `kubedb /kf-configuration.yaml`. + +```bash +$ tree . +├── kubedb +│ ├── kf-configuration.yaml +│ └── Elasticsearch.yaml +1 directories, 2 files +``` + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + configSecret: + name: new-kf-combined-custom-config + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the configuration changes and create a `Reconfigure` ElasticsearchOpsRequest to update the `Elasticsearch` database configuration. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 74m + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 74m + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfigure-ukj41o Reconfigure Successful 24m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 70m + +``` + + + +> We can also reconfigure the parameters creating another secret and reference the secret in the `configSecret` field. Also you can remove the `configSecret` field to use the default parameters. + +### Rotate Elasticsearch Auth + +To do that, create a `kubernetes.io/basic-auth` type k8s secret with the new username and password. + +We will do that using gitops, create the file `kubedb /kf-auth.yaml` with the following content, + +```bash +kubectl create secret generic kf-rotate-auth -n demo \ +--type=kubernetes.io/basic-auth \ +--from-literal=username=Elasticsearch \ +--from-literal=password=Elasticsearch-secret +secret/kf-rotate-auth created + +``` + + + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + authSecret: + kind: Secret + name: kf-rotate-auth + configSecret: + name: new-kf-combined-custom-config + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Change the `authSecret` field to `kf-rotate-auth`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the auth changes and create a `RotateAuth` ElasticsearchOpsRequest to update the `Elasticsearch` database auth. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 7m11s + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 7m11s + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfigure-ukj41o Reconfigure Successful 17h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-rotate-auth-43ris8 RotateAuth Successful 28m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 17h + +``` + + +### TLS configuration + +We can add, rotate or remove TLS configuration using `gitops`. + +To add tls, we are going to create an example `Issuer` that will be used to enable SSL/TLS in Elasticsearch. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. + +- Start off by generating a ca certificates using openssl. + +```bash +$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=ca/O=kubedb" +Generating a RSA private key +................+++++ +........................+++++ +writing new private key to './ca.key' +----- +``` + +- Now we are going to create a ca-secret using the certificate files that we have just generated. + +```bash +$ kubectl create secret tls Elasticsearch-ca \ + --cert=ca.crt \ + --key=ca.key \ + --namespace=demo +secret/Elasticsearch-ca created +``` + +Now, Let's create an `Issuer` using the `Elasticsearch-ca` secret that we have just created. The `YAML` file looks like this: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: kf-issuer + namespace: demo +spec: + ca: + secretName: Elasticsearch-ca +``` + +Let's add that to our `kubedb /kf-issuer.yaml` file. File structure will look like this, +```bash +$ tree . +├── kubedb +│ ├── kf-configuration.yaml +│ ├── kf-issuer.yaml +│ └── Elasticsearch.yaml +1 directories, 4 files +``` + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Add `sslMode` and `tls` fields in the spec. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the tls changes and create a `ReconfigureTLS` ElasticsearchOpsRequest to update the `Elasticsearch` database tls. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops,pods -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 41m + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 75m + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfigure-ukj41o Reconfigure Successful 5d18h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 9m18s +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-rotate-auth-43ris8 RotateAuth Successful 5d1h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 5d19h + +``` + + +> We can also rotate the certificates updating `.spec.tls.certificates` field. Also you can remove the `.spec.tls` field to remove tls for Elasticsearch. + +### Update Version + +List Elasticsearch versions using `kubectl get Elasticsearchversion` and choose desired version that is compatible for upgrade from current version. Check the version constraints and ops request [here](/docs/guides/Elasticsearch/update-version/update-version.md). + +Let's choose `4.0.0` in this example. + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 4.0.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `version` field to `17.4`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the version changes and create a `VersionUpdate` ElasticsearchOpsRequest to update the `Elasticsearch` database version. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 4.0.0 Ready 3h47m + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 3h47m + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfigure-ukj41o Reconfigure Successful 5d22h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 4h16m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-rotate-auth-43ris8 RotateAuth Successful 5d6h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-versionupdate-wyn2dp UpdateVersion Successful 3h51m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 5d23h +``` + + +Now, we are going to verify whether the `Elasticsearch`, `PetSet` and it's `Pod` have updated with new image. Let's check, + +```bash +$ kubectl get Elasticsearch -n demo Elasticsearch-prod -o=jsonpath='{.spec.version}{"\n"}' +4.0.0 + +$ kubectl get petset -n demo Elasticsearch-prod-broker -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/Elasticsearch:4.0.0@sha256:42a79fe8f14b00b1c76d135bbbaf7605b8c66f45cf3eb749c59138f6df288b31 + +$ kubectl get pod -n demo Elasticsearch-prod-broker-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/Elasticsearch:4.0.0@sha256:42a79fe8f14b00b1c76d135bbbaf7605b8c66f45cf3eb749c59138f6df288b31 +``` + +### Enable Monitoring + +If you already don't have a Prometheus server running, deploy one following tutorial from [here](https://github.com/appscode/third-party-tools/blob/master/monitoring/prometheus/operator/README.md#deploy-prometheus-server). + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 4.0.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + monitor: + agent: prometheus.io/operator + prometheus: + exporter: + port: 9091 + serviceMonitor: + labels: + release: prometheus + interval: 10s + deletionPolicy: WipeOut +``` + +Add `monitor` field in the spec. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the monitoring changes and create a `Restart` ElasticsearchOpsRequest to add the `Elasticsearch` database monitoring. List the resources created by `gitops` operator in the `demo` namespace. +```bash +$ kubectl get Elasticsearches.gitops.kubedb.com,Elasticsearches.kubedb.com,Elasticsearchopsrequest -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 4.0.0 Ready 5h12m + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 5h12m + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfigure-ukj41o Reconfigure Successful 6d +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 5h42m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-restart-ljpqih Restart Successful 3m51s +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-rotate-auth-43ris8 RotateAuth Successful 5d7h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-versionupdate-wyn2dp UpdateVersion Successful 5h16m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 6d + +``` + +Verify the monitoring is enabled by checking the prometheus targets. + +There are some other fields that will trigger `Restart` ops request. +- `.spec.monitor` +- `.spec.spec.archiver` +- `.spec.remoteReplica` +- `spec.replication` +- `.spec.standbyMode` +- `.spec.streamingMode` +- `.spec.enforceGroup` +- `.spec.sslMode` etc. + + +## Next Steps + +[//]: # (- Learn Elasticsearch [GitOps](/docs/guides/Elasticsearch/concepts/Elasticsearch-gitops.md)) +- Learn Elasticsearch Scaling + - [Horizontal Scaling](/docs/guides/Elasticsearch/scaling/horizontal-scaling/combined.md) + - [Vertical Scaling](/docs/guides/Elasticsearch/scaling/vertical-scaling/combined.md) +- Learn Version Update Ops Request and Constraints [here](/docs/guides/Elasticsearch/update-version/overview.md) +- Monitor your ElasticsearchQL database with KubeDB using [built-in Prometheus](/docs/guides/Elasticsearch/monitoring/using-builtin-prometheus.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/mongodb/gitops/overview.md b/docs/guides/mongodb/gitops/overview.md new file mode 100644 index 000000000..bfa01c2ff --- /dev/null +++ b/docs/guides/mongodb/gitops/overview.md @@ -0,0 +1,50 @@ +--- +title: Elasticsearch Gitops Overview +description: Elasticsearch Gitops Overview +menu: + docs_{{ .version }}: + identifier: es-gitops-overview + name: Overview + parent: es-gitops + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# GitOps Overview for Elasticsearch + +This guide will give you an overview of how KubeDB `gitops` operator works with Elasticsearch databases using the `gitops.kubedb.com/v1alpha1` API. It will help you understand the GitOps workflow for +managing Elasticsearch databases in Kubernetes. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Elasticsearch](/docs/guides/elasticsearch/concepts/elasticsearch/index.md) + - [ElasticsearchOpsRequest](/docs/guides/elasticsearch/concepts/elasticsearch-ops-request/index.md) + + + +## Workflow GitOps with Elasticsearch + +The following diagram shows how the `KubeDB` GitOps Operator used to sync with your database. Open the image in a new tab to see the enlarged version. + + +
+ + GitOps Flow + +
Fig: GitOps process of Elasticsearch
+ +
+ +1. **Define GitOps Elasticsearch**: Create Custom Resource (CR) of kind `Elasticsearch` using the `gitops.kubedb.com/v1alpha1` API. +2. **Store in Git**: Push the CR to a Git repository. +3. **Automated Deployment**: Use a GitOps tool (like `ArgoCD` or `FluxCD`) to monitor the Git repository and synchronize the state of the Kubernetes cluster with the desired state defined in Git. +4. **Create Database**: The GitOps operator creates a corresponding KubeDB Elasticsearch CR in the Kubernetes cluster to deploy the database. +5. **Handle Updates**: When you update the ElasticsearchGitOps CR, the operator generates an Ops Request to safely apply the update(e.g. `VerticalScaling`, `HorizontalScaling`, `VolumeExapnsion`, `Reconfigure`, `RotateAuth`, `ReconfigureTLS`, `VersionUpdate`, ans `Restart`. + +This flow makes managing Elasticsearch databases efficient, reliable, and fully integrated with GitOps practices. + +In the next doc, we are going to show a step by step guide on running Elasticsearch using GitOps. diff --git a/docs/guides/mssqlserver/gitops/_index.md b/docs/guides/mssqlserver/gitops/_index.md new file mode 100644 index 000000000..cc82b5f6b --- /dev/null +++ b/docs/guides/mssqlserver/gitops/_index.md @@ -0,0 +1,10 @@ +--- +title: Elasticsearch Gitops +menu: + docs_{{ .version }}: + identifier: es-gitops + name: Elasticsearch Gitops + parent: es-elasticsearch-guides + weight: 70 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/mssqlserver/gitops/gitops.md b/docs/guides/mssqlserver/gitops/gitops.md new file mode 100644 index 000000000..332c4f29d --- /dev/null +++ b/docs/guides/mssqlserver/gitops/gitops.md @@ -0,0 +1,900 @@ +--- +title: Elasticsearch Gitops Overview +description: Elasticsearch Gitops Overview +menu: + docs_{{ .version }}: + identifier: es-gitops-overview + name: Overview + parent: es-gitops + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + + + +> New to KubeDB? Please start [here](/docs/README.md). + +# GitOps Elasticsearch using KubeDB GitOps Operator + +This guide will show you how to use `KubeDB` GitOps operator to create Elasticsearch database and manage updates using GitOps workflow. + +## 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` operator in your cluster following the steps [here](/docs/setup/README.md). Pass `--set kubedb-crd-manager.installGitOpsCRDs=true` in the kubedb installation process to enable `GitOps` operator. + +- You need to install GitOps tools like `ArgoCD` or `FluxCD` and configure with your Git Repository to monitor the Git repository and synchronize the state of the Kubernetes cluster with the desired state defined in Git. + + ```bash + $ kubectl create ns monitoring + namespace/monitoring created + + $ kubectl create ns demo + namespace/demo created + ``` +> Note: YAML files used in this tutorial are stored in [docs/examples/Elasticsearch](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/Elasticsearch) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +We are going to use `ArgoCD` in this tutorial. You can install `ArgoCD` in your cluster by following the steps [here](https://argo-cd.readthedocs.io/en/stable/getting_started/). Also, you need to install `argocd` CLI in your local machine. You can install `argocd` CLI by following the steps [here](https://argo-cd.readthedocs.io/en/stable/cli_installation/). + +## Creating Apps via CLI + +### For Public Repository +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace +``` + +### For Private Repository +#### Using HTTPS +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace --username --password +``` + +#### Using SSH +```bash +argocd app create kubedb --repo --path kubedb --dest-server https://kubernetes.default.svc --dest-namespace --ssh-private-key-path ~/.ssh/id_rsa +``` + +## Create Elasticsearch Database using GitOps + +### Create a Elasticsearch GitOps CR +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: es-gitops + namespace: demo +spec: + version: xpack-8.2.3 + enableSSL: true + replicas: 2 + storageType: Durable + storage: + storageClassName: longhorn + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Create a directory like below, +```bash +$ tree . +├── kubedb + └── Elasticsearch.yaml +1 directories, 1 files +``` + +Now commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is created in your cluster. + +Our `gitops` operator will create an actual `Elasticsearch` database CR in the cluster. List the resources created by `gitops` operator in the `demo` namespace. + + +```bash +$ kubectl get Elasticsearch.gitops.kubedb.com,Elasticsearch.kubedb.com -n demo +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 2m56s + +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 2m56s +``` + +List the resources created by `kubedb` operator created for `kubedb.com/v1` Elasticsearch. + +```bash +$ kubectl get petset,pod,secret,service,appbinding -n demo -l 'app.kubernetes.io/instance=Elasticsearch-prod' +NAME AGE +petset.apps.k8s.appscode.com/Elasticsearch-prod-broker 4m49s +petset.apps.k8s.appscode.com/Elasticsearch-prod-controller 4m47s + +NAME READY STATUS RESTARTS AGE +pod/Elasticsearch-prod-broker-0 1/1 Running 0 4m48s +pod/Elasticsearch-prod-broker-1 1/1 Running 0 4m42s +pod/Elasticsearch-prod-controller-0 1/1 Running 0 4m47s +pod/Elasticsearch-prod-controller-1 1/1 Running 0 4m40s + +NAME TYPE DATA AGE +secret/Elasticsearch-prod-auth kubernetes.io/basic-auth 2 4m51s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/Elasticsearch-prod-pods ClusterIP None 9092/TCP,9093/TCP,29092/TCP 4m51s + +NAME TYPE VERSION AGE +appbinding.appcatalog.appscode.com/Elasticsearch-prod kubedb.com/Elasticsearch 3.9.0 4m47s +``` + +## Update Elasticsearch Database using GitOps + +### Scale Elasticsearch Database Resources + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + storageType: Durable + deletionPolicy: WipeOut + ``` + +Resource Requests and Limits are updated to `700m` CPU and `2Gi` Memory. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the resource changes and create a `ElasticsearchOpsRequest` to update the `Elasticsearch` database. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ $ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 22h + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 22h + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-verticalscaling-i0kr1l VerticalScaling Successful 2s +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the one of the pod, +```bash +$ kubectl get pod -n demo Elasticsearch-prod-broker-0 -o json | jq '.spec.containers[0].resources' +{ + "limits": { + "memory": "1536Mi" + }, + "requests": { + "cpu": "500m", + "memory": "1536Mi" + } +} +``` + +### Scale Elasticsearch Replicas +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1540Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + storageClassName: local-path + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `replicas` to `3`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. +Now, `gitops` operator will detect the replica changes and create a `HorizontalScaling` ElasticsearchOpsRequest to update the `Elasticsearch` database replicas. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 22h + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 22h + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-horizontalscaling-j0wni6 HorizontalScaling Successful 13m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-verticalscaling-tfkvi8 VerticalScaling Successful 8m29s +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the number of pods, +```bash +$ kubectl get pod -n demo -l 'app.kubernetes.io/instance=Elasticsearch-prod' +NAME READY STATUS RESTARTS AGE +Elasticsearch-prod-broker-0 1/1 Running 0 34m +Elasticsearch-prod-broker-1 1/1 Running 0 33m +Elasticsearch-prod-broker-2 1/1 Running 0 33m +Elasticsearch-prod-controller-0 1/1 Running 0 32m +Elasticsearch-prod-controller-1 1/1 Running 0 31m +Elasticsearch-prod-controller-2 1/1 Running 0 31m +``` + +We can also scale down the replicas by updating the `replicas` fields. + +### Expand Elasticsearch Volume + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `storage.resources.requests.storage` to `2Gi`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the volume changes and create a `VolumeExpansion` ElasticsearchOpsRequest to update the `Elasticsearch` database volume. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 23m + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 23m + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-horizontalscaling-j0wni6 HorizontalScaling Successful 13m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-verticalscaling-tfkvi8 VerticalScaling Successful 8m29s +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 19m +``` + +After Ops Request becomes `Successful`, We can validate the changes by checking the pvc size, +```bash +$ kubectl get pvc -n demo -l 'app.kubernetes.io/instance=Elasticsearch-prod' +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE +Elasticsearch-prod-data-Elasticsearch-prod-broker-0 Bound pvc-2afd4835-5686-492b-be93-c6e040e0a6c6 2Gi RWO Standard 3h39m +Elasticsearch-prod-data-Elasticsearch-prod-broker-1 Bound pvc-aaf994cc-6b04-4c37-80d5-5e966dad8487 2Gi RWO Standard 3h39m +Elasticsearch-prod-data-Elasticsearch-prod-controller-0 Bound pvc-82d2b233-203d-4df2-a0fd-ecedbc0825b7 2Gi RWO Standard 3h39m +Elasticsearch-prod-data-Elasticsearch-prod-controller-1 Bound pvc-91852c29-ab1a-48ad-9255-a0b15d5a7515 2Gi RWO Standard 3h39m + +``` + +## Reconfigure Elasticsearch + +At first, we will create a secret containing `user.conf` file with required configuration settings. +To know more about this configuration file, check [here](/docs/guides/Elasticsearch/configuration/Elasticsearch-combined.md) +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: new-kf-combined-custom-config + namespace: demo +stringData: + server.properties: |- + log.retention.hours=125 +``` + +Now, we will add this file to `kubedb /kf-configuration.yaml`. + +```bash +$ tree . +├── kubedb +│ ├── kf-configuration.yaml +│ └── Elasticsearch.yaml +1 directories, 2 files +``` + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + configSecret: + name: new-kf-combined-custom-config + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the configuration changes and create a `Reconfigure` ElasticsearchOpsRequest to update the `Elasticsearch` database configuration. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 74m + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 74m + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfigure-ukj41o Reconfigure Successful 24m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 70m + +``` + + + +> We can also reconfigure the parameters creating another secret and reference the secret in the `configSecret` field. Also you can remove the `configSecret` field to use the default parameters. + +### Rotate Elasticsearch Auth + +To do that, create a `kubernetes.io/basic-auth` type k8s secret with the new username and password. + +We will do that using gitops, create the file `kubedb /kf-auth.yaml` with the following content, + +```bash +kubectl create secret generic kf-rotate-auth -n demo \ +--type=kubernetes.io/basic-auth \ +--from-literal=username=Elasticsearch \ +--from-literal=password=Elasticsearch-secret +secret/kf-rotate-auth created + +``` + + + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + authSecret: + kind: Secret + name: kf-rotate-auth + configSecret: + name: new-kf-combined-custom-config + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Change the `authSecret` field to `kf-rotate-auth`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the auth changes and create a `RotateAuth` ElasticsearchOpsRequest to update the `Elasticsearch` database auth. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 7m11s + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 7m11s + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfigure-ukj41o Reconfigure Successful 17h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-rotate-auth-43ris8 RotateAuth Successful 28m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 17h + +``` + + +### TLS configuration + +We can add, rotate or remove TLS configuration using `gitops`. + +To add tls, we are going to create an example `Issuer` that will be used to enable SSL/TLS in Elasticsearch. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. + +- Start off by generating a ca certificates using openssl. + +```bash +$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=ca/O=kubedb" +Generating a RSA private key +................+++++ +........................+++++ +writing new private key to './ca.key' +----- +``` + +- Now we are going to create a ca-secret using the certificate files that we have just generated. + +```bash +$ kubectl create secret tls Elasticsearch-ca \ + --cert=ca.crt \ + --key=ca.key \ + --namespace=demo +secret/Elasticsearch-ca created +``` + +Now, Let's create an `Issuer` using the `Elasticsearch-ca` secret that we have just created. The `YAML` file looks like this: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: kf-issuer + namespace: demo +spec: + ca: + secretName: Elasticsearch-ca +``` + +Let's add that to our `kubedb /kf-issuer.yaml` file. File structure will look like this, +```bash +$ tree . +├── kubedb +│ ├── kf-configuration.yaml +│ ├── kf-issuer.yaml +│ └── Elasticsearch.yaml +1 directories, 4 files +``` + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 3.9.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Add `sslMode` and `tls` fields in the spec. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the tls changes and create a `ReconfigureTLS` ElasticsearchOpsRequest to update the `Elasticsearch` database tls. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops,pods -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 3.9.0 Ready 41m + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 75m + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfigure-ukj41o Reconfigure Successful 5d18h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 9m18s +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-rotate-auth-43ris8 RotateAuth Successful 5d1h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 5d19h + +``` + + +> We can also rotate the certificates updating `.spec.tls.certificates` field. Also you can remove the `.spec.tls` field to remove tls for Elasticsearch. + +### Update Version + +List Elasticsearch versions using `kubectl get Elasticsearchversion` and choose desired version that is compatible for upgrade from current version. Check the version constraints and ops request [here](/docs/guides/Elasticsearch/update-version/update-version.md). + +Let's choose `4.0.0` in this example. + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 4.0.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + deletionPolicy: WipeOut +``` + +Update the `version` field to `17.4`. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the version changes and create a `VersionUpdate` ElasticsearchOpsRequest to update the `Elasticsearch` database version. List the resources created by `gitops` operator in the `demo` namespace. + +```bash +$ kubectl get kf,Elasticsearch,kfops -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 4.0.0 Ready 3h47m + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 3h47m + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfigure-ukj41o Reconfigure Successful 5d22h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 4h16m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-rotate-auth-43ris8 RotateAuth Successful 5d6h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-versionupdate-wyn2dp UpdateVersion Successful 3h51m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 5d23h +``` + + +Now, we are going to verify whether the `Elasticsearch`, `PetSet` and it's `Pod` have updated with new image. Let's check, + +```bash +$ kubectl get Elasticsearch -n demo Elasticsearch-prod -o=jsonpath='{.spec.version}{"\n"}' +4.0.0 + +$ kubectl get petset -n demo Elasticsearch-prod-broker -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/Elasticsearch:4.0.0@sha256:42a79fe8f14b00b1c76d135bbbaf7605b8c66f45cf3eb749c59138f6df288b31 + +$ kubectl get pod -n demo Elasticsearch-prod-broker-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}' +ghcr.io/appscode-images/Elasticsearch:4.0.0@sha256:42a79fe8f14b00b1c76d135bbbaf7605b8c66f45cf3eb749c59138f6df288b31 +``` + +### Enable Monitoring + +If you already don't have a Prometheus server running, deploy one following tutorial from [here](https://github.com/appscode/third-party-tools/blob/master/monitoring/prometheus/operator/README.md#deploy-prometheus-server). + +Update the `Elasticsearch.yaml` with the following, +```yaml +apiVersion: gitops.kubedb.com/v1alpha1 +kind: Elasticsearch +metadata: + name: Elasticsearch-prod + namespace: demo +spec: + version: 4.0.0 + topology: + broker: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + controller: + podTemplate: + spec: + containers: + - name: Elasticsearch + resources: + limits: + memory: 1536Mi + requests: + cpu: 500m + memory: 1536Mi + replicas: 2 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + storageClassName: Standard + storageType: Durable + monitor: + agent: prometheus.io/operator + prometheus: + exporter: + port: 9091 + serviceMonitor: + labels: + release: prometheus + interval: 10s + deletionPolicy: WipeOut +``` + +Add `monitor` field in the spec. Commit the changes and push to your Git repository. Your repository is synced with `ArgoCD` and the `Elasticsearch` CR is updated in your cluster. + +Now, `gitops` operator will detect the monitoring changes and create a `Restart` ElasticsearchOpsRequest to add the `Elasticsearch` database monitoring. List the resources created by `gitops` operator in the `demo` namespace. +```bash +$ kubectl get Elasticsearches.gitops.kubedb.com,Elasticsearches.kubedb.com,Elasticsearchopsrequest -n demo +NAME TYPE VERSION STATUS AGE +Elasticsearch.kubedb.com/Elasticsearch-prod kubedb.com/v1 4.0.0 Ready 5h12m + +NAME AGE +Elasticsearch.gitops.kubedb.com/Elasticsearch-prod 5h12m + +NAME TYPE STATUS AGE +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfigure-ukj41o Reconfigure Successful 6d +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-reconfiguretls-r4mx7v ReconfigureTLS Successful 5h42m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-restart-ljpqih Restart Successful 3m51s +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-rotate-auth-43ris8 RotateAuth Successful 5d7h +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-versionupdate-wyn2dp UpdateVersion Successful 5h16m +Elasticsearchopsrequest.ops.kubedb.com/Elasticsearch-prod-volumeexpansion-41xthr VolumeExpansion Successful 6d + +``` + +Verify the monitoring is enabled by checking the prometheus targets. + +There are some other fields that will trigger `Restart` ops request. +- `.spec.monitor` +- `.spec.spec.archiver` +- `.spec.remoteReplica` +- `spec.replication` +- `.spec.standbyMode` +- `.spec.streamingMode` +- `.spec.enforceGroup` +- `.spec.sslMode` etc. + + +## Next Steps + +[//]: # (- Learn Elasticsearch [GitOps](/docs/guides/Elasticsearch/concepts/Elasticsearch-gitops.md)) +- Learn Elasticsearch Scaling + - [Horizontal Scaling](/docs/guides/Elasticsearch/scaling/horizontal-scaling/combined.md) + - [Vertical Scaling](/docs/guides/Elasticsearch/scaling/vertical-scaling/combined.md) +- Learn Version Update Ops Request and Constraints [here](/docs/guides/Elasticsearch/update-version/overview.md) +- Monitor your ElasticsearchQL database with KubeDB using [built-in Prometheus](/docs/guides/Elasticsearch/monitoring/using-builtin-prometheus.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/mssqlserver/gitops/overview.md b/docs/guides/mssqlserver/gitops/overview.md new file mode 100644 index 000000000..bfa01c2ff --- /dev/null +++ b/docs/guides/mssqlserver/gitops/overview.md @@ -0,0 +1,50 @@ +--- +title: Elasticsearch Gitops Overview +description: Elasticsearch Gitops Overview +menu: + docs_{{ .version }}: + identifier: es-gitops-overview + name: Overview + parent: es-gitops + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# GitOps Overview for Elasticsearch + +This guide will give you an overview of how KubeDB `gitops` operator works with Elasticsearch databases using the `gitops.kubedb.com/v1alpha1` API. It will help you understand the GitOps workflow for +managing Elasticsearch databases in Kubernetes. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Elasticsearch](/docs/guides/elasticsearch/concepts/elasticsearch/index.md) + - [ElasticsearchOpsRequest](/docs/guides/elasticsearch/concepts/elasticsearch-ops-request/index.md) + + + +## Workflow GitOps with Elasticsearch + +The following diagram shows how the `KubeDB` GitOps Operator used to sync with your database. Open the image in a new tab to see the enlarged version. + + +
+ + GitOps Flow + +
Fig: GitOps process of Elasticsearch
+ +
+ +1. **Define GitOps Elasticsearch**: Create Custom Resource (CR) of kind `Elasticsearch` using the `gitops.kubedb.com/v1alpha1` API. +2. **Store in Git**: Push the CR to a Git repository. +3. **Automated Deployment**: Use a GitOps tool (like `ArgoCD` or `FluxCD`) to monitor the Git repository and synchronize the state of the Kubernetes cluster with the desired state defined in Git. +4. **Create Database**: The GitOps operator creates a corresponding KubeDB Elasticsearch CR in the Kubernetes cluster to deploy the database. +5. **Handle Updates**: When you update the ElasticsearchGitOps CR, the operator generates an Ops Request to safely apply the update(e.g. `VerticalScaling`, `HorizontalScaling`, `VolumeExapnsion`, `Reconfigure`, `RotateAuth`, `ReconfigureTLS`, `VersionUpdate`, ans `Restart`. + +This flow makes managing Elasticsearch databases efficient, reliable, and fully integrated with GitOps practices. + +In the next doc, we are going to show a step by step guide on running Elasticsearch using GitOps.