From 22b9da1b760b80e2681488cd8e83a07efebdc72d Mon Sep 17 00:00:00 2001 From: Tamal Saha Date: Thu, 30 Apr 2026 11:09:53 +0600 Subject: [PATCH 1/5] docs(documentdb): add guides and examples --- .../documentdb/quickstart/standalone.yaml | 16 ++ docs/guides/documentdb/README.md | 58 ++++++ docs/guides/documentdb/_index.md | 10 + docs/guides/documentdb/concepts/_index.md | 10 + docs/guides/documentdb/concepts/catalog.md | 47 +++++ docs/guides/documentdb/concepts/documentdb.md | 51 +++++ docs/guides/documentdb/concepts/opsrequest.md | 42 ++++ .../guides/documentdb/configuration/_index.md | 10 + .../documentdb/configuration/overview.md | 44 +++++ docs/guides/documentdb/custom-rbac/_index.md | 10 + .../custom-rbac/using-custom-rbac.md | 161 ++++++++++++++++ docs/guides/documentdb/ops-request/_index.md | 10 + .../guides/documentdb/ops-request/overview.md | 29 +++ .../documentdb/private-registry/_index.md | 10 + .../using-private-registry.md | 143 ++++++++++++++ docs/guides/documentdb/quickstart/_index.md | 10 + .../documentdb/quickstart/quickstart.md | 84 ++++++++ docs/guides/documentdb/quickstart/rbac.md | 180 ++++++++++++++++++ 18 files changed, 925 insertions(+) create mode 100644 docs/examples/documentdb/quickstart/standalone.yaml create mode 100644 docs/guides/documentdb/README.md create mode 100644 docs/guides/documentdb/_index.md create mode 100644 docs/guides/documentdb/concepts/_index.md create mode 100644 docs/guides/documentdb/concepts/catalog.md create mode 100644 docs/guides/documentdb/concepts/documentdb.md create mode 100644 docs/guides/documentdb/concepts/opsrequest.md create mode 100644 docs/guides/documentdb/configuration/_index.md create mode 100644 docs/guides/documentdb/configuration/overview.md create mode 100644 docs/guides/documentdb/custom-rbac/_index.md create mode 100644 docs/guides/documentdb/custom-rbac/using-custom-rbac.md create mode 100644 docs/guides/documentdb/ops-request/_index.md create mode 100644 docs/guides/documentdb/ops-request/overview.md create mode 100644 docs/guides/documentdb/private-registry/_index.md create mode 100644 docs/guides/documentdb/private-registry/using-private-registry.md create mode 100644 docs/guides/documentdb/quickstart/_index.md create mode 100644 docs/guides/documentdb/quickstart/quickstart.md create mode 100644 docs/guides/documentdb/quickstart/rbac.md diff --git a/docs/examples/documentdb/quickstart/standalone.yaml b/docs/examples/documentdb/quickstart/standalone.yaml new file mode 100644 index 000000000..19393ef0d --- /dev/null +++ b/docs/examples/documentdb/quickstart/standalone.yaml @@ -0,0 +1,16 @@ +apiVersion: kubedb.com/v1alpha2 +kind: DocumentDB +metadata: + name: documentdb + namespace: demo +spec: + version: "pg17-0.109.0" + storageType: Durable + deletionPolicy: Delete + replicas: 1 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi diff --git a/docs/guides/documentdb/README.md b/docs/guides/documentdb/README.md new file mode 100644 index 000000000..61dc00e6b --- /dev/null +++ b/docs/guides/documentdb/README.md @@ -0,0 +1,58 @@ +--- +title: DocumentDB +menu: + docs_{{ .version }}: + identifier: documentdb-readme + name: DocumentDB + parent: documentdb-guides + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +url: /docs/{{ .version }}/guides/documentdb/ +aliases: + - /docs/{{ .version }}/guides/documentdb/README/ +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Overview + +KubeDB supports Amazon DocumentDB-compatible workloads through the `DocumentDB` CRD. + +## Supported DocumentDB Features + +| Features | Availability | +|-----------------------------------|:------------:| +| Standalone provisioning | ✓ | +| Persistent volume | ✓ | +| Replicas | ✓ | +| Deletion policy | ✓ | + +## Example DocumentDB Manifest + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: DocumentDB +metadata: + name: documentdb +spec: + version: "pg17-0.109.0" + storageType: Durable + deletionPolicy: Delete + replicas: 1 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi +``` + +## User Guide + +- [Quickstart DocumentDB](/docs/guides/documentdb/quickstart/quickstart.md) with KubeDB operator. +- [DocumentDB CRD Concept](/docs/guides/documentdb/concepts/documentdb.md). +- [DocumentDBVersion CRD Concept](/docs/guides/documentdb/concepts/catalog.md). +- [DocumentDBOpsRequest CRD Concept](/docs/guides/documentdb/concepts/opsrequest.md). +- [Configuration](/docs/guides/documentdb/configuration/overview.md) for replicas, auth, pod, and service settings. +- [Ops Request](/docs/guides/documentdb/ops-request/overview.md). \ No newline at end of file diff --git a/docs/guides/documentdb/_index.md b/docs/guides/documentdb/_index.md new file mode 100644 index 000000000..431376f45 --- /dev/null +++ b/docs/guides/documentdb/_index.md @@ -0,0 +1,10 @@ +--- +title: DocumentDB +menu: + docs_{{ .version }}: + identifier: documentdb-guides + name: DocumentDB + parent: guides + weight: 13 +menu_name: docs_{{ .version }} +--- \ No newline at end of file diff --git a/docs/guides/documentdb/concepts/_index.md b/docs/guides/documentdb/concepts/_index.md new file mode 100644 index 000000000..bb3603877 --- /dev/null +++ b/docs/guides/documentdb/concepts/_index.md @@ -0,0 +1,10 @@ +--- +title: DocumentDB Concepts +menu: + docs_{{ .version }}: + identifier: documentdb-concepts + name: Concepts + parent: documentdb-guides + weight: 15 +menu_name: docs_{{ .version }} +--- \ No newline at end of file diff --git a/docs/guides/documentdb/concepts/catalog.md b/docs/guides/documentdb/concepts/catalog.md new file mode 100644 index 000000000..44ec33353 --- /dev/null +++ b/docs/guides/documentdb/concepts/catalog.md @@ -0,0 +1,47 @@ +--- +title: DocumentDBVersion CRD +menu: + docs_{{ .version }}: + identifier: documentdb-catalog-concepts + name: DocumentDBVersion + parent: documentdb-concepts-documentdb + weight: 15 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# DocumentDBVersion + +## What is DocumentDBVersion + +`DocumentDBVersion` is the catalog CRD that defines which DocumentDB engine image and related components KubeDB should use. + +The value in `DocumentDB.spec.version` must match an available `DocumentDBVersion` resource. + +## DocumentDBVersion Specification + +```yaml +apiVersion: catalog.kubedb.com/v1alpha1 +kind: DocumentDBVersion +metadata: + name: "pg17-0.109.0" +spec: + version: "pg17-0.109.0" + db: + image: "kubedb/documentdb:pg17-0.109.0" + deprecated: false +``` + +## Key fields + +- `metadata.name` is referenced from `DocumentDB.spec.version`. +- `spec.version` is the released database engine version. +- `spec.db.image` is the runtime image used by KubeDB. +- `spec.deprecated` indicates if this catalog entry is deprecated. + +## Next Steps + +- Read the [DocumentDB CRD concept](/docs/guides/documentdb/concepts/documentdb.md). +- Run the [DocumentDB quickstart](/docs/guides/documentdb/quickstart/quickstart.md). \ No newline at end of file diff --git a/docs/guides/documentdb/concepts/documentdb.md b/docs/guides/documentdb/concepts/documentdb.md new file mode 100644 index 000000000..3960588a2 --- /dev/null +++ b/docs/guides/documentdb/concepts/documentdb.md @@ -0,0 +1,51 @@ +--- +title: DocumentDB CRD +menu: + docs_{{ .version }}: + identifier: documentdb-concepts-documentdb + name: DocumentDB + parent: documentdb-concepts + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# DocumentDB + +## What is DocumentDB + +`DocumentDB` is a Kubernetes `CustomResourceDefinition` (CRD) in KubeDB that manages DocumentDB-compatible databases. + +## DocumentDB Spec + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: DocumentDB +metadata: + name: documentdb + namespace: demo +spec: + version: "pg17-0.109.0" + storageType: Durable + deletionPolicy: Delete + replicas: 1 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi +``` + +### Key fields + +- `spec.version` is required and points to a `DocumentDBVersion` resource. +- `spec.replicas` sets number of database instances. +- `spec.storageType` can be `Durable` or `Ephemeral`. +- `spec.storage` defines PVC settings for persistent data. +- `spec.authSecret` optionally references credentials. +- `spec.podTemplate` optionally customizes pods. +- `spec.serviceTemplates` optionally customizes services. +- `spec.deletionPolicy` controls object deletion behavior. \ No newline at end of file diff --git a/docs/guides/documentdb/concepts/opsrequest.md b/docs/guides/documentdb/concepts/opsrequest.md new file mode 100644 index 000000000..fc2ea23ab --- /dev/null +++ b/docs/guides/documentdb/concepts/opsrequest.md @@ -0,0 +1,42 @@ +--- +title: DocumentDBOpsRequest CRD +menu: + docs_{{ .version }}: + identifier: documentdb-opsrequest-concepts + name: DocumentDBOpsRequest + parent: documentdb-concepts-documentdb + weight: 25 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# DocumentDBOpsRequest + +## What is DocumentDBOpsRequest + +`DocumentDBOpsRequest` is the operations CRD KubeDB uses for day-2 lifecycle changes of DocumentDB databases when supported in a release. + +## Current support status + +Based on [new_db.md](/new_db.md), no DocumentDB operation types are currently listed. + +## Expected CRD shape + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: DocumentDBOpsRequest +metadata: + name: documentdb-ops-sample + namespace: demo +spec: + type: Restart + databaseRef: + name: documentdb +``` + +## Next Steps + +- Track [DocumentDB ops overview](/docs/guides/documentdb/ops-request/overview.md) for support updates. +- Use [DocumentDB configuration guide](/docs/guides/documentdb/configuration/overview.md) for declarative spec updates. \ No newline at end of file diff --git a/docs/guides/documentdb/configuration/_index.md b/docs/guides/documentdb/configuration/_index.md new file mode 100644 index 000000000..3efa97d68 --- /dev/null +++ b/docs/guides/documentdb/configuration/_index.md @@ -0,0 +1,10 @@ +--- +title: DocumentDB Configuration +menu: + docs_{{ .version }}: + identifier: documentdb-configuration + name: Configuration + parent: documentdb-guides + weight: 20 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/documentdb/configuration/overview.md b/docs/guides/documentdb/configuration/overview.md new file mode 100644 index 000000000..ce095cf27 --- /dev/null +++ b/docs/guides/documentdb/configuration/overview.md @@ -0,0 +1,44 @@ +--- +title: DocumentDB Configuration Overview +menu: + docs_{{ .version }}: + identifier: documentdb-configuration-overview + name: Overview + parent: documentdb-configuration + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +# DocumentDB Configuration + +This guide shows the main DocumentDB configuration fields you can tune before or after initial deployment. + +## Before You Begin + +- Review the base manifest used in [Quickstart](/docs/guides/documentdb/quickstart/quickstart.md). +- Identify whether you need to change topology, authentication, services, or probes. + +## Common Configuration Fields + +- spec.replicas for number of database instances. +- spec.authSecret for custom credentials. +- spec.podTemplate for pod-level customization. +- spec.serviceTemplates for service exposure. +- spec.healthChecker for probe timing and thresholds. + +## How to Apply Configuration + +Update the DocumentDB resource manifest with the desired fields and apply it again. + +```bash +kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/quickstart/standalone.yaml +kubectl edit documentdb -n demo documentdb +``` + +## Verify + +```bash +kubectl get documentdb -n demo documentdb -o yaml +kubectl describe documentdb -n demo documentdb +``` diff --git a/docs/guides/documentdb/custom-rbac/_index.md b/docs/guides/documentdb/custom-rbac/_index.md new file mode 100644 index 000000000..87409d66f --- /dev/null +++ b/docs/guides/documentdb/custom-rbac/_index.md @@ -0,0 +1,10 @@ +--- +title: Run DocumentDB with Custom RBAC resources +menu: + docs_{{ .version }}: + identifier: documentdb-custom-rbac + name: Custom RBAC + parent: documentdb-guides + weight: 90 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/documentdb/custom-rbac/using-custom-rbac.md b/docs/guides/documentdb/custom-rbac/using-custom-rbac.md new file mode 100644 index 000000000..96025b5e5 --- /dev/null +++ b/docs/guides/documentdb/custom-rbac/using-custom-rbac.md @@ -0,0 +1,161 @@ +--- +title: Run DocumentDB with Custom RBAC resources +menu: + docs_{{ .version }}: + identifier: documentdb-custom-rbac-quickstart + name: Custom RBAC + parent: documentdb-custom-rbac + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Using Custom RBAC Resources + +KubeDB supports finer user control over role based access permissions provided to a DocumentDB instance. This tutorial will show you how to use KubeDB to run a DocumentDB instance with custom RBAC resources. + +## Before You Begin + +At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + +```bash +$ kubectl create ns demo +namespace/demo created +``` + +## Overview + +KubeDB allows users to provide custom RBAC resources, namely, `ServiceAccount`, `Role`, and `RoleBinding` for DocumentDB. This is provided via the `spec.podTemplate.spec.serviceAccountName` field in DocumentDB CRD. If this field is left empty, the KubeDB operator will create a service account name matching the DocumentDB CRD name. + +If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Users are responsible for providing necessary access permissions manually. + +## Custom RBAC for DocumentDB + +At first, let's create a `Service Account` in `demo` namespace. + +```bash +$ kubectl create serviceaccount -n demo my-custom-serviceaccount +serviceaccount/my-custom-serviceaccount created +``` + +Now, we need to create a role that has necessary access permissions for the DocumentDB database named `quick-docdb`. + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/custom-rbac/docdb-custom-role.yaml +role.rbac.authorization.k8s.io/my-custom-role created +``` + +Below is the YAML for the Role we just created. + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role + namespace: demo +rules: +- apiGroups: + - apps + resourceNames: + - quick-docdb + resources: + - petsets + verbs: + - get +- apiGroups: + - kubedb.com + resourceNames: + - quick-docdb + resources: + - documentdbs + verbs: + - get +- apiGroups: + - "" + resources: + - pods + verbs: + - list + - patch +- apiGroups: + - "" + resources: + - pods/exec + verbs: + - create +- apiGroups: + - "" + resources: + - configmaps + verbs: + - create + - get + - update +``` + +Now create a `RoleBinding` to bind this `Role` with the already created service account. + +```bash +$ kubectl create rolebinding my-custom-rolebinding \ + --role=my-custom-role \ + --serviceaccount=demo:my-custom-serviceaccount \ + --namespace=demo +rolebinding.rbac.authorization.k8s.io/my-custom-rolebinding created +``` + +Now, create a DocumentDB CRD specifying `spec.podTemplate.spec.serviceAccountName` field to `my-custom-serviceaccount`. + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: DocumentDB +metadata: + name: quick-docdb + namespace: demo +spec: + version: "5.0.6" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/custom-rbac/docdb-custom-db.yaml +documentdb.kubedb.com/quick-docdb created +``` + +Check that the pod is running: + +```bash +$ kubectl get pod -n demo quick-docdb-0 +NAME READY STATUS RESTARTS AGE +quick-docdb-0 1/1 Running 0 3m +``` + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +kubectl patch -n demo documentdb/quick-docdb -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo documentdb/quick-docdb + +kubectl delete -n demo serviceaccount my-custom-serviceaccount +kubectl delete -n demo role my-custom-role +kubectl delete -n demo rolebinding my-custom-rolebinding +kubectl delete ns demo +``` diff --git a/docs/guides/documentdb/ops-request/_index.md b/docs/guides/documentdb/ops-request/_index.md new file mode 100644 index 000000000..b9ebd21f5 --- /dev/null +++ b/docs/guides/documentdb/ops-request/_index.md @@ -0,0 +1,10 @@ +--- +title: Ops Request +menu: + docs_{{ .version }}: + identifier: documentdb-ops-request + name: Ops Request + parent: documentdb-guides + weight: 30 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/documentdb/ops-request/overview.md b/docs/guides/documentdb/ops-request/overview.md new file mode 100644 index 000000000..ad6231cae --- /dev/null +++ b/docs/guides/documentdb/ops-request/overview.md @@ -0,0 +1,29 @@ +--- +title: DocumentDB Ops Request Overview +menu: + docs_{{ .version }}: + identifier: documentdb-ops-request-overview + name: Overview + parent: documentdb-ops-request + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +# DocumentDB Ops Request + +This page tracks DocumentDB operations supported by the new database matrix used for these guides. + +## Before You Begin + +- Deploy a DocumentDB database first using the [quickstart guide](/docs/guides/documentdb/quickstart/quickstart.md). +- Confirm the current support list in [new_db.md](/new_db.md) for your release. + +## Current Status + +Based on [new_db.md](/new_db.md), no DocumentDB ops request types are listed yet. + +## What to Check Next + +- Watch future KubeDB releases for DocumentDB `OpsRequest` support. +- Use the DocumentDB configuration guide for declarative spec-level changes that do not require an ops workflow. diff --git a/docs/guides/documentdb/private-registry/_index.md b/docs/guides/documentdb/private-registry/_index.md new file mode 100644 index 000000000..3e1fa56b4 --- /dev/null +++ b/docs/guides/documentdb/private-registry/_index.md @@ -0,0 +1,10 @@ +--- +title: Run DocumentDB using Private Registry +menu: + docs_{{ .version }}: + identifier: documentdb-private-registry + name: Private Registry + parent: documentdb-guides + weight: 120 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/documentdb/private-registry/using-private-registry.md b/docs/guides/documentdb/private-registry/using-private-registry.md new file mode 100644 index 000000000..4919e23ca --- /dev/null +++ b/docs/guides/documentdb/private-registry/using-private-registry.md @@ -0,0 +1,143 @@ +--- +title: Run DocumentDB using Private Registry +menu: + docs_{{ .version }}: + identifier: documentdb-using-private-registry + name: Quickstart + parent: documentdb-private-registry + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Using Private Docker Registry + +KubeDB supports using private Docker registries. This tutorial will show you how to run KubeDB managed DocumentDB database using private Docker images. + +## 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/). + +To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + +```bash +$ kubectl create ns demo +namespace/demo created +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/documentdb](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/documentdb) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Prepare Private Docker Registry + +- You will also need a docker private [registry](https://docs.docker.com/registry/) or [private repository](https://docs.docker.com/docker-hub/repos/#private-repositories). In this tutorial we will use private repository of [docker hub](https://hub.docker.com/). + +- You have to push the required images from KubeDB's [Docker hub account](https://hub.docker.com/r/kubedb/) into your private registry. For DocumentDB, push the `DB_IMAGE` of the following DocumentDBVersions, where `deprecated` is not true, to your private registry. + + ```bash + $ kubectl get documentdbversions -o=custom-columns=NAME:.metadata.name,VERSION:.spec.version,DB_IMAGE:.spec.db.image,DEPRECATED:.spec.deprecated + NAME VERSION DB_IMAGE DEPRECATED + 5.0.6 5.0.6 kubedb/documentdb:5.0.6 + ``` + + Docker hub repositories: + +- [kubedb/documentdb](https://hub.docker.com/r/kubedb/documentdb) + +## Create ImagePullSecret + +Run the following command to create an image pull secret for your private Docker registry: + +```bash +$ kubectl create secret docker-registry -n demo myregistrykey \ + --docker-server=DOCKER_REGISTRY_SERVER \ + --docker-username=DOCKER_USER \ + --docker-email=DOCKER_EMAIL \ + --docker-password=DOCKER_PASSWORD +secret/myregistrykey created +``` + +## Install KubeDB Operator + +When installing KubeDB operator, set the flags `--docker-registry` and `--image-pull-secret` to appropriate values. +Follow the steps to [install KubeDB operator](/docs/setup/README.md) properly in cluster so that it points to the DOCKER_REGISTRY you wish to pull images from. + +## Create DocumentDBVersion CRD + +KubeDB uses images specified in DocumentDBVersion CRD for database. You have to create a DocumentDBVersion CRD specifying images from your private registry. Then, point this DocumentDBVersion CRD in `spec.version` field of DocumentDB object. For more details about DocumentDBVersion CRD, please visit [here](/docs/guides/documentdb/concepts/catalog.md). + +Here, is an example of DocumentDBVersion CRD. Replace `PRIVATE_REGISTRY` with your private registry. + +```yaml +apiVersion: catalog.kubedb.com/v1alpha1 +kind: DocumentDBVersion +metadata: + name: "5.0.6" +spec: + db: + image: PRIVATE_REGISTRY/documentdb:5.0.6 + version: "5.0.6" +``` + +Now, create the DocumentDBVersion CRD: + +```bash +$ kubectl apply -f pvt-documentdbversion.yaml +documentdbversion.catalog.kubedb.com/5.0.6 created +``` + +## Deploy DocumentDB from Private Registry + +While deploying DocumentDB from private repository, you have to add `myregistrykey` secret in DocumentDB `spec.podTemplate.spec.imagePullSecrets` and specify your private version in `spec.version` field. + +Below is the DocumentDB object we will create in this tutorial: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: DocumentDB +metadata: + name: pvt-reg-docdb + namespace: demo +spec: + version: "5.0.6" + storageType: Durable + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + podTemplate: + spec: + imagePullSecrets: + - name: myregistrykey + deletionPolicy: WipeOut +``` + +Now run the command to create this DocumentDB object: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/private-registry/pvt-reg-docdb.yaml +documentdb.kubedb.com/pvt-reg-docdb created +``` + +To check if the images pulled successfully from the repository, see if the DocumentDB is in Running state: + +```bash +$ kubectl get pods -n demo --selector="app.kubernetes.io/instance=pvt-reg-docdb" +NAME READY STATUS RESTARTS AGE +pvt-reg-docdb-0 1/1 Running 0 3m +``` + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +kubectl patch -n demo documentdb/pvt-reg-docdb -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo documentdb/pvt-reg-docdb + +kubectl delete ns demo +``` diff --git a/docs/guides/documentdb/quickstart/_index.md b/docs/guides/documentdb/quickstart/_index.md new file mode 100644 index 000000000..b1eb85e89 --- /dev/null +++ b/docs/guides/documentdb/quickstart/_index.md @@ -0,0 +1,10 @@ +--- +title: DocumentDB Quickstart +menu: + docs_{{ .version }}: + identifier: documentdb-quickstart + name: Quickstart + parent: documentdb-guides + weight: 15 +menu_name: docs_{{ .version }} +--- \ No newline at end of file diff --git a/docs/guides/documentdb/quickstart/quickstart.md b/docs/guides/documentdb/quickstart/quickstart.md new file mode 100644 index 000000000..86f1de408 --- /dev/null +++ b/docs/guides/documentdb/quickstart/quickstart.md @@ -0,0 +1,84 @@ +--- +title: DocumentDB Quickstart +menu: + docs_{{ .version }}: + identifier: documentdb-quickstart-overview + name: Overview + parent: documentdb-quickstart + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Running DocumentDB + +This tutorial shows how to run a DocumentDB database with KubeDB. + +> Note: YAML files used in this tutorial are stored in [docs/examples/documentdb/quickstart](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/documentdb/quickstart). + +## Before You Begin + +- Ensure you have a Kubernetes cluster and `kubectl` access. +- Install KubeDB from [/docs/setup/README.md](/docs/setup/README.md). +- This tutorial uses `docs/examples/documentdb/quickstart/standalone.yaml` as the working example manifest. +- Create namespace: + +```bash +kubectl create ns demo +``` + +## Check Available StorageClass + +```bash +kubectl get storageclass +``` + +## Check Available DocumentDBVersion + +```bash +kubectl get documentdbversions +``` + +## Create a DocumentDB Database + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: DocumentDB +metadata: + name: documentdb + namespace: demo +spec: + version: "pg17-0.109.0" + storageType: Durable + deletionPolicy: Delete + replicas: 1 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi +``` + +```bash +kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/quickstart/standalone.yaml +kubectl get documentdb -n demo documentdb -w +``` + +## Verify DocumentDB Database + +```bash +kubectl get documentdb -n demo +kubectl describe documentdb -n demo documentdb +``` + +When `status.phase` is `Ready`, the database is ready to accept connections. + +## Cleaning up + +```bash +kubectl delete documentdb -n demo documentdb +kubectl delete ns demo +``` \ No newline at end of file diff --git a/docs/guides/documentdb/quickstart/rbac.md b/docs/guides/documentdb/quickstart/rbac.md new file mode 100644 index 000000000..7da96f158 --- /dev/null +++ b/docs/guides/documentdb/quickstart/rbac.md @@ -0,0 +1,180 @@ +--- +title: RBAC for DocumentDB +menu: + docs_{{ .version }}: + identifier: documentdb-rbac-quickstart + name: RBAC + parent: documentdb-quickstart + weight: 15 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# RBAC Permissions for DocumentDB + +When RBAC is enabled in your cluster, KubeDB automatically creates the necessary Role, ServiceAccount, and RoleBinding for each DocumentDB instance. This tutorial explains what permissions are granted and how to verify them. + +Here is the list of additional permissions required by the PetSet of DocumentDB: + +| Kubernetes Resource | Resource Names | Permission required | +|---------------------|-----------------------|---------------------| +| petsets | `{documentdb-name}` | get | +| pods | | list, patch | +| pods/exec | | create | +| documentdbs | | get | +| configmaps | `{documentdb-name}` | get, update, create | + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +- To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + +```bash +$ kubectl create ns demo +namespace/demo created +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/documentdb](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/documentdb) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Create a DocumentDB Database + +Below is the DocumentDB object created in this tutorial. + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: DocumentDB +metadata: + name: quick-docdb + namespace: demo +spec: + version: "5.0.6" + storageType: Durable + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: Delete +``` + +Create the above DocumentDB object: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/quickstart/quick-docdb.yaml +documentdb.kubedb.com/quick-docdb created +``` + +When this DocumentDB object is created, KubeDB operator creates Role, ServiceAccount and RoleBinding with the matching DocumentDB name and uses that ServiceAccount in the corresponding PetSet. + +### Role + +```bash +$ kubectl get role -n demo quick-docdb -o yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + labels: + app.kubernetes.io/component: database + app.kubernetes.io/instance: quick-docdb + app.kubernetes.io/managed-by: kubedb.com + app.kubernetes.io/name: documentdbs.kubedb.com + name: quick-docdb + namespace: demo +rules: +- apiGroups: + - apps + resourceNames: + - quick-docdb + resources: + - petsets + verbs: + - get +- apiGroups: + - kubedb.com + resourceNames: + - quick-docdb + resources: + - documentdbs + verbs: + - get +- apiGroups: + - "" + resources: + - pods + verbs: + - get + - list + - patch +- apiGroups: + - "" + resources: + - pods/exec + verbs: + - create +- apiGroups: + - "" + resources: + - configmaps + verbs: + - create + - get + - update +``` + +### ServiceAccount + +```bash +$ kubectl get serviceaccount -n demo quick-docdb -o yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + labels: + app.kubernetes.io/component: database + app.kubernetes.io/instance: quick-docdb + app.kubernetes.io/managed-by: kubedb.com + app.kubernetes.io/name: documentdbs.kubedb.com + name: quick-docdb + namespace: demo +``` + +### RoleBinding + +```bash +$ kubectl get rolebinding -n demo quick-docdb -o yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + labels: + app.kubernetes.io/component: database + app.kubernetes.io/instance: quick-docdb + app.kubernetes.io/managed-by: kubedb.com + app.kubernetes.io/name: documentdbs.kubedb.com + name: quick-docdb + namespace: demo +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: quick-docdb +subjects: +- kind: ServiceAccount + name: quick-docdb + namespace: demo +``` + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +kubectl patch -n demo documentdb/quick-docdb -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo documentdb/quick-docdb + +kubectl delete ns demo +``` From 23b67b06adac711dce03af1da31d5a7a437b03a6 Mon Sep 17 00:00:00 2001 From: sabnaj Date: Wed, 6 May 2026 16:56:15 +0600 Subject: [PATCH 2/5] documentdb-docs Signed-off-by: sabnaj --- .../initialization/script-documentdb.yaml | 19 ++ docs/guides/documentdb/concepts/catalog.md | 39 ++- docs/guides/documentdb/concepts/documentdb.md | 262 +++++++++++++++++- docs/guides/documentdb/concepts/opsrequest.md | 42 --- .../guides/documentdb/configuration/_index.md | 10 - .../documentdb/configuration/overview.md | 44 --- .../custom-rbac/using-custom-rbac.md | 228 +++++++++++++-- .../documentdb/initialization/_index.md | 12 + .../initialization/script_source.md | 246 ++++++++++++++++ docs/guides/documentdb/ops-request/_index.md | 10 - .../guides/documentdb/ops-request/overview.md | 29 -- 11 files changed, 768 insertions(+), 173 deletions(-) create mode 100644 docs/examples/documentdb/initialization/script-documentdb.yaml delete mode 100644 docs/guides/documentdb/concepts/opsrequest.md delete mode 100644 docs/guides/documentdb/configuration/_index.md delete mode 100644 docs/guides/documentdb/configuration/overview.md create mode 100644 docs/guides/documentdb/initialization/_index.md create mode 100644 docs/guides/documentdb/initialization/script_source.md delete mode 100644 docs/guides/documentdb/ops-request/_index.md delete mode 100644 docs/guides/documentdb/ops-request/overview.md diff --git a/docs/examples/documentdb/initialization/script-documentdb.yaml b/docs/examples/documentdb/initialization/script-documentdb.yaml new file mode 100644 index 000000000..ed8e5cd89 --- /dev/null +++ b/docs/examples/documentdb/initialization/script-documentdb.yaml @@ -0,0 +1,19 @@ +apiVersion: kubedb.com/v1alpha2 +kind: DocumentDB +metadata: + name: script-documentdb + namespace: demo +spec: + version: "pg17-0.109.0" + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi + init: + script: + configMap: + name: documentdb-init-script + diff --git a/docs/guides/documentdb/concepts/catalog.md b/docs/guides/documentdb/concepts/catalog.md index 44ec33353..4b9d7a308 100644 --- a/docs/guides/documentdb/concepts/catalog.md +++ b/docs/guides/documentdb/concepts/catalog.md @@ -16,9 +16,12 @@ section_menu_id: guides ## What is DocumentDBVersion -`DocumentDBVersion` is the catalog CRD that defines which DocumentDB engine image and related components KubeDB should use. +`DocumentDB` is a Kubernetes `Custom Resource Definitions` (CRD). It provides a declarative configuration to specify the docker images to be used for [DocumentDB](https://documentdb.apache.org) database deployed with KubeDB in a Kubernetes native way. + +When you install KubeDB, a `DocumentDBVersion` custom resource will be created automatically for every supported DocumentDB versions. You have to specify the name of `DocumentDBVersion` CR in `spec.version` field of [DocumentDB](/docs/guides/documentdb/concepts/documentdb.md) crd. Then, KubeDB will use the docker images specified in the `DocumentDB` CR to create your expected database. + +Using a separate CRD for specifying respective docker images, and pod security policy names allow us to modify the images, and policies independent of KubeDB operator.This will also allow the users to use a custom image for the database. -The value in `DocumentDB.spec.version` must match an available `DocumentDBVersion` resource. ## DocumentDBVersion Specification @@ -34,14 +37,32 @@ spec: deprecated: false ``` -## Key fields +### metadata.name + +`metadata.name` is a required field that specifies the name of the `DocumentDB` CR. You have to specify this name in `spec.version` field of [DocumentDB](/docs/guides/documentdb/concepts/documentdb.md) CR. + +We follow this convention for naming DocumentDBVersion CR: + +- Name format: `{Original DocumentDB image version}-{modification tag}` + +We use official Apache DocumentDB release tar files to build docker images for supporting DocumentDB versions and re-tag the image with v1, v2 etc. modification tag when there's any. An image with higher modification tag will have more features than the images with lower modification tag. Hence, it is recommended to use DocumentDB CR with the highest modification tag to enjoy the latest features. + +### spec.version + +`spec.version` is a required field that specifies the original version of DocumentDB database that has been used to build the docker image specified in `spec.db.image` field. + +### spec.deprecated + +`spec.deprecated` is an optional field that specifies whether the docker images specified here is supported by the current KubeDB operator. + +The default value of this field is `false`. If `spec.deprecated` is set to `true`, KubeDB operator will skip processing this CRD object and will add a event to the CRD object specifying that the DB version is deprecated. + +### spec.db.image + +`spec.db.image` is a required field that specifies the docker image which will be used to create PetSet by KubeDB operator to create expected DocumentDB database. -- `metadata.name` is referenced from `DocumentDB.spec.version`. -- `spec.version` is the released database engine version. -- `spec.db.image` is the runtime image used by KubeDB. -- `spec.deprecated` indicates if this catalog entry is deprecated. ## Next Steps -- Read the [DocumentDB CRD concept](/docs/guides/documentdb/concepts/documentdb.md). -- Run the [DocumentDB quickstart](/docs/guides/documentdb/quickstart/quickstart.md). \ No newline at end of file +- Learn about DocumentDB CRD [here](/docs/guides/documentdb/concepts/documentdb.md). +- Deploy your first DocumentDB database with KubeDB by following the guide [here](/docs/guides/documentdb/quickstart/guide/index.md). \ No newline at end of file diff --git a/docs/guides/documentdb/concepts/documentdb.md b/docs/guides/documentdb/concepts/documentdb.md index 3960588a2..4fe9c5b1c 100644 --- a/docs/guides/documentdb/concepts/documentdb.md +++ b/docs/guides/documentdb/concepts/documentdb.md @@ -20,6 +20,10 @@ section_menu_id: guides ## DocumentDB Spec +As with all other Kubernetes objects, a DocumentDB needs `apiVersion`, `kind`, and `metadata` fields. It also needs a `.spec` section. + +Below is an example DocumentDB object. + ```yaml apiVersion: kubedb.com/v1alpha2 kind: DocumentDB @@ -28,24 +32,260 @@ metadata: namespace: demo spec: version: "pg17-0.109.0" - storageType: Durable - deletionPolicy: Delete replicas: 1 + authSecret: + name: documentdb-auth + storageType: Durable storage: + storageClassName: standard accessModes: - ReadWriteOnce resources: requests: storage: 5Gi + podTemplate: + metadata: + annotations: + passMe: ToDatabasePod + controller: + annotations: + passMe: ToPetSet + spec: + serviceAccountName: my-custom-sa + schedulerName: my-scheduler + nodeSelector: + disktype: ssd + imagePullSecrets: + - name: myregistrykey + containers: + - name: documentdb + env: + - name: DOCUMENTDB_DB + value: documentdb + resources: + requests: + memory: "64Mi" + cpu: "250m" + limits: + memory: "128Mi" + cpu: "500m" + tolerations: + - key: dedicated + operator: Equal + value: database + effect: NoSchedule + volumes: + - name: custom-volume + emptyDir: {} + podPlacementPolicy: + name: default + serviceTemplates: + - alias: primary + metadata: + annotations: + passMe: ToService + spec: + type: ClusterIP + ports: + - name: documentdb + port: 27017 + deletionPolicy: Delete + healthChecker: + periodSeconds: 10 + timeoutSeconds: 10 + failureThreshold: 3 + disableWriteCheck: false +``` +### spec.version + +`spec.version` is a required field specifying the name of the [DocumentDBVersion](/docs/guides/documentdb/concepts/documentdbversion.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `documentdb` resources, + +- `pg17-0.109.0` + +### spec.replicas + +`spec.replicas` the number of members in DocumentDB replicaset. + +### spec.authSecret + +`spec.authSecret` is an optional field that points to a Secret used to hold credentials for `documentdb` admin user. If not set, KubeDB operator creates a new Secret `{documentdb-object-name}-auth` for storing the password for `admin` user for each DocumentDB object. + +We can use this field in 3 mode. +1. Using an external secret. In this case, You need to create an auth secret first with required fields, then specify the secret name when creating the DocumentDB object using `spec.authSecret.name` & set `spec.authSecret.externallyManaged` to true. +```yaml +authSecret: + name: + externallyManaged: true +``` + +2. Specifying the secret name only. In this case, You need to specify the secret name when creating the DocumentDB object using `spec.authSecret.name`. `externallyManaged` is by default false. +```yaml +authSecret: + name: +``` + +3. Let KubeDB do everything for you. In this case, no work for you. + +AuthSecret contains a `user` key and a `password` key which contains the `username` and `password` respectively for DocumentDB `admin` user. + +Example: + +```bash +$ kubectl create secret generic documentdb-auth -n demo \ +--from-literal=username=jhon-doe \ +--from-literal=password=6q8u_2jMOW-OOZXk +secret "documentdb" created +``` + +```yaml +apiVersion: v1 +data: + password: NnE4dV8yak1PVy1PT1pYaw== + username: amhvbi1kb2U= +kind: Secret +metadata: + name: documentdb-auth + namespace: demo +type: Opaque +``` + +Secrets provided by users are not managed by KubeDB, and therefore, won't be modified or garbage collected by the KubeDB operator (version 0.13.0 and higher). + +### spec.storageType + +`spec.storageType` is an optional field that specifies the type of storage to use for database. It can be either `Durable` or `Ephemeral`. The default value of this field is `Durable`. If `Ephemeral` is used then KubeDB will create DocumentDB cluster using [emptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume. + +### spec.storage + +If you don't set `spec.storageType:` to `Ephemeral` then `spec.storage` field is required. This field specifies the StorageClass of PVCs dynamically allocated to store data for the database. This storage spec will be passed to the PetSet created by KubeDB operator to run database pods. You can specify any StorageClass available in your cluster with appropriate resource requests. + +- `spec.storage.storageClassName` is the name of the StorageClass used to provision PVCs. PVCs don’t necessarily have to request a class. A PVC with its storageClassName set equal to "" is always interpreted to be requesting a PV with no class, so it can only be bound to PVs with no class (no annotation or one set equal to ""). A PVC with no storageClassName is not quite the same and is treated differently by the cluster depending on whether the DefaultStorageClass admission plugin is turned on. +- `spec.storage.accessModes` uses the same conventions as Kubernetes PVCs when requesting storage with specific access modes. +- `spec.storage.resources` can be used to request specific quantities of storage. This follows the same resource model used by PVCs. + +To learn how to configure `spec.storage`, please visit the links below: + +- https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims + +### spec.podTemplate + +KubeDB allows providing a template for database pod through `spec.podTemplate`. KubeDB operator will pass the information provided in `spec.podTemplate` to the PetSet created for Postgres database. + +KubeDB accept following fields to set in `spec.podTemplate:` + +- metadata + - annotations (pod's annotation) +- controller + - annotations (petset's annotation) +- spec: + - containers + - volumes + - podPlacementPolicy + - serviceAccountName + - initContainers + - imagePullSecrets + - nodeSelector + - schedulerName + - tolerations + - priorityClassName + - priority + - securityContext + +You can check out the full list [here](https://github.com/kmodules/offshoot-api/blob/master/api/v2/types.go#L26C1-L279C1). +Uses of some field of `spec.podTemplate` is described below, + +#### spec.podTemplate.spec.tolerations + +The `spec.podTemplate.spec.tolerations` is an optional field. This can be used to specify the pod's tolerations. + +#### spec.podTemplate.spec.volumes + +The `spec..podTemplate..volumes` is an optional field. This can be used to provide the list of volumes that can be mounted by containers belonging to the pod. + +#### spec.podTemplate.spec.podPlacementPolicy + +`spec.podTemplate.spec.podPlacementPolicy` is an optional field. This can be used to provide the reference of the `podPlacementPolicy`. `name` of the podPlacementPolicy is referred under this attribute. This will be used by our Petset controller to place the db pods throughout the region, zone & nodes according to the policy. It utilizes kubernetes affinity & podTopologySpreadContraints feature to do so. +```yaml +spec: + podPlacementPolicy: + name: default ``` -### Key fields +#### spec.podTemplate.spec.nodeSelector + +`spec..podTemplate.spec.nodeSelector` is an optional field that specifies a map of key-value pairs. For the pod to be eligible to run on a node, the node must have each of the indicated key-value pairs as labels (it can have additional labels as well). To learn more, see [here](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector) . + +### spec.serviceTemplates + +You can also provide template for the services created by KubeDB operator for DocumentDB cluster through `spec.serviceTemplates`. This will allow you to set the type and other properties of the services. + +KubeDB allows following fields to set in `spec.serviceTemplates`: +- `alias` represents the identifier of the service. It has the following possible value: + - `stats` for is used for the `exporter` service identification. + + +- metadata: + - labels + - annotations +- spec: + - type + - ports + - clusterIP + - externalIPs + - loadBalancerIP + - loadBalancerSourceRanges + - externalTrafficPolicy + - healthCheckNodePort + - sessionAffinityConfig + +See [here](https://github.com/kmodules/offshoot-api/blob/kubernetes-1.21.1/api/v1/types.go#L237) to understand these fields in detail. + + +#### spec.podTemplate.spec.containers + +The `spec.podTemplate.spec.containers` can be used to provide the list containers and their configurations for to the database pod. some of the fields are described below, + +##### spec.podTemplate.spec.containers[].name +The `spec.podTemplate.spec.containers[].name` field used to specify the name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated. + +##### spec.podTemplate.spec.containers[].args +`spec.podTemplate.spec.containers[].args` is an optional field. This can be used to provide additional arguments to database installation. + +##### spec.podTemplate.spec.containers[].env + +`spec.podTemplate.spec.containers[].env` is an optional field that specifies the environment variables to pass to the Redis containers. + +##### spec.podTemplate.spec.containers[].resources + +`spec.podTemplate.spec.containers[].resources` is an optional field. This can be used to request compute resources required by containers of the database pods. To learn more, visit [here](http://kubernetes.io/docs/user-guide/compute-resources/). + +### spec.deletionPolicy + +`deletionPolicy` gives flexibility whether to `nullify`(reject) the delete operation of `DocumentDB` crd or which resources KubeDB should keep or delete when you delete `DocumentDB` crd. KubeDB provides following four deletion policies: + +- DoNotTerminate +- WipeOut +- Halt +- Delete + +When `deletionPolicy` is `DoNotTerminate`, KubeDB takes advantage of `ValidationWebhook` feature in Kubernetes 1.9.0 or later clusters to implement `DoNotTerminate` feature. If admission webhook is enabled, `DoNotTerminate` prevents users from deleting the database as long as the `spec.deletionPolicy` is set to `DoNotTerminate`. + +> For more details you can visit [here](https://appscode.com/blog/post/deletion-policy/) + +## spec.healthChecker +It defines the attributes for the health checker. +- `spec.healthChecker.periodSeconds` specifies how often to perform the health check. +- `spec.healthChecker.timeoutSeconds` specifies the number of seconds after which the probe times out. +- `spec.healthChecker.failureThreshold` specifies minimum consecutive failures for the healthChecker to be considered failed. +- `spec.healthChecker.disableWriteCheck` specifies whether to disable the writeCheck or not. + +Know details about KubeDB Health checking from this [blog post](https://appscode.com/blog/post/kubedb-health-checker/). + +## Next Steps + +- Learn how to use KubeDB to run Apache DocumentDB cluster [here](/docs/guides/documentdb/README.md). +- Detail concepts of [DocumentDB object](/docs/guides/documentdb/concepts/documentdb.md). + +[//]: # (- Learn to use KubeDB managed DocumentDB objects using [CLIs](/docs/guides/documentdb/cli/cli.md).) +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). -- `spec.version` is required and points to a `DocumentDBVersion` resource. -- `spec.replicas` sets number of database instances. -- `spec.storageType` can be `Durable` or `Ephemeral`. -- `spec.storage` defines PVC settings for persistent data. -- `spec.authSecret` optionally references credentials. -- `spec.podTemplate` optionally customizes pods. -- `spec.serviceTemplates` optionally customizes services. -- `spec.deletionPolicy` controls object deletion behavior. \ No newline at end of file diff --git a/docs/guides/documentdb/concepts/opsrequest.md b/docs/guides/documentdb/concepts/opsrequest.md deleted file mode 100644 index fc2ea23ab..000000000 --- a/docs/guides/documentdb/concepts/opsrequest.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: DocumentDBOpsRequest CRD -menu: - docs_{{ .version }}: - identifier: documentdb-opsrequest-concepts - name: DocumentDBOpsRequest - parent: documentdb-concepts-documentdb - weight: 25 -menu_name: docs_{{ .version }} -section_menu_id: guides ---- - -> New to KubeDB? Please start [here](/docs/README.md). - -# DocumentDBOpsRequest - -## What is DocumentDBOpsRequest - -`DocumentDBOpsRequest` is the operations CRD KubeDB uses for day-2 lifecycle changes of DocumentDB databases when supported in a release. - -## Current support status - -Based on [new_db.md](/new_db.md), no DocumentDB operation types are currently listed. - -## Expected CRD shape - -```yaml -apiVersion: ops.kubedb.com/v1alpha1 -kind: DocumentDBOpsRequest -metadata: - name: documentdb-ops-sample - namespace: demo -spec: - type: Restart - databaseRef: - name: documentdb -``` - -## Next Steps - -- Track [DocumentDB ops overview](/docs/guides/documentdb/ops-request/overview.md) for support updates. -- Use [DocumentDB configuration guide](/docs/guides/documentdb/configuration/overview.md) for declarative spec updates. \ No newline at end of file diff --git a/docs/guides/documentdb/configuration/_index.md b/docs/guides/documentdb/configuration/_index.md deleted file mode 100644 index 3efa97d68..000000000 --- a/docs/guides/documentdb/configuration/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: DocumentDB Configuration -menu: - docs_{{ .version }}: - identifier: documentdb-configuration - name: Configuration - parent: documentdb-guides - weight: 20 -menu_name: docs_{{ .version }} ---- diff --git a/docs/guides/documentdb/configuration/overview.md b/docs/guides/documentdb/configuration/overview.md deleted file mode 100644 index ce095cf27..000000000 --- a/docs/guides/documentdb/configuration/overview.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DocumentDB Configuration Overview -menu: - docs_{{ .version }}: - identifier: documentdb-configuration-overview - name: Overview - parent: documentdb-configuration - weight: 10 -menu_name: docs_{{ .version }} -section_menu_id: guides ---- - -# DocumentDB Configuration - -This guide shows the main DocumentDB configuration fields you can tune before or after initial deployment. - -## Before You Begin - -- Review the base manifest used in [Quickstart](/docs/guides/documentdb/quickstart/quickstart.md). -- Identify whether you need to change topology, authentication, services, or probes. - -## Common Configuration Fields - -- spec.replicas for number of database instances. -- spec.authSecret for custom credentials. -- spec.podTemplate for pod-level customization. -- spec.serviceTemplates for service exposure. -- spec.healthChecker for probe timing and thresholds. - -## How to Apply Configuration - -Update the DocumentDB resource manifest with the desired fields and apply it again. - -```bash -kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/quickstart/standalone.yaml -kubectl edit documentdb -n demo documentdb -``` - -## Verify - -```bash -kubectl get documentdb -n demo documentdb -o yaml -kubectl describe documentdb -n demo documentdb -``` diff --git a/docs/guides/documentdb/custom-rbac/using-custom-rbac.md b/docs/guides/documentdb/custom-rbac/using-custom-rbac.md index 96025b5e5..005a1f9d1 100644 --- a/docs/guides/documentdb/custom-rbac/using-custom-rbac.md +++ b/docs/guides/documentdb/custom-rbac/using-custom-rbac.md @@ -12,9 +12,9 @@ section_menu_id: guides > New to KubeDB? Please start [here](/docs/README.md). -# Using Custom RBAC Resources +# Using Custom RBAC resources -KubeDB supports finer user control over role based access permissions provided to a DocumentDB instance. This tutorial will show you how to use KubeDB to run a DocumentDB instance with custom RBAC resources. +KubeDB (version 0.13.0 and higher) supports finer user control over role based access permissions provided to a DocumentDB instance. This tutorial will show you how to use KubeDB to run DocumentDB instance with custom RBAC resources. ## Before You Begin @@ -29,11 +29,17 @@ $ kubectl create ns demo namespace/demo created ``` +> Note: YAML files used in this tutorial are stored in [docs/examples/documentdb](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/documentdb) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + ## Overview -KubeDB allows users to provide custom RBAC resources, namely, `ServiceAccount`, `Role`, and `RoleBinding` for DocumentDB. This is provided via the `spec.podTemplate.spec.serviceAccountName` field in DocumentDB CRD. If this field is left empty, the KubeDB operator will create a service account name matching the DocumentDB CRD name. +KubeDB allows users to provide custom RBAC resources, namely, `ServiceAccount`, `Role`, and `RoleBinding` for DocumentDB. This is provided via the `spec.podTemplate.spec.serviceAccountName` field in DocumentDB CRD. If this field is left empty, the KubeDB operator will create a service account name matching DocumentDB crd name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this service account. + +If a service account name is given, but there's no existing service account by that name, the KubeDB operator will create one, and Role and RoleBinding that provide necessary access permissions will also be generated for this service account. + +If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Since this service account is not managed by KubeDB, users are responsible for providing necessary access permissions manually. -If a service account name is given, and there's an existing service account by that name, the KubeDB operator will use that existing service account. Users are responsible for providing necessary access permissions manually. +This guide will show you how to create custom `Service Account`, `Role`, and `RoleBinding` for a DocumentDB instance named `quick-docdb` to provide the bare minimum access permissions. ## Custom RBAC for DocumentDB @@ -44,7 +50,24 @@ $ kubectl create serviceaccount -n demo my-custom-serviceaccount serviceaccount/my-custom-serviceaccount created ``` -Now, we need to create a role that has necessary access permissions for the DocumentDB database named `quick-docdb`. +It should create a service account. + +```yaml +$ kubectl get serviceaccount -n demo my-custom-serviceaccount -o yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + creationTimestamp: "2019-05-30T04:23:39Z" + name: my-custom-serviceaccount + namespace: demo + resourceVersion: "21657" + selfLink: /api/v1/namespaces/demo/serviceaccounts/my-custom-serviceaccount + uid: b2ec2b05-8292-11e9-8d10-080027a8b217 +secrets: +- name: my-custom-serviceaccount-token-t8zxd +``` + +Now, we need to create a role that has necessary access permissions for the DocumentDB Database named `quick-docdb`. ```bash $ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/custom-rbac/docdb-custom-role.yaml @@ -99,26 +122,58 @@ rules: - update ``` +Please note that resourceName `quick-docdb` is unique to `quick-docdb` DocumentDB instance. Another database `quick-docdb-2`, for example, will require the resourceName to be `quick-docdb-2`. + Now create a `RoleBinding` to bind this `Role` with the already created service account. ```bash -$ kubectl create rolebinding my-custom-rolebinding \ - --role=my-custom-role \ - --serviceaccount=demo:my-custom-serviceaccount \ - --namespace=demo +$ kubectl create rolebinding my-custom-rolebinding --role=my-custom-role --serviceaccount=demo:my-custom-serviceaccount --namespace=demo rolebinding.rbac.authorization.k8s.io/my-custom-rolebinding created ``` +It should bind `my-custom-role` and `my-custom-serviceaccount` successfully. + +```yaml +$ kubectl get rolebinding -n demo my-custom-rolebinding -o yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + creationTimestamp: "2019-05-30T04:54:56Z" + name: my-custom-rolebinding + namespace: demo + resourceVersion: "23944" + selfLink: /apis/rbac.authorization.k8s.io/v1/namespaces/demo/rolebindings/my-custom-rolebinding + uid: 123afc02-8297-11e9-8d10-080027a8b217 +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: my-custom-role +subjects: +- kind: ServiceAccount + name: my-custom-serviceaccount + namespace: demo +``` + Now, create a DocumentDB CRD specifying `spec.podTemplate.spec.serviceAccountName` field to `my-custom-serviceaccount`. +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/custom-rbac/docdb-custom-db.yaml +documentdb.kubedb.com/quick-docdb created +``` + +Below is the YAML for the DocumentDB crd we just created. + ```yaml apiVersion: kubedb.com/v1alpha2 kind: DocumentDB metadata: name: quick-docdb namespace: demo + labels: + app.kubernetes.io/component: database + app.kubernetes.io/instance: quick-docdb spec: - version: "5.0.6" + version: "pg17-0.109.0" storageType: Durable podTemplate: spec: @@ -129,16 +184,12 @@ spec: - ReadWriteOnce resources: requests: - storage: 1Gi - deletionPolicy: WipeOut + storage: 5Gi ``` -```bash -$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/custom-rbac/docdb-custom-db.yaml -documentdb.kubedb.com/quick-docdb created -``` +Now, wait a few minutes. the KubeDB operator will create necessary PVC, petset, services, secret etc. If everything goes well, we should see that a pod with the name `quick-docdb-0` has been created. -Check that the pod is running: +Check that the petset's pod is running ```bash $ kubectl get pod -n demo quick-docdb-0 @@ -146,6 +197,131 @@ NAME READY STATUS RESTARTS AGE quick-docdb-0 1/1 Running 0 3m ``` +Check the pod's log to see if the database is ready +```bash +```bash +$ kubectl logs -f -n demo second-docdb-0 +``` + +Once we see `database system is ready to accept connections` in the log, the database is ready. + +## Reusing Service Account + +An existing service account can be reused in another DocumentDB Database. However, users need to create a new Role specific to that DocumentDB and bind it to the existing service account so that all the necessary access permissions are available to run the new DocumentDB Database. + +For example, to reuse `my-custom-serviceaccount` in a new Database `second-docdb`, create a role that has all the necessary access permissions for this DocumentDB Database. + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/custom-rbac/docdb-custom-role-two.yaml +role.rbac.authorization.k8s.io/my-custom-role-two created +``` + +Below is the YAML for the Role we just created. + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: my-custom-role-two + namespace: demo +rules: +- apiGroups: + - apps + resourceNames: + - second-docdb + resources: + - petsets + verbs: + - get +- apiGroups: + - kubedb.com + resourceNames: + - second-docdb + resources: + - documentdbs + verbs: + - get +- apiGroups: + - "" + resources: + - pods + verbs: + - list + - patch +- apiGroups: + - "" + resources: + - pods/exec + verbs: + - create +- apiGroups: + - "" + resources: + - configmaps + verbs: + - create + - get + - update +``` + +Now create a `RoleBinding` to bind `my-custom-role-two` with the already created `my-custom-serviceaccount`. + +```bash +$ kubectl create rolebinding my-custom-rolebinding-two --role=my-custom-role-two --serviceaccount=demo:my-custom-serviceaccount --namespace=demo +rolebinding.rbac.authorization.k8s.io/my-custom-rolebinding-two created +``` + +Now, create DocumentDB CRD `second-docdb` using the existing service account name `my-custom-serviceaccount` in the `spec.podTemplate.spec.serviceAccountName` field. + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/custom-rbac/docdb-custom-db-two.yaml +documentdb.kubedb.com/second-docdb created +``` + +Below is the YAML for the DocumentDB crd we just created. + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: DocumentDB +metadata: + name: second-docdb + namespace: demo + labels: + app.kubernetes.io/component: database + app.kubernetes.io/instance: second-docdb +spec: + version: "pg17-0.109.0" + storageType: Durable + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi +``` + +Now, wait a few minutes. the KubeDB operator will create necessary PVC, petset, services, secret etc. If everything goes well, we should see that a pod with the name `second-docdb-0` has been created. + +Check that the petset's pod is running + +```bash +$ kubectl get pod -n demo second-docdb-0 +NAME READY STATUS RESTARTS AGE +second-docdb-0 1/1 Running 0 3m +``` + +Check the pod's log to see if the database is ready + +```bash +$ kubectl logs -f -n demo second-docdb-0 +``` + +`database system is ready to accept connections` in the log signifies that the database is running successfully. + ## Cleaning up To cleanup the Kubernetes resources created by this tutorial, run: @@ -154,8 +330,24 @@ To cleanup the Kubernetes resources created by this tutorial, run: kubectl patch -n demo documentdb/quick-docdb -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" kubectl delete -n demo documentdb/quick-docdb -kubectl delete -n demo serviceaccount my-custom-serviceaccount +kubectl patch -n demo documentdb/second-docdb -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo documentdb/second-docdb + kubectl delete -n demo role my-custom-role +kubectl delete -n demo role my-custom-role-two + kubectl delete -n demo rolebinding my-custom-rolebinding +kubectl delete -n demo rolebinding my-custom-rolebinding-two + +kubectl delete sa -n demo my-custom-serviceaccount + kubectl delete ns demo ``` + +If you would like to uninstall the KubeDB operator, please follow the steps [here](/docs/setup/README.md). + +## Next Steps + +- Learn about initializing [DocumentDB with Script](/docs/guides/documentdb/initialization/script_source.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). + diff --git a/docs/guides/documentdb/initialization/_index.md b/docs/guides/documentdb/initialization/_index.md new file mode 100644 index 000000000..eb9d3989c --- /dev/null +++ b/docs/guides/documentdb/initialization/_index.md @@ -0,0 +1,12 @@ +--- +title: DocumentDB Initialization +menu: + docs_{{ .version }}: + identifier: documentdb-initialization-documentdb + name: Initialization + parent: documentdb-guides + weight: 40 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + diff --git a/docs/guides/documentdb/initialization/script_source.md b/docs/guides/documentdb/initialization/script_source.md new file mode 100644 index 000000000..aaf815e84 --- /dev/null +++ b/docs/guides/documentdb/initialization/script_source.md @@ -0,0 +1,246 @@ +--- +title: Initialize DocumentDB using Script Source +menu: + docs_{{ .version }}: + identifier: documentdb-script-source-initialization + name: Using Script + parent: documentdb-initialization-documentdb + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Initialize DocumentDB with Script + +KubeDB supports DocumentDB database initialization. This tutorial will show you how to use KubeDB to initialize a DocumentDB database from script. + +## Before You Begin + +At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). + +To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. + +```bash +$ kubectl create ns demo +namespace/demo created + +$ kubectl get ns demo +NAME STATUS AGE +demo Active 5s +``` + +> Note: YAML files used in this tutorial are stored in [docs/examples/documentdb](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/documentdb) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Prepare Initialization Scripts + +DocumentDB supports initialization with `.sh`, `.sql` and `.sql.gz` files. In this tutorial, we will use a sample initialization script to set up the database with necessary schema and tables. + +We will use a ConfigMap as script source. You can use any Kubernetes supported [volume](https://kubernetes.io/docs/concepts/storage/volumes) as script source. + +At first, we will create a ConfigMap from initialization script file. Then, we will provide this ConfigMap as script source in `init.script` of DocumentDB crd spec. + +Let's create a ConfigMap with initialization script, + +```bash +$ kubectl create configmap -n demo documentdb-init-script \ +--from-literal=data.sql="CREATE SCHEMA IF NOT EXISTS data; CREATE TABLE IF NOT EXISTS data.dashboard (id SERIAL PRIMARY KEY, title VARCHAR(255), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);" +configmap/documentdb-init-script created +``` + +## Create DocumentDB with script source + +Following YAML describes the DocumentDB object with `init.script`, + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: DocumentDB +metadata: + name: script-documentdb + namespace: demo +spec: + version: "pg17-0.109.0" + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi + init: + script: + configMap: + name: documentdb-init-script +``` + +Here, + +- `init.script` specifies scripts used to initialize the database when it is being created. + +VolumeSource provided in `init.script` will be mounted in Pod and will be executed while creating DocumentDB. + +Now, let's create the DocumentDB crd which YAML we have shown above, + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/initialization/script-documentdb.yaml +documentdb.kubedb.com/script-documentdb created +``` + +Now, wait until DocumentDB goes in `Running` state. Verify that the database is in `Running` state using following command, + +```bash +$ kubectl get documentdb -n demo script-documentdb +NAME VERSION STATUS AGE +script-documentdb pg17-0.109.0 Running 39s +``` + +You can use `kubectl dba describe` command to view which resources has been created by KubeDB for this DocumentDB object. + +```bash +$ kubectl dba describe documentdb -n demo script-documentdb +Name: script-documentdb +Namespace: demo +CreationTimestamp: Wed, 09 Jan 2025 12:05:51 +0000 +Labels: +Annotations: kubectl.kubernetes.io/last-applied-configuration={"apiVersion":"kubedb.com/v1alpha2","kind":"DocumentDB"... +Replicas: 1 total +Status: Running +Init: + script: +Volume: + Type: ConfigMap (a volume populated by a ConfigMap) + Name: documentdb-init-script + Optional: false + StorageType: Durable +Volume: + StorageClass: standard + Capacity: 5Gi + Access Modes: RWO + +PetSet: + Name: script-documentdb + CreationTimestamp: Wed, 09 Jan 2026 12:05:52 +0000 + Labels: app.kubernetes.io/name=documentdbs.kubedb.com + app.kubernetes.io/instance=script-documentdb + Annotations: + Replicas: 1 desired | 1 total + Pods Status: 1 Running / 0 Waiting / 0 Succeeded / 0 Failed + +Service: + Name: script-documentdb + Labels: app.kubernetes.io/name=documentdbs.kubedb.com + app.kubernetes.io/instance=script-documentdb + Annotations: + Type: ClusterIP + IP: 10.108.14.12 + Port: db 27017/TCP + TargetPort: db/TCP + Endpoints: 192.168.1.31:27017 + +Database Secret: + Name: script-documentdb-auth + Labels: app.kubernetes.io/name=documentdbs.kubedb.com + app.kubernetes.io/instance=script-documentdb + Annotations: + +Type: Opaque + +Data +==== + password: 16 bytes + username: 8 bytes + +Topology: + Type Pod StartTime Phase + ---- --- --------- ----- + primary script-documentdb-0 2025-01-09 12:05:52 +0000 Running + +No Snapshots. + +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Successful 1m DocumentDB operator Successfully created Service + Normal Successful 57s DocumentDB operator Successfully created PetSet + Normal Successful 57s DocumentDB operator Successfully created DocumentDB + Normal Successful 57s DocumentDB operator Successfully patched PetSet + Normal Successful 57s DocumentDB operator Successfully patched DocumentDB +``` + +## Verify Initialization + +Now let's connect to our DocumentDB `script-documentdb` to verify that the database has been initialized successfully. + +**Connection Information:** + +- Host name/address: you can use any of these + - Service: `script-documentdb.demo` + - Pod IP: (`$ kubectl get pods script-documentdb-0 -n demo -o yaml | grep podIP`) +- Port: `27017` +- Maintenance database: `postgres` + +- Username: Run following command to get *username*, + + ```bash + $ kubectl get secrets -n demo script-documentdb-auth -o jsonpath='{.data.username}' | base64 -d + postgres + ``` + +- Password: Run the following command to get *password*, + + ```bash + $ kubectl get secrets -n demo script-documentdb-auth -o jsonpath='{.data.password}' | base64 -d + + ``` + +You can verify the initialization by checking the pod logs to see if the initialization scripts were executed successfully. You can also connect to DocumentDB and run commands to verify the initialized resources. + +```bash +$ kubectl logs -f -n demo script-documentdb-0 +``` + +Look for messages in the pod logs indicating that the initialization script was executed during database startup. You should see output similar to: + +``` +[2026-01-09T12:05:51.697Z] Starting DocumentDB server +[2026-01-09T12:05:52.753Z] initdb: initialized database +[2026-01-09T12:05:52.822Z] server started +... +[2026-01-09T12:05:53.500Z] database system is ready to accept connections +``` + +This confirms that the initialization scripts were executed during the database startup process, and the `data` schema with the `dashboard` table has been created as specified in the initialization script. + +## Using External Script Files + +You can also use external script files from various sources. Here's an example creating a ConfigMap from a file URL or local file: + +```bash +# From local file +$ kubectl create configmap -n demo documentdb-init-script \ +--from-file=data.sql=./init.sql + +# From URL +$ kubectl create configmap -n demo documentdb-init-script \ +--from-literal=data.sql="$(curl -fsSL https://example.com/init.sql)" +``` + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl patch -n demo documentdb/script-documentdb -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +$ kubectl delete -n demo documentdb/script-documentdb + +$ kubectl delete -n demo configmap/documentdb-init-script +$ kubectl delete ns demo +``` + +## Next Steps +- Learn about [custom RBAC](/docs/guides/documentdb/custom-rbac/using-custom-rbac.md) for DocumentDB. +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). + diff --git a/docs/guides/documentdb/ops-request/_index.md b/docs/guides/documentdb/ops-request/_index.md deleted file mode 100644 index b9ebd21f5..000000000 --- a/docs/guides/documentdb/ops-request/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Ops Request -menu: - docs_{{ .version }}: - identifier: documentdb-ops-request - name: Ops Request - parent: documentdb-guides - weight: 30 -menu_name: docs_{{ .version }} ---- diff --git a/docs/guides/documentdb/ops-request/overview.md b/docs/guides/documentdb/ops-request/overview.md deleted file mode 100644 index ad6231cae..000000000 --- a/docs/guides/documentdb/ops-request/overview.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: DocumentDB Ops Request Overview -menu: - docs_{{ .version }}: - identifier: documentdb-ops-request-overview - name: Overview - parent: documentdb-ops-request - weight: 10 -menu_name: docs_{{ .version }} -section_menu_id: guides ---- - -# DocumentDB Ops Request - -This page tracks DocumentDB operations supported by the new database matrix used for these guides. - -## Before You Begin - -- Deploy a DocumentDB database first using the [quickstart guide](/docs/guides/documentdb/quickstart/quickstart.md). -- Confirm the current support list in [new_db.md](/new_db.md) for your release. - -## Current Status - -Based on [new_db.md](/new_db.md), no DocumentDB ops request types are listed yet. - -## What to Check Next - -- Watch future KubeDB releases for DocumentDB `OpsRequest` support. -- Use the DocumentDB configuration guide for declarative spec-level changes that do not require an ops workflow. From e696a91a14cc79b3afd285dff75029e8c29b66fa Mon Sep 17 00:00:00 2001 From: sabnaj Date: Wed, 6 May 2026 17:21:50 +0600 Subject: [PATCH 3/5] deleted initializaiotn Signed-off-by: sabnaj --- .../initialization/script-documentdb.yaml | 19 -- .../documentdb/initialization/_index.md | 12 - .../initialization/script_source.md | 246 ------------------ 3 files changed, 277 deletions(-) delete mode 100644 docs/examples/documentdb/initialization/script-documentdb.yaml delete mode 100644 docs/guides/documentdb/initialization/_index.md delete mode 100644 docs/guides/documentdb/initialization/script_source.md diff --git a/docs/examples/documentdb/initialization/script-documentdb.yaml b/docs/examples/documentdb/initialization/script-documentdb.yaml deleted file mode 100644 index ed8e5cd89..000000000 --- a/docs/examples/documentdb/initialization/script-documentdb.yaml +++ /dev/null @@ -1,19 +0,0 @@ -apiVersion: kubedb.com/v1alpha2 -kind: DocumentDB -metadata: - name: script-documentdb - namespace: demo -spec: - version: "pg17-0.109.0" - storage: - storageClassName: "standard" - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 5Gi - init: - script: - configMap: - name: documentdb-init-script - diff --git a/docs/guides/documentdb/initialization/_index.md b/docs/guides/documentdb/initialization/_index.md deleted file mode 100644 index eb9d3989c..000000000 --- a/docs/guides/documentdb/initialization/_index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: DocumentDB Initialization -menu: - docs_{{ .version }}: - identifier: documentdb-initialization-documentdb - name: Initialization - parent: documentdb-guides - weight: 40 -menu_name: docs_{{ .version }} -section_menu_id: guides ---- - diff --git a/docs/guides/documentdb/initialization/script_source.md b/docs/guides/documentdb/initialization/script_source.md deleted file mode 100644 index aaf815e84..000000000 --- a/docs/guides/documentdb/initialization/script_source.md +++ /dev/null @@ -1,246 +0,0 @@ ---- -title: Initialize DocumentDB using Script Source -menu: - docs_{{ .version }}: - identifier: documentdb-script-source-initialization - name: Using Script - parent: documentdb-initialization-documentdb - weight: 10 -menu_name: docs_{{ .version }} -section_menu_id: guides ---- - -> New to KubeDB? Please start [here](/docs/README.md). - -# Initialize DocumentDB with Script - -KubeDB supports DocumentDB database initialization. This tutorial will show you how to use KubeDB to initialize a DocumentDB database from script. - -## Before You Begin - -At first, you need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). - -Now, install KubeDB cli on your workstation and KubeDB operator in your cluster following the steps [here](/docs/setup/README.md). - -To keep things isolated, this tutorial uses a separate namespace called `demo` throughout this tutorial. - -```bash -$ kubectl create ns demo -namespace/demo created - -$ kubectl get ns demo -NAME STATUS AGE -demo Active 5s -``` - -> Note: YAML files used in this tutorial are stored in [docs/examples/documentdb](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/documentdb) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). - -## Prepare Initialization Scripts - -DocumentDB supports initialization with `.sh`, `.sql` and `.sql.gz` files. In this tutorial, we will use a sample initialization script to set up the database with necessary schema and tables. - -We will use a ConfigMap as script source. You can use any Kubernetes supported [volume](https://kubernetes.io/docs/concepts/storage/volumes) as script source. - -At first, we will create a ConfigMap from initialization script file. Then, we will provide this ConfigMap as script source in `init.script` of DocumentDB crd spec. - -Let's create a ConfigMap with initialization script, - -```bash -$ kubectl create configmap -n demo documentdb-init-script \ ---from-literal=data.sql="CREATE SCHEMA IF NOT EXISTS data; CREATE TABLE IF NOT EXISTS data.dashboard (id SERIAL PRIMARY KEY, title VARCHAR(255), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);" -configmap/documentdb-init-script created -``` - -## Create DocumentDB with script source - -Following YAML describes the DocumentDB object with `init.script`, - -```yaml -apiVersion: kubedb.com/v1alpha2 -kind: DocumentDB -metadata: - name: script-documentdb - namespace: demo -spec: - version: "pg17-0.109.0" - storage: - storageClassName: "standard" - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 5Gi - init: - script: - configMap: - name: documentdb-init-script -``` - -Here, - -- `init.script` specifies scripts used to initialize the database when it is being created. - -VolumeSource provided in `init.script` will be mounted in Pod and will be executed while creating DocumentDB. - -Now, let's create the DocumentDB crd which YAML we have shown above, - -```bash -$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/documentdb/initialization/script-documentdb.yaml -documentdb.kubedb.com/script-documentdb created -``` - -Now, wait until DocumentDB goes in `Running` state. Verify that the database is in `Running` state using following command, - -```bash -$ kubectl get documentdb -n demo script-documentdb -NAME VERSION STATUS AGE -script-documentdb pg17-0.109.0 Running 39s -``` - -You can use `kubectl dba describe` command to view which resources has been created by KubeDB for this DocumentDB object. - -```bash -$ kubectl dba describe documentdb -n demo script-documentdb -Name: script-documentdb -Namespace: demo -CreationTimestamp: Wed, 09 Jan 2025 12:05:51 +0000 -Labels: -Annotations: kubectl.kubernetes.io/last-applied-configuration={"apiVersion":"kubedb.com/v1alpha2","kind":"DocumentDB"... -Replicas: 1 total -Status: Running -Init: - script: -Volume: - Type: ConfigMap (a volume populated by a ConfigMap) - Name: documentdb-init-script - Optional: false - StorageType: Durable -Volume: - StorageClass: standard - Capacity: 5Gi - Access Modes: RWO - -PetSet: - Name: script-documentdb - CreationTimestamp: Wed, 09 Jan 2026 12:05:52 +0000 - Labels: app.kubernetes.io/name=documentdbs.kubedb.com - app.kubernetes.io/instance=script-documentdb - Annotations: - Replicas: 1 desired | 1 total - Pods Status: 1 Running / 0 Waiting / 0 Succeeded / 0 Failed - -Service: - Name: script-documentdb - Labels: app.kubernetes.io/name=documentdbs.kubedb.com - app.kubernetes.io/instance=script-documentdb - Annotations: - Type: ClusterIP - IP: 10.108.14.12 - Port: db 27017/TCP - TargetPort: db/TCP - Endpoints: 192.168.1.31:27017 - -Database Secret: - Name: script-documentdb-auth - Labels: app.kubernetes.io/name=documentdbs.kubedb.com - app.kubernetes.io/instance=script-documentdb - Annotations: - -Type: Opaque - -Data -==== - password: 16 bytes - username: 8 bytes - -Topology: - Type Pod StartTime Phase - ---- --- --------- ----- - primary script-documentdb-0 2025-01-09 12:05:52 +0000 Running - -No Snapshots. - -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Successful 1m DocumentDB operator Successfully created Service - Normal Successful 57s DocumentDB operator Successfully created PetSet - Normal Successful 57s DocumentDB operator Successfully created DocumentDB - Normal Successful 57s DocumentDB operator Successfully patched PetSet - Normal Successful 57s DocumentDB operator Successfully patched DocumentDB -``` - -## Verify Initialization - -Now let's connect to our DocumentDB `script-documentdb` to verify that the database has been initialized successfully. - -**Connection Information:** - -- Host name/address: you can use any of these - - Service: `script-documentdb.demo` - - Pod IP: (`$ kubectl get pods script-documentdb-0 -n demo -o yaml | grep podIP`) -- Port: `27017` -- Maintenance database: `postgres` - -- Username: Run following command to get *username*, - - ```bash - $ kubectl get secrets -n demo script-documentdb-auth -o jsonpath='{.data.username}' | base64 -d - postgres - ``` - -- Password: Run the following command to get *password*, - - ```bash - $ kubectl get secrets -n demo script-documentdb-auth -o jsonpath='{.data.password}' | base64 -d - - ``` - -You can verify the initialization by checking the pod logs to see if the initialization scripts were executed successfully. You can also connect to DocumentDB and run commands to verify the initialized resources. - -```bash -$ kubectl logs -f -n demo script-documentdb-0 -``` - -Look for messages in the pod logs indicating that the initialization script was executed during database startup. You should see output similar to: - -``` -[2026-01-09T12:05:51.697Z] Starting DocumentDB server -[2026-01-09T12:05:52.753Z] initdb: initialized database -[2026-01-09T12:05:52.822Z] server started -... -[2026-01-09T12:05:53.500Z] database system is ready to accept connections -``` - -This confirms that the initialization scripts were executed during the database startup process, and the `data` schema with the `dashboard` table has been created as specified in the initialization script. - -## Using External Script Files - -You can also use external script files from various sources. Here's an example creating a ConfigMap from a file URL or local file: - -```bash -# From local file -$ kubectl create configmap -n demo documentdb-init-script \ ---from-file=data.sql=./init.sql - -# From URL -$ kubectl create configmap -n demo documentdb-init-script \ ---from-literal=data.sql="$(curl -fsSL https://example.com/init.sql)" -``` - -## Cleaning up - -To cleanup the Kubernetes resources created by this tutorial, run: - -```bash -$ kubectl patch -n demo documentdb/script-documentdb -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" -$ kubectl delete -n demo documentdb/script-documentdb - -$ kubectl delete -n demo configmap/documentdb-init-script -$ kubectl delete ns demo -``` - -## Next Steps -- Learn about [custom RBAC](/docs/guides/documentdb/custom-rbac/using-custom-rbac.md) for DocumentDB. -- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). - From 755c2b213e0678b59f0f04265907fb76b61cf553 Mon Sep 17 00:00:00 2001 From: sabnaj Date: Mon, 11 May 2026 15:44:06 +0600 Subject: [PATCH 4/5] dockerhub repo Signed-off-by: sabnaj --- docs/guides/documentdb/README.md | 71 +++++++++++++++---- docs/guides/documentdb/concepts/catalog.md | 2 +- docs/guides/documentdb/concepts/documentdb.md | 18 +---- .../custom-rbac/using-custom-rbac.md | 6 +- .../using-private-registry.md | 16 ++--- 5 files changed, 70 insertions(+), 43 deletions(-) diff --git a/docs/guides/documentdb/README.md b/docs/guides/documentdb/README.md index 61dc00e6b..bc69b57fe 100644 --- a/docs/guides/documentdb/README.md +++ b/docs/guides/documentdb/README.md @@ -17,18 +17,31 @@ aliases: # Overview -KubeDB supports Amazon DocumentDB-compatible workloads through the `DocumentDB` CRD. +KubeDB supports MongoDB-compatible documentdb database using the DocumentDB Custom Resource Definition (CRD). You can define the desired DocumentDB configuration in a YAML manifest, and KubeDB provisions and manages the necessary Kubernetes resources. + +KubeDB simplifies deploying and managing DocumentDB on Kubernetes with a declarative API. It automates common operational tasks such as: + +- Creating and provisioning standalone DocumentDB instances +- Managing persistent storage and data recovery +- Handling authentication and authorization +- Customizing pod templates and service configurations +- Monitoring database health ## Supported DocumentDB Features -| Features | Availability | -|-----------------------------------|:------------:| -| Standalone provisioning | ✓ | -| Persistent volume | ✓ | -| Replicas | ✓ | -| Deletion policy | ✓ | +| Features | Availability | +|----------------------------------|:------------:| +| Standalone DocumentDB deployment | ✓ | +| Persistent volume | ✓ | +| Authentication secret | ✓ | +| Pod and service customization | ✓ | +| Health checker | ✓ | +| Custom RBAC | ✓ | +| Private registry | ✓ | + ## Example DocumentDB Manifest +Here's a simple example of a DocumentDB deployment: ```yaml apiVersion: kubedb.com/v1alpha2 @@ -48,11 +61,43 @@ spec: storage: 5Gi ``` +For a complete list of available configuration options, see the [DocumentDB CRD Documentation](/docs/guides/documentdb/concepts/documentdb.md). + ## User Guide -- [Quickstart DocumentDB](/docs/guides/documentdb/quickstart/quickstart.md) with KubeDB operator. -- [DocumentDB CRD Concept](/docs/guides/documentdb/concepts/documentdb.md). -- [DocumentDBVersion CRD Concept](/docs/guides/documentdb/concepts/catalog.md). -- [DocumentDBOpsRequest CRD Concept](/docs/guides/documentdb/concepts/opsrequest.md). -- [Configuration](/docs/guides/documentdb/configuration/overview.md) for replicas, auth, pod, and service settings. -- [Ops Request](/docs/guides/documentdb/ops-request/overview.md). \ No newline at end of file +Learn about DocumentDB features and how to use them: + +### Quickstart +- [Quickstart](/docs/guides/documentdb/quickstart/quickstart.md) - Deploy your first DocumentDB instance with KubeDB operator + +### Concepts +- [DocumentDB CRD](/docs/guides/documentdb/concepts/documentdb.md) - Understand the DocumentDB Custom Resource Definition and all available configuration options +- [DocumentDBVersion CRD](/docs/guides/documentdb/concepts/catalog.md) - Learn about specifying DocumentDB versions and docker images + +### Setup & Configuration +- [Custom RBAC](/docs/guides/documentdb/custom-rbac/using-custom-rbac.md) - Setup custom ServiceAccount, Role, and RoleBinding for DocumentDB instances +- [Using Private Registry](/docs/guides/documentdb/private-registry/using-private-registry.md) - Deploy DocumentDB using images from a private docker registry + + + +## Architecture + +KubeDB uses a PetSet (similar to StatefulSet) to manage DocumentDB instances, ensuring stable network identities and persistent storage. Each DocumentDB instance: + +- Runs as a single pod in a PetSet +- Uses a PersistentVolume for data storage + +## What's Next + +- **Want to learn more?** Check out the [DocumentDB Concepts](/docs/guides/documentdb/concepts/documentdb.md) page and explore the [Configuration](/docs/guides/documentdb/concepts/documentdb.md) options. +- **Want to deploy DocumentDB?** Follow the [Quickstart](/docs/guides/documentdb/quickstart/quickstart.md) guide. +- **Want to set up custom RBAC?** See the [Custom RBAC](/docs/guides/documentdb/custom-rbac/using-custom-rbac.md) guide. +- **Want to use a private registry?** Follow the [Private Registry](/docs/guides/documentdb/private-registry/using-private-registry.md) guide. + +## Support + +To speak with us, use the [Slack channel](http://slack.appscode.com) in the `#kubedb` room. + +## Contributing + +Want to help improve KubeDB? Please start [here](/docs/CONTRIBUTING.md). \ No newline at end of file diff --git a/docs/guides/documentdb/concepts/catalog.md b/docs/guides/documentdb/concepts/catalog.md index 4b9d7a308..4f1eb7233 100644 --- a/docs/guides/documentdb/concepts/catalog.md +++ b/docs/guides/documentdb/concepts/catalog.md @@ -65,4 +65,4 @@ The default value of this field is `false`. If `spec.deprecated` is set to `true ## Next Steps - Learn about DocumentDB CRD [here](/docs/guides/documentdb/concepts/documentdb.md). -- Deploy your first DocumentDB database with KubeDB by following the guide [here](/docs/guides/documentdb/quickstart/guide/index.md). \ No newline at end of file +- Deploy your first DocumentDB database with KubeDB by following the guide [here](/docs/guides/documentdb/quickstart/guides/index.md). \ No newline at end of file diff --git a/docs/guides/documentdb/concepts/documentdb.md b/docs/guides/documentdb/concepts/documentdb.md index 4fe9c5b1c..506c315f0 100644 --- a/docs/guides/documentdb/concepts/documentdb.md +++ b/docs/guides/documentdb/concepts/documentdb.md @@ -91,14 +91,10 @@ spec: port: 27017 deletionPolicy: Delete healthChecker: - periodSeconds: 10 - timeoutSeconds: 10 - failureThreshold: 3 - disableWriteCheck: false ``` ### spec.version -`spec.version` is a required field specifying the name of the [DocumentDBVersion](/docs/guides/documentdb/concepts/documentdbversion.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `documentdb` resources, +`spec.version` is a required field specifying the name of the [DocumentDBVersion](/docs/guides/documentdb/concepts/catalog.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `documentdb` resources, - `pg17-0.109.0` @@ -169,7 +165,7 @@ To learn how to configure `spec.storage`, please visit the links below: ### spec.podTemplate -KubeDB allows providing a template for database pod through `spec.podTemplate`. KubeDB operator will pass the information provided in `spec.podTemplate` to the PetSet created for Postgres database. +KubeDB allows providing a template for database pod through `spec.podTemplate`. KubeDB operator will pass the information provided in `spec.podTemplate` to the PetSet created for DocumentDB database. KubeDB accept following fields to set in `spec.podTemplate:` @@ -257,7 +253,7 @@ The `spec.podTemplate.spec.containers[].name` field used to specify the name of ##### spec.podTemplate.spec.containers[].resources -`spec.podTemplate.spec.containers[].resources` is an optional field. This can be used to request compute resources required by containers of the database pods. To learn more, visit [here](http://kubernetes.io/docs/user-guide/compute-resources/). +`spec.podTemplate.spec.containers[].resources` is an optional field. This can be used to request compute resources required by containers of the database pods. To learn more, visit [here](https://kubernetes.io/docs/concepts/storage/). ### spec.deletionPolicy @@ -272,14 +268,6 @@ When `deletionPolicy` is `DoNotTerminate`, KubeDB takes advantage of `Validation > For more details you can visit [here](https://appscode.com/blog/post/deletion-policy/) -## spec.healthChecker -It defines the attributes for the health checker. -- `spec.healthChecker.periodSeconds` specifies how often to perform the health check. -- `spec.healthChecker.timeoutSeconds` specifies the number of seconds after which the probe times out. -- `spec.healthChecker.failureThreshold` specifies minimum consecutive failures for the healthChecker to be considered failed. -- `spec.healthChecker.disableWriteCheck` specifies whether to disable the writeCheck or not. - -Know details about KubeDB Health checking from this [blog post](https://appscode.com/blog/post/kubedb-health-checker/). ## Next Steps diff --git a/docs/guides/documentdb/custom-rbac/using-custom-rbac.md b/docs/guides/documentdb/custom-rbac/using-custom-rbac.md index 005a1f9d1..a9a0c714d 100644 --- a/docs/guides/documentdb/custom-rbac/using-custom-rbac.md +++ b/docs/guides/documentdb/custom-rbac/using-custom-rbac.md @@ -57,7 +57,7 @@ $ kubectl get serviceaccount -n demo my-custom-serviceaccount -o yaml apiVersion: v1 kind: ServiceAccount metadata: - creationTimestamp: "2019-05-30T04:23:39Z" + creationTimestamp: "2025-05-30T04:23:39Z" name: my-custom-serviceaccount namespace: demo resourceVersion: "21657" @@ -138,7 +138,7 @@ $ kubectl get rolebinding -n demo my-custom-rolebinding -o yaml apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: - creationTimestamp: "2019-05-30T04:54:56Z" + creationTimestamp: "2025-05-30T04:54:56Z" name: my-custom-rolebinding namespace: demo resourceVersion: "23944" @@ -347,7 +347,5 @@ kubectl delete ns demo If you would like to uninstall the KubeDB operator, please follow the steps [here](/docs/setup/README.md). ## Next Steps - -- Learn about initializing [DocumentDB with Script](/docs/guides/documentdb/initialization/script_source.md). - Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/documentdb/private-registry/using-private-registry.md b/docs/guides/documentdb/private-registry/using-private-registry.md index 4919e23ca..b394d7464 100644 --- a/docs/guides/documentdb/private-registry/using-private-registry.md +++ b/docs/guides/documentdb/private-registry/using-private-registry.md @@ -37,14 +37,10 @@ namespace/demo created ```bash $ kubectl get documentdbversions -o=custom-columns=NAME:.metadata.name,VERSION:.spec.version,DB_IMAGE:.spec.db.image,DEPRECATED:.spec.deprecated - NAME VERSION DB_IMAGE DEPRECATED - 5.0.6 5.0.6 kubedb/documentdb:5.0.6 + NAME VERSION DB_IMAGE DEPRECATED + pg17-0.109.0 pg17-0.109.0 kubedb/documentdb:5.0.6 ``` - Docker hub repositories: - -- [kubedb/documentdb](https://hub.docker.com/r/kubedb/documentdb) - ## Create ImagePullSecret Run the following command to create an image pull secret for your private Docker registry: @@ -73,18 +69,18 @@ Here, is an example of DocumentDBVersion CRD. Replace `PRIVATE_REGISTRY` with yo apiVersion: catalog.kubedb.com/v1alpha1 kind: DocumentDBVersion metadata: - name: "5.0.6" + name: "pg17-0.109.0" spec: db: image: PRIVATE_REGISTRY/documentdb:5.0.6 - version: "5.0.6" + version: "pg17-0.109.0" ``` Now, create the DocumentDBVersion CRD: ```bash $ kubectl apply -f pvt-documentdbversion.yaml -documentdbversion.catalog.kubedb.com/5.0.6 created +documentdbversion.catalog.kubedb.com/pg17-0.109.0 created ``` ## Deploy DocumentDB from Private Registry @@ -100,7 +96,7 @@ metadata: name: pvt-reg-docdb namespace: demo spec: - version: "5.0.6" + version: "pg17-0.109.0" storageType: Durable storage: storageClassName: "standard" From a7eeff2faf14c7c455006cabac95776ba9074a3a Mon Sep 17 00:00:00 2001 From: sabnaj Date: Tue, 12 May 2026 11:58:51 +0600 Subject: [PATCH 5/5] modified rbac role Signed-off-by: sabnaj --- .../custom-rbac/using-custom-rbac.md | 94 ++++++++------- docs/guides/documentdb/quickstart/rbac.md | 114 +++++++++++++----- 2 files changed, 138 insertions(+), 70 deletions(-) diff --git a/docs/guides/documentdb/custom-rbac/using-custom-rbac.md b/docs/guides/documentdb/custom-rbac/using-custom-rbac.md index a9a0c714d..be088c17d 100644 --- a/docs/guides/documentdb/custom-rbac/using-custom-rbac.md +++ b/docs/guides/documentdb/custom-rbac/using-custom-rbac.md @@ -74,7 +74,7 @@ $ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" > role.rbac.authorization.k8s.io/my-custom-role created ``` -Below is the YAML for the Role we just created. +Below is the YAML for the Role we just created. This role grants the minimum permissions needed for DocumentDB health checker to operate. ```yaml apiVersion: rbac.authorization.k8s.io/v1 @@ -84,45 +84,47 @@ metadata: namespace: demo rules: - apiGroups: - - apps - resourceNames: - - quick-docdb + - "" resources: - - petsets + - pods verbs: - get + - list + - watch - apiGroups: - - kubedb.com - resourceNames: - - quick-docdb + - "" resources: - - documentdbs + - pods/exec verbs: - - get + - create - apiGroups: - "" resources: - - pods + - secrets verbs: - - list - - patch + - get - apiGroups: - "" resources: - - pods/exec + - services verbs: - - create + - get + - list - apiGroups: - "" resources: - - configmaps + - endpoints verbs: - - create - get - - update + - list ``` -Please note that resourceName `quick-docdb` is unique to `quick-docdb` DocumentDB instance. Another database `quick-docdb-2`, for example, will require the resourceName to be `quick-docdb-2`. +These permissions allow the DocumentDB health checker to: +- **pods (get, list, watch)**: Monitor pod status and changes +- **pods/exec (create)**: Execute health check commands inside the pod +- **secrets (get)**: Access authentication credentials +- **services (get, list)**: Discover service endpoints +- **endpoints (get, list)**: Monitor endpoint availability Now create a `RoleBinding` to bind this `Role` with the already created service account. @@ -184,7 +186,7 @@ spec: - ReadWriteOnce resources: requests: - storage: 5Gi + storage: 10Gi ``` Now, wait a few minutes. the KubeDB operator will create necessary PVC, petset, services, secret etc. If everything goes well, we should see that a pod with the name `quick-docdb-0` has been created. @@ -197,10 +199,13 @@ NAME READY STATUS RESTARTS AGE quick-docdb-0 1/1 Running 0 3m ``` -Check the pod's log to see if the database is ready -```bash +Check the pod's log to see if the database is ready: + ```bash -$ kubectl logs -f -n demo second-docdb-0 +$ kubectl logs -f -n demo quick-docdb-0 +2025-05-30 04:25:31.456 UTC [1] LOG: starting DocumentDB +2025-05-30 04:25:31.789 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 27017 +2025-05-30 04:25:32.123 UTC [1] LOG: database system is ready to accept connections ``` Once we see `database system is ready to accept connections` in the log, the database is ready. @@ -216,7 +221,7 @@ $ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" > role.rbac.authorization.k8s.io/my-custom-role-two created ``` -Below is the YAML for the Role we just created. +Below is the YAML for the Role we just created. This role grants the minimum permissions needed for the second DocumentDB instance. ```yaml apiVersion: rbac.authorization.k8s.io/v1 @@ -226,42 +231,39 @@ metadata: namespace: demo rules: - apiGroups: - - apps - resourceNames: - - second-docdb + - "" resources: - - petsets + - pods verbs: - get + - list + - watch - apiGroups: - - kubedb.com - resourceNames: - - second-docdb + - "" resources: - - documentdbs + - pods/exec verbs: - - get + - create - apiGroups: - "" resources: - - pods + - secrets verbs: - - list - - patch + - get - apiGroups: - "" resources: - - pods/exec + - services verbs: - - create + - get + - list - apiGroups: - "" resources: - - configmaps + - endpoints verbs: - - create - get - - update + - list ``` Now create a `RoleBinding` to bind `my-custom-role-two` with the already created `my-custom-serviceaccount`. @@ -301,7 +303,7 @@ spec: - ReadWriteOnce resources: requests: - storage: 5Gi + storage: 10Gi ``` Now, wait a few minutes. the KubeDB operator will create necessary PVC, petset, services, secret etc. If everything goes well, we should see that a pod with the name `second-docdb-0` has been created. @@ -314,10 +316,13 @@ NAME READY STATUS RESTARTS AGE second-docdb-0 1/1 Running 0 3m ``` -Check the pod's log to see if the database is ready +Check the pod's log to see if the database is ready: ```bash $ kubectl logs -f -n demo second-docdb-0 +2025-05-30 04:30:15.456 UTC [1] LOG: starting DocumentDB +2025-05-30 04:30:15.789 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 27017 +2025-05-30 04:30:16.123 UTC [1] LOG: database system is ready to accept connections ``` `database system is ready to accept connections` in the log signifies that the database is running successfully. @@ -347,5 +352,8 @@ kubectl delete ns demo If you would like to uninstall the KubeDB operator, please follow the steps [here](/docs/setup/README.md). ## Next Steps + +- Learn about [DocumentDB CRD](/docs/guides/documentdb/concepts/documentdb.md). +- Learn about [DocumentDBVersion CRD](/docs/guides/documentdb/concepts/catalog.md). - Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). diff --git a/docs/guides/documentdb/quickstart/rbac.md b/docs/guides/documentdb/quickstart/rbac.md index 7da96f158..3320fa417 100644 --- a/docs/guides/documentdb/quickstart/rbac.md +++ b/docs/guides/documentdb/quickstart/rbac.md @@ -16,15 +16,15 @@ section_menu_id: guides When RBAC is enabled in your cluster, KubeDB automatically creates the necessary Role, ServiceAccount, and RoleBinding for each DocumentDB instance. This tutorial explains what permissions are granted and how to verify them. -Here is the list of additional permissions required by the PetSet of DocumentDB: +Here is the list of additional permissions required by the health checker and DocumentDB operations: -| Kubernetes Resource | Resource Names | Permission required | -|---------------------|-----------------------|---------------------| -| petsets | `{documentdb-name}` | get | -| pods | | list, patch | -| pods/exec | | create | -| documentdbs | | get | -| configmaps | `{documentdb-name}` | get, update, create | +| Kubernetes Resource | Permissions | +|---------------------|---------------------| +| pods | get, list, watch | +| pods/exec | create | +| secrets | get | +| services | get, list | +| endpoints | get, list | ## Before You Begin @@ -52,7 +52,7 @@ metadata: name: quick-docdb namespace: demo spec: - version: "5.0.6" + version: "pg17-0.109.0" storageType: Durable storage: storageClassName: "standard" @@ -60,7 +60,7 @@ spec: - ReadWriteOnce resources: requests: - storage: 1Gi + storage: 10Gi deletionPolicy: Delete ``` @@ -73,8 +73,14 @@ documentdb.kubedb.com/quick-docdb created When this DocumentDB object is created, KubeDB operator creates Role, ServiceAccount and RoleBinding with the matching DocumentDB name and uses that ServiceAccount in the corresponding PetSet. +## Verify RBAC Resources Created + +Let's verify what RBAC resources KubeDB has created for the DocumentDB instance. + ### Role +KubeDB operator creates a Role object `quick-docdb` in the same namespace as the DocumentDB object. This Role grants the necessary permissions for the DocumentDB pod to operate. + ```bash $ kubectl get role -n demo quick-docdb -o yaml apiVersion: rbac.authorization.k8s.io/v1 @@ -89,47 +95,47 @@ metadata: namespace: demo rules: - apiGroups: - - apps - resourceNames: - - quick-docdb + - "" resources: - - petsets + - pods verbs: - get + - list + - watch - apiGroups: - - kubedb.com - resourceNames: - - quick-docdb + - "" resources: - - documentdbs + - pods/exec verbs: - - get + - create - apiGroups: - "" resources: - - pods + - secrets verbs: - get - - list - - patch - apiGroups: - "" resources: - - pods/exec + - services verbs: - - create + - get + - list - apiGroups: - "" resources: - - configmaps + - endpoints verbs: - - create - get - - update + - list ``` +This Role grants the minimum required permissions for DocumentDB health checker to monitor the database and access necessary cluster resources. The permissions include pod monitoring, secret access, and service discovery. + ### ServiceAccount +KubeDB operator creates a ServiceAccount object `quick-docdb` in the same namespace as the DocumentDB object. + ```bash $ kubectl get serviceaccount -n demo quick-docdb -o yaml apiVersion: v1 @@ -144,8 +150,17 @@ metadata: namespace: demo ``` +This ServiceAccount is used by the DocumentDB health checker container to monitor the database. You can verify it's being used by checking the PetSet: + +```bash +$ kubectl get petset -n demo quick-docdb -o jsonpath='{.spec.template.spec.serviceAccountName}' +quick-docdb +``` + ### RoleBinding +KubeDB operator creates a RoleBinding object `quick-docdb` in the same namespace as the DocumentDB object. + ```bash $ kubectl get rolebinding -n demo quick-docdb -o yaml apiVersion: rbac.authorization.k8s.io/v1 @@ -168,6 +183,43 @@ subjects: namespace: demo ``` +This RoleBinding binds the Role `quick-docdb` with the ServiceAccount `quick-docdb`, granting the health checker permissions to monitor the DocumentDB instance and access necessary resources. + +## Verify DocumentDB is Running + +Let's verify that the DocumentDB instance is running with the correct RBAC configuration: + +```bash +$ kubectl get documentdb -n demo quick-docdb +NAME VERSION STATUS AGE +quick-docdb pg17-0.109.0 Running 5m +``` + +Check that the pod is running: + +```bash +$ kubectl get pods -n demo quick-docdb-0 +NAME READY STATUS RESTARTS AGE +quick-docdb-0 1/1 Running 0 5m +``` + +View the pod logs to confirm the database started successfully: + +```bash +$ kubectl logs -n demo quick-docdb-0 +2025-01-12 10:30:15.123 UTC [1] LOG: starting DocumentDB +2025-01-12 10:30:15.456 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 27017 +2025-01-12 10:30:15.789 UTC [1] LOG: database system is ready to accept connections +``` + +## Custom RBAC + +If you need fine-grained control over RBAC permissions or want to use a custom service account, please refer to the [Custom RBAC Guide](/docs/guides/documentdb/custom-rbac/using-custom-rbac.md) for detailed instructions. + +## Automatic Resource Cleanup + +When you delete the DocumentDB instance, KubeDB automatically cleans up the associated RBAC resources (Role, ServiceAccount, and RoleBinding) since they are owned by the DocumentDB object. + ## Cleaning up To cleanup the Kubernetes resources created by this tutorial, run: @@ -178,3 +230,11 @@ kubectl delete -n demo documentdb/quick-docdb kubectl delete ns demo ``` + +## Next Steps + +- Read the [DocumentDB CRD Concept](/docs/guides/documentdb/concepts/documentdb.md) for detailed DocumentDB specification. +- Read the [DocumentDBVersion CRD Concept](/docs/guides/documentdb/concepts/catalog.md) for DatabaseVersion specification. +- Learn [Custom RBAC](/docs/guides/documentdb/custom-rbac/using-custom-rbac.md) for fine-grained access control. +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). +