diff --git a/docs/guides/oracle/README.md b/docs/guides/oracle/README.md index e6952f370..49174c054 100644 --- a/docs/guides/oracle/README.md +++ b/docs/guides/oracle/README.md @@ -17,18 +17,18 @@ aliases: ## Supported Oracle Features -| Features | Availability | -|------------------------------------|:------------:| -| Clustering | ✓ | -| Data Guard | ✓ | -| Synchronous Replication | ✓ | -| Streaming Replication | ✓ | -| Automatic Failover | ✓ | -| Persistent Volume | ✓ | -| Initialization using Script | ✓ | -| Using Custom docker image | ✓ | - -## Life Cycle of a Oracle Object +| Features | Availability | +|---------------------------------------------------|:------------:| +| Standalone Oracle Deployment | ✓ | +| Oracle Data Guard (Primary/Standby Topology) | ✓ | +| Synchronous and Asynchronous Replication | ✓ | +| Fast-Start Failover (FSFO) | ✓ | +| Automatic Failover Workflow | ✓ | +| Persistent Storage with PVC | ✓ | +| Pod-Level Resource and Security Customization | ✓ | +| Custom Container Image via OracleVersion Catalog | ✓ | + +## Life Cycle of an Oracle Object

lifecycle @@ -37,5 +37,53 @@ aliases: ## User Guide - [Quickstart Oracle](/docs/guides/oracle/quickstart/guide.md) with KubeDB Operator. +- Learn Oracle deployment and behavior through the [Oracle CRD Concepts](/docs/guides/oracle/concepts/oracle.md) guide. +- Explore high availability and automatic recovery using [Failover and Disaster Recovery](/docs/guides/oracle/failover/overview.md). +- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md). + +## A Guide to Oracle Operations in KubeDB + +The `Oracle` custom resource helps you manage day-2 operations for Oracle databases on Kubernetes through a declarative API. You can define your target topology, resource profile, and failover behavior, and KubeDB continuously reconciles runtime state with your desired state. + +### Choose the Right Deployment Mode + +KubeDB Oracle supports two deployment modes: + +- **Standalone**: A single-instance Oracle deployment, typically used for development, test, and low-complexity workloads. +- **DataGuard**: A multi-node deployment with primary/standby roles for high availability and disaster recovery. + +The [Quickstart guide](/docs/guides/oracle/quickstart/guide.md) walks through creating an Oracle instance and validating the generated resources. + +### Understand Oracle CRD Structure + +The [Oracle Concepts guide](/docs/guides/oracle/concepts/oracle.md) explains important fields in the `Oracle` spec, including: + +- Base settings like `version`, `mode`, `edition`, and `replicas`. +- Data Guard settings such as `protectionMode`, `syncMode`, and failover observer configuration. +- Storage and pod template customization for production-ready runtime behavior. +- Lifecycle controls, including `deletionPolicy`. + +Use this guide as the authoritative reference when designing manifests for either standalone or Data Guard deployments. + +### Plan for High Availability and Failover + +For production Oracle clusters, Data Guard is the key reliability building block. The [failover overview](/docs/guides/oracle/failover/overview.md) details: + +- How primary and standby members are coordinated. +- How redo transport and apply flows affect recovery characteristics. +- How Fast-Start Failover (FSFO) and observer behavior impact automatic failover. +- Practical failure simulation scenarios and expected cluster behavior. + +This is the best starting point for validating RTO/RPO expectations before promoting Oracle workloads to production. + +### Recommended Workflow + +For new users and platform teams, follow this sequence: + +1. Deploy a baseline instance from [Quickstart](/docs/guides/oracle/quickstart/guide.md). +2. Review CRD-level controls in [Oracle Concepts](/docs/guides/oracle/concepts/oracle.md). +3. Enable and test recovery paths using [Failover and Disaster Recovery](/docs/guides/oracle/failover/overview.md). + +By following this progression, you can move from initial deployment to production-grade high availability with a clear operational model. diff --git a/docs/guides/oracle/backup/_index.md b/docs/guides/oracle/backup/_index.md new file mode 100644 index 000000000..e0b8957e7 --- /dev/null +++ b/docs/guides/oracle/backup/_index.md @@ -0,0 +1,10 @@ +--- +title: Oracle Backup +menu: + docs_{{ .version }}: + identifier: oracle-backup + name: Backup + parent: oracle-guides + weight: 30 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/backup/overview.md b/docs/guides/oracle/backup/overview.md new file mode 100644 index 000000000..16abbacd3 --- /dev/null +++ b/docs/guides/oracle/backup/overview.md @@ -0,0 +1,58 @@ +--- +title: Oracle Backup Overview +menu: + docs_{{ .version }}: + identifier: oracle-backup-overview + name: Overview + parent: oracle-backup + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Oracle Backup Overview + +This guide will give an overview of how KubeDB supports backup and restore for `Oracle` databases using [KubeStash](https://kubestash.com). + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) +- You should be familiar with the following `KubeStash` concepts: + - [BackupStorage](https://kubestash.com/docs/latest/concepts/crds/backupstorage/) + - [BackupConfiguration](https://kubestash.com/docs/latest/concepts/crds/backupconfiguration/) + - [BackupSession](https://kubestash.com/docs/latest/concepts/crds/backupsession/) + - [RestoreSession](https://kubestash.com/docs/latest/concepts/crds/restoresession/) + - [RetentionPolicy](https://kubestash.com/docs/latest/concepts/crds/retentionpolicy/) + +## How Backup Works + +KubeStash uses a sidecar-based approach to backup Oracle databases. The backup process consists of the following steps: + +1. At first, a user creates a `BackupStorage` CR that defines the backend storage location (e.g., S3, GCS, Azure Blob). + +2. Then, the user creates a `RetentionPolicy` CR that defines how long backup snapshots will be retained. + +3. Then, the user creates a `BackupConfiguration` CR that references the target `Oracle` database, the `BackupStorage`, and the `RetentionPolicy`. A backup schedule (cron expression) can be defined. + +4. When a `BackupConfiguration` CR is created, KubeStash creates a `CronJob` to trigger backup sessions at the scheduled time. + +5. On each scheduled time, a `BackupSession` CR is created. KubeStash executes the backup in a temporary job that connects to the Oracle database and writes a snapshot to the backend storage. + +6. The backup snapshot is stored in the backend storage and a `Snapshot` CR is created to track the backup metadata. + +## How Restore Works + +The restore process consists of the following steps: + +1. At first, the user creates a target `Oracle` database (or uses an existing one). + +2. Then, the user creates a `RestoreSession` CR referencing the `Snapshot` to restore and the target `Oracle` database. + +3. KubeStash executes the restore in a temporary job that reads the snapshot from the backend storage and restores the data to the target Oracle database. + +4. After the restore completes, the `RestoreSession` status transitions to `Succeeded`. + +In the next docs, we are going to show step-by-step guides on backup and restore of Oracle databases using KubeStash. diff --git a/docs/guides/oracle/concepts/catalog.md b/docs/guides/oracle/concepts/catalog.md new file mode 100644 index 000000000..4d125863b --- /dev/null +++ b/docs/guides/oracle/concepts/catalog.md @@ -0,0 +1,74 @@ +--- +title: OracleVersion CRD +menu: + docs_{{ .version }}: + identifier: oracle-catalog-concepts + name: OracleVersion + parent: oracle-concepts-oracle + weight: 15 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# OracleVersion + +## What is OracleVersion + +`OracleVersion` is a Kubernetes `Custom Resource Definitions` (CRD). It provides a declarative configuration to specify the Docker images to be used for [Oracle](https://oracle.tech/) database deployed with KubeDB in a Kubernetes native way. + +When you install KubeDB, a `OracleVersion` custom resource will be created automatically for every supported Oracle version. You have to specify the name of the `OracleVersion` CRD in `spec.version` field of the [Oracle](/docs/guides/oracle/concepts/oracle.md) CRD. Then, KubeDB will use the Docker images specified in the `OracleVersion` CRD to create your expected database. + +Using a separate CRD for specifying respective Docker images allows us to modify images independent of the KubeDB operator. This also allows users to use a custom image for the database. + +## OracleVersion Specification + +As with all other Kubernetes objects, a `OracleVersion` needs `apiVersion`, `kind`, and `metadata` fields. It also needs a `.spec` section. + +```yaml +apiVersion: catalog.kubedb.com/v1alpha1 +kind: OracleVersion +metadata: + name: "21.3.0" +spec: + coordinator: + image: "ghcr.io/kubedb/oracle-coordinator:v0.10.0" + version: "21.3.0" + db: + image: "container-registry.oracle.com/database/enterprise:21.3.0.0" + exporter: + image: "container-registry.oracle.com/database/observability-exporter:2.2.1" + deprecated: false +``` + +### metadata.name + +`metadata.name` is a required field that specifies the name of the `OracleVersion` CRD. You have to specify this name in `spec.version` field of the [Oracle](/docs/guides/oracle/concepts/oracle.md) CRD. + +The naming convention for `OracleVersion` CRD follows the pattern `{Original Oracle version}`. + +### spec.version + +`spec.version` is a required field that specifies the original version of the Oracle 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 are supported by the current KubeDB operator. + +The default value of this field is `false`. If `spec.deprecated` is set to `true`, KubeDB operator will not create the database and other respective resources for this version. + +### spec.db.image + +`spec.db.image` is a required field that specifies the Docker image which will be used to create the StatefulSet by KubeDB operator to create the expected Oracle database. + +```bash +$ kubectl get oracleversions +NAME VERSION DB_IMAGE DEPRECATED AGE +21.3.0 21.3.0 container-registry.oracle.com/database/enterprise:21.3.0.0 3d +``` + +## Next Steps + +- Learn about the [Oracle CRD](/docs/guides/oracle/concepts/oracle.md). +- Deploy your first Oracle database with KubeDB by following the guide [here](/docs/guides/oracle/quickstart/quickstart.md). \ No newline at end of file diff --git a/docs/guides/oracle/concepts/opsrequest.md b/docs/guides/oracle/concepts/opsrequest.md new file mode 100644 index 000000000..68a208781 --- /dev/null +++ b/docs/guides/oracle/concepts/opsrequest.md @@ -0,0 +1,165 @@ +--- +title: OracleOpsRequest CRD +menu: + docs_{{ .version }}: + identifier: oracle-opsrequest-concepts + name: OracleOpsRequest + parent: oracle-concepts-oracle + weight: 25 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# OracleOpsRequest + +## What is OracleOpsRequest + +`OracleOpsRequest` is a Kubernetes `Custom Resource Definitions` (CRD). It provides declarative configuration for [Oracle](https://oracle.tech/) administrative operations like database version updating, horizontal scaling, vertical scaling, etc. in a Kubernetes native way. + +## OracleOpsRequest CRD Specifications + +Like any official Kubernetes resource, a `OracleOpsRequest` has `TypeMeta`, `ObjectMeta`, `Spec` and `Status` sections. + +Here are some sample `OracleOpsRequest` CRs for different administrative operations: + +**Sample `OracleOpsRequest` for updating database version:** + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-update-version + namespace: demo +spec: + type: UpdateVersion + databaseRef: + name: oracle-sample + updateVersion: + targetVersion: "1.18.0" +status: + conditions: + - lastTransitionTime: "2024-10-01T10:00:00Z" + message: The controller has updated the Oracle successfully + reason: OpsRequestSuccessful + status: "True" + type: Successful + phase: Successful +``` + +**Sample `OracleOpsRequest` for horizontal scaling:** + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-hscale-up + namespace: demo +spec: + type: HorizontalScaling + databaseRef: + name: oracle-sample + horizontalScaling: + node: 5 +status: + conditions: + - lastTransitionTime: "2024-10-01T10:00:00Z" + message: The controller has scaled/updated the Oracle successfully + reason: OpsRequestSuccessful + status: "True" + type: Successful + phase: Successful +``` + +**Sample `OracleOpsRequest` for vertical scaling:** + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-vscale + namespace: demo +spec: + type: VerticalScaling + databaseRef: + name: oracle-sample + verticalScaling: + node: + resources: + requests: + memory: "1Gi" + cpu: "500m" + limits: + memory: "1Gi" + cpu: "500m" +status: + conditions: + - lastTransitionTime: "2024-10-01T10:00:00Z" + message: The controller has scaled/updated the Oracle successfully + reason: OpsRequestSuccessful + status: "True" + type: Successful + phase: Successful +``` + +### OracleOpsRequest `Spec` + +A `OracleOpsRequest` object has the following fields in the `spec` section: + +#### spec.databaseRef + +`spec.databaseRef` is a required field that points to the [Oracle](/docs/guides/oracle/concepts/oracle.md) object where the administrative operations will be applied. It contains: + +- `spec.databaseRef.name` — the name of the target Oracle database (required). + +#### spec.type + +`spec.type` specifies the type of operation that will be applied to the database. Supported operations are: + +- `Reconfigure` — reconfigure a running Oracle database with new configuration. +- `ReconfigureTLS` — reconfigure TLS configuration for a running Oracle database. +- `Restart` — restart the database pods in a rolling fashion. +- `RotateAuth` — rotate the authentication credentials of a running Oracle database. +- `UpdateVersion` — update the version of a running Oracle database. +- `HorizontalScaling` — scale the number of nodes up or down. +- `VerticalScaling` — vertically scale the resources (CPU and memory) of database pods. +- `VolumeExpansion` — expand the persistent volume claim size of a running Oracle database. + +#### spec.updateVersion + +`spec.updateVersion` is used when `spec.type` is `UpdateVersion`. It contains: + +- `spec.updateVersion.targetVersion` — the target `OracleVersion` to update to. + +#### spec.horizontalScaling + +`spec.horizontalScaling` is used when `spec.type` is `HorizontalScaling`. It contains: + +- `spec.horizontalScaling.node` — the desired number of Oracle nodes. + +#### spec.verticalScaling + +`spec.verticalScaling` is used when `spec.type` is `VerticalScaling`. It contains: + +- `spec.verticalScaling.node.resources` — the CPU and memory resource requests and limits for Oracle nodes. + +#### spec.volumeExpansion + +`spec.volumeExpansion` is used when `spec.type` is `VolumeExpansion`. It contains: + +- `spec.volumeExpansion.node` — the new desired storage size for Oracle nodes. +- `spec.volumeExpansion.mode` — the volume expansion mode. Can be `Online` or `Offline`. + +#### spec.timeout + +`spec.timeout` is an optional field that specifies the timeout duration for the OpsRequest to complete. If the OpsRequest does not complete within the specified timeout, it will be marked as failed. The value is in the form of a Kubernetes duration (e.g., `5m`, `1h`). + +#### spec.apply + +`spec.apply` is an optional field that specifies when the OpsRequest will be applied. Possible values are `Always` and `IfReady`. The default is `IfReady`, which means the OpsRequest will only be applied when the target database is in `Ready` state. + +## Next Steps + +- See [Oracle ops request overview](/docs/guides/oracle/ops-request/overview.md) for operation links. +- Follow operation tutorials like [Restart](/docs/guides/oracle/restart/restart.md) and [Volume Expansion](/docs/guides/oracle/volume-expansion/volume-expansion.md). \ No newline at end of file diff --git a/docs/guides/oracle/configuration/_index.md b/docs/guides/oracle/configuration/_index.md new file mode 100644 index 000000000..b2780416c --- /dev/null +++ b/docs/guides/oracle/configuration/_index.md @@ -0,0 +1,10 @@ +--- +title: Oracle Configuration +menu: + docs_{{ .version }}: + identifier: oracle-configuration + name: Configuration + parent: oracle-guides + weight: 22 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/configuration/using-config-file.md b/docs/guides/oracle/configuration/using-config-file.md new file mode 100644 index 000000000..c102532f7 --- /dev/null +++ b/docs/guides/oracle/configuration/using-config-file.md @@ -0,0 +1,142 @@ +--- +title: Run Oracle with Custom Configuration +menu: + docs_{{ .version }}: + identifier: oracle-using-config-file + name: Config File + parent: oracle-configuration + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Using Custom Configuration File + +KubeDB supports providing custom configuration for Oracle. This tutorial will show you how to use KubeDB to run a Oracle database with custom configuration. + +## 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/oracle/configuration](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/oracle/configuration) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Overview + +Oracle allows configuring the database via a YAML configuration file named `production.yaml`. When the Oracle Docker image starts, it merges configuration from the default `config.yaml` with any `production.yaml` file present. KubeDB takes advantage of this feature to allow users to provide their custom configuration. To know more about configuring Oracle, see [here](https://oracle.tech/documentation/guides/configuration/). + +At first, you have to create a config file named `production.yaml` with your desired configuration. Then create a Secret with this configuration file and provide its name in `spec.configuration.secretName`. The operator reads this Secret and mounts it into the Oracle pods automatically. + +In this tutorial, we will configure `log_level` and `service.max_request_size_mb` via a custom config file. + +## Custom Configuration + +At first, let's create a `production.yaml` file with custom settings: + +```yaml +log_level: INFO +service: + max_request_size_mb: 64 +storage: + performance: + max_search_threads: 4 +``` + +Now, create a Secret with this configuration file: + +```bash +$ kubectl create secret generic -n demo oracle-config \ + --from-file=production.yaml=./production.yaml +secret/oracle-config created +``` + +Verify the Secret has the configuration file: + +```yaml +$ kubectl get secret -n demo oracle-config -o yaml +apiVersion: v1 +data: + production.yaml: bG9nX2xldmVsOiBJTkZPCnNlcnZpY2U6CiAgbWF4X3JlcXVlc3Rfc2l6ZV9tYjogNjQK... +kind: Secret +metadata: + name: oracle-config + namespace: demo +``` + +Now, create the `Oracle` CR specifying `spec.configuration.secretName` field: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/configuration/oracle-configuration.yaml +oracle.kubedb.com/custom-oracle created +``` + +Below is the YAML for the `Oracle` CR we just created: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: custom-oracle + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + configuration: + secretName: oracle-config + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Now, wait a few minutes. KubeDB operator will create the necessary PVC, StatefulSet, services, and secrets. If everything goes well, we will see that a pod with the name `custom-oracle-0` has been created. + +Check that the StatefulSet's pod is running: + +```bash +$ kubectl get pod -n demo custom-oracle-0 +NAME READY STATUS RESTARTS AGE +custom-oracle-0 1/1 Running 0 2m +``` + +Now, wait for the `Oracle` CR to go into `Ready` state: + +```bash +$ kubectl get oracle -n demo custom-oracle +NAME VERSION STATUS AGE +custom-oracle 1.17.0 Ready 3m +``` + +We can check that the Oracle database is running with our custom configuration by accessing the telemetry endpoint: + +```bash +$ kubectl port-forward -n demo pod/custom-oracle-0 1521:1521 & +$ curl http://localhost:1521/telemetry | jq '.result.app.max_request_size_mb' +64 +``` + +The output confirms the database is using our custom `max_request_size_mb` value of `64`. + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracle -n demo custom-oracle +kubectl delete secret -n demo oracle-config +kubectl delete ns demo +``` \ No newline at end of file diff --git a/docs/guides/oracle/custom-rbac/_index.md b/docs/guides/oracle/custom-rbac/_index.md new file mode 100644 index 000000000..0318d8527 --- /dev/null +++ b/docs/guides/oracle/custom-rbac/_index.md @@ -0,0 +1,10 @@ +--- +title: Oracle Custom RBAC +menu: + docs_{{ .version }}: + identifier: oracle-custom-rbac + name: Custom RBAC + parent: oracle-guides + weight: 17 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/custom-rbac/using-custom-rbac.md b/docs/guides/oracle/custom-rbac/using-custom-rbac.md new file mode 100644 index 000000000..e72eaf378 --- /dev/null +++ b/docs/guides/oracle/custom-rbac/using-custom-rbac.md @@ -0,0 +1,215 @@ +--- +title: Run Oracle with Custom RBAC resources +menu: + docs_{{ .version }}: + identifier: oracle-custom-rbac-quickstart + name: Custom RBAC + parent: oracle-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 Oracle instance. This tutorial will show you how to use KubeDB to run a Oracle 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 +``` + +> **Note:** YAML files used in this tutorial are stored in [docs/examples/oracle/custom-rbac](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/oracle/custom-rbac) 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 Oracle. This is provided via the `spec.podTemplate.spec.serviceAccountName` field in the Oracle CRD. If this field is left empty, the KubeDB operator will create a ServiceAccount matching the Oracle name. Role and RoleBinding that provide necessary access permissions will also be generated automatically for this ServiceAccount. + +If a ServiceAccount name is given but there is no existing ServiceAccount by that name, the KubeDB operator will create one, and Role and RoleBinding will also be generated automatically. + +If a ServiceAccount name is given and there is an existing ServiceAccount by that name, the KubeDB operator will use that existing ServiceAccount. Since this ServiceAccount is not managed by KubeDB, users are responsible for providing necessary access permissions manually. + +This guide will show you how to create custom `ServiceAccount`, `Role`, and `RoleBinding` for a Oracle instance named `oracle-custom-rbac` to provide the bare minimum access permissions. + +## Custom RBAC for Oracle + +At first, let's create a `ServiceAccount` in the `demo` namespace: + +```bash +$ kubectl create serviceaccount -n demo my-custom-serviceaccount +serviceaccount/my-custom-serviceaccount created +``` + +Verify that the ServiceAccount was created: + +```yaml +$ kubectl get serviceaccount -n demo my-custom-serviceaccount -o yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: my-custom-serviceaccount + namespace: demo +``` + +Now, create a Role that has the necessary access permissions for the Oracle database named `oracle-custom-rbac`: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/custom-rbac/oracle-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: + - oracle-custom-rbac + resources: + - statefulsets + verbs: + - get +- apiGroups: + - kubedb.com + resourceNames: + - oracle-custom-rbac + resources: + - oracles + verbs: + - get +- apiGroups: + - "" + resources: + - pods + verbs: + - list + - patch + - delete +- apiGroups: + - "" + resources: + - pods/exec + verbs: + - create +- apiGroups: + - "" + resources: + - secrets + verbs: + - get + - list +- apiGroups: + - "" + resources: + - configmaps + verbs: + - create + - get + - update +``` + +Note that `resourceNames` like `oracle-custom-rbac` are unique to this particular Oracle instance. Another database instance `oracle-custom-rbac-2` would require these `resourceNames` to be updated accordingly. + +Now, create a `RoleBinding` to bind this `Role` with the already created ServiceAccount: + +```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 +``` + +Verify the RoleBinding was created: + +```yaml +$ kubectl get rolebinding -n demo my-custom-rolebinding -o yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: my-custom-rolebinding + namespace: demo +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: my-custom-role +subjects: +- kind: ServiceAccount + name: my-custom-serviceaccount + namespace: demo +``` + +Now, create a `Oracle` CR 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/oracle/custom-rbac/oracle-custom-db.yaml +oracle.kubedb.com/oracle-custom-rbac created +``` + +Below is the YAML for the `Oracle` CR we just created: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: oracle-custom-rbac + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + podTemplate: + spec: + serviceAccountName: my-custom-serviceaccount + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Now, wait a few minutes. If everything goes well, we will see that the Oracle pods are running with the custom ServiceAccount: + +```bash +$ kubectl get oracle -n demo oracle-custom-rbac +NAME VERSION STATUS AGE +oracle-custom-rbac 1.17.0 Ready 2m + +$ kubectl get pod -n demo -l app.kubernetes.io/instance=oracle-custom-rbac -o=custom-columns=NAME:.metadata.name,SERVICEACCOUNT:.spec.serviceAccountName +NAME SERVICEACCOUNT +oracle-custom-rbac-0 my-custom-serviceaccount +oracle-custom-rbac-1 my-custom-serviceaccount +oracle-custom-rbac-2 my-custom-serviceaccount +``` + +The output confirms that all Oracle pods are running with our custom `my-custom-serviceaccount` ServiceAccount. + +## Cleaning up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracle -n demo oracle-custom-rbac +kubectl delete rolebinding -n demo my-custom-rolebinding +kubectl delete role -n demo my-custom-role +kubectl delete serviceaccount -n demo my-custom-serviceaccount +kubectl delete ns demo +``` \ No newline at end of file diff --git a/docs/guides/oracle/failover/overview.md b/docs/guides/oracle/failover/overview.md index a237b882e..e518d1513 100644 --- a/docs/guides/oracle/failover/overview.md +++ b/docs/guides/oracle/failover/overview.md @@ -1,5 +1,5 @@ --- -title: Oracle Faoilover and Disaster Recovery +title: Oracle Failover and Disaster Recovery menu: docs_{{ .version }}: identifier: guides-oracle-fdr-overview diff --git a/docs/guides/oracle/monitoring/_index.md b/docs/guides/oracle/monitoring/_index.md new file mode 100644 index 000000000..a0fe4ff33 --- /dev/null +++ b/docs/guides/oracle/monitoring/_index.md @@ -0,0 +1,10 @@ +--- +title: Oracle Monitoring +menu: + docs_{{ .version }}: + identifier: oracle-monitoring + name: Monitoring + parent: oracle-guides + weight: 20 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/monitoring/overview.md b/docs/guides/oracle/monitoring/overview.md new file mode 100644 index 000000000..532b08a5e --- /dev/null +++ b/docs/guides/oracle/monitoring/overview.md @@ -0,0 +1,38 @@ +--- +title: Oracle Monitoring Overview +menu: + docs_{{ .version }}: + identifier: oracle-monitoring-overview + name: Overview + parent: oracle-monitoring + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Oracle Monitoring Overview + +This guide will give an overview of how KubeDB supports monitoring for `Oracle` databases. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + +## How KubeDB Monitoring Works + +KubeDB uses Prometheus to monitor `Oracle` databases. KubeDB operator watches the `Oracle` CR and sets up monitoring as follows: + +1. When a `Oracle` database is deployed with `spec.monitor` configured, KubeDB creates a dedicated `stats` service (or uses the existing service) with the appropriate annotations for Prometheus scraping. + +2. KubeDB supports two monitoring approaches: + - **Builtin Prometheus** — uses Prometheus' built-in auto-discovery mechanism (`prometheus.io/scrape` annotations on the stats service). + - **Prometheus Operator** — creates a `ServiceMonitor` CR that is picked up by the Prometheus Operator. + +3. The Oracle stats service exposes Prometheus-compatible metrics at the `/metrics` endpoint, including metrics about collections, vectors, memory usage, and gRPC/REST request performance. + +4. Prometheus scrapes the metrics from the stats service and makes them available for alerting and dashboards. + +In the next docs, we are going to show step-by-step guides on monitoring a Oracle database using Builtin Prometheus and Prometheus Operator. diff --git a/docs/guides/oracle/monitoring/using-builtin-prometheus.md b/docs/guides/oracle/monitoring/using-builtin-prometheus.md new file mode 100644 index 000000000..9dda235a9 --- /dev/null +++ b/docs/guides/oracle/monitoring/using-builtin-prometheus.md @@ -0,0 +1,159 @@ +--- +title: Monitor Oracle using Builtin Prometheus Discovery +menu: + docs_{{ .version }}: + identifier: oracle-using-builtin-prometheus-monitoring + name: Builtin Prometheus + parent: oracle-monitoring + weight: 20 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Monitoring Oracle with Builtin Prometheus + +This tutorial will show you how to monitor `Oracle` database using builtin [Prometheus](https://github.com/prometheus/prometheus) scraper. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install `KubeDB` operator in your cluster following the steps [here](/docs/setup/README.md). + +- If you are not familiar with how to configure Prometheus to scrape metrics from various Kubernetes resources, please read the tutorial from [here](https://github.com/appscode/third-party-tools/tree/master/monitoring/prometheus/builtin). + +- To learn how Prometheus monitoring works with KubeDB in general, please visit [here](/docs/guides/oracle/monitoring/overview.md). + +- To keep Prometheus resources isolated, we are going to use a separate namespace called `monitoring` to deploy respective monitoring resources. We are going to deploy the database in `demo` namespace. + +```bash +$ kubectl create ns monitoring +namespace/monitoring created + +$ kubectl create ns demo +namespace/demo created +``` + +> **Note:** YAML files used in this tutorial are stored in [docs/examples/oracle/monitoring](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/oracle/monitoring) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Deploy Oracle with Monitoring Enabled + +At first, let's deploy a `Oracle` database with monitoring enabled. Below is the `Oracle` object that we are going to create: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: builtin-prom-oracle + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + monitor: + agent: prometheus.io/builtin + deletionPolicy: WipeOut +``` + +Here, + +- `spec.monitor.agent: prometheus.io/builtin` specifies that we are going to monitor this server using builtin Prometheus scraper. + +Let's create the `Oracle` CR we have shown above: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/monitoring/builtin-prom-oracle.yaml +oracle.kubedb.com/builtin-prom-oracle created +``` + +Now, wait for the database to go into `Ready` state: + +```bash +$ kubectl get oracle -n demo builtin-prom-oracle +NAME VERSION STATUS AGE +builtin-prom-oracle 1.17.0 Ready 1m +``` + +KubeDB will create a separate stats service with name `{Oracle cr name}-stats` for monitoring purpose. + +```bash +$ kubectl get svc -n demo --selector="app.kubernetes.io/instance=builtin-prom-oracle" +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +builtin-prom-oracle ClusterIP 10.102.7.190 1521/TCP 87s +builtin-prom-oracle-stats ClusterIP 10.102.128.153 1521/TCP 56s +``` + +Here, `builtin-prom-oracle-stats` service has been created for monitoring purpose. Let's describe the service: + +```bash +$ kubectl describe svc -n demo builtin-prom-oracle-stats +Name: builtin-prom-oracle-stats +Namespace: demo +Labels: app.kubernetes.io/component=database + app.kubernetes.io/instance=builtin-prom-oracle + app.kubernetes.io/managed-by=kubedb.com + app.kubernetes.io/name=oracles.kubedb.com +Annotations: monitoring.appscode.com/agent: prometheus.io/builtin + prometheus.io/path: /metrics + prometheus.io/port: 1521 + prometheus.io/scrape: true +Selector: app.kubernetes.io/instance=builtin-prom-oracle,app.kubernetes.io/name=oracles.kubedb.com +Type: ClusterIP +Port: metrics 1521/TCP +TargetPort: metrics/TCP +Endpoints: 10.244.1.5:1521,10.244.1.6:1521,10.244.1.7:1521 +``` + +You can see that the service contains the following annotations: + +``` +prometheus.io/scrape: true +prometheus.io/path: /metrics +prometheus.io/port: 1521 +``` + +The Prometheus server will discover this service endpoint using these annotations and will scrape metrics from all endpoints. + +## Configure Prometheus to Scrape + +To get the monitoring of this `Oracle` database, you need to configure a Prometheus server. Below is the necessary configuration: + +```yaml +global: + scrape_interval: 15s + +scrape_configs: +- job_name: 'kubedb-databases' + kubernetes_sd_configs: + - role: endpoints + relabel_configs: + - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scrape] + regex: true + action: keep + - source_labels: [__meta_kubernetes_service_annotation_prometheus_io_path] + regex: (.+) + target_label: __metrics_path__ + action: replace +``` + +## Verify Monitoring + +Once Prometheus is configured and running, you can check the monitoring is working by navigating to the Prometheus dashboard (by default at `localhost:9090`). You should see the `builtin-prom-oracle-stats` endpoint in the list of scrape targets. + +## Cleaning up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracle -n demo builtin-prom-oracle +kubectl delete ns demo +kubectl delete ns monitoring +``` \ No newline at end of file diff --git a/docs/guides/oracle/monitoring/using-prometheus-operator.md b/docs/guides/oracle/monitoring/using-prometheus-operator.md new file mode 100644 index 000000000..bb5df5a5f --- /dev/null +++ b/docs/guides/oracle/monitoring/using-prometheus-operator.md @@ -0,0 +1,180 @@ +--- +title: Monitor Oracle using Prometheus Operator +menu: + docs_{{ .version }}: + identifier: oracle-using-prometheus-operator-monitoring + name: Prometheus Operator + parent: oracle-monitoring + weight: 30 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Monitoring Oracle Using Prometheus Operator + +[Prometheus operator](https://github.com/prometheus-operator/prometheus-operator) provides a simple and Kubernetes-native way to deploy and configure Prometheus server. This tutorial will show you how to use Prometheus operator to monitor `Oracle` database deployed with KubeDB. + +## 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 learn how Prometheus monitoring works with KubeDB in general, please visit [here](/docs/guides/oracle/monitoring/overview.md). + +- To keep Prometheus resources isolated, we are going to use a separate namespace called `monitoring` to deploy respective monitoring resources. We are going to deploy the database in `demo` namespace. + +```bash +$ kubectl create ns monitoring +namespace/monitoring created + +$ kubectl create ns demo +namespace/demo created +``` + +- We need a [Prometheus operator](https://github.com/prometheus-operator/prometheus-operator) instance running. If you don't already have a running instance, deploy one following the docs from [here](https://github.com/appscode/third-party-tools/blob/master/monitoring/prometheus/operator/README.md). + +- If you don't already have a Prometheus server running, deploy one following the tutorial from [here](https://github.com/appscode/third-party-tools/blob/master/monitoring/prometheus/operator/README.md#deploy-prometheus-server). + +> **Note:** YAML files used in this tutorial are stored in [docs/examples/oracle/monitoring](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/oracle/monitoring) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Find out required labels for ServiceMonitor + +We need to know the labels used to select `ServiceMonitor` by a `Prometheus` CR. We are going to provide these labels in `spec.monitor.prometheus.serviceMonitor.labels` field of the `Oracle` CR so that KubeDB creates `ServiceMonitor` object accordingly. + +At first, let's find out the available Prometheus server in our cluster: + +```bash +$ kubectl get prometheus --all-namespaces +NAMESPACE NAME AGE +monitoring prometheus 18m +``` + +Now, let's view the YAML of the available Prometheus server `prometheus` in `monitoring` namespace: + +```yaml +$ kubectl get prometheus -n monitoring prometheus -o yaml +apiVersion: monitoring.coreos.com/v1 +kind: Prometheus +metadata: + labels: + prometheus: prometheus + name: prometheus + namespace: monitoring +spec: + replicas: 1 + resources: + requests: + memory: 400Mi + serviceAccountName: prometheus + serviceMonitorSelector: + matchLabels: + release: prometheus +``` + +Notice the `spec.serviceMonitorSelector` section. Here, `release: prometheus` label is used to select `ServiceMonitor` CR. So, we are going to use this label in `spec.monitor.prometheus.serviceMonitor.labels` field of the `Oracle` CR. + +## Deploy Oracle with Monitoring Enabled + +At first, let's deploy a `Oracle` database with monitoring enabled. Below is the `Oracle` object that we are going to create: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: coreos-prom-oracle + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + monitor: + agent: prometheus.io/operator + prometheus: + serviceMonitor: + labels: + release: prometheus + interval: 10s + deletionPolicy: WipeOut +``` + +Here, + +- `spec.monitor.agent: prometheus.io/operator` specifies that we are going to monitor this server using Prometheus operator. +- `spec.monitor.prometheus.serviceMonitor.labels` specifies that KubeDB should create `ServiceMonitor` with these labels. +- `spec.monitor.prometheus.serviceMonitor.interval` specifies how frequently Prometheus should scrape this database. + +Let's create the `Oracle` CR we have shown above: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/monitoring/coreos-prom-oracle.yaml +oracle.kubedb.com/coreos-prom-oracle created +``` + +Now, wait for the database to go into `Ready` state: + +```bash +$ kubectl get oracle -n demo coreos-prom-oracle +NAME VERSION STATUS AGE +coreos-prom-oracle 1.17.0 Ready 1m +``` + +KubeDB will create a `ServiceMonitor` object for this `Oracle` database: + +```bash +$ kubectl get servicemonitor -n demo +NAME AGE +coreos-prom-oracle 65s +``` + +Let's verify the `ServiceMonitor` has the labels we specified: + +```bash +$ kubectl get servicemonitor -n demo coreos-prom-oracle -o yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + labels: + app.kubernetes.io/component: database + app.kubernetes.io/instance: coreos-prom-oracle + app.kubernetes.io/managed-by: kubedb.com + app.kubernetes.io/name: oracles.kubedb.com + release: prometheus + name: coreos-prom-oracle + namespace: demo +spec: + endpoints: + - honorLabels: true + interval: 10s + path: /metrics + port: metrics + namespaceSelector: + matchNames: + - demo + selector: + matchLabels: + app.kubernetes.io/instance: coreos-prom-oracle + app.kubernetes.io/name: oracles.kubedb.com +``` + +Notice that the `ServiceMonitor` has the label `release: prometheus`, which will be picked up by the Prometheus server. + +## Verify Monitoring + +Once everything is set up, you can visit the Prometheus dashboard. The `coreos-prom-oracle` service monitor will be discovered and its metrics will be scraped. You should be able to query Oracle metrics in Prometheus. + +## Cleaning up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracle -n demo coreos-prom-oracle +kubectl delete ns demo +kubectl delete ns monitoring +``` \ No newline at end of file diff --git a/docs/guides/oracle/ops-request/_index.md b/docs/guides/oracle/ops-request/_index.md new file mode 100644 index 000000000..0a86bbc46 --- /dev/null +++ b/docs/guides/oracle/ops-request/_index.md @@ -0,0 +1,10 @@ +--- +title: Oracle Ops-Request +menu: + docs_{{ .version }}: + identifier: oracle-ops-request + name: Ops-Request + parent: oracle-guides + weight: 27 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/ops-request/overview.md b/docs/guides/oracle/ops-request/overview.md new file mode 100644 index 000000000..f582adee4 --- /dev/null +++ b/docs/guides/oracle/ops-request/overview.md @@ -0,0 +1,51 @@ +--- +title: Oracle Ops Request Overview +menu: + docs_{{ .version }}: + identifier: oracle-ops-request-overview + name: Overview + parent: oracle-ops-request + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Oracle Day-2 Operations + +This guide provides an overview of the day-2 operational workflows that KubeDB supports for `Oracle` databases via the `OracleOpsRequest` CRD. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + +## Supported Operations + +KubeDB supports the following day-2 operations for Oracle: + +| Operation | Description | +|-----------|-------------| +| [UpdateVersion](/docs/guides/oracle/update-version/overview.md) | Update the version of a running Oracle database | +| [HorizontalScaling](/docs/guides/oracle/scaling/horizontal-scaling/overview.md) | Scale the number of Oracle nodes up or down | +| [VerticalScaling](/docs/guides/oracle/scaling/vertical-scaling/overview.md) | Update CPU and memory resources of Oracle nodes | +| [VolumeExpansion](/docs/guides/oracle/volume-expansion/overview.md) | Expand the persistent volume claim size of Oracle nodes | +| [Reconfigure](/docs/guides/oracle/reconfigure/overview.md) | Reconfigure a running Oracle database with new configuration | +| [ReconfigureTLS](/docs/guides/oracle/reconfigure-tls/overview.md) | Add, rotate, or remove TLS certificates for Oracle | +| [Restart](/docs/guides/oracle/restart/restart.md) | Restart the Oracle database pods in a rolling fashion | +| [RotateAuth](/docs/guides/oracle/rotate-auth/overview.md) | Rotate the authentication credentials of a Oracle database | + +## How Ops Requests Work + +All day-2 operations for Oracle are performed through the `OracleOpsRequest` CRD. The general workflow is: + +1. The user creates a `OracleOpsRequest` CR with the desired operation type and parameters. +2. `KubeDB-ops-manager` operator watches for `OracleOpsRequest` CRs. +3. When it finds one, it pauses the `Oracle` object to prevent conflicting operations. +4. The operator performs the requested operation (e.g., updates images, scales nodes, expands volumes). +5. After the operation completes successfully, the operator updates the `Oracle` object and resumes it. +6. The `OracleOpsRequest` status transitions to `Successful`. + +> **Note:** Only one `OracleOpsRequest` should be active at a time for a given `Oracle` database. Wait for one operation to complete before starting another. diff --git a/docs/guides/oracle/private-registry/_index.md b/docs/guides/oracle/private-registry/_index.md new file mode 100644 index 000000000..5b031552d --- /dev/null +++ b/docs/guides/oracle/private-registry/_index.md @@ -0,0 +1,10 @@ +--- +title: Oracle Private Registry +menu: + docs_{{ .version }}: + identifier: oracle-private-registry + name: Private Registry + parent: oracle-guides + weight: 18 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/private-registry/using-private-registry.md b/docs/guides/oracle/private-registry/using-private-registry.md new file mode 100644 index 000000000..17909d355 --- /dev/null +++ b/docs/guides/oracle/private-registry/using-private-registry.md @@ -0,0 +1,146 @@ +--- +title: Run Oracle using Private Registry +menu: + docs_{{ .version }}: + identifier: oracle-using-private-registry + name: Quickstart + parent: oracle-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 registry. This tutorial will show you how to run KubeDB managed Oracle 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/oracle/private-registry](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/oracle/private-registry) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Prepare Private Docker Registry + +You will 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 a private repository on [Docker Hub](https://hub.docker.com/). + +You need to push the required images from KubeDB's [Docker hub account](https://hub.docker.com/r/oracle/) into your private registry. For Oracle, push `DB_IMAGE` of the following `OracleVersion`s, where `deprecated` is not true, to your private registry. + +```bash +$ kubectl get oracleversions -o=custom-columns=NAME:.metadata.name,VERSION:.spec.version,DB_IMAGE:.spec.db.image,DEPRECATED:.spec.deprecated +NAME VERSION DB_IMAGE DEPRECATED +21.3.0 21.3.0 container-registry.oracle.com/database/enterprise:21.3.0.0 +``` + +Docker hub repository: +- [oracle/oracle](https://hub.docker.com/r/oracle/oracle) + +## Create ImagePullSecret + +`ImagePullSecrets` is a type of Kubernetes Secret whose purpose is to pull private images from a Docker registry. It allows you to specify the URL of the Docker registry, credentials for logging in, and the image name of your private Docker image. + +Run the following command, substituting the appropriate uppercase values, 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 +``` + +If you wish to follow other ways to pull private images see [official docs](https://kubernetes.io/docs/concepts/containers/images/) of Kubernetes. + +## Install KubeDB operator + +When installing KubeDB operator, set the flags `--docker-registry` and `--image-pull-secret` to the appropriate values. Follow the steps to [install KubeDB operator](/docs/setup/README.md) properly in your cluster so that it points to the `DOCKER_REGISTRY` you wish to pull images from. + +## Create OracleVersion CRD + +KubeDB uses images specified in `OracleVersion` CRD for the database. You have to create a `OracleVersion` CRD specifying images from your private registry. Then, you have to point this `OracleVersion` CRD in `spec.version` field of the `Oracle` object. For more details about `OracleVersion` CRD, please visit [here](/docs/guides/oracle/concepts/catalog.md). + +Here is an example of a `OracleVersion` CRD. Replace `PRIVATE_REGISTRY` with your private registry: + +```yaml +apiVersion: catalog.kubedb.com/v1alpha1 +kind: OracleVersion +metadata: + name: "21.3.0-private" +spec: + coordinator: + image: PRIVATE_REGISTRY/oracle-coordinator:v0.10.0 + db: + image: PRIVATE_REGISTRY/database/enterprise:21.3.0.0 + exporter: + image: PRIVATE_REGISTRY/database/observability-exporter:2.2.1 + version: "21.3.0" +``` + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/private-registry/oracleversion.yaml +oracleversion.catalog.kubedb.com/21.3.0-private created +``` + +## Deploy Oracle from Private Registry + +While deploying `Oracle` from private registry, you have to add `myregistrykey` secret in `spec.podTemplate.spec.imagePullSecrets` and specify `21.3.0-private` in `spec.version` field. + +Below is the YAML for Oracle crd we are going to create: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: pvt-reg-oracle + namespace: demo +spec: + version: "21.3.0-private" + replicas: 3 + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + podTemplate: + spec: + imagePullSecrets: + - name: myregistrykey + deletionPolicy: WipeOut +``` + +Now run the command to create this Oracle object: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/private-registry/pvt-reg-oracle.yaml +oracle.kubedb.com/pvt-reg-oracle created +``` + +To check if the images pulled successfully from the registry, wait for the Oracle to go into `Ready` state: + +```bash +$ kubectl get oracle -n demo pvt-reg-oracle -w +NAME VERSION STATUS AGE +pvt-reg-oracle 21.3.0-private Provisioning 5s +pvt-reg-oracle 21.3.0-private Ready 1m +``` + +## Cleaning up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracle -n demo pvt-reg-oracle +kubectl delete ns demo +``` \ No newline at end of file diff --git a/docs/guides/oracle/quickstart/guide.md b/docs/guides/oracle/quickstart/guide.md index 9dceaca08..8792436bb 100644 --- a/docs/guides/oracle/quickstart/guide.md +++ b/docs/guides/oracle/quickstart/guide.md @@ -19,9 +19,7 @@ This tutorial will show you how to use KubeDB to run an Oracle database.

  lifecycle

->Note: The YAML files used in this tutorial are stored in [docs/examples/oracle/quickstart](https://github.com/kubedb/docs/tree/{{ -< param "info.version" >}}/docs/examples/oracle/quickstart) folder in the GitHub repository kubedb/docs -. +>Note: The YAML files used in this tutorial are stored in [docs/examples/oracle/quickstart](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/oracle/quickstart) folder in the GitHub repository kubedb/docs. ## Before You Begin @@ -57,7 +55,7 @@ NAME VERSION DISTRIBUTION DB_IMAGE DEPRECATED KubeDB implements an Oracle CRD to define Oracle database specifications. Below is an example: -```shell +```yaml apiVersion: kubedb.com/v1alpha2 kind: Oracle metadata: diff --git a/docs/guides/oracle/quickstart/rbac.md b/docs/guides/oracle/quickstart/rbac.md new file mode 100644 index 000000000..36a08908c --- /dev/null +++ b/docs/guides/oracle/quickstart/rbac.md @@ -0,0 +1,216 @@ +--- +title: Oracle RBAC +menu: + docs_{{ .version }}: + identifier: oracle-sample-rbac + name: RBAC + parent: oracle-sample + weight: 20 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# RBAC Permissions for Oracle + +If RBAC is enabled in clusters, some Oracle-specific RBAC permissions are required. These permissions are required for the KubeDB operator to manage Oracle pods properly. + +Here is the list of additional permissions required by the StatefulSet of Oracle: + +| Kubernetes Resource | Resource Names | Permission required | +|---------------------|-----------------|------------------------| +| statefulsets | `{oracle-name}` | get | +| pods | | list, patch | +| pods/exec | | create | +| oracles | | get | +| configmaps | `{oracle-name}` | get, update, create | +| secrets | | get, list | + +## 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/oracle/quickstart](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/oracle/quickstart) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Create a Oracle Database + +Below is the `Oracle` object created in this tutorial: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: oracle-sample + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: Delete +``` + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/quickstart/oracle-sample.yaml +oracle.kubedb.com/oracle-sample created +``` + +When this `Oracle` object is created, KubeDB operator creates a Role, ServiceAccount, and RoleBinding with the matching Oracle name and uses that ServiceAccount in the corresponding StatefulSet. + +Let's see what KubeDB operator has created for additional RBAC permissions. + +### Role + +KubeDB operator creates a Role object `oracle-sample` in the same namespace as the Oracle object: + +```yaml +$ kubectl get role -n demo oracle-sample -o yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + labels: + app.kubernetes.io/component: database + app.kubernetes.io/instance: oracle-sample + app.kubernetes.io/managed-by: kubedb.com + app.kubernetes.io/name: oracles.kubedb.com + name: oracle-sample + namespace: demo + ownerReferences: + - apiVersion: kubedb.com/v1alpha2 + blockOwnerDeletion: true + controller: true + kind: Oracle + name: oracle-sample +rules: +- apiGroups: + - apps + resourceNames: + - oracle-sample + resources: + - statefulsets + verbs: + - get +- apiGroups: + - kubedb.com + resourceNames: + - oracle-sample + resources: + - oracles + verbs: + - get +- apiGroups: + - "" + resources: + - pods + verbs: + - get + - list + - patch + - delete +- apiGroups: + - "" + resources: + - pods/exec + verbs: + - create +- apiGroups: + - "" + resources: + - secrets + verbs: + - get + - list +- apiGroups: + - "" + resources: + - configmaps + verbs: + - create + - get + - update +``` + +### ServiceAccount + +KubeDB operator creates a ServiceAccount object `oracle-sample` in the same namespace as the Oracle object: + +```yaml +$ kubectl get serviceaccount -n demo oracle-sample -o yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + labels: + app.kubernetes.io/component: database + app.kubernetes.io/instance: oracle-sample + app.kubernetes.io/managed-by: kubedb.com + app.kubernetes.io/name: oracles.kubedb.com + name: oracle-sample + namespace: demo + ownerReferences: + - apiVersion: kubedb.com/v1alpha2 + blockOwnerDeletion: true + controller: true + kind: Oracle + name: oracle-sample +``` + +This ServiceAccount is used in the StatefulSet created for the Oracle object. + +### RoleBinding + +KubeDB operator creates a RoleBinding object `oracle-sample` in the same namespace as the Oracle object: + +```yaml +$ kubectl get rolebinding -n demo oracle-sample -o yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + labels: + app.kubernetes.io/component: database + app.kubernetes.io/instance: oracle-sample + app.kubernetes.io/managed-by: kubedb.com + app.kubernetes.io/name: oracles.kubedb.com + name: oracle-sample + namespace: demo + ownerReferences: + - apiVersion: kubedb.com/v1alpha2 + blockOwnerDeletion: true + controller: true + kind: Oracle + name: oracle-sample +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: oracle-sample +subjects: +- kind: ServiceAccount + name: oracle-sample + namespace: demo +``` + +This object binds Role `oracle-sample` with ServiceAccount `oracle-sample`. + +## Cleaning up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl patch -n demo oracle/oracle-sample -p '{"spec":{"deletionPolicy":"WipeOut"}}' --type="merge" +kubectl delete -n demo oracle/oracle-sample +kubectl delete ns demo +``` \ No newline at end of file diff --git a/docs/guides/oracle/reconfigure-tls/_index.md b/docs/guides/oracle/reconfigure-tls/_index.md new file mode 100644 index 000000000..af3015b15 --- /dev/null +++ b/docs/guides/oracle/reconfigure-tls/_index.md @@ -0,0 +1,10 @@ +--- +title: Reconfigure TLS +menu: + docs_{{ .version }}: + identifier: oracle-reconfigure-tls + name: Reconfigure TLS + parent: oracle-guides + weight: 33 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/reconfigure-tls/overview.md b/docs/guides/oracle/reconfigure-tls/overview.md new file mode 100644 index 000000000..1c2677a4e --- /dev/null +++ b/docs/guides/oracle/reconfigure-tls/overview.md @@ -0,0 +1,59 @@ +--- +title: Reconfiguring Oracle TLS +menu: + docs_{{ .version }}: + identifier: oracle-reconfigure-tls-overview + name: Overview + parent: oracle-reconfigure-tls + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Reconfiguring TLS for Oracle + +This guide will give an overview of how KubeDB Ops-manager reconfigures TLS for a `Oracle` database. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) +- Use the example files from `docs/examples/oracle/quickstart/distributed.yaml` and `docs/examples/oracle/reconfigure-tls/ops-request.yaml`. + +```bash +kubectl create ns demo +``` + +## Deploy Oracle + +```bash +kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/quickstart/distributed.yaml +kubectl get oracle -n demo oracle-sample -w +``` + +## How Reconfigure TLS Works + +The Reconfigure TLS process consists of the following steps: + +1. At first, a user creates a `Oracle` CR. + +2. `KubeDB-Provisioner` operator watches the `Oracle` CR. + +3. When the operator finds a `Oracle` CR, it creates a `StatefulSet` and related necessary stuff like secrets, services, etc. + +4. Then, in order to reconfigure TLS of the `Oracle` database, the user creates a `OracleOpsRequest` CR specifying the desired TLS configuration. The user can add TLS to an existing non-TLS database, rotate the existing certificates, or remove TLS entirely. + +5. `KubeDB` Ops-manager operator watches the `OracleOpsRequest` CR. + +6. When it finds a `OracleOpsRequest` CR, it pauses the `Oracle` object so that the `KubeDB-Provisioner` operator doesn't perform any operations on the `Oracle` during the TLS reconfiguration process. + +7. Then the `KubeDB` Ops-manager operator updates the TLS secrets and restarts the pods in a rolling fashion with the new TLS configuration. + +8. After the successful TLS reconfiguration, the `KubeDB` Ops-manager updates the `Oracle` object to reflect the updated TLS state. + +9. After the successful Reconfigure TLS, the `KubeDB` Ops-manager resumes the `Oracle` object so that the `KubeDB-Provisioner` resumes its usual operations. + +In the next doc, we are going to show a step-by-step guide on reconfiguring TLS for a Oracle database using `OracleOpsRequest` CRD. diff --git a/docs/guides/oracle/reconfigure-tls/reconfigure-tls.md b/docs/guides/oracle/reconfigure-tls/reconfigure-tls.md new file mode 100644 index 000000000..e2e63fe42 --- /dev/null +++ b/docs/guides/oracle/reconfigure-tls/reconfigure-tls.md @@ -0,0 +1,252 @@ +--- +title: Reconfigure TLS of Oracle +menu: + docs_{{ .version }}: + identifier: oracle-reconfigure-tls-cluster + name: Cluster + parent: oracle-reconfigure-tls + weight: 30 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Reconfigure Oracle TLS/SSL (Transport Encryption) + +KubeDB supports reconfiguring TLS/SSL certificates for Oracle — adding, removing, updating, and rotating certificates via a `OracleOpsRequest`. This tutorial will show you how to use KubeDB to reconfigure TLS/SSL encryption. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install `cert-manager` v1.0.0 or later to your cluster to manage your SSL/TLS certificates from [here](https://cert-manager.io/docs/installation/). + +- Now, install `KubeDB` in your cluster following the steps [here](/docs/setup/README.md). + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + - [TLS/SSL Overview](/docs/guides/oracle/tls/overview.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/guides/oracle/reconfigure-tls/yamls](/docs/guides/oracle/reconfigure-tls/yamls) directory of [kubedb/docs](https://github.com/kubedb/docs) repository. + +## Add TLS to a Oracle database + +Here, we are going to create a Oracle database without TLS and then reconfigure the database to use TLS. + +### Deploy Oracle without TLS + +In this section, we are going to deploy a Oracle cluster without TLS. Below is the YAML of the `Oracle` CR that we are going to create: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: oracle-sample + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Let's create the `Oracle` CR we have shown above: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/reconfigure-tls/yamls/oracle.yaml +oracle.kubedb.com/oracle-sample created +``` + +Now, wait until `oracle-sample` has status `Ready`: + +```bash +$ kubectl get oracle -n demo +NAME VERSION STATUS AGE +oracle-sample 1.17.0 Ready 3m22s +``` + +### Create Issuer + +Now, we are going to create an example `Issuer` that will be used to enable SSL/TLS in Oracle. Alternatively you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. By following the below steps, we are going to create our desired issuer, + +1. Start off by generating our ca-certificates using openssl, + +```bash +$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=oracle/O=kubedb" +Generating a RSA private key +................+++++ +........................+++++ +writing new private key to './ca.key' +``` + +2. Create a secret using the certificate files we have just generated, + +```bash +$ kubectl create secret tls oracle-ca --cert=ca.crt --key=ca.key --namespace=demo +secret/oracle-ca created +``` + +3. Now we are going to create an `Issuer` using the `oracle-ca` secret that contains the CA certificate we have just created: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: oracle-issuer + namespace: demo +spec: + ca: + secretName: oracle-ca +``` + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/reconfigure-tls/yamls/issuer.yaml +issuer.cert-manager.io/oracle-issuer created +``` + +### Add TLS + +Now, we are going to create a `OracleOpsRequest` to add TLS to the running database. + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-add-tls + namespace: demo +spec: + type: ReconfigureTLS + databaseRef: + name: oracle-sample + tls: + issuerRef: + name: oracle-issuer + kind: Issuer + apiGroup: "cert-manager.io" + certificates: + - alias: server + subject: + organizations: + - kubedb:server + dnsNames: + - localhost + ipAddresses: + - "127.0.0.1" +``` + +Here, + +- `spec.databaseRef.name` specifies that we are performing reconfigure TLS operation on `oracle-sample` database. +- `spec.type` specifies that we are performing `ReconfigureTLS` on our database. +- `spec.tls.issuerRef` specifies the issuer to use for signing certificates. +- `spec.tls.certificates` specifies the certificate configuration. + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/reconfigure-tls/yamls/add-tls.yaml +oracleopsrequest.ops.kubedb.com/qdops-add-tls created +``` + +Let's wait for `OracleOpsRequest` to be `Successful`: + +```bash +$ watch -n 3 kubectl get OracleOpsRequest -n demo qdops-add-tls +Every 3.0s: kubectl get OracleOpsRequest -n demo qdops-add-tls + +NAME TYPE STATUS AGE +qdops-add-tls ReconfigureTLS Successful 6m30s +``` + +## Rotate Certificates + +Now we are going to rotate the certificates of the database. + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-rotate-tls + namespace: demo +spec: + type: ReconfigureTLS + databaseRef: + name: oracle-sample + tls: + rotateCertificates: true +``` + +Here, + +- `spec.tls.rotateCertificates` specifies that we are requesting to rotate the certificates of the `oracle-sample` database. + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/reconfigure-tls/yamls/rotate-tls.yaml +oracleopsrequest.ops.kubedb.com/qdops-rotate-tls created +``` + +Let's wait for `OracleOpsRequest` to be `Successful`: + +```bash +$ kubectl get oracleopsrequest -n demo qdops-rotate-tls +NAME TYPE STATUS AGE +qdops-rotate-tls ReconfigureTLS Successful 3m8s +``` + +## Remove TLS from the Database + +In this section, we are going to reconfigure TLS setting of the database by removing the TLS configuration. + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-remove-tls + namespace: demo +spec: + type: ReconfigureTLS + databaseRef: + name: oracle-sample + tls: + remove: true +``` + +Here, + +- `spec.tls.remove` specifies that we are removing the TLS configuration from `oracle-sample` database. + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/reconfigure-tls/yamls/remove-tls.yaml +oracleopsrequest.ops.kubedb.com/qdops-remove-tls created +``` + +Let's wait for `OracleOpsRequest` to be `Successful`: + +```bash +$ kubectl get oracleopsrequest -n demo qdops-remove-tls +NAME TYPE STATUS AGE +qdops-remove-tls ReconfigureTLS Successful 4m20s +``` + +## Cleaning up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracleopsrequest -n demo qdops-add-tls qdops-rotate-tls qdops-remove-tls +kubectl delete oracle -n demo oracle-sample +kubectl delete issuer -n demo oracle-issuer +kubectl delete ns demo +``` \ No newline at end of file diff --git a/docs/guides/oracle/reconfigure/_index.md b/docs/guides/oracle/reconfigure/_index.md new file mode 100644 index 000000000..b0a14c9a8 --- /dev/null +++ b/docs/guides/oracle/reconfigure/_index.md @@ -0,0 +1,10 @@ +--- +title: Reconfigure +menu: + docs_{{ .version }}: + identifier: oracle-reconfigure + name: Reconfigure + parent: oracle-guides + weight: 32 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/reconfigure/overview.md b/docs/guides/oracle/reconfigure/overview.md new file mode 100644 index 000000000..99d335eef --- /dev/null +++ b/docs/guides/oracle/reconfigure/overview.md @@ -0,0 +1,47 @@ +--- +title: Reconfiguring Oracle +menu: + docs_{{ .version }}: + identifier: oracle-reconfigure-overview + name: Overview + parent: oracle-reconfigure + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Reconfiguring Oracle + +This guide will give an overview of how KubeDB Ops-manager reconfigures a `Oracle` database. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + +## How Reconfiguration Works + +The Reconfiguration process consists of the following steps: + +1. At first, a user creates a `Oracle` CR. + +2. `KubeDB-Provisioner` operator watches the `Oracle` CR. + +3. When the operator finds a `Oracle` CR, it creates a `StatefulSet` and related necessary stuff like secrets, services, etc. + +4. Then, in order to reconfigure the `Oracle` database, the user creates a `OracleOpsRequest` CR with the new configuration. The user can provide the new configuration either via a new config secret, via `applyConfig`, or by removing the custom configuration (reverting to defaults). + +5. `KubeDB` Ops-manager operator watches the `OracleOpsRequest` CR. + +6. When it finds a `OracleOpsRequest` CR, it pauses the `Oracle` object so that the `KubeDB-Provisioner` operator doesn't perform any operations on the `Oracle` during the reconfiguration process. + +7. Then the `KubeDB` Ops-manager operator updates the configuration secret and restarts the pods in a rolling fashion to apply the new configuration. + +8. After the successful configuration update, the `KubeDB` Ops-manager updates the `Oracle` object to reflect the updated configuration state. + +9. After the successful reconfiguration, the `KubeDB` Ops-manager resumes the `Oracle` object so that the `KubeDB-Provisioner` resumes its usual operations. + +In the next doc, we are going to show a step-by-step guide on reconfiguring a Oracle database using `OracleOpsRequest` CRD. diff --git a/docs/guides/oracle/reconfigure/reconfigure.md b/docs/guides/oracle/reconfigure/reconfigure.md new file mode 100644 index 000000000..f3071a5ce --- /dev/null +++ b/docs/guides/oracle/reconfigure/reconfigure.md @@ -0,0 +1,248 @@ +--- +title: Reconfigure Oracle +menu: + docs_{{ .version }}: + identifier: oracle-reconfigure-cluster + name: Cluster + parent: oracle-reconfigure + weight: 30 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Reconfigure Oracle + +This guide will show you how to use `KubeDB` Enterprise operator to reconfigure a Oracle cluster. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. + +- Install `KubeDB` Community and Enterprise operator in your cluster following the steps [here](/docs/setup/README.md). + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + - [Reconfigure Overview](/docs/guides/oracle/reconfigure/overview.md) + +To keep everything isolated, we are going to use a separate namespace called `demo` throughout this tutorial. + +```bash +$ kubectl create ns demo +namespace/demo created +``` + +> **Note:** YAML files used in this tutorial are stored in [docs/guides/oracle/reconfigure/yamls](/docs/guides/oracle/reconfigure/yamls) directory of [kubedb/docs](https://github.com/kubedb/docs) repository. + +### Prepare Oracle + +Now, we are going to deploy a `Oracle` cluster with an initial configuration. + +#### Deploy Oracle with custom config + +First, we will create a `oracle.yaml` config file containing our initial configuration settings. + +```yaml +# oracle.yaml +storage: + performance: + max_search_threads: 4 +``` + +Now, we will create a secret with this configuration file. + +```bash +$ kubectl create secret generic -n demo oracle-configuration --from-file=./oracle.yaml +secret/oracle-configuration created +``` + +Below is the YAML of the `Oracle` CR that we are going to create: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: oracle-sample + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + configuration: + secretName: oracle-configuration + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Let's create the `Oracle` CR we have shown above: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/reconfigure/yamls/oracle.yaml +oracle.kubedb.com/oracle-sample created +``` + +Now, wait until `oracle-sample` has status `Ready`: + +```bash +$ kubectl get oracle -n demo +NAME VERSION STATUS AGE +oracle-sample 1.17.0 Ready 3m42s +``` + +### Reconfigure using new config secret + +Now we will reconfigure this database to change `max_search_threads` to `8`. + +First, we will create a new `oracle.yaml` file containing the updated configuration: + +```yaml +# oracle.yaml +storage: + performance: + max_search_threads: 8 +``` + +Then, we will create a new secret with this configuration file: + +```bash +$ kubectl create secret generic -n demo new-oracle-configuration --from-file=./oracle.yaml +secret/new-oracle-configuration created +``` + +#### Create OracleOpsRequest + +Now, we will use this secret to replace the previous secret using a `OracleOpsRequest` CR. Below is the YAML of the `OracleOpsRequest` that we are going to create: + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-reconfigure-config + namespace: demo +spec: + type: Reconfigure + databaseRef: + name: oracle-sample + configuration: + configSecret: + name: new-oracle-configuration +``` + +Here, + +- `spec.databaseRef.name` specifies that we are reconfiguring `oracle-sample` database. +- `spec.type` specifies that we are performing `Reconfigure` on our database. +- `spec.configuration.configSecret.name` specifies the name of the new configuration secret. + +Let's create the `OracleOpsRequest` CR we have shown above: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/reconfigure/yamls/reconfigure-using-secret.yaml +oracleopsrequest.ops.kubedb.com/qdops-reconfigure-config created +``` + +#### Verify the new configuration is working + +If everything goes well, `KubeDB` Enterprise operator will update the `configuration.secretName` of the `Oracle` object. + +Let's wait for `OracleOpsRequest` to be `Successful`: + +```bash +$ kubectl get qdops -n demo +NAME TYPE STATUS AGE +qdops-reconfigure-config Reconfigure Successful 3m21s +``` + +### Reconfigure using applyConfig + +We can also reconfigure our existing secret by modifying configuration inline using `applyConfig`. Below is the YAML of the `OracleOpsRequest`: + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-reconfigure-apply-config + namespace: demo +spec: + type: Reconfigure + databaseRef: + name: oracle-sample + configuration: + applyConfig: + oracle.yaml: | + storage: + performance: + max_search_threads: 6 +``` + +> **Note:** You can modify multiple fields of your current configuration using `applyConfig`. If you don't have any existing config secret, `applyConfig` will create a new secret for you. + +Here, + +- `spec.databaseRef.name` specifies that we are reconfiguring `oracle-sample` database. +- `spec.type` specifies that we are performing `Reconfigure` on our database. +- `spec.configuration.applyConfig` contains the inline configuration to apply. + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/reconfigure/yamls/apply-config.yaml +oracleopsrequest.ops.kubedb.com/qdops-reconfigure-apply-config created +``` + +#### Verify the new configuration is working + +Let's wait for `OracleOpsRequest` to be `Successful`: + +```bash +$ kubectl get qdops qdops-reconfigure-apply-config -n demo +NAME TYPE STATUS AGE +qdops-reconfigure-apply-config Reconfigure Successful 4m59s +``` + +### Remove Custom Configuration + +We can also remove existing custom config using `OracleOpsRequest`. Set `spec.configuration.removeCustomConfig: true` to remove the existing custom configuration. + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-reconfigure-remove + namespace: demo +spec: + type: Reconfigure + databaseRef: + name: oracle-sample + configuration: + removeCustomConfig: true +``` + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/reconfigure/yamls/remove-config.yaml +oracleopsrequest.ops.kubedb.com/qdops-reconfigure-remove created +``` + +Let's wait for `OracleOpsRequest` to be `Successful`: + +```bash +$ kubectl get qdops qdops-reconfigure-remove -n demo +NAME TYPE STATUS AGE +qdops-reconfigure-remove Reconfigure Successful 2m10s +``` + +After this, the `Oracle` CR will no longer reference a custom `configuration.secretName` and the database will use its default configuration. + +## Cleaning up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracleopsrequest -n demo qdops-reconfigure-config qdops-reconfigure-apply-config qdops-reconfigure-remove +kubectl delete oracle -n demo oracle-sample +kubectl delete ns demo +``` \ No newline at end of file diff --git a/docs/guides/oracle/restart/_index.md b/docs/guides/oracle/restart/_index.md new file mode 100644 index 000000000..0955f9e99 --- /dev/null +++ b/docs/guides/oracle/restart/_index.md @@ -0,0 +1,10 @@ +--- +title: Restart Oracle +menu: + docs_{{ .version }}: + identifier: oracle-restart + name: Restart + parent: oracle-guides + weight: 31 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/restart/restart.md b/docs/guides/oracle/restart/restart.md new file mode 100644 index 000000000..7bf7547de --- /dev/null +++ b/docs/guides/oracle/restart/restart.md @@ -0,0 +1,165 @@ +--- +title: Restart Oracle +menu: + docs_{{ .version }}: + identifier: oracle-restart-overview + name: Restart Oracle + parent: oracle-restart + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Restart Oracle + +KubeDB supports restarting the Oracle database via a `OracleOpsRequest`. Restarting is useful if some pods are stuck in a non-running phase or are not working correctly. This tutorial will show you how to use that. + +## 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` in your cluster following the steps [here](/docs/setup/README.md). + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.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/oracle/restart](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/oracle/restart) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Deploy Oracle + +In this section, we are going to deploy a Oracle database using KubeDB. + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: oracle-sample + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Let's create the `Oracle` CR we have shown above, + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/restart/oracle.yaml +oracle.kubedb.com/oracle-sample created +``` + +Now, wait until `oracle-sample` has status `Ready`: + +```bash +$ kubectl get oracle -n demo +NAME VERSION STATUS AGE +oracle-sample 1.17.0 Ready 3m47s +``` + +## Apply Restart OpsRequest + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-restart + namespace: demo +spec: + type: Restart + databaseRef: + name: oracle-sample + timeout: 3m + apply: Always +``` + +- `spec.type` specifies the type of the OpsRequest. +- `spec.databaseRef` holds the name of the Oracle database. The db should be available in the same namespace as the OpsRequest. +- The meaning of `spec.timeout` & `spec.apply` fields can be found [here](/docs/guides/oracle/concepts/opsrequest.md). + +Let's create the `OracleOpsRequest` CR we have shown above, + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/restart/ops.yaml +oracleopsrequest.ops.kubedb.com/qdops-restart created +``` + +Now the Ops-manager operator will restart the Oracle pods one by one, waiting for each pod to come back to `Running` state before proceeding to the next. + +```bash +$ kubectl get qdops -n demo qdops-restart +NAME TYPE STATUS AGE +qdops-restart Restart Successful 3m25s +``` + +```bash +$ kubectl get qdops -n demo qdops-restart -o yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-restart + namespace: demo +spec: + apply: Always + databaseRef: + name: oracle-sample + timeout: 3m + type: Restart +status: + conditions: + - lastTransitionTime: "2026-05-01T10:00:00Z" + message: Oracle ops request is restarting nodes + observedGeneration: 1 + reason: Restart + status: "True" + type: Restart + - lastTransitionTime: "2026-05-01T10:02:30Z" + message: Successfully restarted all nodes + observedGeneration: 1 + reason: RestartNodes + status: "True" + type: RestartNodes + - lastTransitionTime: "2026-05-01T10:00:10Z" + message: evict pod; ConditionStatus:True + observedGeneration: 1 + status: "True" + type: EvictPod + - lastTransitionTime: "2026-05-01T10:01:05Z" + message: check pod ready; ConditionStatus:True + observedGeneration: 1 + status: "True" + type: CheckPodReady + - lastTransitionTime: "2026-05-01T10:02:30Z" + message: Successfully completed the modification process. + observedGeneration: 1 + reason: Successful + status: "True" + type: Successful + observedGeneration: 1 + phase: Successful +``` + +## Cleaning up + +To cleanup the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracleopsrequest -n demo qdops-restart +kubectl delete oracle -n demo oracle-sample +kubectl delete ns demo +``` diff --git a/docs/guides/oracle/rotate-auth/_index.md b/docs/guides/oracle/rotate-auth/_index.md new file mode 100644 index 000000000..85e27009b --- /dev/null +++ b/docs/guides/oracle/rotate-auth/_index.md @@ -0,0 +1,10 @@ +--- +title: Rotate Auth +menu: + docs_{{ .version }}: + identifier: oracle-rotate-auth + name: Rotate Auth + parent: oracle-guides + weight: 34 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/rotate-auth/overview.md b/docs/guides/oracle/rotate-auth/overview.md new file mode 100644 index 000000000..6eccc4015 --- /dev/null +++ b/docs/guides/oracle/rotate-auth/overview.md @@ -0,0 +1,47 @@ +--- +title: Rotating Oracle Credentials +menu: + docs_{{ .version }}: + identifier: oracle-rotate-auth-overview + name: Overview + parent: oracle-rotate-auth + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Rotating Oracle Authentication Credentials + +This guide will give an overview of how KubeDB Ops-manager rotates the authentication credentials of a `Oracle` database. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + +## How Rotate Auth Works + +The Rotate Auth process consists of the following steps: + +1. At first, a user creates a `Oracle` CR. + +2. `KubeDB-Provisioner` operator watches the `Oracle` CR. + +3. When the operator finds a `Oracle` CR, it creates a `StatefulSet` and generates an `authSecret` containing the initial API key for the Oracle database. + +4. Then, in order to rotate the authentication credentials, the user creates a `OracleOpsRequest` CR with `type: RotateAuth`. The user can optionally provide a new custom secret, or let KubeDB auto-generate a new API key. + +5. `KubeDB` Ops-manager operator watches the `OracleOpsRequest` CR. + +6. When it finds a `OracleOpsRequest` CR, it pauses the `Oracle` object so that the `KubeDB-Provisioner` operator doesn't perform any operations on the `Oracle` during the credential rotation process. + +7. Then the `KubeDB` Ops-manager operator generates a new API key (or uses the provided secret), updates the `authSecret`, and restarts the pods in a rolling fashion to apply the new credentials. + +8. After the successful credential rotation, the `KubeDB` Ops-manager updates the `Oracle` object to reflect the updated auth state. + +9. After the successful Rotate Auth, the `KubeDB` Ops-manager resumes the `Oracle` object so that the `KubeDB-Provisioner` resumes its usual operations. + +In the next doc, we are going to show a step-by-step guide on rotating authentication credentials of a Oracle database using `OracleOpsRequest` CRD. diff --git a/docs/guides/oracle/rotate-auth/rotateauth.md b/docs/guides/oracle/rotate-auth/rotateauth.md new file mode 100644 index 000000000..e765faf71 --- /dev/null +++ b/docs/guides/oracle/rotate-auth/rotateauth.md @@ -0,0 +1,165 @@ +--- +title: Rotate Auth of Oracle +menu: + docs_{{ .version }}: + identifier: oracle-rotate-auth-cluster + name: Cluster + parent: oracle-rotate-auth + weight: 30 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Rotate Authentication for Oracle + +KubeDB supports rotating authentication credentials (API key) for Oracle via a `OracleOpsRequest`. This tutorial will show you how to use KubeDB to rotate authentication credentials. + +## 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` in your cluster following the steps [here](/docs/setup/README.md). + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.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/oracle/rotate-auth](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/examples/oracle/rotate-auth) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs). + +## Deploy Oracle + +In this section, we are going to deploy a Oracle database using KubeDB. + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: oracle-sample + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Let's create the `Oracle` CR we have shown above: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/rotate-auth/oracle.yaml +oracle.kubedb.com/oracle-sample created +``` + +Now, wait until `oracle-sample` has status `Ready`: + +```bash +$ kubectl get oracle -n demo +NAME VERSION STATUS AGE +oracle-sample 1.17.0 Ready 3m22s +``` + +When Oracle is deployed, KubeDB creates a secret called `oracle-sample-auth` (format: `{db-name}-auth`) that stores the API key used for authentication. + +```bash +$ kubectl get secret -n demo oracle-sample-auth -o jsonpath='{.data.api-key}' | base64 --decode + +``` + +## Apply RotateAuth OpsRequest + +Now, we are going to create a `OracleOpsRequest` to rotate the authentication credentials. + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-rotate-auth + namespace: demo +spec: + type: RotateAuth + databaseRef: + name: oracle-sample +``` + +Here, + +- `spec.databaseRef.name` specifies that we are rotating auth credentials for `oracle-sample` Oracle database. +- `spec.type` specifies that we are performing `RotateAuth` on our database. + +Let's create the `OracleOpsRequest` CR we have shown above: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/rotate-auth/ops.yaml +oracleopsrequest.ops.kubedb.com/qdops-rotate-auth created +``` + +## Verify Authentication Rotated + +If everything goes well, `KubeDB` ops-manager operator will rotate the authentication credentials of the `Oracle` database. + +Let's wait for `OracleOpsRequest` to be `Successful`: + +```bash +$ watch -n 3 kubectl get OracleOpsRequest -n demo qdops-rotate-auth +Every 3.0s: kubectl get OracleOpsRequest -n demo qdops-rotate-auth + +NAME TYPE STATUS AGE +qdops-rotate-auth RotateAuth Successful 2m15s +``` + +We can see from the above output that the `OracleOpsRequest` has succeeded. Now let's check if the authentication secret has been updated: + +```bash +$ kubectl get secret -n demo oracle-sample-auth -o jsonpath='{.data.api-key}' | base64 --decode + +``` + +You can see that the API key has been rotated. The new key is different from the initial key. KubeDB has automatically updated the Oracle instances to use the new credentials. + +## Rotate Auth with a Custom Secret + +You can also rotate the authentication credentials using a custom secret that you provide: + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-rotate-auth-custom + namespace: demo +spec: + type: RotateAuth + databaseRef: + name: oracle-sample + authentication: + secretRef: + name: my-custom-auth-secret +``` + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/examples/oracle/rotate-auth/ops-custom.yaml +oracleopsrequest.ops.kubedb.com/qdops-rotate-auth-custom created +``` + +## Cleaning up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracleopsrequest -n demo qdops-rotate-auth qdops-rotate-auth-custom +kubectl delete oracle -n demo oracle-sample +kubectl delete ns demo +``` \ No newline at end of file diff --git a/docs/guides/oracle/scaling/_index.md b/docs/guides/oracle/scaling/_index.md new file mode 100644 index 000000000..24cf8cdbf --- /dev/null +++ b/docs/guides/oracle/scaling/_index.md @@ -0,0 +1,10 @@ +--- +title: Scaling +menu: + docs_{{ .version }}: + identifier: oracle-scaling + name: Scaling + parent: oracle-guides + weight: 37 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/scaling/horizontal-scaling/_index.md b/docs/guides/oracle/scaling/horizontal-scaling/_index.md new file mode 100644 index 000000000..e8b1591d5 --- /dev/null +++ b/docs/guides/oracle/scaling/horizontal-scaling/_index.md @@ -0,0 +1,10 @@ +--- +title: Horizontal Scaling +menu: + docs_{{ .version }}: + identifier: oracle-horizontal-scaling + name: Horizontal Scaling + parent: oracle-scaling + weight: 10 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/scaling/horizontal-scaling/overview.md b/docs/guides/oracle/scaling/horizontal-scaling/overview.md new file mode 100644 index 000000000..ea66e4c0b --- /dev/null +++ b/docs/guides/oracle/scaling/horizontal-scaling/overview.md @@ -0,0 +1,47 @@ +--- +title: Oracle Horizontal Scaling Overview +menu: + docs_{{ .version }}: + identifier: oracle-horizontal-scaling-overview + name: Overview + parent: oracle-horizontal-scaling + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Oracle Horizontal Scaling + +This guide will give an overview of how KubeDB Ops-manager scales the number of nodes in a `Oracle` database cluster. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + +## How Horizontal Scaling Works + +The Horizontal Scaling process consists of the following steps: + +1. At first, a user creates a `Oracle` CR. + +2. `KubeDB-Provisioner` operator watches the `Oracle` CR. + +3. When the operator finds a `Oracle` CR, it creates a `StatefulSet` with the specified number of node replicas, along with related necessary stuff like secrets, services, etc. + +4. Then, in order to scale the number of nodes in the `Oracle` cluster, the user creates a `OracleOpsRequest` CR with the desired node count. + +5. `KubeDB` Ops-manager operator watches the `OracleOpsRequest` CR. + +6. When it finds a `OracleOpsRequest` CR, it pauses the `Oracle` object so that the `KubeDB-Provisioner` operator doesn't perform any operations on the `Oracle` during the scaling process. + +7. Then the `KubeDB` Ops-manager operator scales the `StatefulSet` to the desired number of replicas. + +8. After the successful scaling of the `StatefulSet`, the `KubeDB` Ops-manager updates the replica count in the `Oracle` object to reflect the updated state. + +9. After the successful Horizontal Scaling, the `KubeDB` Ops-manager resumes the `Oracle` object so that the `KubeDB-Provisioner` resumes its usual operations. + +In the next doc, we are going to show a step-by-step guide on Horizontal Scaling of a Oracle database using `OracleOpsRequest` CRD. diff --git a/docs/guides/oracle/scaling/horizontal-scaling/scale-horizontally/index.md b/docs/guides/oracle/scaling/horizontal-scaling/scale-horizontally/index.md new file mode 100644 index 000000000..1d4cf4c98 --- /dev/null +++ b/docs/guides/oracle/scaling/horizontal-scaling/scale-horizontally/index.md @@ -0,0 +1,234 @@ +--- +title: Scale Oracle Horizontally +menu: + docs_{{ .version }}: + identifier: oracle-scale-horizontally + name: Scale Horizontally + parent: oracle-horizontal-scaling + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Horizontal Scale Oracle Cluster + +This guide will show you how to use `KubeDB` Ops Manager to increase/decrease the number of nodes in a `Oracle` cluster. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install `KubeDB` in your cluster following the steps [here](/docs/setup/README.md). + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + - [Horizontal Scaling Overview](/docs/guides/oracle/scaling/horizontal-scaling/overview.md) + +To keep everything isolated, we are going to use a separate namespace called `demo` throughout this tutorial. + +```bash +$ kubectl create ns demo +namespace/demo created +``` + +> **Note:** YAML files used in this tutorial are stored in [docs/guides/oracle/scaling/horizontal-scaling/scale-horizontally/yamls](/docs/guides/oracle/scaling/horizontal-scaling/scale-horizontally/yamls) directory of [kubedb/docs](https://github.com/kubedb/docs) repository. + +### Apply Horizontal Scaling on Oracle Cluster + +Here, we are going to deploy a `Oracle` cluster using a supported version by `KubeDB` operator. Then we are going to apply horizontal scaling on it. + +#### Prepare Cluster + +At first, we are going to deploy a cluster with 3 nodes. Then, we are going to add two additional nodes through horizontal scaling. Finally, we will remove 1 node from the cluster again via horizontal scaling. + +**Deploy Oracle Cluster:** + +In this section, we are going to deploy a Oracle cluster with 3 nodes. Then, in the next section we will scale the cluster using horizontal scaling. Below is the YAML of the `Oracle` CR that we are going to create: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: oracle-sample + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Let's create the `Oracle` CR we have shown above: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/scaling/horizontal-scaling/scale-horizontally/yamls/oracle.yaml +oracle.kubedb.com/oracle-sample created +``` + +**Wait for the cluster to be ready:** + +`KubeDB` operator watches for `Oracle` objects using Kubernetes API. When a `Oracle` object is created, `KubeDB` operator will create a new PetSet, Services, and Secrets, etc. + +Now, watch `Oracle` is going to `Running` state and also watch `PetSet` and its pods: + +```bash +$ watch -n 3 kubectl get oracle -n demo oracle-sample +Every 3.0s: kubectl get oracle -n demo oracle-sample + +NAME VERSION STATUS AGE +oracle-sample 1.17.0 Ready 4m40m + + +$ watch -n 3 kubectl get petset -n demo oracle-sample +Every 3.0s: kubectl get petset -n demo oracle-sample + +NAME READY AGE +oracle-sample 3/3 4m41m + + +$ watch -n 3 kubectl get pods -n demo +Every 3.0s: kubectl get pod -n demo + +NAME READY STATUS RESTARTS AGE +oracle-sample-0 1/1 Running 0 4m25m +oracle-sample-1 1/1 Running 0 4m26m +oracle-sample-2 1/1 Running 0 4m26m +``` + +Let's check the current number of nodes: + +```bash +$ kubectl get oracle -n demo oracle-sample -o=jsonpath='{.spec.replicas}{"\n"}' +3 +``` + +We are ready to apply the `OracleOpsRequest` CR to scale horizontally. + +#### Scale Up + +Here, we are going to scale up the cluster from 3 nodes to 5 nodes. + +**Create OracleOpsRequest:** + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-hscale-up + namespace: demo +spec: + type: HorizontalScaling + databaseRef: + name: oracle-sample + horizontalScaling: + node: 5 +``` + +Here, + +- `spec.databaseRef.name` specifies that we are performing horizontal scaling on `oracle-sample` Oracle database. +- `spec.type` specifies that we are performing `HorizontalScaling` on our database. +- `spec.horizontalScaling.node` specifies the desired number of nodes after scaling. + +Let's create the `OracleOpsRequest` CR we have shown above: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/scaling/horizontal-scaling/scale-horizontally/yamls/hscale-up.yaml +oracleopsrequest.ops.kubedb.com/qdops-hscale-up created +``` + +**Verify Oracle scale-up completed successfully:** + +```bash +$ watch -n 3 kubectl get OracleOpsRequest -n demo qdops-hscale-up +Every 3.0s: kubectl get OracleOpsRequest -n demo qdops-hscale-up + +NAME TYPE STATUS AGE +qdops-hscale-up HorizontalScaling Successful 3m57s +``` + +Now let's verify that the number of nodes has increased: + +```bash +$ kubectl get oracle -n demo oracle-sample -o=jsonpath='{.spec.replicas}{"\n"}' +5 + +$ kubectl get pods -n demo +NAME READY STATUS RESTARTS AGE +oracle-sample-0 1/1 Running 0 10m +oracle-sample-1 1/1 Running 0 10m +oracle-sample-2 1/1 Running 0 10m +oracle-sample-3 1/1 Running 0 2m +oracle-sample-4 1/1 Running 0 1m +``` + +#### Scale Down + +Here, we are going to scale down the cluster from 5 nodes to 4 nodes. + +**Create OracleOpsRequest:** + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-hscale-down + namespace: demo +spec: + type: HorizontalScaling + databaseRef: + name: oracle-sample + horizontalScaling: + node: 4 +``` + +Let's create the `OracleOpsRequest` CR we have shown above: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/scaling/horizontal-scaling/scale-horizontally/yamls/hscale-down.yaml +oracleopsrequest.ops.kubedb.com/qdops-hscale-down created +``` + +**Verify Oracle scale-down completed successfully:** + +```bash +$ watch -n 3 kubectl get OracleOpsRequest -n demo qdops-hscale-down +Every 3.0s: kubectl get OracleOpsRequest -n demo qdops-hscale-down + +NAME TYPE STATUS AGE +qdops-hscale-down HorizontalScaling Successful 2m15s +``` + +Now let's verify that the number of nodes has decreased: + +```bash +$ kubectl get oracle -n demo oracle-sample -o=jsonpath='{.spec.replicas}{"\n"}' +4 + +$ kubectl get pods -n demo +NAME READY STATUS RESTARTS AGE +oracle-sample-0 1/1 Running 0 14m +oracle-sample-1 1/1 Running 0 14m +oracle-sample-2 1/1 Running 0 14m +oracle-sample-3 1/1 Running 0 6m +``` + +We have successfully performed horizontal scaling on the Oracle cluster. + +## Cleaning Up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracle -n demo oracle-sample +kubectl delete OracleOpsRequest -n demo qdops-hscale-up qdops-hscale-down +``` \ No newline at end of file diff --git a/docs/guides/oracle/scaling/vertical-scaling/_index.md b/docs/guides/oracle/scaling/vertical-scaling/_index.md new file mode 100644 index 000000000..4933ca021 --- /dev/null +++ b/docs/guides/oracle/scaling/vertical-scaling/_index.md @@ -0,0 +1,10 @@ +--- +title: Vertical Scaling +menu: + docs_{{ .version }}: + identifier: oracle-vertical-scaling + name: Vertical Scaling + parent: oracle-scaling + weight: 20 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/scaling/vertical-scaling/overview.md b/docs/guides/oracle/scaling/vertical-scaling/overview.md new file mode 100644 index 000000000..ea9d224ea --- /dev/null +++ b/docs/guides/oracle/scaling/vertical-scaling/overview.md @@ -0,0 +1,47 @@ +--- +title: Oracle Vertical Scaling Overview +menu: + docs_{{ .version }}: + identifier: oracle-vertical-scaling-overview + name: Overview + parent: oracle-vertical-scaling + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Oracle Vertical Scaling + +This guide will give an overview of how KubeDB Ops-manager updates the CPU and memory resources of `Oracle` database nodes. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + +## How Vertical Scaling Works + +The Vertical Scaling process consists of the following steps: + +1. At first, a user creates a `Oracle` CR. + +2. `KubeDB-Provisioner` operator watches the `Oracle` CR. + +3. When the operator finds a `Oracle` CR, it creates a `StatefulSet` and related necessary stuff like secrets, services, etc. + +4. Then, in order to update the CPU and memory resources of the `Oracle` database nodes, the user creates a `OracleOpsRequest` CR with the desired resource specifications. + +5. `KubeDB` Ops-manager operator watches the `OracleOpsRequest` CR. + +6. When it finds a `OracleOpsRequest` CR, it pauses the `Oracle` object so that the `KubeDB-Provisioner` operator doesn't perform any operations on the `Oracle` during the scaling process. + +7. Then the `KubeDB` Ops-manager operator updates the resources of the `StatefulSet` pods to the desired values defined in the `OracleOpsRequest` CR. + +8. After the successful resource update of the pods, the `KubeDB` Ops-manager updates the resource specifications in the `Oracle` object to reflect the updated state. + +9. After the successful Vertical Scaling, the `KubeDB` Ops-manager resumes the `Oracle` object so that the `KubeDB-Provisioner` resumes its usual operations. + +In the next doc, we are going to show a step-by-step guide on Vertical Scaling of a Oracle database using `OracleOpsRequest` CRD. diff --git a/docs/guides/oracle/scaling/vertical-scaling/scale-vertically/index.md b/docs/guides/oracle/scaling/vertical-scaling/scale-vertically/index.md new file mode 100644 index 000000000..671283745 --- /dev/null +++ b/docs/guides/oracle/scaling/vertical-scaling/scale-vertically/index.md @@ -0,0 +1,191 @@ +--- +title: Scale Oracle Vertically +menu: + docs_{{ .version }}: + identifier: oracle-scale-vertically + name: Scale Vertically + parent: oracle-vertical-scaling + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Vertical Scale Oracle Cluster + +This guide will show you how to use `KubeDB` Ops Manager to update the resources of a `Oracle` instance. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install `KubeDB` Provisioner and Ops-manager operator in your cluster following the steps [here](/docs/setup/README.md). + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + - [Vertical Scaling Overview](/docs/guides/oracle/scaling/vertical-scaling/overview.md) + +To keep everything isolated, we are going to use a separate namespace called `demo` throughout this tutorial. + +```bash +$ kubectl create ns demo +namespace/demo created +``` + +> **Note:** YAML files used in this tutorial are stored in [docs/guides/oracle/scaling/vertical-scaling/scale-vertically/yamls](/docs/guides/oracle/scaling/vertical-scaling/scale-vertically/yamls) directory of [kubedb/docs](https://github.com/kubedb/docs) repository. + +### Apply Vertical Scaling on Oracle Cluster + +Here, we are going to deploy a `Oracle` cluster using a supported version by `KubeDB` operator. Then we are going to apply vertical scaling on it. + +**Deploy Oracle:** + +In this section, we are going to deploy a Oracle cluster. Then, in the next section, we will update the resources of the database nodes using vertical scaling. Below is the YAML of the `Oracle` CR that we are going to create: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: oracle-sample + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Let's create the `Oracle` CR we have shown above: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/scaling/vertical-scaling/scale-vertically/yamls/oracle.yaml +oracle.kubedb.com/oracle-sample created +``` + +**Wait for the cluster to be ready:** + +```bash +$ watch -n 3 kubectl get oracle -n demo oracle-sample +Every 3.0s: kubectl get oracle -n demo oracle-sample + +NAME VERSION STATUS AGE +oracle-sample 1.17.0 Ready 3m16s + +$ watch -n 3 kubectl get petset -n demo oracle-sample +Every 3.0s: kubectl get petset -n demo oracle-sample + +NAME READY AGE +oracle-sample 3/3 3m54s + +$ watch -n 3 kubectl get pod -n demo +Every 3.0s: kubectl get pod -n demo + +NAME READY STATUS RESTARTS AGE +oracle-sample-0 1/1 Running 0 4m51s +oracle-sample-1 1/1 Running 0 3m50s +oracle-sample-2 1/1 Running 0 3m46s +``` + +Let's check the resources of the `oracle-sample-0` pod: + +```bash +$ kubectl get pod -n demo oracle-sample-0 -o json | jq '.spec.containers[0].resources' +{ + "limits": { + "memory": "1Gi" + }, + "requests": { + "cpu": "250m", + "memory": "512Mi" + } +} +``` + +We are ready to apply the `OracleOpsRequest` CR to vertically scale the cluster. + +#### Create OracleOpsRequest for Vertical Scaling + +In order to update the resources of the database, we have to create a `OracleOpsRequest` CR with our desired resources. Below is the YAML of the `OracleOpsRequest` CR that we are going to create: + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-vscale + namespace: demo +spec: + type: VerticalScaling + databaseRef: + name: oracle-sample + verticalScaling: + node: + resources: + requests: + cpu: "500m" + memory: "1Gi" + limits: + cpu: "1" + memory: "2Gi" +``` + +Here, + +- `spec.databaseRef.name` specifies that we are performing vertical scaling on `oracle-sample` Oracle database. +- `spec.type` specifies that we are performing `VerticalScaling` on our database. +- `spec.verticalScaling.node.resources` specifies the desired CPU and memory resources for the Oracle nodes. + +Let's create the `OracleOpsRequest` CR we have shown above: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/scaling/vertical-scaling/scale-vertically/yamls/vscale.yaml +oracleopsrequest.ops.kubedb.com/qdops-vscale created +``` + +#### Verify Oracle vertical scaling completed successfully + +If everything goes well, `KubeDB` Ops-manager operator will update the resources of the `Oracle` object and related `PetSet`. + +Let's wait for `OracleOpsRequest` to be `Successful`: + +```bash +$ watch -n 3 kubectl get OracleOpsRequest -n demo qdops-vscale +Every 3.0s: kubectl get OracleOpsRequest -n demo qdops-vscale + +NAME TYPE STATUS AGE +qdops-vscale VerticalScaling Successful 3m12s +``` + +Now, let's verify that the resources of the pods have been updated: + +```bash +$ kubectl get pod -n demo oracle-sample-0 -o json | jq '.spec.containers[0].resources' +{ + "limits": { + "cpu": "1", + "memory": "2Gi" + }, + "requests": { + "cpu": "500m", + "memory": "1Gi" + } +} +``` + +You can see from the above output that the resources of the `oracle-sample-0` pod have been updated successfully. All pods in the cluster will have the same updated resource configuration. + +## Cleaning Up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracle -n demo oracle-sample +kubectl delete OracleOpsRequest -n demo qdops-vscale +``` \ No newline at end of file diff --git a/docs/guides/oracle/tls/_index.md b/docs/guides/oracle/tls/_index.md new file mode 100644 index 000000000..ab6ad340e --- /dev/null +++ b/docs/guides/oracle/tls/_index.md @@ -0,0 +1,10 @@ +--- +title: Oracle TLS +menu: + docs_{{ .version }}: + identifier: oracle-tls + name: TLS + parent: oracle-guides + weight: 25 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/tls/configure/index.md b/docs/guides/oracle/tls/configure/index.md new file mode 100644 index 000000000..3a8bdecee --- /dev/null +++ b/docs/guides/oracle/tls/configure/index.md @@ -0,0 +1,173 @@ +--- +title: Configure TLS in Oracle +menu: + docs_{{ .version }}: + identifier: oracle-tls-configure + name: Configure TLS + parent: oracle-tls + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Configure TLS/SSL in Oracle + +`KubeDB` provides support for TLS/SSL encryption for `Oracle`. This tutorial will show you how to use `KubeDB` to deploy a `Oracle` database with TLS/SSL configuration. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install [`cert-manager`](https://cert-manager.io/docs/installation/) v1.4.0 or later to your cluster to manage your SSL/TLS certificates. + +- Install `KubeDB` in your cluster following the steps [here](/docs/setup/README.md). + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [TLS Overview](/docs/guides/oracle/tls/overview.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/guides/oracle/tls/configure/yamls](/docs/guides/oracle/tls/configure/yamls) directory of [kubedb/docs](https://github.com/kubedb/docs) repository. + +### Deploy Oracle database with TLS/SSL configuration + +As a pre-requisite, we are going to create an Issuer/ClusterIssuer. This Issuer/ClusterIssuer is used to create certificates. Then we are going to deploy a Oracle with TLS/SSL configuration. + +### Create Issuer/ClusterIssuer + +Now, we are going to create an example `Issuer` that will be used throughout the duration of this tutorial. Alternatively, you can follow this [cert-manager tutorial](https://cert-manager.io/docs/configuration/ca/) to create your own `Issuer`. By following the below steps, we are going to create our desired issuer, + +- Start off by generating our ca-certificates using openssl: + +```bash +openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ca.key -out ./ca.crt -subj "/CN=oracle/O=kubedb" +``` + +- Create a secret using the certificate files we have just generated: + +```bash +$ kubectl create secret tls oracle-ca --cert=ca.crt --key=ca.key --namespace=demo +secret/oracle-ca created +``` + +Now, we are going to create an `Issuer` using the `oracle-ca` secret that contains the CA certificate we have just created. Below is the YAML of the `Issuer` CR that we are going to create: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: oracle-ca-issuer + namespace: demo +spec: + ca: + secretName: oracle-ca +``` + +Let's create the `Issuer` CR we have shown above: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/tls/configure/yamls/issuer.yaml +issuer.cert-manager.io/oracle-ca-issuer created +``` + +### Deploy Oracle cluster with TLS/SSL configuration + +Here, our issuer `oracle-ca-issuer` is ready to deploy a `Oracle` cluster with TLS/SSL configuration. Below is the YAML for the Oracle cluster that we are going to create: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: oracle-tls + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + tcpsConfig: + tls: + issuerRef: + apiGroup: cert-manager.io + name: oracle-ca-issuer + kind: Issuer + certificates: + - alias: server + subject: + organizations: + - kubedb:server + dnsNames: + - localhost + ipAddresses: + - "127.0.0.1" + storage: + storageClassName: "standard" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Here, + +- `spec.tcpsConfig.tls.issuerRef` refers to the `oracle-ca-issuer` issuer. +- `spec.tcpsConfig.tls.certificates` provides options to configure certificate renewal and keep-alive. You can find more details from [here](/docs/guides/oracle/concepts/oracle.md#tls). + +**Deploy Oracle Cluster:** + +Let's create the `Oracle` CR we have shown above: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/tls/configure/yamls/tls-oracle.yaml +oracle.kubedb.com/oracle-tls created +``` + +**Wait for the database to be ready:** + +Now, watch `Oracle` going to `Running` state and also watch `PetSet` and its pods going to `Running` state: + +```bash +$ watch kubectl get oracle -n demo oracle-tls +NAME VERSION STATUS AGE +oracle-tls 1.17.0 Ready 62s + +$ watch -n 3 kubectl get petset -n demo oracle-tls +NAME READY AGE +oracle-tls 3/3 2m30s + +$ watch -n 3 kubectl get pod -n demo -l app.kubernetes.io/instance=oracle-tls +NAME READY STATUS RESTARTS AGE +oracle-tls-0 1/1 Running 0 3m5s +oracle-tls-1 1/1 Running 0 2m40s +oracle-tls-2 1/1 Running 0 2m20s +``` + +**Verify TLS/SSL configuration:** + +Now, let's verify the TLS/SSL configuration by checking the secrets created for the Oracle database: + +```bash +$ kubectl get secrets -n demo | grep oracle-tls +oracle-tls-server-cert kubernetes.io/tls 3 3m +oracle-tls-client-cert kubernetes.io/tls 3 3m +``` + +The TLS certificates have been created and the Oracle cluster is now configured to use TLS/SSL for both client connections and peer-to-peer communication. + +## Cleaning up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracle -n demo oracle-tls +kubectl delete issuer -n demo oracle-ca-issuer +kubectl delete ns demo +``` \ No newline at end of file diff --git a/docs/guides/oracle/tls/overview.md b/docs/guides/oracle/tls/overview.md new file mode 100644 index 000000000..479d309ff --- /dev/null +++ b/docs/guides/oracle/tls/overview.md @@ -0,0 +1,49 @@ +--- +title: Oracle TLS Overview +menu: + docs_{{ .version }}: + identifier: oracle-tls-overview + name: Overview + parent: oracle-tls + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Oracle TLS/SSL Encryption + +This guide will give an overview of how KubeDB supports TLS/SSL encryption for `Oracle` databases. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + +## How TLS Works for Oracle + +KubeDB uses `cert-manager` to manage TLS certificates for Oracle databases. The TLS configuration process consists of the following steps: + +1. At first, a user creates a `ClusterIssuer` or `Issuer` using `cert-manager`. + +2. The user then creates a `Oracle` CR with the `spec.tls` field configured, pointing to the `Issuer` or `ClusterIssuer`. + +3. `KubeDB-Provisioner` operator watches the `Oracle` CR. + +4. When the operator finds a `Oracle` CR with `spec.tls` configured, it requests TLS certificates from `cert-manager` using the specified issuer. + +5. `cert-manager` creates the certificates and stores them in a `Secret`. + +6. `KubeDB-Provisioner` operator creates the `StatefulSet` with the TLS secrets mounted, enabling encrypted communication. + +7. The `Oracle` database nodes use these certificates for encrypted client-to-server and peer-to-peer communication. + +KubeDB supports the following TLS configurations for Oracle: + +- **Add TLS** — Enable TLS on an existing non-TLS Oracle database using a `OracleOpsRequest`. +- **Rotate TLS** — Rotate the existing TLS certificates to refresh expiring certificates. +- **Remove TLS** — Remove TLS from an existing TLS-enabled Oracle database. + +In the next doc, we are going to show a step-by-step guide on configuring TLS for a Oracle database. diff --git a/docs/guides/oracle/update-version/_index.md b/docs/guides/oracle/update-version/_index.md new file mode 100644 index 000000000..2e56a2260 --- /dev/null +++ b/docs/guides/oracle/update-version/_index.md @@ -0,0 +1,10 @@ +--- +title: Update Version +menu: + docs_{{ .version }}: + identifier: oracle-update-version + name: Update Version + parent: oracle-guides + weight: 35 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/update-version/overview.md b/docs/guides/oracle/update-version/overview.md new file mode 100644 index 000000000..dbaba454e --- /dev/null +++ b/docs/guides/oracle/update-version/overview.md @@ -0,0 +1,47 @@ +--- +title: Updating Oracle Version +menu: + docs_{{ .version }}: + identifier: oracle-update-version-overview + name: Overview + parent: oracle-update-version + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Updating Oracle Version + +This guide will give you an overview of how KubeDB Ops-manager updates the version of a `Oracle` database. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + +## How the Update Process Works + +The updating process consists of the following steps: + +1. At first, a user creates a `Oracle` CR. + +2. `KubeDB-Provisioner` operator watches for the `Oracle` CR. + +3. When it finds one, it creates a `StatefulSet` and related necessary stuff like secrets, services, etc. + +4. Then, in order to update the version of the `Oracle` database, the user creates a `OracleOpsRequest` CR with the desired target version. + +5. `KubeDB-ops-manager` operator watches for `OracleOpsRequest`. + +6. When it finds one, it pauses the `Oracle` object so that the `KubeDB-Provisioner` operator doesn't perform any operations on the `Oracle` during the updating process. + +7. By looking at the target version from the `OracleOpsRequest` CR, the `KubeDB-ops-manager` operator updates the images of the `StatefulSet` for the new version. + +8. After successful update of the `StatefulSet` and its Pod images, the `KubeDB-ops-manager` updates the image of the `Oracle` object to reflect the updated cluster state. + +9. After successful update of the `Oracle` object, the `KubeDB` Ops-manager resumes the `Oracle` object so that the `KubeDB-Provisioner` can resume its usual operations. + +In the next doc, we are going to show a step-by-step guide on updating a Oracle database using the `UpdateVersion` operation. diff --git a/docs/guides/oracle/update-version/versionupgrading/index.md b/docs/guides/oracle/update-version/versionupgrading/index.md new file mode 100644 index 000000000..4811b5f47 --- /dev/null +++ b/docs/guides/oracle/update-version/versionupgrading/index.md @@ -0,0 +1,296 @@ +--- +title: Update Oracle Version +menu: + docs_{{ .version }}: + identifier: oracle-version-upgrading + name: Version Upgrading + parent: oracle-update-version + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Update Oracle Version + +This guide will show you how to use `KubeDB` ops-manager operator to update the version of `Oracle` cr. + +## Before You Begin + +- At first, you need to have a Kubernetes cluster, and the `kubectl` command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using [kind](https://kind.sigs.k8s.io/docs/user/quick-start/). + +- Install `KubeDB` in your cluster following the steps [here](/docs/setup/README.md). + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + - [Updating Overview](/docs/guides/oracle/update-version/overview/index.md) + +To keep everything isolated, we are going to use a separate namespace called `demo` throughout this tutorial. + +```bash +$ kubectl create ns demo +namespace/demo created +``` + +> **Note:** YAML files used in this tutorial are stored in [docs/guides/oracle/update-version/versionupgrading/yamls](/docs/guides/oracle/update-version/versionupgrading/yamls) directory of [kubedb/docs](https://github.com/kubedb/docs) repository. + +### Apply Version Updating on Oracle + +Here, we are going to deploy a `Oracle` instance using a supported version by `KubeDB` provisioner. Then we are going to apply update-ops-request on it. + +#### Prepare Oracle + +At first, we are going to deploy a Oracle instance using a supported `Oracle` version. In the next two sections, we are going to find out the supported versions and version update constraints. + +**Find supported OracleVersion:** + +When you have installed `KubeDB`, it has created `OracleVersion` CR for all supported `Oracle` versions. Let's check the supported versions: + +```bash +$ kubectl get oracleversion +NAME VERSION DB_IMAGE DEPRECATED AGE +1.7.4 1.7.4 oracle/oracle:v1.7.4 5m +1.8.4 1.8.4 oracle/oracle:v1.8.4 5m +1.9.7 1.9.7 oracle/oracle:v1.9.7 5m +1.10.1 1.10.1 oracle/oracle:v1.10.1 5m +1.11.5 1.11.5 oracle/oracle:v1.11.5 5m +1.12.6 1.12.6 oracle/oracle:v1.12.6 5m +1.13.4 1.13.4 oracle/oracle:v1.13.4 5m +1.14.1 1.14.1 oracle/oracle:v1.14.1 5m +1.15.1 1.15.1 oracle/oracle:v1.15.1 5m +1.16.1 1.16.1 oracle/oracle:v1.16.1 5m +1.17.0 1.17.0 oracle/oracle:v1.17.0 5m +1.18.0 1.18.0 oracle/oracle:v1.18.0 5m +``` + +The version above that does not show `DEPRECATED` `true` is supported by `KubeDB` for `Oracle`. You can use any non-deprecated version. Now, we are going to select a non-deprecated version from `OracleVersion` for the `Oracle` instance that we will update from this version to another. In the next section, we are going to verify version update constraints. + +**Check update Constraints:** + +Oracle supports rolling version updates. You can update from any currently running version to a newer patch or minor version. Major version jumps should follow the Oracle upstream upgrade notes. For example, you can update directly from `1.17.0` to `1.18.0`. + +Let's get one of the `oracleversion` YAMLs: + +```bash +$ kubectl get oracleversion 1.17.0 -o yaml | kubectl neat +apiVersion: catalog.kubedb.com/v1alpha1 +kind: OracleVersion +metadata: + labels: + app.kubernetes.io/instance: kubedb + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: kubedb-catalog + name: "1.17.0" +spec: + coordinator: + image: ghcr.io/kubedb/oracle-coordinator:v0.10.0 + db: + image: oracle/oracle:v1.17.0 + exporter: + image: container-registry.oracle.com/database/observability-exporter:2.2.1 + version: "21.3.0" +``` + +**Deploy Oracle Instance:** + +In this section, we are going to deploy a Oracle instance. Then, in the next section, we will update the version of the database using `UpdateVersion`. Below is the YAML of the `Oracle` cr that we are going to create: + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: oracle-sample + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + storage: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Let's create the `Oracle` cr we have shown above: + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/update-version/versionupgrading/yamls/oracle.yaml +oracle.kubedb.com/oracle-sample created +``` + +**Wait for the database to be ready:** + +`KubeDB` operator watches for `Oracle` objects using Kubernetes API. When a `Oracle` object is created, `KubeDB` operator will create a new PetSet, Services, and Secrets, etc. + +Now, watch `Oracle` is going to `Running` state and also watch `PetSet` and its pod is created and going to `Running` state: + +```bash +$ watch -n 3 kubectl get oracle -n demo +Every 3.0s: kubectl get oracle -n demo + +NAME VERSION STATUS AGE +oracle-sample 1.17.0 Ready 3m42s + +$ watch -n 3 kubectl get petset -n demo oracle-sample +Every 3.0s: kubectl get petset -n demo oracle-sample + +NAME READY AGE +oracle-sample 3/3 4m17s + +$ watch -n 3 kubectl get pod -n demo +Every 3.0s: kubectl get pods -n demo + +NAME READY STATUS RESTARTS AGE +oracle-sample-0 1/1 Running 0 4m55s +oracle-sample-1 1/1 Running 0 4m12s +oracle-sample-2 1/1 Running 0 3m38s +``` + +Let's verify the `Oracle`, the `PetSet` and its `Pod` image version: + +```bash +$ kubectl get oracle -n demo oracle-sample -o=jsonpath='{.spec.version}{"\n"}' +1.17.0 + +$ kubectl get petset -n demo oracle-sample -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}' +oracle/oracle:v1.17.0 + +$ kubectl get pod -n demo oracle-sample-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}' +oracle/oracle:v1.17.0 +``` + +We are ready to apply version updating on this `Oracle` instance. + +#### UpdateVersion + +Here, we are going to update `Oracle` from version `1.17.0` to `1.18.0`. + +**Create OracleOpsRequest:** + +To update the instance, you have to create a `OracleOpsRequest` cr with your desired version that is supported by `KubeDB`. Below is the YAML of the `OracleOpsRequest` cr that we are going to create: + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-update-version + namespace: demo +spec: + type: UpdateVersion + updateVersion: + targetVersion: "1.18.0" + databaseRef: + name: oracle-sample +``` + +Here, + +- `spec.databaseRef.name` specifies that we are performing operation on `oracle-sample` Oracle database. +- `spec.type` specifies that we are going to perform `UpdateVersion` on our database. +- `spec.updateVersion.targetVersion` specifies the expected version `1.18.0` after updating. + +Let's create the `OracleOpsRequest` cr we have shown above: + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/update-version/versionupgrading/yamls/update_version.yaml +oracleopsrequest.ops.kubedb.com/qdops-update-version created +``` + +**Verify Oracle version updated successfully:** + +If everything goes well, `KubeDB` ops-manager operator will update the image of `Oracle`, `PetSet`, and its `Pod`. + +At first, we will wait for `OracleOpsRequest` to be successful. Run the following command to watch `OracleOpsRequest` cr: + +```bash +$ watch -n 3 kubectl get OracleOpsRequest -n demo qdops-update-version +Every 3.0s: kubectl get OracleOpsRequest -n demo qdops-update-version + +NAME TYPE STATUS AGE +qdops-update-version UpdateVersion Successful 3m12s +``` + +We can see from the above output that the `OracleOpsRequest` has succeeded. If we describe the `OracleOpsRequest`, we shall see that the `Oracle`, `PetSet`, and its `Pod` have updated with a new image. + +```bash +$ kubectl describe OracleOpsRequest -n demo qdops-update-version +Name: qdops-update-version +Namespace: demo +Labels: +Annotations: +API Version: ops.kubedb.com/v1alpha1 +Kind: OracleOpsRequest +Spec: + Database Ref: + Name: oracle-sample + Type: UpdateVersion + Update Version: + Target Version: 1.18.0 +Status: + Conditions: + Last Transition Time: 2026-05-01T10:00:00Z + Message: Oracle ops request is updating version + Observed Generation: 1 + Reason: UpdateVersion + Status: True + Type: UpdateVersion + Last Transition Time: 2026-05-01T10:00:05Z + Message: Successfully updated PetSets update strategy type + Observed Generation: 1 + Reason: UpdatePetSets + Status: True + Type: UpdatePetSets + Last Transition Time: 2026-05-01T10:00:30Z + Message: Successfully updated pod images + Observed Generation: 1 + Reason: UpdatePetSetImage + Status: True + Type: UpdatePetSetImage + Last Transition Time: 2026-05-01T10:02:45Z + Message: Successfully completed the modification process. + Observed Generation: 1 + Reason: Successful + Status: True + Type: Successful + Observed Generation: 1 + Phase: Successful +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal PauseDatabase 3m12s KubeDB Enterprise Operator Pausing Oracle demo/oracle-sample + Normal PauseDatabase 3m12s KubeDB Enterprise Operator Successfully paused Oracle demo/oracle-sample + Normal Updating 3m12s KubeDB Enterprise Operator Updating PetSets + Normal Updating 3m12s KubeDB Enterprise Operator Successfully Updated PetSets + Normal UpdatePetSetImage 1m10s KubeDB Enterprise Operator Successfully Updated pod images + Normal ResumeDatabase 1m10s KubeDB Enterprise Operator Resuming Oracle demo/oracle-sample + Normal ResumeDatabase 1m10s KubeDB Enterprise Operator Successfully resumed Oracle demo/oracle-sample + Normal Successful 1m10s KubeDB Enterprise Operator Successfully Updated Database +``` + +Now, we are going to verify whether the `Oracle`, `PetSet` and its `Pod` have updated with the new image. Let's check: + +```bash +$ kubectl get oracle -n demo oracle-sample -o=jsonpath='{.spec.version}{"\n"}' +1.18.0 + +$ kubectl get petset -n demo oracle-sample -o=jsonpath='{.spec.template.spec.containers[0].image}{"\n"}' +oracle/oracle:v1.18.0 + +$ kubectl get pod -n demo oracle-sample-0 -o=jsonpath='{.spec.containers[0].image}{"\n"}' +oracle/oracle:v1.18.0 +``` + +You can see above that our `Oracle` has been updated with the new version. It verifies that we have successfully updated our Oracle instance. + +## Cleaning Up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +kubectl delete oracle -n demo oracle-sample +kubectl delete OracleOpsRequest -n demo qdops-update-version +``` \ No newline at end of file diff --git a/docs/guides/oracle/volume-expansion/_index.md b/docs/guides/oracle/volume-expansion/_index.md new file mode 100644 index 000000000..253a32eaa --- /dev/null +++ b/docs/guides/oracle/volume-expansion/_index.md @@ -0,0 +1,10 @@ +--- +title: Volume Expansion +menu: + docs_{{ .version }}: + identifier: oracle-volume-expansion + name: Volume Expansion + parent: oracle-guides + weight: 36 +menu_name: docs_{{ .version }} +--- diff --git a/docs/guides/oracle/volume-expansion/overview.md b/docs/guides/oracle/volume-expansion/overview.md new file mode 100644 index 000000000..6082f0015 --- /dev/null +++ b/docs/guides/oracle/volume-expansion/overview.md @@ -0,0 +1,49 @@ +--- +title: Expanding Oracle Storage +menu: + docs_{{ .version }}: + identifier: oracle-volume-expansion-overview + name: Overview + parent: oracle-volume-expansion + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Oracle Volume Expansion + +This guide will give an overview of how KubeDB Ops-manager expands the volume of a `Oracle` database. + +## Before You Begin + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + +## How Volume Expansion Works + +The Volume Expansion process consists of the following steps: + +1. At first, a user creates a `Oracle` Custom Resource (CR). + +2. `KubeDB-Provisioner` operator watches the `Oracle` CR. + +3. When the operator finds a `Oracle` CR, it creates a `StatefulSet` and related necessary stuff like pods, PVCs, secrets, services, etc. + +4. Each StatefulSet creates a Persistent Volume according to the volume claim template. This Persistent Volume will be expanded by the `KubeDB` Ops-manager operator. + +5. Then, in order to expand the volume of the `Oracle` database, the user creates a `OracleOpsRequest` CR with the desired new storage size. + +6. `KubeDB` Ops-manager operator watches the `OracleOpsRequest` CR. + +7. When it finds a `OracleOpsRequest` CR, it pauses the `Oracle` object so that the `KubeDB-Provisioner` operator doesn't perform any operations on the `Oracle` during the volume expansion process. + +8. Then the `KubeDB` Ops-manager operator expands the persistent volumes to the expected size defined in the `OracleOpsRequest` CR. + +9. After the successful expansion of the volumes, the `KubeDB` Ops-manager updates the new volume size in the `Oracle` object to reflect the updated state. + +10. After the successful Volume Expansion, the `KubeDB` Ops-manager resumes the `Oracle` object so that the `KubeDB-Provisioner` resumes its usual operations. + +In the next doc, we are going to show a step-by-step guide on Volume Expansion of a Oracle database using `OracleOpsRequest` CRD. diff --git a/docs/guides/oracle/volume-expansion/volume-expansion.md b/docs/guides/oracle/volume-expansion/volume-expansion.md new file mode 100644 index 000000000..710dd1f54 --- /dev/null +++ b/docs/guides/oracle/volume-expansion/volume-expansion.md @@ -0,0 +1,252 @@ +--- +title: Expand Oracle Volume +menu: + docs_{{ .version }}: + identifier: oracle-volume-expansion-cluster + name: Cluster + parent: oracle-volume-expansion + weight: 10 +menu_name: docs_{{ .version }} +section_menu_id: guides +--- + +> New to KubeDB? Please start [here](/docs/README.md). + +# Expand Oracle Volume + +This guide will show you how to use `KubeDB` Ops-manager operator to expand the volume of a Oracle database. + +## 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. + +- You must have a `StorageClass` that supports volume expansion. + +- Install `KubeDB` Provisioner and Ops-manager operator in your cluster following the steps [here](/docs/setup/README.md). + +- You should be familiar with the following `KubeDB` concepts: + - [Oracle](/docs/guides/oracle/concepts/oracle.md) + - [OracleOpsRequest](/docs/guides/oracle/concepts/opsrequest.md) + - [Volume Expansion Overview](/docs/guides/oracle/volume-expansion/overview.md) + +To keep everything isolated, we are going to use a separate namespace called `demo` throughout this tutorial. + +```bash +$ kubectl create ns demo +namespace/demo created +``` + +> **Note:** YAML files used in this tutorial are stored in [docs/guides/oracle/volume-expansion/yamls](/docs/guides/oracle/volume-expansion/yamls) directory of [kubedb/docs](https://github.com/kubedb/docs) repository. + +## Expand Volume of Oracle Database + +Here, we are going to deploy a `Oracle` cluster using a supported version by `KubeDB` operator. Then we are going to apply `OracleOpsRequest` to expand its volume. + +### Prepare Oracle Database + +At first verify that your cluster has a storage class that supports volume expansion. Let's check, + +```bash +$ kubectl get storageclass +NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE +standard (default) rancher.io/local-path Delete WaitForFirstConsumer false 5m +standard-expandable kubernetes.io/gce-pd Delete Immediate true 5m +``` + +We can see the `standard-expandable` storage class has `ALLOWVOLUMEEXPANSION` field as `true`. So, this storage class supports volume expansion. We can use it. + +Now, we are going to deploy a `Oracle` cluster with version `1.17.0`. + +#### Deploy Oracle + +In this section, we are going to deploy a Oracle cluster with 1Gi volume. Then, in the next section we will expand its volume to 3Gi using `OracleOpsRequest` CRD. Below is the YAML of the `Oracle` CR that we are going to create, + +```yaml +apiVersion: kubedb.com/v1alpha2 +kind: Oracle +metadata: + name: oracle-sample + namespace: demo +spec: + version: "21.3.0" + replicas: 3 + storage: + storageClassName: "standard-expandable" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi + deletionPolicy: WipeOut +``` + +Let's create the `Oracle` CR we have shown above, + +```bash +$ kubectl create -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/volume-expansion/yamls/oracle.yaml +oracle.kubedb.com/oracle-sample created +``` + +Now, wait until `oracle-sample` has status `Ready`: + +```bash +$ kubectl get oracle -n demo +NAME VERSION STATUS AGE +oracle-sample 1.17.0 Ready 3m47s +``` + +Let's check volume size from the PetSet and from the persistent volumes: + +```bash +$ kubectl get petset -n demo oracle-sample -o json | jq '.spec.volumeClaimTemplates[].spec.resources.requests.storage' +"1Gi" + +$ kubectl get pvc -n demo +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE +oracle-sample-oracle-sample-0 Bound pvc-a1b2c3d4-e5f6-7890-abcd-ef1234567890 1Gi RWO standard-expandable 4m +oracle-sample-oracle-sample-1 Bound pvc-b2c3d4e5-f6a7-8901-bcde-f01234567891 1Gi RWO standard-expandable 3m +oracle-sample-oracle-sample-2 Bound pvc-c3d4e5f6-a7b8-9012-cdef-012345678902 1Gi RWO standard-expandable 2m +``` + +You can see the PetSet has 1Gi storage, and the capacity of the persistent volumes is also 1Gi. + +We are now ready to apply the `OracleOpsRequest` CR to expand the volume of this database. + +### Volume Expansion + +Here, we are going to expand the volume of the Oracle cluster. + +#### Create OracleOpsRequest + +In order to expand the volume of the database, we have to create a `OracleOpsRequest` CR with our desired volume size. Below is the YAML of the `OracleOpsRequest` CR that we are going to create, + +```yaml +apiVersion: ops.kubedb.com/v1alpha1 +kind: OracleOpsRequest +metadata: + name: qdops-vol-exp + namespace: demo +spec: + apply: IfReady + databaseRef: + name: oracle-sample + type: VolumeExpansion + volumeExpansion: + mode: Online + node: 3Gi +``` + +Here, + +- `spec.databaseRef.name` specifies that we are performing volume expansion operation on `oracle-sample` Oracle database. +- `spec.type` specifies that we are performing `VolumeExpansion` on our database. +- `spec.volumeExpansion.node` specifies the desired volume size. +- `spec.volumeExpansion.mode` specifies the desired volume expansion mode (`Online` or `Offline`). + +> Note: If the StorageClass doesn't support `Online` volume expansion, try offline volume expansion by using `spec.volumeExpansion.mode: "Offline"`. + +During `Online` VolumeExpansion KubeDB expands volume without pausing the database object; it directly updates the underlying PVC. For `Offline` volume expansion, the database is paused, the Pods are deleted, the PVC is updated, and then the database Pods are recreated with the updated PVC. + +Let's create the `OracleOpsRequest` CR we have shown above, + +```bash +$ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/oracle/volume-expansion/yamls/qdops-vol-exp.yaml +oracleopsrequest.ops.kubedb.com/qdops-vol-exp created +``` + +#### Verify Oracle volume expanded successfully + +If everything goes well, `KubeDB` Ops-manager operator will update the volume size of the `Oracle` object and related `PetSet` and `Persistent Volumes`. + +Let's wait for `OracleOpsRequest` to be `Successful`. Run the following command to watch `OracleOpsRequest` CR, + +```bash +$ kubectl get oracleopsrequest -n demo +NAME TYPE STATUS AGE +qdops-vol-exp VolumeExpansion Successful 10m +``` + +We can see from the above output that the `OracleOpsRequest` has succeeded. If we describe the `OracleOpsRequest` we will get an overview of the steps that were followed to expand the volume of the database. + +```bash +$ kubectl describe oracleopsrequest qdops-vol-exp -n demo +Name: qdops-vol-exp +Namespace: demo +Labels: +Annotations: +API Version: ops.kubedb.com/v1alpha1 +Kind: OracleOpsRequest +Spec: + Apply: IfReady + Database Ref: + Name: oracle-sample + Type: VolumeExpansion + Volume Expansion: + Mode: Online + Node: 3Gi +Status: + Conditions: + Last Transition Time: 2026-05-01T10:04:19Z + Message: Oracle ops request is expanding volume of database + Observed Generation: 1 + Reason: Running + Status: True + Type: Running + Last Transition Time: 2026-05-01T10:05:12Z + Message: Online Volume Expansion performed successfully in Oracle pods for OracleOpsRequest: demo/qdops-vol-exp + Observed Generation: 1 + Reason: VolumeExpansion + Status: True + Type: VolumeExpansion + Last Transition Time: 2026-05-01T10:06:08Z + Message: PetSet is recreated + Observed Generation: 1 + Reason: ReadyPetSets + Status: True + Type: ReadyPetSets + Last Transition Time: 2026-05-01T10:06:52Z + Message: Successfully Expanded Volume. + Observed Generation: 1 + Reason: Successful + Status: True + Type: Successful + Observed Generation: 1 + Phase: Successful +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal PauseDatabase 12m KubeDB Ops-manager Operator Pausing Oracle demo/oracle-sample + Normal PauseDatabase 12m KubeDB Ops-manager Operator Successfully paused Oracle demo/oracle-sample + Normal VolumeExpansion 11m KubeDB Ops-manager Operator Online Volume Expansion performed successfully in Oracle pods for OracleOpsRequest: demo/qdops-vol-exp + Normal ResumeDatabase 11m KubeDB Ops-manager Operator Resuming Oracle demo/oracle-sample + Normal ResumeDatabase 11m KubeDB Ops-manager Operator Successfully resumed Oracle demo/oracle-sample + Normal ReadyPetSets 10m KubeDB Ops-manager Operator PetSet is recreated + Normal Successful 10m KubeDB Ops-manager Operator Successfully Expanded Volume +``` + +Now, we are going to verify from the `PetSet` and `Persistent Volumes` whether the volume of the Oracle database has expanded to meet the desired state: + +```bash +$ kubectl get petset -n demo oracle-sample -o json | jq '.spec.volumeClaimTemplates[].spec.resources.requests.storage' +"3Gi" + +$ kubectl get pvc -n demo +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE +oracle-sample-oracle-sample-0 Bound pvc-a1b2c3d4-e5f6-7890-abcd-ef1234567890 3Gi RWO standard-expandable 14m +oracle-sample-oracle-sample-1 Bound pvc-b2c3d4e5-f6a7-8901-bcde-f01234567891 3Gi RWO standard-expandable 13m +oracle-sample-oracle-sample-2 Bound pvc-c3d4e5f6-a7b8-9012-cdef-012345678902 3Gi RWO standard-expandable 12m +``` + +The above output verifies that we have successfully expanded the volume of the Oracle database. + +## Cleaning Up + +To clean up the Kubernetes resources created by this tutorial, run: + +```bash +$ kubectl delete oracle -n demo oracle-sample +oracle.kubedb.com "oracle-sample" deleted + +$ kubectl delete oracleopsrequest -n demo qdops-vol-exp +oracleopsrequest.ops.kubedb.com "qdops-vol-exp" deleted +``` \ No newline at end of file