Documentation Changes for v1.1.0 release

oracle · s1saurabh · Jul 13, 2023 · Aug 15, 2023 · Aug 15, 2023 · Aug 23, 2023
commit 375a5878603bf63e627f0d00c9a551da745adf4a
diff --git a/README.md b/README.md
@@ -63,59 +63,53 @@ Oracle strongly recommends that you ensure your system meets the following [Prer
 
 * ### Role Binding for access management
 
-  When the Oracle DB Operator is operating with multiple namespaces and access management is required, you need to complete the following additional steps:
-  - Have the Oralce DB Operator monitor only certain defined namespaces.
-  - Apply role binding for those namespaces for access control.
-
-  Follow the below steps:
-
-  1. Download the [oracle-database-operator.yaml](./oracle-database-operator.yaml) file.
-  2. Add the comma separated namespaces under `WATCH_NAMESPACE`. For example:
-     ```sh
-     - name: WATCH_NAMESPACE
-       value: "oracle-database-operator-system,shns"
-     ```
-     This is needed when you want the DB Operator to monitor `shns` and `oracle-database-operator-system` namespaces.
-
-     If you are going to work with more namespaces, then you will need to add them under `WATCH_NAMESPACE`. 
-
-     Save the `oracle-database-operator-system.yaml` file after this change.
-  3. Create a role binding file for the namespace you are going to work in. 
-
-     In this case, its the namespace `shns` and you need to create a file like below for it:
-
-     ```sh
-     ---
-     apiVersion: rbac.authorization.k8s.io/v1
-     kind: RoleBinding
-     metadata:
-       name: oracle-database-operator-oracle-database-operator-manager-rolebinding1
-       namespace: shns
-     roleRef:
-       apiGroup: rbac.authorization.k8s.io
-       kind: ClusterRole
-       name: oracle-database-operator-manager-role
-     subjects:
-     - kind: ServiceAccount
-       name: default
-       namespace: oracle-database-operator-system
-     ```
-
-     If you are testing with multiple namespaces, make sure you create that many binding files and apply them before applying `oracle-database-operator.yaml`. 
-
-     NOTE: You need to change the namespace in that binding file from `shns` and also change the binding name `oracle-database-operator-oracle-database-operator-manager-rolebinding1` to a new binding name.
-
-  4. Apply the role binding file like below:
-     ```sh
-     kubectl apply -f shns_binding.yaml
-     ```
+  OraOperator supports the following two modes of deployment:
+  ##### 1. Cluster Scope Deployment
+
+    This is the default mode wherein OraOperator is deployed to operate in a cluster scope and watch all the namespaces cluster wide
+
+  - Grant the `serviceaccount:oracle-database-operator-system:default` cluster wide access for the resources by applying [cluster-role-binding.yaml](./rbac/cluster-role-binding.yaml)
+
+    ```sh
+      kubectl apply -f cluster-role-binding.yaml
+    ```
+
+  - Then apply the [oracle-database-operator.yaml](./oracle-database-operator.yaml) to deploy the Operator
+
+    ```sh
+      kubectl apply -f oracle-database-operator.yaml
+    ```
+
+  ##### 2. Namespaced Scope Deployment
+
+   In this mode OraOperator can be deployed to operate in a namespaced scope and watch one or many namespaces
+
+  - Grant `serviceaccount:oracle-database-operator-system:default` service account with resource access in the required namespaces. For example, to watch only the default namespace, apply the [default-ns-role-binding.yaml](./rbac/default-ns-role-binding.yaml)
+
+    ```sh
+      kubectl apply -f default-ns-role-binding.yaml
+    ```
+    For watching additional namespaces, create different role binding files for each namespace taking [default-ns-role-binding.yaml](./rbac/default-ns-role-binding.yaml) as a template and changing the `metadata.name` and `metadata.namespace` fields
+
+  - Now edit the [oracle-database-operator.yaml](./oracle-database-operator.yaml) to add the required namespaces under `WATCH_NAMESPACE`. Use comma separated values for multiple namespaces
+
+    ```sh
+    - name: WATCH_NAMESPACE
+      value: "default"
+    ```
+  - Then apply the edited [oracle-database-operator.yaml](./oracle-database-operator.yaml) to deploy the Operator
+
+    ```sh
+      kubectl apply -f oracle-database-operator.yaml
+    ```
+
 
 * ### ClusterRole and ClusterRoleBinding for NodePort services
 
-  For exposing services on each Node's IP and port (the NodePort) apply the [oracle-database-operator-nodes-rbac.yaml](./oracle-database-operator-nodes-rbac.yaml). This is not required for LoadBalancer services.
+  For exposing services on each Node's IP and port (the NodePort) apply the [node-rbac.yaml](./rbac/node-rbac.yaml). This is not required for LoadBalancer services.
 
   ```sh
-    kubectl apply -f oracle-database-operator-nodes-rbac.yaml
+    kubectl apply -f manager-role-nodes-rbac.yaml
   ```
 
 ## Install Oracle DB Operator

diff --git a/docs/sidb/README.md b/docs/sidb/README.md
@@ -47,7 +47,20 @@ Oracle Database Operator for Kubernetes (`OraOperator`) includes the Single Inst
 
 ## Prerequisites
 
-Oracle strongly recommends that you follow the [prerequisites](./PREREQUISITES.md).
+* Oracle strongly recommends that you follow the [prerequisites](./PREREQUISITES.md)
+* For managing the required levels of access, configure [role binding](../../README.md#role-binding-for-access-management)
+* For exposing the database via Nodeport services, apply [RBAC](../../rbac/node-rbac.yaml)
+  ```sh
+    kubectl apply -f rbac/node-rbac.yaml
+  ```
+* For automatic storage expansion of block volumes, apply [RBAC](../../rbac/storage-class-rbac.yaml)
+  ```sh
+    kubectl apply -f rbac/storage-class-rbac.yaml
+  ```
+* For automatic execution of custom scripts post database setup or startup, apply [RBAC](../../rbac/persistent-volume-rbac.yaml)
+  ```sh
+    kubectl apply -f rbac/persistent-volume-rbac.yaml
+  ```
 
 ## SingleInstanceDatabase Resource
 
@@ -306,7 +319,8 @@ $ kubectl patch singleinstancedatabase sidb-sample -p '{"spec":{"persistence":{"
 ```
 
 **Note:**
-- For storage expansion to work, the storage class should have been configured to `allowVolumeExpansion:true`
+- Storage expansion requires the storage class to be configured with `allowVolumeExpansion:true`
+- Storage expansion requires read and watch access for storage account as mentioned in [prerequisites](#prerequisites)
 - User can only scale up a volume/storage and not scale down
 
 #### Static Persistence
@@ -791,7 +805,7 @@ $ kubectl --type=merge -p '{"spec":{"setAsPrimaryDatabase":"ORCLS1"}}' patch dat
 
 ### Patch Primary and Standby databases in Data Guard configuration
 
-Databases (both primary and standby) running in you cluster and managed by the Oracle Database operator can be patched or rolled back between release updates of the same major release. While patching databases configured with the dataguard broker you need to first patch the Primary database followed by seconday/standby databases in any order. 
+Databases (both primary and standby) running in you cluster and managed by the Oracle Database operator can be patched or rolled back between release updates of the same major release. While patching databases configured with the dataguard broker you need to first patch the Primary database followed by Standby databases in any order.
 
 To patch an existing database, edit and apply the **[config/samples/sidb/singleinstancedatabase_patch.yaml](../../config/samples/sidb/singleinstancedatabase_patch.yaml)** file of the database resource/object either by specifying a new release update for image attributes, or by running the following command:
 
@@ -825,6 +839,8 @@ Custom scripts (sql and/or shell scripts) can be executed after the initial data
 
 Create a persistent volume using [static provisioning](#static-persistence) and then specify the name of this volume with the `<.spec.persistence.scriptsVolumeName>` field which corresponds to the `scriptsVolumeName` field of the persistence section in the **[singleinstancedatabase.yaml](../../config/samples/sidb/singleinstancedatabase.yaml)**.
 
+**Note:**
+- Executing custom scripts requires read and list access for persistent volumes as mentioned in [prerequisites](#prerequisites)
 
 ## OracleRestDataService Resource
 

diff --git a/rbac/cluster-role-binding.yaml b/rbac/cluster-role-binding.yaml
@@ -0,0 +1,15 @@
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: oracle-database-operator-oracle-database-operator-manager-rolebinding
+  namespace: oracle-database-operator-system
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: oracle-database-operator-manager-role
+subjects:
+- kind: ServiceAccount
+  name: default
+  namespace: oracle-database-operator-system
+---
diff --git a/rbac/default-ns-role-binding.yaml b/rbac/default-ns-role-binding.yaml
@@ -0,0 +1,15 @@
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: oracle-database-operator-oracle-database-operator-manager-rolebinding
+  namespace: default
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: oracle-database-operator-manager-role
+subjects:
+- kind: ServiceAccount
+  name: default
+  namespace: oracle-database-operator-system
+---
diff --git a/oracle-database-operator-nodes-rbac.yaml → rbac/node-rbac.yaml b/oracle-database-operator-nodes-rbac.yaml → rbac/node-rbac.yaml
@@ -2,7 +2,7 @@
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
-  name: oracle-database-operator-manager-role-nodes
+  name: oracle-database-operator-manager-role-node
 rules:
 - apiGroups:
   - ""
@@ -15,11 +15,11 @@ rules:
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRoleBinding
 metadata:
-  name: oracle-database-operator-manager-role-clusterrolebindings
+  name: oracle-database-operator-manager-role-node-cluster-role-binding
 roleRef:
   apiGroup: rbac.authorization.k8s.io
   kind: ClusterRole
-  name: oracle-database-operator-manager-role-nodes
+  name: oracle-database-operator-manager-role-node
 subjects:
 - kind: ServiceAccount
   name: default

diff --git a/rbac/persistent-volume-rbac.yaml b/rbac/persistent-volume-rbac.yaml
@@ -0,0 +1,27 @@
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: oracle-database-operator-manager-role-persistent-volume
+rules:
+- apiGroups:
+  - ""
+  resources:
+  - persistentvolumes
+  verbs:
+  - get
+  - list
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: oracle-database-operator-manager-role-persistent-volume-cluster-role-binding
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: oracle-database-operator-manager-role-persistent-volume
+subjects:
+- kind: ServiceAccount
+  name: default
+  namespace: oracle-database-operator-system
+---
diff --git a/rbac/storage-class-rbac.yaml b/rbac/storage-class-rbac.yaml
@@ -0,0 +1,28 @@
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: oracle-database-operator-manager-role-storage-class
+rules:
+- apiGroups:
+  - storage.k8s.io
+  resources:
+  - storageclasses
+  verbs:
+  - get
+  - list
+  - watch
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: oracle-database-operator-manager-role-storage-class-cluster-role-binding
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: oracle-database-operator-manager-role-storage-class
+subjects:
+- kind: ServiceAccount
+  name: default
+  namespace: oracle-database-operator-system
+---