Merge pull request #177 from oracle/ordssrvs_documentation

Ordssrvs documentation

Author: mmalvezz

README.md

@@ -189,10 +189,7 @@ The following quickstarts are designed for specific database configurations:
 * [Containerized Oracle Globally Distributed Database](./docs/sharding/README.md)
 * [Oracle Multitenant Database](./docs/multitenant/README.md)
 * [Oracle Base Database Service (OBDS)](./docs/dbcs/README.md)
-
-
-The following quickstart is designed for non-database configurations:
-* [Oracle Database Observability](./docs/observability/README.md)
+* [ORDS Services (ORDSSRVS)](./docs/ordsservices/README.md)
 
 
 The following quickstart is designed for non-database configurations:

docs/ordsservices/README.md

@@ -25,22 +25,53 @@ It supports the majority of ORDS configuration settings as per the [API Document
 The ORDS and APEX schemas can be [automatically installed/upgraded](./autoupgrade.md) into the Oracle Database by the ORDS controller.
 
 ORDS Version support: 
-* v22.1+
+* 24.1.1  
+(Newer versions of ORDS will be supported in the next update of OraOperator)
 
 Oracle Database Version: 
 * 19c
 * 23ai (incl. 23ai Free)
 
+### Prerequisites
 
-### Common Configurations
+1. Oracle Database Operator  
+
+    Install the Oracle Database Operator (OraOperator) using the instructions in the [README](https://github.com/oracle/oracle-database-operator/blob/main/README.md) file.
+
+1. Namespace  
+
+    For a dedicated namespace deployment of the ORDSSRVS controller, refer to the "Namespace Scoped Deployment" section in the OraOperator [README](https://github.com/oracle/oracle-database-operator/blob/main/README.md#2-namespace-scoped-deployment).
+
+    The following examples deploy the controller to the 'ordsnamespace' namespace.
+
+    Create the namespace:
+    ```bash
+    kubectl create namespace ordsnamespace
+    ```
+
+    Apply namespace role binding [ordsnamespace-role-binding.yaml](./examples/ordsnamespace-role-binding.yaml):
+    ```bash
+    kubectl apply -f ordsnamespace-role-binding.yaml
+    ```
+
+    Edit OraOperator to add the namespace under WATCH_NAMESPACE:
+    ```yaml
+    - name: WATCH_NAMESPACE
+    value: "default,<your namespaces>,ordsnamespace"
+    ```
+
+### Common configuration examples
 
 A few common configuration examples can be used to quickly familiarise yourself with the ORDS Custom Resource Definition.
 The "Conclusion" section of each example highlights specific settings to enable functionality that maybe of interest.
 
-* [Containerised Single Instance Database using the Oracontroller](./examples/sidb_container.md)
-* [Multipool, Multidatabase using a TNS Names file](./examples/multi_pool.md)
-* [Autonomous Database using the Oracontroller](./examples/adb_oraoper.md) - (Customer Managed ORDS) <sup>*See [Limitations](#limitations)</sup>
-* [Autonomous Database without the Oracontroller](./examples/adb.md) - (Customer Managed ORDS)
+Before 
+
+* [Pre-existing Database](./examples/existing_db.md)
+* [Containerised Single Instance Database (SIDB)](./examples/sidb_container.md)
+* [Multidatabase using a TNS Names file](./examples/multi_pool.md)
+* [Autonomous Database using the OraOperator](./examples/adb_oraoper.md) <sup>*See [Limitations](#limitations)</sup>
+* [Autonomous Database without the OraOperator](./examples/adb.md)
 * [Oracle API for MongoDB Support](./examples/mongo_api.md)
 
 Running through all examples in the same Kubernetes cluster illustrates the ability to run multiple ORDS instances with a variety of different configurations.

docs/ordsservices/examples/adb.md

@@ -5,11 +5,7 @@ This example walks through using the **ORDSSRVS controller** with an Oracle Auto
 This assumes that an ADB has already been provisioned and is configured as "Secure Access from Anywhere".  
 Note that if behind a Proxy, this example will not work as the Wallet will need to be modified to support the proxy configuration.
 
-
-### Cert-Manager and Oracle Database Operator installation
-
-Install the [Cert Manager](https://github.com/cert-manager/cert-manager/releases/download/v1.14.4/cert-manager.yaml) and the [Oracle Database Operator](https://github.com/oracle/oracle-database-operator) using the instractions in the Operator [README](https://github.com/oracle/oracle-database-operator/blob/main/README.md) file.
-
+Before testing this example, please verify the prerequisites : [ORDSSRVS prerequisites](../README.md#prerequisites)
 
 ### ADB Wallet Secret
 
@@ -25,13 +21,13 @@ kubectl create secret generic adb-wallet \
 Create a Secret for the ADB ADMIN password, replacing <ADMIN_PASSWORD> with the real password:
 
 ```bash
-echo <ADMIN_PASSWORD> adb-db-auth-enc
-openssl  genpkey -algorithm RSA  -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 > ca.k
+echo ${ADMIN_PASSWORD} > adb-db-auth-enc
+openssl  genpkey -algorithm RSA  -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 > ca.key
 openssl rsa -in ca.key -outform PEM  -pubout -out public.pem
 kubectl create secret generic prvkey --from-file=privateKey=ca.key  -n ordsnamespace
-openssl rsautl -encrypt -pubin -inkey public.pem -in adb-db-auth-enc |base64 > e_sidb-db-auth-enc
-kubectl create secret generic adb-db-auth-enc --from-file=password=e_sidb-db-auth-enc -n  ordsnamespace
-rm adb-db-auth-enc e_sidb-db-auth-enc
+openssl rsautl -encrypt -pubin -inkey public.pem -in adb-db-auth-enc |base64 > e_adb-db-auth-enc
+kubectl create secret generic adb-oraoper-db-auth-enc  --from-file=password=e_adb-db-auth-enc -n  ordsnamespace
+rm adb-db-auth-enc e_adb-db-auth-enc
 ```
 
 ### Create RestDataServices Resource
@@ -43,22 +39,24 @@ rm adb-db-auth-enc e_sidb-db-auth-enc
 
     Replace <ADB_NAME> with the ADB Name and ensure that the `db.wallet.zip.service` is valid for your ADB Workload (e.g. _TP or _HIGH, etc.):
 
-    ```bash
-    echo "
-    apiVersion: database.oracle.com/v1
-    kind: OrdsSrvs
+    ```yaml
+    apiVersion: database.oracle.com/v4
+    kind:  OrdsSrvs
     metadata:
       name: ords-adb
       namespace: ordsnamespace
     spec:
       image: container-registry.oracle.com/database/ords:24.1.1
-      globalSettings:
-        database.api.enabled: true
+      forceRestart: true
       encPrivKey:
         secretName: prvkey
         passwordKey: privateKey
+      globalSettings:
+        database.api.enabled: true
       poolSettings:
         - poolName: adb
+          restEnabledSql.active: true
+          plsql.gateway.mode: direct
           db.wallet.zip.service: <ADB_NAME>_TP
           dbWalletSecret:
             secretName: adb-wallet
@@ -68,18 +66,16 @@ rm adb-db-auth-enc e_sidb-db-auth-enc
           plsql.gateway.mode: proxied
           db.username: ORDS_PUBLIC_USER_OPER
           db.secret:
-            secretName:  adb-db-auth-enc
-            passwordKey: password
+            secretName:  adb-oraoper-db-auth-enc
           db.adminUser: ADMIN
           db.adminUser.secret:
-            secretName:  adb-db-auth-enc
-            passwordKey: password" | kubectl apply -f -
+            secretName:  adb-oraoper-db-auth-enc
     ```
     <sup>latest container-registry.oracle.com/database/ords version, **24.1.1**, valid as of **30-May-2024**</sup>
     
 1. Watch the restdataservices resource until the status is **Healthy**:
     ```bash
-    kubectl get ordssrvs  ords-adb -w
+    kubectl get -n ordsnamespace ordssrvs ords-adb -w
     ```
 
     **NOTE**: If this is the first time pulling the ORDS image, it may take up to 5 minutes.  If APEX
@@ -91,7 +87,7 @@ rm adb-db-auth-enc e_sidb-db-auth-enc
 Open a port-forward to the ORDS service, for example:
 
 ```bash
-kubectl port-forward service/ords-adb 8443:8443
+kubectl port-forward service/ords-adb -n ordsnamespace 8443:8443
 ```
 
 Direct your browser to: `https://localhost:8443/ords/adb`

docs/ordsservices/examples/adb_oraoper.md

@@ -4,23 +4,15 @@ This example walks through using the **ORDS Controller** with a Containerised Or
 
 When connecting to a mTLS enabled ADB while using the OraOperator to retreive the Wallet as is done in the example, it is currently not supported to have multiple, different databases supported by the single Ordssrvs resource.  This is due to a requirement to set the `TNS_ADMIN` parameter at the Pod level ([#97](https://github.com/oracle/oracle-database-operator/issues/97)).
 
-### Cert-Manager and  Oracle Database Operator installation
-
-Install the [Cert Manager](https://github.com/cert-manager/cert-manager/releases/download/v1.14.4/cert-manager.yaml) and the [Oracle Database Operator](https://github.com/oracle/oracle-database-operator) using the instractions in the Operator [README](https://github.com/oracle/oracle-database-operator/blob/main/README.md) file.
+Before testing this example, please verify the prerequisites : [ORDSSRVS prerequisites](../README.md#prerequisites)
 
 ### Setup Oracle Cloud Authorisation
 
-In order for the OraOperator to access the ADB, some pre-requisites are required, as detailed [here](https://github.com/oracle/oracle-database-operator/blob/main/docs/adb/ADB_PREREQUISITES.md).  Either establish Instance Principles or create the required ConfigMap/Secret.  This example uses the later:
+In order for the OraOperator to access the ADB, some additional pre-requisites are required, as detailed [here](https://github.com/oracle/oracle-database-operator/blob/main/docs/adb/ADB_PREREQUISITES.md).  
+Either establish Instance Principles or create the required ConfigMap/Secret.  This example uses the later, using the helper script [set_ocicredentials.sh](https://github.com/oracle/oracle-database-operator/blob/main/set_ocicredentials.sh) :
 
 ```bash
-kubectl create configmap oci-cred \
---from-literal=tenancy=<TENANCY_OCID> \
---from-literal=user=<USER_OCID> \
---from-literal=fingerprint=<FINGERPRINT> \
---from-literal=region=<REGION>
-
-kubectl create secret generic oci-privatekey \
---from-file=privatekey=<full path to private key>
+./set_ocicredentials.sh run -n ordsnamespace
 ```
 
 ### ADB ADMIN Password Secret
@@ -31,6 +23,7 @@ Create a Secret for the ADB Admin password:
 DB_PWD=$(echo "ORDSpoc_$(date +%H%S%M)")
 
 kubectl create secret generic adb-oraoper-db-auth \
+  -n ordsnamespace \
   --from-literal=adb-oraoper-db-auth=${DB_PWD}
 ```
 
@@ -40,87 +33,82 @@ kubectl create secret generic adb-oraoper-db-auth \
 
 1. Obtain the OCID of the ADB and set to an environment variable:
 
-  ```
-  export ADB_OCID=<insert OCID here>
-  ```
+    ```bash
+    export ADB_OCID=<insert OCID here>
+    ```
 
-1. Create a manifest to bind to the ADB.
+1. Create and apply a manifest to bind to the ADB.
+    "adb-oraoper-tns-admin" secret will be created by the controller.
 
-    ```bash
-    echo "
-    apiVersion: database.oracle.com/v1alpha1
+    ```yaml
+    apiVersion: database.oracle.com/v4
     kind: AutonomousDatabase
     metadata:
       name: adb-oraoper
+      namespace: ordsnamespace
     spec:
-      hardLink: false
-      ociConfig:
-        configMapName: oci-cred
-        secretName: oci-privatekey
-      details:
-        autonomousDatabaseOCID: $ADB_OCID
-        wallet:
+      action: Sync
+      wallet:
           name: adb-oraoper-tns-admin
           password:
             k8sSecret:
-              name: adb-oraoper-db-auth" | kubectl apply -f -
+              name: adb-oraoper-db-auth
+      details:
+        id: $ADB_OCID
     ```
 
 1. Update the ADMIN Password:
 
-```bash
-  kubectl patch adb adb-oraoper --type=merge \
-    -p '{"spec":{"details":{"adminPassword":{"k8sSecret":{"name":"adb-oraoper-db-auth"}}}}}'
-```
+    ```bash
+    kubectl patch adb adb-oraoper --type=merge \
+      -n ordsnamespace \
+      -p '{"spec":{"details":{"adminPassword":{"k8sSecret":{"name":"adb-oraoper-db-auth"}}}}}'
+    ```
 
 1. Watch the `adb` resource until the STATE is **AVAILABLE**:
 
     ```bash
-    kubectl get adb/adb-oraoper -w
+    kubectl get -n ordsnamespace adb/adb-oraoper -w
     ```
 
 ### Create encrypted password 
 
-
 ```bash
-echo ${DB_PWD} adb-db-auth-enc
-openssl  genpkey -algorithm RSA  -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 > ca.k
+echo ${DB_PWD} > adb-db-auth-enc
+openssl  genpkey -algorithm RSA  -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 > ca.key
 openssl rsa -in ca.key -outform PEM  -pubout -out public.pem
 kubectl create secret generic prvkey --from-file=privateKey=ca.key  -n ordsnamespace
 openssl rsautl -encrypt -pubin -inkey public.pem -in adb-db-auth-enc |base64 > e_adb-db-auth-enc
 kubectl create secret generic adb-oraoper-db-auth-enc  --from-file=password=e_adb-db-auth-enc -n  ordsnamespace
 rm adb-db-auth-enc e_adb-db-auth-enc
 ```
 
-
-
 ### Create OrdsSrvs Resource
 
 1. Obtain the Service Name from the OraOperator
 
-  ```bash
-  SERVICE_NAME=$(kubectl get adb adb-oraoper -o=jsonpath='{.spec.details.dbName}'_TP)
-  ```
+    ```bash
+    SERVICE_NAME=$(kubectl get -n ordsnamespace adb adb-oraoper -o=jsonpath='{.spec.details.dbName}'_TP)
+    ```
 
 1. Create a manifest for ORDS.
 
     As an ADB already maintains ORDS and APEX, `autoUpgradeORDS` and `autoUpgradeAPEX` will be ignored if set.  A new DB User for ORDS will be created to avoid conflict with the pre-provisioned one.  This user will be
     named, `ORDS_PUBLIC_USER_OPER` if `db.username` is either not specified or set to `ORDS_PUBLIC_USER`.
 
-    ```bash
-    echo "
-    apiVersion: database.oracle.com/v1
+    ```yaml
+    apiVersion: database.oracle.com/v4
     kind:  OrdsSrvs
     metadata:
       name: ords-adb-oraoper
       namespace: ordsnamespace
     spec:
       image: container-registry.oracle.com/database/ords:24.1.1
       forceRestart: true
-    encPrivKey:
-      secretName: prvkey
-      passwordKey: privateKey
-    globalSettings:
+      encPrivKey:
+        secretName: prvkey
+        passwordKey: privateKey
+      globalSettings:
         database.api.enabled: true
       poolSettings:
         - poolName: adb-oraoper
@@ -134,11 +122,9 @@ rm adb-db-auth-enc e_adb-db-auth-enc
           db.username: ORDS_PUBLIC_USER_OPER
           db.secret:
             secretName:  adb-oraoper-db-auth-enc
-            passwordKey: adb-oraoper-db-auth-enc
           db.adminUser: ADMIN
           db.adminUser.secret:
             secretName:  adb-oraoper-db-auth-enc
-            passwordKey: adb-oraoper-db-auth-enc" | kubectl apply -f -
     ```
     <sup>latest container-registry.oracle.com/database/ords version, **24.1.1**, valid as of **30-May-2024**</sup>
 
@@ -157,7 +143,7 @@ rm adb-db-auth-enc e_adb-db-auth-enc
 Open a port-forward to the ORDS service, for example:
 
 ```bash
-kubectl port-forward service/ords-adb-oraoper 8443:8443
+kubectl port-forward service/ords-adb-oraoper -n ordsnamespace 8443:8443
 ```
 
 Direct your browser to: `https://localhost:8443/ords/adb-oraoper`