|
| 1 | +# Oracle Database Operator for Kubernetes |
| 2 | + |
| 3 | +## Make Oracle Database Kubernetes-Native |
| 4 | + |
| 5 | +As part of Oracle's resolution to make Oracle Database Kubernetes-native (that is, observable and operable by Kubernetes), Oracle is announcing _Oracle Database Operator for Kubernetes_ (`OraOperator`). |
| 6 | + |
| 7 | +Since Oracle Database 19c, Oracle Database images have been supported in containers (Docker, Podman) for production use and Kubernetes deployment with Helm Charts. This release includes Oracle Database Operator, which is a new open source product that extends the Kubernetes API with custom resources and controllers for automating Oracle Database lifecycle management. |
| 8 | + |
| 9 | +In this release, `OraOperator` supports the following Oracle Database configurations: |
| 10 | + |
| 11 | +* Oracle Autonomous Database on shared Oracle Cloud Infrastructure (OCI), also known as ADB-S |
| 12 | +* Containerized Single Instance databases (SIDB) deployed in the Oracle Kubernetes Engine (OKE) |
| 13 | +* Containerized Sharded databases (SHARDED) deployed in OKE |
| 14 | + |
| 15 | +Oracle will continue to expand Oracle Database Operator support for additional Oracle Database configurations. |
| 16 | + |
| 17 | +## Features Summary |
| 18 | + |
| 19 | +This release of Oracle Database Operator for Kubernetes (the operator) supports the following lifecycle operations: |
| 20 | + |
| 21 | +* ADB-S: provision, bind, start, stop, terminate (soft/hard), scale (down/up) |
| 22 | +* SIDB: provision, clone, patch (in-place/out-of-place), update database initialization parameters, update database configuration (Flashback, archiving), Oracle Enterprise Manager (EM) Express (a basic observability console) |
| 23 | +* SHARDED: provision/deploy sharded databases and the shard topology, add a new shard, delete an existing shard |
| 24 | + |
| 25 | +Upcoming releases will support new configurations, operations and capabilities. |
| 26 | + |
| 27 | +## Release Status |
| 28 | + |
| 29 | +**CAUTION:** The current release of `OraOperator` (v0.1.0) is for development and test only. DO NOT USE IN PRODUCTION. |
| 30 | + |
| 31 | +This release can be deployed on the following platforms: |
| 32 | + |
| 33 | +* [Oracle Container Engine for Kubernetes (OKE)](https://www.oracle.com/cloud-native/container-engine-kubernetes/) with Kubernetes 1.17 or later |
| 34 | +* In an on-premises [Oracle Linux Cloud Native Environment(OLCNE)](https://docs.oracle.com/en/operating-systems/olcne/) 1.3 or later |
| 35 | + |
| 36 | +In upcoming releases, the operator will be certified against third-party Kubernetes clusters. |
| 37 | + |
| 38 | +## Prerequisites |
| 39 | + |
| 40 | +Oracle strongly recommends that you ensure your system meets the following [Prerequisites](./PREREQUISITES.md). |
| 41 | + |
| 42 | +* ### Install cert-manager |
| 43 | + |
| 44 | + The operator uses webhooks for validating user input before persisting it in Etcd. Webhooks require TLS certificates that are generated and managed by a certificate manager. |
| 45 | + |
| 46 | + Install the certificate manager with the following command: |
| 47 | + |
| 48 | + ```sh |
| 49 | + kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.yaml |
| 50 | + ``` |
| 51 | + |
| 52 | +* ### Create Operator Image Pull Secrets |
| 53 | + |
| 54 | + Sign into [https://container-registry.oracle.com/](https://container-registry.oracle.com/) and accept the license agreement for the Operator image. |
| 55 | + |
| 56 | + Create an image pull secret for Oracle Container Registry: |
| 57 | + |
| 58 | + ```sh |
| 59 | + kubectl create namespace oracle-database-operator-system |
| 60 | + kubectl create secret docker-registry container-registry-secret -n oracle-database-operator-system --docker-server=container-registry.oracle.com --docker-username='<oracle-sso-email-address>' --docker-password='<oracle-sso-password>' --docker-email='<oracle-sso-email-address>' |
| 61 | + ``` |
| 62 | + |
| 63 | +## Quick Install of the Operator |
| 64 | + |
| 65 | + To install the operator in the cluster quickly, you can use a single [oracle-database-operator.yaml](https://github.com/oracle/oracle-database-operator/blob/main/oracle-database-operator.yaml) file. Operator pod replicas are set to a default of 3 for High Availability, which can be scaled up and down. |
| 66 | + |
| 67 | + Run the following command |
| 68 | + |
| 69 | + ```sh |
| 70 | + kubectl apply -f oracle-database-operator.yaml |
| 71 | + ``` |
| 72 | + |
| 73 | + Ensure that operator pods are up and running |
| 74 | + |
| 75 | + ```sh |
| 76 | + $ kubectl get pods -n oracle-database-operator-system |
| 77 | + |
| 78 | + NAME READY STATUS RESTARTS AGE |
| 79 | + pod/oracle-database-operator-controller-manager-78666fdddb-s4xcm 1/1 Running 0 11d |
| 80 | + pod/oracle-database-operator-controller-manager-78666fdddb-5k6n4 1/1 Running 0 11d |
| 81 | + pod/oracle-database-operator-controller-manager-78666fdddb-t6bzb 1/1 Running 0 11d |
| 82 | + |
| 83 | + ``` |
| 84 | + |
| 85 | +* Check the resources |
| 86 | + |
| 87 | +You should see that the operator is up and running, along with the shipped controllers. |
| 88 | + |
| 89 | +For more details, see [Oracle Database Operator Installation Instrunctions](./doc/installation/OPERATOR_INSTALLATION_README.md). |
| 90 | + |
| 91 | +## Getting Started with the Operator (Quickstart) |
| 92 | + |
| 93 | +The quickstarts are designed for specific database configurations, including: |
| 94 | + |
| 95 | +* [Oracle Autonomous Database](./doc/adb/ORACLE_ADB_CONTROLLER_README.md) |
| 96 | +* [Oracle Database Single Instance configuration](./doc/sidb/ORACLE_SIDB_CONTROLLER_README.md) |
| 97 | +* [Oracle Database configured with Oracle Sharding](./doc/sharding/ORACLE_SHARDING_CONTROLLER_README.md) |
| 98 | + |
| 99 | +YAML file templates are available under [`/config/samples`](./config/samples/). You can copy and edit these template files to configure them for your use cases. |
| 100 | + |
| 101 | +## Uninstall the Operator |
| 102 | + |
| 103 | + To uninstall the operator, the final step consists of deciding whether or not you want to delete the CRDs and APIServices that were introduced to the cluster by the operator. Choose one of the following options: |
| 104 | + |
| 105 | +* ### Deleting the CRDs and APIServices |
| 106 | + |
| 107 | + To delete all the CRD instances deployed to cluster by the operator, run the following commands, where <namespace> is the namespace of the cluster object: |
| 108 | + |
| 109 | + ```sh |
| 110 | + kubectl delete singleinstancedatabase.database.oracle.com --all -n <namespace> |
| 111 | + kubectl delete shardingdatabase.database.oracle.com --all -n <namespace> |
| 112 | + kubectl delete autonomousdatabase.database.oracle.com --all -n <namespace> |
| 113 | + ``` |
| 114 | + |
| 115 | + After all CRD instances are deleted, it is safe to remove the CRDs, APISerivces and operator deployment. |
| 116 | + |
| 117 | + ```sh |
| 118 | + kubectl delete -f oracle-database-operator.yaml --ignore-not-found=true |
| 119 | + ``` |
| 120 | + |
| 121 | + Note: If the CRD instances are not deleted, and the operator is deleted by using the preceding command, then operator deployment and instance objects (pods,services,PVCs, and so on) are deleted. However, the CRD deletion stops responding, because the CRD instances have finalizers that can only be removed by the operator pod, which is deleted when the APIServices are deleted. |
| 122 | + |
| 123 | +* ### Retain the CRDs and APIservices |
| 124 | + |
| 125 | + To delete the operator deployment and retain the CRDs, run the following commands: |
| 126 | + |
| 127 | + ```sh |
| 128 | + kubectl delete deployment.apps/oracle-database-operator-controller-manager -n oracle-database-operator-system |
| 129 | + ``` |
| 130 | + |
| 131 | +## Documentation |
| 132 | + |
| 133 | +* [Oracle Autonomous Database](https://docs.oracle.com/en-us/iaas/Content/Database/Concepts/adboverview.htm) |
| 134 | +* [Oracle Database Single Instance](https://docs.oracle.com/en/database/oracle/oracle-database/) |
| 135 | +* [Oracle Database Sharding](https://docs.oracle.com/en/database/oracle/oracle-database/21/shard/index.html) |
| 136 | + |
| 137 | +## Contributing |
| 138 | + |
| 139 | +See [Contributing to this Repository](./CONTRIBUTING.md) |
| 140 | + |
| 141 | +## Support |
| 142 | + |
| 143 | +You can submit a GitHub issue, or you can also file an [Oracle Support service](https://support.oracle.com/portal/) request, using the product id: 14430. |
| 144 | + |
| 145 | +## Security |
| 146 | + |
| 147 | +Secure platforms are an important basis for general system security. Ensure that your deployment is in compliance with common security practices. |
| 148 | + |
| 149 | +### Managing Sensitive Data |
| 150 | +Kubernetes secrets are the usual means for storing credentials or passwords input for access. The operator reads the Secrets programmatically, which limits exposure of sensitive data. However, to protect your sensitive data, Oracle strongly recommends that you set and get sensitive data from Oracle Cloud Infrastructure Vault, or from third-party Vaults. |
| 151 | + |
| 152 | +The following is an example of a YAML file fragment for specifying Oracle Cloud Infrastructure Vault as the repository for the admin password. |
| 153 | + ``` |
| 154 | + adminPassword: |
| 155 | + ociSecretOCID: ocid1.vaultsecret.oc1... |
| 156 | +``` |
| 157 | +Examples in this repository where passwords are entered on the command line are for demonstration purposes only. |
| 158 | + |
| 159 | +### Reporting a Security Issue |
| 160 | + |
| 161 | +See [Reporting security vulnerabilities](./SECURITY.md) |
| 162 | + |
| 163 | + |
| 164 | + |
| 165 | +## License |
| 166 | + |
| 167 | +Copyright (c) 2021 Oracle and/or its affiliates. |
| 168 | +Released under the Universal Permissive License v1.0 as shown at [https://oss.oracle.com/licenses/upl/](https://oss.oracle.com/licenses/upl/) |
0 commit comments