Cleaned up the Persistent volumes section, renamed domain-on-pv-helper script and updated README.

ankedia · ankedia · commit 4fe362c5ce1f · 2023-06-30T17:10:23.000Z
diff --git a/documentation/site/content/managing-domains/domain-on-pv/usage.md b/documentation/site/content/managing-domains/domain-on-pv/usage.md
@@ -405,7 +405,7 @@ in the directory specified in `domain.spec.domainHome`, and the application dire
 
 1. If the underlying storage volume is dynamically allocated, then delete the PVC with `ReclaimPolcy: delete` and recreate the PVC.
 2. Attach a pod to the shared volume and then access the pod to remove the contents.  See the sample script,
-[Domain on PV helper script](https://github.com/oracle/weblogic-kubernetes-operator/blob/main/kubernetes/samples/scripts/domain-lifecycle/domain-on-pv-helper.sh).
+[PV and PVC helper script](https://github.com/oracle/weblogic-kubernetes-operator/blob/main/kubernetes/samples/scripts/domain-lifecycle/pv-pvc-helper.sh).
 3. Delete the domain resource.
 
    ```
diff --git a/documentation/site/content/managing-domains/persistent-storage/_index.md b/documentation/site/content/managing-domains/persistent-storage/_index.md
@@ -1,9 +1,11 @@
 +++
-title = "Persistent volumes"
+title = "Persistent Storage"
 date = 2019-02-23T16:45:09-05:00
 weight = 7.5
 pre = "<b> </b>"
 description = "Use a Kubernetes PersistentVolume (PV) and PersistentVolumeClaim (PVC) to store WebLogic domain homes and log files."
 +++
 
+This section provides general information about settting up Persistent storage which can be used as storage for WebLogic domain homes and log files. 
+
 {{% children style="h4" description="true" %}}
diff --git a/documentation/site/content/managing-domains/persistent-storage/oci-fss-pv.md b/documentation/site/content/managing-domains/persistent-storage/oci-fss-pv.md
@@ -11,90 +11,68 @@ an update to properly initialize the file ownership on the persistent volume
 when the domain is initially created."
 ---
 
+Refer to the OCI documentation for [setting up storage for kubernetes clusters](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contengcreatingpersistentvolumeclaim.htm) for details.
+
+For provisioning PVCs on the OCI File Storage Service, refer to the documentation [here](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contengcreatingpersistentvolumeclaim_Provisioning_PVCs_on_FSS.htm#Provisioning_Persistent_Volume_Claims_on_the_FileStorageService).
+
 If you are running your Kubernetes cluster on Oracle Container Engine
 for Kubernetes (commonly known as OKE), and you use Oracle Cloud Infrastructure File Storage (FSS)
-for persistent volumes to store the WebLogic domain home, then the file system
-handling, as demonstrated in the operator persistent volume sample, will require
-an update to properly initialize the file ownership on the persistent volume
-when the domain is initially created.
+for persistent volumes to store the WebLogic domain home or log files, then the file system
+handling will require an update to properly initialize the file ownership on the persistent volume 
+when the domain is initially created.  
 
 {{% notice note %}}
 File permission handling on persistent volumes can differ between
 cloud providers and even with the underlying storage handling on
-Linux based systems. These instructions provide one option to
-update file ownership used by the standard Oracle images where
-UID `1000` and GID `1000` typically represent the `oracle` or `opc` user.
-For more information on persistent volume handling,
-see [Persistent storage]({{< relref "/managing-domains/persistent-storage/_index.md" >}}).
+Linux based systems. 
+The operator will create directories on the PV under the shared mount path. 
+These instructions provide one option to update the file ownership and permissions.
 {{% /notice %}}
 
 
-#### Failure during domain creation with persistent volume sample
+#### Updating the permissions of shared directory on Persistent storage
+The operator provides a utility script `pv-pvc-helper.sh` as part of the lifecycle scripts to change the ownership and permissions of the shared directory on Persistent storage.
 
-The existing sample for [creation of a domain home on persistent volume](https://github.com/oracle/weblogic-kubernetes-operator/tree/{{< latestMinorVersion >}}/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv)
-uses a Kubernetes Job to create the domain. The sample uses an
-`initContainers` section to change the file ownership which will
-fail for Oracle Cloud Infrastructure FSS created volumes used with an OKE cluster.
+This script launches a Pod and mounts the specified PVC in the Pod containers at the specified mount path. You can then exec in the Pod and manually change the permissions or ownership.
+
+For more details, see the `Examine, change permissions or delete PV contents` section in the [README](https://github.com/oracle/weblogic-kubernetes-operator/tree/{{< latestMinorVersion >}}/kubernetes/samples/scripts/domain-lifecycle/README.md) file for the `pv-pvc-helper.sh` script details.
+
+For example, run the following command to create the pod.
 
-The Oracle Cloud Infrastructure FSS volume contains some files that are not modifiable thus
-causing the Kubernetes Job to fail. The failure is seen in the
-description of the Kubernetes Job pod:
-```shell
-$ kubectl describe -n domain1-ns pod domain1-create-weblogic-sample-domain-job-wdkvs
-```
 ```
-Init Containers:
-  fix-pvc-owner:
-    Container ID:  docker://7051b6abdc296c76e937246df03d157926f2f7477e63b6af3bf65f6ae1ceddee
-    Image:         container-registry.oracle.com/middleware/weblogic:12.2.1.3
-    Image ID:      docker-pullable://container-registry.oracle.com/middleware/weblogic@sha256:47dfd4fdf6b56210a6c49021b57dc2a6f2b0d3b3cfcd253af7a75ff6e7421498
-    Port:          <none>
-    Host Port:     <none>
-    Command:
-      sh
-      -c
-      chown -R 1000:0 /shared
-    State:          Terminated
-      Reason:       Error
-      Exit Code:    1
-      Started:      Wed, 12 Feb 2020 18:28:53 +0000
-      Finished:     Wed, 12 Feb 2020 18:28:53 +0000
-    Ready:          False
-    Restart Count:  0
-    Environment:    <none>
+$ pv-pvc-helper.sh -n sample-domain1-ns -r -c sample-domain1-weblogic-sample-pvc -m /shared
 ```
-**NOTE**: As of December, 2022, Oracle will continue support of WebLogic Server 12.2.1.3, for six months _only_, for PSUs and security patches. CPU images for WebLogic Server 12.2.1.3 will be published in the January, 2023, and April, 2023, CPU cycles.
 
-#### Updating the domain on persistent volume sample
-In the following snippet of the [create-domain-job-template.yaml](https://github.com/oracle/weblogic-kubernetes-operator/blob/{{< latestMinorVersion >}}/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/create-domain-job-template.yaml),
-you can see the updated `command` for the init container:
-```yaml
-apiVersion: batch/v1
-kind: Job
+This will create a pod with following specifications.
+```
+apiVersion: v1
+kind: Pod
 metadata:
-  name: %DOMAIN_UID%-create-weblogic-sample-domain-job
-  namespace: %NAMESPACE%
+  name: pvhelper
+  namespace: sample-domain1-ns
 spec:
-  template:
-    metadata:
-    ...
-    spec:
-      restartPolicy: Never
-      initContainers:
-        - name: fix-pvc-owner
-          image: %WEBLOGIC_IMAGE%
-          command: ["sh", "-c", "chown 1000:0 %DOMAIN_ROOT_DIR%/. && find %DOMAIN_ROOT_DIR%/. -maxdepth 1 ! -name '.snapshot' ! -name '.' -print0 | xargs -r -0 chown -R 1000:0"]
-          volumeMounts:
-          - name: weblogic-sample-domain-storage-volume
-            mountPath: %DOMAIN_ROOT_DIR%
-          securityContext:
-            runAsUser: 0
-            runAsGroup: 0
-      containers:
-        - name: create-weblogic-sample-domain-job
-          image: %WEBLOGIC_IMAGE%
-...
+  containers:
+  - args:
+    - sleep
+    - infinity
+    image: ghcr.io/oracle/oraclelinux:8-slim
+    name: pvhelper
+    volumeMounts:
+    - name: pv-volume
+      mountPath: /shared
+  volumes:
+  - name: pv-volume
+    persistentVolumeClaim:
+      claimName: wko-domain-on-pv-pvc
+```
+
+Run the following command to exec into the Pod.
+```
+$ kubectl -n sample-domain1-ns exec -it pvhelper -- /bin/sh
+```
+
+After you get a shell to the running pod container, change the directory to `/shared` and you can change the ownership or permissions using appropriate `chown` or `chmod` commands. For example,
+
+```
+chown 1000:0 /shared/. && find /shared/. -maxdepth 1 ! -name '.snapshot' ! -name '.' -print0 | xargs -r -0 chown -R 1000:0
 ```
-Use this new `command` in your copy of this template file. This will result in
-the ownership being updated for the expected files only, before the WebLogic
-domain is created on the persistent volume.
diff --git a/documentation/site/content/managing-domains/persistent-storage/pv-pvc.md b/documentation/site/content/managing-domains/persistent-storage/pv-pvc.md
@@ -1,5 +1,5 @@
 +++
-title = "Host paths and other PVs"
+title = "Persistent Volumes and Persistent Volume Claims"
 date = 2019-02-23T16:45:09-05:00
 weight = 1
 description = "Use a Kubernetes PersistentVolume (PV) and PersistentVolumeClaim (PVC) to store WebLogic domain homes and log files."
@@ -15,52 +15,18 @@ The following prerequisites must be fulfilled before proceeding with the creatio
 * Make sure that all the servers in the WebLogic domain are able to reach the storage location.
 * Make sure that the host directory that will be used, already exists and has the appropriate file permissions set.
 
-### Storage locations
+### Persistent Volume Storage locations
 PersistentVolumes can point to different storage locations, for example NFS servers or a local directory path. For a list of available options, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/).
 
 **Note regarding HostPath**: In a single-node Kubernetes cluster, such as may be used for testing or proof of concept activities, `HOST_PATH` provides the simplest configuration.  In a multinode Kubernetes cluster, a `HOST_PATH` that is located on shared storage mounted by all nodes in the Kubernetes cluster is the simplest configuration.  If nodes do not have shared storage, then NFS is probably the most widely available option.  There are other options listed in the referenced table.
 
-The PersistentVolume for the domain must be created using the appropriate tools before running the script to create the domain.  In the simplest case, namely the `HOST_PATH` provider, this means creating a directory on the Kubernetes master and ensuring that it has the correct permissions:
+The operator provides a sample script to create the PersistentVolume and PersistentVolumeClaim for the domain. this script must be executed before creating the domain.  Beginning with Operator 4.1.0, for Domain on PV [domain home source type]({{< relref "/managing-domains/choosing-a-model/_index.md" >}}), the operator provides options to create the PV and PVC. See [Domain on PV documentation]({{< relref "/managing-domains/domain-on-pv/_index.md" >}}) for more details.
 
-```shell
-$ mkdir -m 777 -p /path/to/domain1PersistentVolume
-```
-
-**Note regarding NFS**: In the current GA version, the Oracle Container Engine for Kubernetes supports network block storage that can be shared across nodes with access permission RWOnce (meaning that only one can write, others can read only). At this time, the WebLogic on Kubernetes domain created by the WebLogic Kubernetes Operator, requires a shared file system to store the WebLogic domain configuration, which MUST be accessible from all the pods across the nodes. As a workaround, you need to install an NFS server on one node and share the file system across all the nodes.
-
-#### PersistentVolume GID annotation
-
-The `HOST_PATH` directory permissions can be made more secure by using a Kubernetes annotation on the
-PersistentVolume that provides the group identifier (GID) which will be added to pods using the PersistentVolume.
-
-For example, if the GID of the directory is `6789`, then the directory can be updated to remove permissions
-other than for the user and group along with the PersistentVolume being annotated with the specified GID:
-
-```shell
-$ chmod 770 /path/to/domain1PersistentVolume
-```
-```shell
-$ kubectl annotate pv domain1-weblogic-sample-pv pv.beta.kubernetes.io/gid=6789
-```
-
-After the domain is created and servers are running, the group ownership of the PersistentVolume files
-can be updated to the specified GID which will provide read access to the group members. Typically,
-files created from a pod onto the PersistentVolume will have UID `1000` and GID `1000` which is the
-`oracle` user from the WebLogic Server image.
-
-An example of updating the group ownership on the PersistentVolume would be as follows:
+#### Persistent Volumes using HostPath approach
+The `HOST_PATH` provider is the simplest case for creating a Persistent Volume. It requires creating a directory on the Kubernetes master and ensuring that it has the correct permissions:
 
 ```shell
-$ cd /path/to/domain1PersistentVolume
-```
-```shell
-$ sudo chgrp 6789 applications domains logs stores
-```
-```shell
-$ sudo chgrp -R 6789 domains/
-```
-```shell
-$ sudo chgrp -R 6789 logs/
+$ mkdir -m 777 -p /path/to/domain1PersistentVolume
 ```
 
 ### YAML files
@@ -69,16 +35,7 @@ Persistent volumes and claims are described in YAML files. For each PersistentVo
 
 For sample YAML templates, refer to the [PersistentVolumes example]({{< relref "/samples/storage/_index.md" >}}).
 
-### Kubernetes resources
-
-After you have written your YAML files, use them to create the PersistentVolume by creating Kubernetes resources using the `kubectl create -f` command:
-
-```shell
-$ kubectl create -f pv.yaml
-```
-```shell
-$ kubectl create -f pvc.yaml
-```
+For more details, refer to [Kubernetes examples](https://github.com/kubernetes/examples/), and the PV/PVC examples [here](https://github.com/kubernetes/examples/tree/master/staging/volumes).
 
 #### Verify the results
 
@@ -97,10 +54,7 @@ This section provides details of common problems that might occur while running
 
 #### PersistentVolume provider not configured correctly
 
-Possibly the most common problem experienced during testing was the incorrect configuration of the PersistentVolume provider. The PersistentVolume must be accessible to all Kubernetes Nodes, and must be able to be mounted as Read/Write/Many. If this is not the case, the PersistentVolume creation will fail.
+Possibly the most common problem experienced during testing was the incorrect configuration of the PersistentVolume provider. The PersistentVolume must be accessible to all Kubernetes Nodes, and must be able to be mounted as `Read/Write/Many`. If this is not the case, the PersistentVolume creation will fail.
 
 The simplest case is where the `HOST_PATH` provider is used. This can be either with one Kubernetes Node, or with the `HOST_PATH` residing in shared storage available at the same location on every node (for example, on an NFS mount). In this case, the path used for the PersistentVolume must have its permission bits set to 777.
 
-#### Further reading
-
-* See the blog, [How to run WebLogic clusters on the Oracle Cloud Infrastructure Container Engine for Kubernetes](https://blogs.oracle.com/weblogicserver/how-to-run-weblogic-clusters-on-the-oracle-cloud-infrastructure-container-engine-for-kubernetes).
diff --git a/documentation/site/content/samples/domains/domain-home-on-pv/_index.md b/documentation/site/content/samples/domains/domain-home-on-pv/_index.md
@@ -36,7 +36,7 @@ Location | Description |
 `kubernetes/samples/scripts/create-weblogic-domain/ingresses` | Ingress resources. |
 `kubernetes/samples/scripts/domain-lifecycle/opss-wallet.sh` | Utility script for exporting or importing a JRF domain OPSS wallet file. |
 `kubernetes/samples/scripts/domain-lifecycle/waitForDomain.sh` | Utility script that optionally waits for the pods in a domain to reach their expected `Completed`, `image`, and `ready` state. |
-`kubernetes/samples/scripts/domain-lifecycle/domain-on-pv-helper.sh` | Utility script to examine or clean up the contents of shared directories on the persistent volume. |
+`kubernetes/samples/scripts/domain-lifecycle/pv-pvc-helper.sh` | Utility script to examine or clean up the contents of shared directories on the persistent volume. |
 
 #### Ensuring your Kubernetes cluster can access images
 
diff --git a/documentation/site/content/samples/domains/domain-home-on-pv/sample.md b/documentation/site/content/samples/domains/domain-home-on-pv/sample.md
@@ -447,14 +447,14 @@ Now that all the sample resources have been deployed, you can invoke the sample
 Follow the cleanup instructions [here]({{< relref "samples/domains/domain-home-on-pv/cleanup.md" >}}) to remove the domain, cluster and other associated resources.
 
 Sometimes in production, but most likely in testing environments, you might also want to remove the Domain on PV contents that are generated using this sample.
-You can use the `domain-on-pv-helper.sh` helper script in the domain lifecycle directory for this.
+You can use the `pv-pvc-helper.sh` helper script in the domain lifecycle directory for this.
 The script launches a Kubernetes pod named `pvhelper` using the provided persistent volume claim name and the mount path.
 You can run `kubectl exec` to get a shell to the running pod container and run commands to examine or clean up the
 contents of shared directories on the persistent volume.
 For example:
 ```shell
 $ cd /tmp/weblogic-kubernetes-operator/kubernetes/samples/scripts/domain-lifecycle
-$ ./domain-on-pv-helper.sh -n sample-domain1-ns -c sample-domain1-weblogic-sample-pvc -m /shared
+$ ./pv-pvc-helper.sh -n sample-domain1-ns -r -c sample-domain1-weblogic-sample-pvc -m /shared
 ```
 {{%expand "Click here to see the output." %}}
 ```
diff --git a/kubernetes/samples/scripts/domain-lifecycle/README.md b/kubernetes/samples/scripts/domain-lifecycle/README.md
@@ -27,6 +27,8 @@ For information on how to start, stop, restart, and scale WebLogic Server instan
   - [`kubectl --watch`](#kubectl---watch)
   - [`clusterStatus.sh`](#clusterstatussh)
   - [`waitForDomain.sh`](#waitfordomainsh)
+- [Examine, change permissions or delete PV contents](#examine-change-or-delete-pv-contents)
+  - [`pv-pvc-helper.sh`](#pv-pvc-helpersh)  
 
 ### Prerequisites
 
@@ -274,3 +276,66 @@ Use the following command to wait for a domain to fully shut down:
 ```
 $ waitForDomain.sh -n my-namespace -d my-domain -p 0
 ```
+
+### Examine, change, or delete PV contents
+
+#### `pv-pvc-helper.sh` 
+
+Use this helper script for examining, changing permissions or deleting the contents of persistent volume (such as domain files or logs) for a WebLogic Domain on PV or Model in Image domain.
+The script launches a a Kubernetes pod named as 'pvhelper' using the provided persistent volume claim name and the mount path.
+You can run the 'kubectl exec' to get a shell to the running pod container and run commands to examine or clean up the contents of shared directories on persistent volume.
+Use 'kubectl delete pvhelper -n <namespace>' command to delete the pod after it's no longer needed.
+
+Use the following command for script usage:
+
+```
+$ domain-on-pv-helper.sh -h
+```
+
+Following is an example command to launch the helper pod with PVC name `sample-domain1-weblogic-sample-pvc` and mount path `/shared`.
+
+```
+$ domain-on-pv-helper.sh -n sample-domain1-ns -c sample-domain1-weblogic-sample-pvc -m /shared
+```
+
+After the pod is created, use following command to get a shell to the running pod container.
+
+```
+$ kubectl -n sample-domain1-ns exec -it pvhelper -- /bin/sh
+```
+
+After you get a shell to the running pod container, you can recursively delete the contents of the domain home and applications 
+directories using rm -rf /shared/domains/sample-domain1 and rm -rf /shared/applications/sample-domain1 commands. Since these 
+commands will actually delete files on the persistent storage, we recommend that you understand and execute these commands carefully.
+
+Use the following command to delete the pod after it's no longer needed.
+
+```
+$ kubectl delete pod pvhelper -n <namespace>
+```
+
+### OPSS Wallet utility
+
+The OPSS wallet utility is a helper script for JRF type domains that can save an OPSS key
+wallet from a running domain's introspector configmap to a file, and/or
+restore an OPSS key wallet file to a Kubernetes secret for use by a
+domain that you're about to run.
+
+Use the following command for script usage:
+
+```
+$ opss-wallet.sh -?
+```
+
+For example, run the following command to save an OPSS key wallet from a running domain to file './ewallet.p12':
+
+```
+$ opss-wallet.sh -s
+```
+
+Run the following command to restore the OPSS key wallet from file './ewallet.p12' to secret
+'sample-domain1-opss-walletfile-secret' for use by a domain you're about to run:
+
+```
+$ opss-wallet.sh -r
+```
diff --git a/kubernetes/samples/scripts/domain-lifecycle/pv-pvc-helper.sh b/kubernetes/samples/scripts/domain-lifecycle/pv-pvc-helper.sh
