Merge pull request #724 from oracle/final-final-doc-review

final doc review

Author: rjeberhard

site/apache.md

@@ -1,13 +1,14 @@
-**TODO** finish this page - make sure we tell people how to run 
-a db in a pod with persistent storage, and how to configure the 
-persistent store/leases etc in there
 
 # Running the Oracle Database in Kubernetes
 
 If you wish to run the Oracle Database inside your Kubernetes cluster, in order to place 
 your state store, leasing tables, etc., in that database, then you can use this 
 sample to install the database. 
 
+You must configure your database to store its DB files
+on persistent storage.  Refer to your cloud vendor's documentation for details of 
+available storage providers and how to create a persistent volume and attach it to a pod.
+
 First create a namespace for the database: 
 
 ``` 
@@ -43,6 +44,7 @@ spec:
       - name: dshm
         emptyDir:
           medium: Memory
+      # add your volume mount for your persistent storage here
       containers:
       - name: database
         command:
@@ -58,6 +60,7 @@ spec:
         volumeMounts:
           - mountPath: /dev/shm
             name: dshm
+          # add your persistent storage for DB files here
         env:
           - name: DB_SID
             value: OraDoc

site/database.md

@@ -1,41 +1,62 @@
-**TODO** review and udpate - link into [lb](load-balancing.md)
-
 # Load balancing with Ingress
-Ingress is a approach provided by k8s to hook up and run a load balancer. Pls see detail in [the Ingress doc](https://kubernetes.io/docs/concepts/services-networking/ingress/).  
+Ingresses are one approach provided by Kubernetes to configure load balancers. 
+Depending on the version of Kubernetes you are using, and your cloud provider, you may need to use Ingresses.
+Please refer to [the Ingress documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/) 
+for more information about Ingresses.  
+
+## WebLogic clusters as backends of Ingress
 
-## WebLogic domains as backends of Ingress
+In an Ingress object, a list of backends are provided for each target that will be load balanced.  Each backend is typically 
+[a Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/), more specifically, a combination of a `serviceName` and a `servicePort`. 
 
-In Ingress a backend is defined as [a k8s service](https://kubernetes.io/docs/concepts/services-networking/service/), more specifically, a combination of a `serviceName` and a `servicePort`. A WebLogic domain is a backend of the load balancer. When the WebLogic operator creates a WebLogic domain, it always creates a k8s service for each WebLogic cluster in the domain. With the proper label selector defined in the generated service, the service contains all-and-only the running WebLogic server pods within the WebLogic cluster.
+When the WebLogic operator creates a WebLogic domain, it also creates a service for each WebLogic cluster in the domain. 
+The operator defines the service such that its selector will match all WebLogic server pods within the WebLogic cluster
+which are in the "ready" state.
 
-The name of the k8s service generated for a WebLogic cluster follows the pattern '<domainUID>-cluster-<clusterName>'. For instance, if the doaminUID is 'domain1' and the cluster name is 'cluster-1', the corresponding k8s service name generated by WebLogic operator will be 'domain1-cluster-cluster-1'. 
+The name of the service created for a WebLogic cluster follows the pattern `<domainUID>-cluster-<clusterName>`. 
+For example, if the `domainUID` is `domain1` and the cluster name is `cluster-1`, the corresponding service 
+will be named `domain1-cluster-cluster-1`. 
 
-The service name has the following limitation in k8s:
+The service name must comply with standard Kubernetes rules for naming of object and in particular with DNS-1035:
 > A DNS-1035 label must consist of lower case alphanumeric characters or '-', start with an alphabetic character, and end with an alphanumeric character (e.g. 'my-name',  or 'abc-123', regex used for validation is '[a-z]([-a-z0-9]*[a-z0-9])?').
 
-To meet the limitation, if the domainUID or the cluster name contains some upper-case characters or  `_` , in the generated service name the upper-case characters will be converted to lower-case and `_` will be converted to `-` . For instance, if the doaminUID is 'myDomain_1' and the cluster name is 'myCluster_1', the corresponding k8s service name generated by WebLogic operator will be  'mydomain-1-cluster-mycluster-1'. 
+To comply with these requirements, if the `domainUID` or the cluster name contains some upper-case characters or underscores, then 
+in the service name the upper-case characters will be converted to lower-case and underscores will be converted to hyphens. 
+For example, if the `domainUID` is `myDomain_1` and the cluster name is `myCluster_1`, the corresponding service will be named
+`mydomain-1-cluster-mycluster-1`. 
 
-The service, `serviceName` and `servicePort`, of a WebLogic cluster will be used in the routing rules defined in Ingress resources and the load balancer will route traffic to the WebLogic servers within the cluster based on the rules. Note that eac traffic load, redirected by the load balancer, is not sent to the service directly, but instead, to one endpoint of the service based on its load-balancing algorithm. The load balancer depends on the k8s platform to maintain the live endpoint list of the service.
+The service, `serviceName` and `servicePort`, of a WebLogic cluster will be used in the routing rules defined in the Ingress 
+object and the load balancer will route traffic to the WebLogic servers within the cluster based on the rules. 
+
+**Note** Most common ingress controllers, for example Traefik, Voyager and nginx, 
+understand that there are zero or more actual pods behind the service, and they actually 
+build their backend list and route requests to those backends directly, not through the service.  This means that 
+requests are properly balanced across the pods, according to the load balancing algorithm 
+in use.  Most ingress controllers also 
+subscribe to updates on the service and adjust their internal backend sets when 
+additional pods become ready, or pods enter a non-ready state.
 
 ## Steps to setup an Ingress load balancer
 
 1. Install the Ingress controller.  
 After the Ingress controller is running, it monitors Ingress resources in given namespace(s) and acts accordingly.
 
-1. Install Ingress Resource(s)  
-Ingress resources contain routing rules to one or more backends. And Ingress controller is responsible to apply the rules to the underline load balancer.  
+1. Create Ingress Resource(s)  
+Ingress resources contain routing rules to one or more backends. An Ingress controller is responsible to apply the rules to the underlying load balancer.
 There are two approaches to create the Ingress resource:  
    1. Use the helm chart [ingress-per-domain](../kubernetes/samples/charts/ingress-per-domain).  
-   Each Ingress provider support a bunch of different annotations in Ingress resources. This helm chart allows you to define the routing rules without dealing with the detailed provider-specific annotations. Currently we support two Ingress providers: Traefik and Voyager. The limitation of the helm chart is that it only support one WebLogic cluster as the backend.  
-
-   1. Create and install the Ingress yaml manually.  
-   Manually edit the Ingress yaml file and then install it to the k8s cluster. 
+   Each Ingress provider supports a number of annotations in Ingress resources. This helm chart allows you to define the routing rules without dealing with the detailed provider-specific annotations. Currently we support two Ingress providers: Traefik and Voyager. 
+   
+   1. Create the Ingress resource manually from a YAML file.  
+   Manually create an Ingress YAML file and then apply it to the Kubernetes cluster. 
 
 ## Guide and samples for Traefik and Voyager/HAProxy
-Traefik and Voyager/HAProxy are both popular Ingress providers. We provide detail guide to install and configure these two Ingress providers, specially in front of WebLogic domain(s).
+Traefik and Voyager/HAProxy are both popular Ingress controllers. 
+Information about how to install and configure these to load balance WebLogic clusters is provided here:
  - [Treafik guide](../kubernetes/samples/charts/traefik/README.md)
  - [Voyager guide](../kubernetes/samples/charts/voyager/README.md)
 
-We also provide Ingress samples for these two Ingress providers, with multiple WebLogic clusters as the backends and covering different routing rules, host-routing and path-routing, and TLS termination.
+Samples are also provided for these two Ingress controllers, showing how to manage multiple WebLogic clusters as the backends, using different routing rules, host-routing and path-routing; and TLS termination:
 - [Treafik samples](../kubernetes/samples/charts/traefik/samples)
 - [Voyager samples](../kubernetes/samples/charts/voyager/samples)