Merge pull request #1054 from oracle/host-pv-gid-annotation

Documenation for using a GID annotated Persistent Volume - Resolves #931

Author: rjeberhard

docs-source/content/userguide/managing-domains/persistent-storage/_index.md

@@ -22,14 +22,41 @@ Persistent volumes can point to different storage locations, for example NFS ser
 
 The persistent volume 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:
 
-```
+```bash
 $ mkdir -m 777 -p /path/to/domain1PersistentVolume
 ```
 
 **Note regarding NFS**: In the current GA version, the OCI 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 Server 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.
 
 Currently, we recommend that you use NFS version 3.0 for running WebLogic Server on OCI Container Engine for Kubernetes. During certification, we found that when using NFS 4.0, the servers in the WebLogic domain went into a failed state intermittently. Because multiple threads use NFS (default store, diagnostics store, Node Manager, logging, and `domain_home`), there are issues when accessing the file store. These issues are removed by changing the NFS to version 3.0.
 
+#### Persistent volume GID annotation
+
+The `HOST_PATH` directory permissions can be made more secure by using a Kubernetes annotation on the
+persistent volume that provides the group identifier (GID) which will be added to pods using the persistent volume.
+
+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 persistent volume being annotated with the specified GID:
+
+```bash
+$ chmod 770 /path/to/domain1PersistentVolume
+$ kubectl annotate pv domain1-weblogic-sample-pv pv.beta.kubernetes.io/gid=6789
+```
+
+Typically, after the domain is created and servers are running, the group ownership of the persistent volume files
+can be updated to the specified GID which will provide read access to the group members. Normally
+files created from a pod onto the persistent volume will have UID `1000` and GID `1000` which is the
+`oracle` user from the WebLogic Docker image.
+
+An example of updating the group ownership on the persistent volume would be as follows:
+
+```bash
+$ cd /path/to/domain1PersistentVolume
+$ sudo chgrp 6789 applications domains logs stores
+$ sudo chgrp -R 6789 domains/
+$ sudo chgrp -R 6789 logs/
+```
+
 ### YAML files
 
 Persistent volumes and claims are described in YAML files. For each persistent volume, you should create one persistent volume YAML file and one persistent volume claim YAML file. In the example below, you will find two YAML templates, one for the volume and one for the claim. As stated above, they either can be dedicated to a specific domain, or shared across multiple domains. For the use cases where a volume will be dedicated to a particular domain, it is a best practice to label it with `weblogic.domainUID=[domain name]`. This makes it easy to search for, and clean up resources associated with that particular domain.