WIP. more doc updates (#653)

* Doc NOTE from Monica

* more doc updates - in the domain section

* fix prereqs

Author: markxnelson

site/domains.md

@@ -2,8 +2,22 @@
 
 ## Create and manage WebLogic domains
 
-In this version of the operator, a WebLogic domain can be persisted either to a persistent volume (PV) or in a Docker image.
-(Describe the pros and cons of both these approaches.)
+In this version of the operator, a WebLogic domain can be located either in a persistent volume (PV) or in a Docker image.
+There are advantages to both approaches, and there are sometimes technical limitations of various 
+cloud providers that may make one approach better suited to your needs.
+You can also mix and match on a domain by domain basis.
+
+| Domain on a persistent volume | Domain in a Docker image |
+| --- | --- |
+| Allows you to use the same standard read-only Docker image for every server in every domain. | Requires a different image for each domain, but all servers in that domain use the same image. |
+| No state is kept in Docker images making them completely throw away (cattle not pets). | Runtime state should not be kept in the images, but applications and confguration are. |
+| The domain is long-lived, so you can mutate the configuration or deploy new applications using standard methods (admin console, WLST, etc.) | If you want to mutate the domain configuration or deploy application updates, you must create a new image. |
+| Logs are automatically placed on persistent storage.  | Logs are kept in the images, and sent to the Pod's log (stdout) unless you manually place them on persistent storage.  |
+| Patches can be applied by simply changing the image and rolling the domain.  | To apply patches, you must create a new domain-specific image and then roll the domain.  | 
+| Many cloud providers do not provide persistent volumes that are shared across availability zones, so you may not be able to use a single persistent volume.  You may need to use some kind of volume replication technology or a clustered file system. | You do not have to worry about volume replication across availability zones since each Pod has its own copy of the domain.  WebLogic replication will handle propagation of any online configuration changes.  | 
+| CI/CD pipelines may be more complicated because you would probably need to run WLST against the live domain directory to effect changes.  | CI/CD pipelines are simpler because you can create the whole domain in the image and don't have to worry about a persistent copy of the domain.  | 
+| There are less images to manage and store, which could provide significant storage and network savings.  |  There are more images to manage and store in this approach. |
+| You may be able to use standard Oracle-provided images or at least a very small number of self-built images, e.g. with patches installed. | You may need to do more work to set up processes to build and maintain your images. |
 
 * WebLogic binary image when domain is persisted to a PV (as in Operator v1.1)
 * WebLogic domain image where the domain is persisted to a Docker image (new for Operator v2.0).  The WebLogic domain image will contain the WebLogic binaries, domain configuration, and applications.
@@ -17,26 +31,58 @@ You create the WebLogic domain inside of a Docker image or in a PV using WebLogi
 
 Perform these steps to prepare your Kubernetes cluster to run a WebLogic domain:
 
-* Create the domain namespace.  One or more domains can share a namespace.
-* Define RBAC roles for the domain.
-* Create a Kubernetes secret for the Administration Server boot credentials.
-* Optionally, [create a PV & persistent volume claim (PVC)](kubernetes/samples/scripts/create-weblogic-domain-pv-pvc/README.md) which can hold the domain home, logs, and application binaries.
-* [Configure a load balancer](kubernetes/samples/charts/README.md) to manage the domains and ingresses.
+1. Create the domain namespace(s).  One or more domains can share a namespace. A single instance of the operator can manage multiple namespaces.
+
+   ``` 
+   kubectl create namespace domain-namespace-1
+   ```
+
+   Replace `domain-namespace-1` with name you want to use.  The name must follow standard Kubernetes naming conventions, i.e. lower case, 
+   numbers and hyphens.
+
+1. Define RBAC roles for the domain.  **TODO** what RBAC roles?
+1. Create a Kubernetes secret containing the Administration Server boot credentials.  You can do this manually or using 
+   [the provided sample](/kubernetes/samples/scripts/create-weblogic-domain-credentials/README.md).  To create
+   the secret manually, use this command: 
+   
+   ``` 
+   kubectl -n domain-namespace-1 \ 
+           create secret generic domain1-weblogic-credentials \
+           --from-literal=username=weblogic \
+           --from-literal=password=welcome1
+   ```
+   
+   Replace `domain-namespace-1` with the namespace that the domain will be in.
+   Replace `domain1-weblogic-credentials` with the name of the secret.  The operator expects the secret name to be
+   the `domainUID` followed by the literal string `-weblogic-credentials` and many of the samples assume this name. 
+   Replace the string `weblogic` in the third line with the username for the administrative user. 
+   Replace the string `welcome1` in the fourth line with the password.
+   
+1. Optionally, [create a PV & persistent volume claim (PVC)](kubernetes/samples/scripts/create-weblogic-domain-pv-pvc/README.md) which can hold the domain home, logs, and application binaries.
+   Even if you put your domain in a Docker image, you may wish to put the logs on a persistent volume so that they are avilable after the Pods terminate.
+   This may be instead of, or as well as, other approaches like streaming logs into Elasticsearch.
+1. [Configure load balancer(s)](kubernetes/samples/charts/README.md) to manage access to any WebLogic clusters.
 
 ### Important considerations for WebLogic domains in Kubernetes
 
 Please be aware of the following important considerations for WebLogic domains
 running in Kubernetes.
 
-* Channel Listen Addresses in a configuration must either be left completely unset (e.g. not set to anything), or must be set to the exact required value of ‘DOMAIN_UID-SERVER_NAME’ (with all lower case, underscores converted to dashes).  This includes default, SSL, admin, and custom channels.     
+* Channel Listen Addresses in a configuration must either be left completely unset (e.g. not set to anything), or must be set to the exact required value, which will be in the form of the `domainUID` 
+  followed by a hyphen and then the server name (with all lower case, underscores converted to dashes).  For example `domain1-admin-server`. This includes default, SSL, admin, and custom channels.     
+* If you choose to expose any WebLogic channels outside the Kubernetes cluster, e.g. the administration port or a T3 channel to 
+  allow WLST access, you need to ensure that you allocate each channel a unique port number across the entire 
+  Kubernetes cluster.  If you expose the administration port in each WebLogic domain in the Kubernetes cluster, then each one must 
+  have a different port.  This is required because `NodePorts` are used to expose channels outside the Kubernetes cluster.
+* If using a `hostPath` persistent volume, then it must be available on all worker nodes in the cluster and have read/write/many permissions for all container/pods in the WebLogic Server deployment.  Be aware 
+  that many cloud provider's volume providers may no support volumes across availability zones.  You may want to use NFS or a clustered file system to work around this limitation.
 
 The following features are not certified or supported in this release:
 
 * Whole Server Migration,
 * Consensus Leasing,
 * Node Manager (although it is used internally for the liveness probe and to start WebLogic Server instances),
 * Multicast,
-* If using a hostPath persistent volume, then it must have read/write/many permissions for all container/pods in the WebLogic Server deployment,
 * Multitenancy, and
 * Production redeployment.
 

site/user-guide.md

@@ -56,8 +56,8 @@ Before using the operator, you might want to read the [design philosophy](design
 ## Prerequisites
 
 * Kubernetes 1.10.11+, 1.11.5+, and 1.12.3+  (check with `kubectl version`).
-* Flannel networking v0.9.1-amd64 (check with `docker images | grep flannel`)
-* Docker 18.03.1.ce (check with `docker version`)
-* Oracle WebLogic Server 12.2.1.3.0
-* If you wish to use dynamic clusters and/or Configuration Overrides, patch 28076014 is required.
+* Flannel networking v0.9.1-amd64 (check with `docker images | grep flannel`).
+* Docker 18.03.1.ce (check with `docker version`).
+* Oracle WebLogic Server 12.2.1.3.0 with patch 28076014.
+* You must have the `cluster-admin` role to install the operator.
 

site/weblogic-docker-images.md

@@ -75,5 +75,6 @@ run WebLogic 12.2.1.3 in Kubernetes using the operator.
 
 ## Creating a custom image with your domain inside the image
 
-**TODO** write me 
+**TODO** write me and, in this section, add:
 
+ **Note**: Oracle recommends keeping the domain home image private in the local repository.