Merge pull request #210 from oracle/rmarano

first pass edits for May release

Author: mriccell

README.md

@@ -4,18 +4,21 @@ Built with [Wercker](http://www.wercker.com)
 
 [![wercker status](https://app.wercker.com/status/68ce42623fce7fb2e52d304de8ea7530/m/develop "wercker status")](https://app.wercker.com/project/byKey/68ce42623fce7fb2e52d304de8ea7530)
 
-Many organizations are exploring, testing, or actively moving application workloads into a cloud environment, either in house or using an external cloud provider.  Kubernetes has emerged as a leading cloud platform and is seeing widespread adoption.  But a new computing model does not necessarily mean new applications or workloads; many of the existing application workloads running in environments designed and built over many years, before the ‘cloud era’, are still mission critical today.  As such, there is a lot of interest in moving such workloads into a cloud environment, like Kubernetes, without forcing application rewrites, retesting and additional process and cost.  There is also a desire to not just run the application in the new environment, but to run it ‘well’ – to adopt some of the idioms of the new environment and to realize some of the benefits of that new environment.
+Many organizations are exploring, testing, or actively moving application workloads into a cloud environment, either in house or using an external cloud provider.  Kubernetes has emerged as a leading cloud platform and is seeing widespread adoption.  But a new computing model does not necessarily mean new applications or workloads; many of the existing application workloads running in environments designed and built over many years, before the ‘cloud era’, are still mission critical today.  As such, there is a lot of interest in moving such workloads into a cloud environment, like Kubernetes, without forcing application rewrites, retesting, and additional process and cost.  There is also a desire to not just run the application in the new environment, but to run it ‘well’ – to adopt some of the idioms of the new environment and to realize some of the benefits of that new environment.
+
+Oracle has been working with the WebLogic community to find ways to make it as easy as possible for organizations using WebLogic Server to run important workloads, to move those workloads into the cloud.  One aspect of that effort is the creation of the Oracle WebLogic Server Kubernetes Operator.  This release of the Operator provides a number of features to assist with the management of WebLogic domains in a Kubernetes environment, including:
+
+*	A mechanism to create a WebLogic domain on a Kubernetes persistent volume. This persistent volume can reside in NFS.
+*	A mechanism to define a WebLogic domain as a Kubernetes resource (using a Kubernetes custom resource definition).
+*	The ability to automatically start servers based on declarative startup parameters and desired states.
+* The ability to manage a WebLogic configured or dynamic cluster.
+*	The ability to automatically expose the WebLogic Server Administration Console outside the Kubernetes cluster (if desired).
+*	The ability to automatically expose T3 channels outside the Kubernetes domain (if desired).
+*	The ability to automatically expose HTTP paths on a WebLogic domain outside the Kubernetes domain with load balancing, and to update the load balancer when Managed Servers in the WebLogic domain are started or stopped.
+*	The ability to scale a WebLogic domain by starting and stopping Managed Servers on demand, or by integrating with a REST API to initiate scaling based on WLDF, Prometheus/Grafana, or other rules.
+*	The ability to publish Operator and WebLogic Server logs into Elasticsearch and interact with them in Kibana.
 
-Oracle has been working with the WebLogic community to find ways to make it as easy as possible for organizations using WebLogic Server to run important workloads, to move those workloads into the cloud.  One aspect of that effort is the creation of the Oracle WebLogic Server Kubernetes Operator.  The Technology Preview release of the Operator provides a number of features to assist with the management of WebLogic domains in a Kubernetes environment, including:
 
-*	A mechanism to create a WebLogic domain on a Kubernetes persistent volume
-*	A mechanism to define a WebLogic domain as a Kubernetes resource (using a Kubernetes custom resource definition)
-*	The ability to automatically start servers based on declarative startup parameters and desired states
-*	The ability to automatically expose the WebLogic Server Administration Console outside the Kubernetes cluster (if desired)
-*	The ability to automatically expose T3 channels outside the Kubernetes domain (if desired)
-*	The ability to automatically expose HTTP paths on a WebLogic domain outside the Kubernetes domain with load balancing, and to update the load balancer when Managed Servers in the WebLogic domain are started or stopped
-*	The ability to scale a WebLogic domain by starting and stopping Managed Servers on demand, or by integrating with a REST API to initiate scaling based on WLDF, Prometheus/Grafana or other rules
-*	The ability to publish Operator and WebLogic Server logs into ElasticSearch and interact with them in Kibana.
 
 As part of Oracle’s ongoing commitment to open source in general, and to Kubernetes and the Cloud Native Computing Foundation specifically, Oracle has open sourced the Operator and is committed to enhancing it with additional features.  Oracle welcomes feedback, issues, pull requests, and feature requests from the WebLogic community.
 
@@ -41,7 +44,7 @@ In this documentation, several important terms are used and are intended to have
 Before using the operator, it is highly recommended that you read the [design philosophy](site/design.md) to develop an understanding of the operator's design, and the [architectural overview](site/architecture.md) to understand its architecture, including how WebLogic domains are deployed in Kubernetes using the operator.  It is also worth reading the details of the [Kubernetes RBAC definitions](site/rbac.md) required by the operator.
 
 # Exposing applications outside the Kubernetes cluster
-The operator can configure services to expose WebLogic applications and features outside of the Kubernetes cluster.  Care should be taken when exposing anything externally to ensure that the appropriate security considerations are taken into account.  There is no significant difference between a WebLogic domain running in a Kubernetes cluster and a domain running in a traditional data center in this regard.  The same kinds of considerations should be taken into account, for example:
+The operator can configure services to expose WebLogic applications and features outside of the Kubernetes cluster.  Care should be taken when exposing anything externally to ensure that the appropriate security considerations are taken into account. In this regard, there is no significant difference between a WebLogic domain running in a Kubernetes cluster and a domain running in a traditional data center.  The same kinds of considerations should be taken into account, for example:
 
 * Only expose those protocols and ports that need to be exposed.
 *	Use secure protocols (HTTPS, T3S, and such).
@@ -68,12 +71,11 @@ The Oracle WebLogic Server Kubernetes Operator has the following requirements:
 
 # Restrictions
 
-The following features are not certified or supported in the Technology Preview release at the time of writing:
+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)
-*	Dynamic domains (the current certification only covers configured clusters; certification of dynamic clusters is planned at a future date)
 *	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
@@ -97,9 +99,9 @@ If you would rather see the developers demonstrating the operator rather than re
 
 * [Installing the operator](https://youtu.be/B5UmY2xAJnk) includes the installation and also shows using the operator's REST API.
 * [Creating a WebLogic domain with the operator](https://youtu.be/Ey7o8ldKv9Y) shows the creation of two WebLogic domains including accessing the Administration Console and looking at the various resources created in Kubernetes - services, Ingresses, pods, load balancers, and such.
-* [Deploying a web application, scaling a WebLogic cluster with the operator and verifying load balancing](https://youtu.be/hx4OPhNFNDM)
+* [Deploying a web application, scaling a WebLogic cluster with the operator and verifying load balancing](https://youtu.be/hx4OPhNFNDM).
 * [Using WLST against a domain running in Kubernetes](https://youtu.be/eY-KXEk8rI4) shows how to create a data source for an Oracle database that is also running in Kubernetes.
-* [Scaling a WebLogic cluster with WLDF](https://youtu.be/Q8iZi2e9HvU)
+* [Scaling a WebLogic cluster with WLDF](https://youtu.be/Q8iZi2e9HvU).
 * Watch this space, more to come!
 
 Like what you see?  Read on for all the nitty-gritty details...
@@ -125,7 +127,7 @@ All of the [installation steps are explained in detail here](site/installation.m
 
 ## Using the operator's REST services
 
-The operator provides a REST API that can be used to obtain information about the configuration and to initiate scaling actions. Please refer to [Using the operator's REST services](site/rest.md) for details about how to use the REST APIs.
+The operator provides a REST API that you can use to obtain information about the configuration and to initiate scaling actions. Please refer to [Using the operator's REST services](site/rest.md) for details about how to use the REST APIs.
 
 ## Creating a WebLogic domain with the operator
 
@@ -156,15 +158,25 @@ Please refer to [Scaling a WebLogic cluster](site/scaling.md) for more informati
 
 Please refer to [Shutting down a domain](site/shutdown-domain.md) for information about how to shut down a domain running in Kubernetes.
 
-## Load balancing with an Ingress Controller or a Web Server
 
-You can choose a load balancer provider for your WebLogic domains running in a Kubernetes cluster. Please refer to Load balancing with Voyager Ingress Controller (link TBD), [Load balancing with Traefik Ingress Controller](site/traefik.md), and [Load balancing with Apache Web Server](site/apache.md) for information about the current capabilities and setup instructions for each of the supported load balancers.
+## Load balancing with an Ingress controller or a web server
+
+You can choose a load balancer provider for your WebLogic domains running in a Kubernetes cluster. Please refer to Load balancing with Voyager Ingress Controller, [Load balancing with Traefik Ingress Controller](site/traefik.md), and [Load balancing with Apache Web Server](site/apache.md) for information about the current capabilities and setup instructions for each of the supported load balancers.
+
 
 [comment]: # (Exporting operator logs to ELK.  The operator provides an option to export its log files to the ELK stack. Please refer to [ELK integration]site/elk.md for information about this capability.)
 
 ## Removing a domain
 
-To permanently remove a domain from a Kubernetes cluster, first shut down the domain using the instructions provided above in the section titled “Shutting down a domain”, then remove the persistent volume claim and the persistent volume using these commands:
+To permanently remove the Kubernetes resources for a domain from a Kubernetes cluster, run the [Delete WebLogic domain resources](kubernetes/delete-weblogic-domain-resources.sh) script. This script will delete a specific domain, or all domains, and all the Kubernetes resources associated with a set of given domains. The script will also attempt a clean shutdown of a domain’s WebLogic pods before deleting its resources.  You can run the script in a test mode to show what would be shutdown and deleted without actually performing the shutdowns and deletions.   For script help, use its `-h` option.
+
+The script will remove only domain-related resources which are labeled with the `domainUID` label, such as resources created by the [Create WebLogic domain](kubernetes/create-weblogic-domain.sh) script or the [integration tests](src/integration-tests/bash/run.sh).  If you manually created resources and have not labelled them with a `domainUID`, the script will not remove them.   One way to label a resource that has already been deployed is:
+
+```
+kubectl -n <Namespace> label <ResourceType> <ResourceName> domainUID=<domainUID>
+```
+
+To manually remove the persistent volume claim and the persistent volume, use these commands:
 
 ```
 kubectl delete pvc PVC-NAME -n NAMESPACE
@@ -173,7 +185,7 @@ kubectl delete pv PV-NAME
 
 Find the names of the persistent volume claim (represented above as `PVC-NAME`) and the persistent volume (represented as `PV-NAME`) in the domain custom resource YAML file, or if it is not available, check for the `domainUID` in the metadata on the persistent volumes. Replace `NAMESPACE` with the namespace that the operator is running in.
 
-To permanently delete the actual domain configuration, delete the physical volume using the appropriate tools.  For example, if the persistent volume used the `HostPath provider`, then delete the corresponding directory on the Kubernetes master.
+To permanently delete the actual WebLogic domain configuration and domain home, delete the physical volume using the appropriate tools.  For example, if the persistent volume used the `HostPath` provider, then delete the corresponding directory on the Kubernetes master.
 
 ## Removing the operator
 
@@ -192,7 +204,7 @@ To remove more than one operator, repeat these steps for each operator namespace
 
 # Recent changes
 
-See [Recent changes](site/recent-changes.md) for recent changes to the operator, including any backwards incompatible changes.
+See [Recent changes](site/recent-changes.md) for recent changes to the operator, including any backward incompatible changes.
 
 
 # Developer guide
@@ -213,7 +225,7 @@ If you have any questions about a possible submission, feel free to open an issu
 
 Pull requests can be made under The Oracle Contributor Agreement (OCA), which is available at [https://www.oracle.com/technetwork/community/oca-486395.html](https://www.oracle.com/technetwork/community/oca-486395.html).
 
-For pull requests to be accepted, the bottom of the commit message must have the following line using the contributor’s name and e-mail address as it appears in the OCA Signatories list.
+For pull requests to be accepted, the bottom of the commit message must have the following line, using the contributor’s name and e-mail address as it appears in the OCA Signatories list.
 
 ```
 Signed-off-by: Your Name <[email protected]>
@@ -230,7 +242,7 @@ Only pull requests from committers that can be verified as having signed the OCA
 ## Pull request process
 
 *	Fork the repository.
-*	Create a branch in your fork to implement the changes. We recommend using the issue number as part of your branch name, e.g. `1234-fixes`.
+*	Create a branch in your fork to implement the changes. We recommend using the issue number as part of your branch name, for example, `1234-fixes`.
 *	Ensure that any documentation is updated with the changes that are required by your fix.
 *	Ensure that any samples are updated if the base image has been changed.
 *	Submit the pull request. Do not leave the pull request blank. Explain exactly what your changes are meant to do and provide simple steps on how to validate your changes. Ensure that you reference the issue you created as well. We will assign the pull request to 2-3 people for review before it is merged.