Merge pull request #848 from oracle/rmarano

fine-tune edits

Author: rjeberhard

site/architecture.md

@@ -3,7 +3,7 @@
 The operator consists of the following parts:
 
 *	The operator runtime, a process that runs in a Docker container deployed into a Kubernetes pod and which performs the actual management tasks.
-* The model for a Kubernetes custom resource definition (CRD) that when installed in a Kubernetes cluster allows the Kubernetes API server to manage instances of this new type representing the operational details and status of WebLogic domains. 
+* The model for a Kubernetes custom resource definition (CRD) that when installed in a Kubernetes cluster allows the Kubernetes API server to manage instances of this new type representing the operational details and status of WebLogic domains.
 *	A Helm chart for installing the operator runtime and related resources.
 * A variety of sample shell scripts for preparing or packaging  WebLogic domains for running in Kubernetes.
 * A variety of sample Helm charts or shell scripts for conditionally exposing WebLogic endpoints outside the Kubernetes cluster.
@@ -25,7 +25,7 @@ The diagram below shows the general layout of high-level components, including o
 
 The Kubernetes cluster has several namespaces.  Components may be deployed into namespaces as follows:
 
-*	The operator is deployed into its own namespace.  If the Elastic Stack integration option is configured, then a logstash pod will also be deployed in the operator’s namespace.
+*	The operator is deployed into its own namespace.  If the Elastic Stack integration option is configured, then a Logstash pod will also be deployed in the operator’s namespace.
 *	WebLogic domains will be deployed into various namespaces.  There can be more than one domain in a namespace, if desired.  There is no limit on the number of domains or namespaces that an operator can manage.  Note that there can be more than one operator in a Kubernetes cluster, but each operator is configured with a list of the specific namespaces that it is responsible for.  The operator will not take any action on any domain that is not in one of the namespaces the operator is configured to manage.
 * Customers are responsible for load balancer configuration, which will typically be in the same namespace with domains or in a system, shared namespace such as the `kube-system` namespace.
 *	Customers are responsible for Elasticsearch and Kibana deployment, which are typically deployed in the `default` namespace.
@@ -38,8 +38,8 @@ The diagram below shows how the various parts of a WebLogic domain are manifest
 
 This diagram shows the following details:
 
-*	An optional persistent volume is created by the customer using one of the available providers.  If the persistent volume is shared across the domain or members of a cluster, the chosen provider must support “Read Write Many” access mode.  The shared state on the persistent volume may include the “domain” directory, the “applications” directory, a directory for storing logs and a directory for any file-based persistence stores.
-*	A pod is created for the WebLogic Administration Server.  This pod is labeled with `weblogic.domainUID`, `weblogic.serverName` and `weblogic.domainName`.  One container runs in this pod.  WebLogic Node Manager and Administration Server processes are run inside this container.  The Node Manager process is used as an internal implementation detail for the liveness probe, for patching, and to provide monitoring and control capabilities to the Administration Console.  It is not intended to be used for other purposes, and it may be removed in some future release.
+*	An optional, persistent volume is created by the customer using one of the available providers.  If the persistent volume is shared across the domain or members of a cluster, then the chosen provider must support “Read Write Many” access mode.  The shared state on the persistent volume may include the “domain” directory, the “applications” directory, a directory for storing logs, and a directory for any file-based persistence stores.
+*	A pod is created for the WebLogic Administration Server.  This pod is labeled with `weblogic.domainUID`, `weblogic.serverName`, and `weblogic.domainName`.  One container runs in this pod.  WebLogic Node Manager and Administration Server processes are run inside this container.  The Node Manager process is used as an internal implementation detail for the liveness probe, for patching, and to provide monitoring and control capabilities to the Administration Console.  It is not intended to be used for other purposes, and it may be removed in some future release.
 *	A `ClusterIP` type service is created for the Administration Server pod.  This service provides a stable, well-known network (DNS) name for the Administration Server.  This name is derived from the `domainUID` and the Administration Server name, and it is known before starting up any pod.  The Administration Server `ListenAddress` is set to this well-known name.  `ClusterIP` type services are only visible inside the Kubernetes cluster.  They are used to provide the well-known names that all of the servers in a domain use to communicate with each other.  This service is labeled with `weblogic.domainUID` and `weblogic.domainName`.
 *	A `NodePort` type service is optionally created for the Administration Server pod.  This service provides HTTP access to the Administration Server to clients that are outside the Kubernetes cluster.  This service is intended to be used to access the WebLogic Server Administration Console or for the T3 protocol for WLST connections.  This service is labeled with `weblogic.domainUID` and `weblogic.domainName`.
 *	A pod is created for each WebLogic Managed Server.  These pods are labeled with `weblogic.domainUID`, `weblogic.serverName`, and `weblogic.domainName`.  One container runs in each pod.  WebLogic Node Manager and Managed Server processes are run inside each of these containers.  The Node Manager process is used as an internal implementation detail for the liveness probe.  It is not intended to be used for other purposes, and it may be removed in some future release.
@@ -51,13 +51,13 @@ The diagram below shows the components inside the containers running WebLogic Se
 ![Inside a container](images/inside-a-container.png)
 
 The domain resource specifies a Docker image, defaulting to `store/oracle/weblogic:12.2.1.3`. All containers running WebLogic Server use this same Docker image. Depending on the use case, this image could contain the WebLogic Server product binaries or also include the domain directory.
-**Note**: During a rolling event caused by a change to the domain resource's image field, containers will be using a mix of the updated value of the image field and its previous value.
+**Note**: During a rolling event caused by a change to the domain resource's `image` field, containers will be using a mix of the updated value of the `image` field and its previous value.
 
 Within the container, the following aspects are configured by the operator:
 
-*	The `ENTRYPOINT` is configured to a script that starts up a Node Manager process, and then uses WLST to request that Node Manager start the server.  Node Manager is used to start servers so that the socket connection to the server will be available to obtain server status even when the server is unresponsive.  This is used by the liveness probe.
+*	The `ENTRYPOINT` is configured by a script that starts up a Node Manager process, and then uses WLST to request that Node Manager start the server.  Node Manager is used to start servers so that the socket connection to the server will be available to obtain server status even when the server is unresponsive.  This is used by the liveness probe.
 * The liveness probe is configured to check that the server is alive by querying the Node Manager process.  The liveness probe is by default configured to check liveness every 15 seconds, and to timeout after 5 seconds.  If a pod fails the liveness probe, Kubernetes will restart that container.
-*	The readiness probe is configured to use the WebLogic Server ReadyApp.  The readiness probe is used to determine if the server is ready to accept user requests.  The readiness is used to determine when a server should be included in a load balancer's endpoints, when a restarted server is fully started in the case of a rolling restart, and for various other purposes.
+*	The readiness probe is configured to use the WebLogic Server ReadyApp framework.  The readiness probe is used to determine if the server is ready to accept user requests.  The readiness is used to determine when a server should be included in a load balancer's endpoints, when a restarted server is fully started in the case of a rolling restart, and for various other purposes.
 *	A shutdown hook is configured that will execute a script that performs a graceful shutdown of the server.  This ensures that servers have an opportunity to shut down cleanly before they are killed.
 
 ## Domain state stored outside Docker images

site/domain-resource.md

@@ -19,7 +19,7 @@ For sample YAML templates, see the [Domain resource example](../kubernetes/sampl
 
 # Kubernetes resources
 
-After you have written your YAML files, please use them to create your WLS domain artifacts using the `kubectl apply -f` command.
+After you have written your YAML files, you use them to create your WLS domain artifacts using the `kubectl apply -f` command.
 
 ```
 $ kubectl apply -f domain-resource.yaml

site/domains.md

@@ -9,13 +9,13 @@ You can also mix and match on a domain-by-domain basis.
 | --- | --- |
 | Let's you 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 configuration are. |
-| The domain is long-lived, so you can mutate the configuration or deploy new applications using standard methods (Administration Console, WLST, etc.) | If you want to mutate the domain configuration or deploy application updates, you must create a new image. |
+| The domain is long-lived, so you can mutate the configuration or deploy new applications using standard methods (Administration Console, WLST, and such). | 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, for example, with patches installed. | You may need to do more work to set up processes to build and maintain your images. |
+| You may be able to use standard Oracle-provided images or, at least, a very small number of self-built images, for example, with patches installed. | You may need to do more work to set up processes to build and maintain your images. |
 
 ### Preparing the Kubernetes cluster to run WebLogic domains
 
@@ -30,7 +30,7 @@ Perform these steps to prepare your Kubernetes cluster to run a WebLogic domain:
    Replace `domain-namespace-1` with name you want to use.  The name must follow standard Kubernetes naming conventions, that is, lower case,
    numbers, and hyphens.
 
-1. Create a Kubernetes secret containing the Administration Server boot credentials.  You can do this manually or using
+1. Create a Kubernetes secret containing the Administration Server boot credentials.  You can do this manually or by using
    [the provided sample](/kubernetes/samples/scripts/create-weblogic-domain-credentials/README.md).  To create
    the secret manually, use this command:
 
@@ -48,7 +48,7 @@ Perform these steps to prepare your Kubernetes cluster to run a WebLogic domain:
    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 available after the pods terminate.
+   Even if you put your domain in a Docker image, you may want to put the logs on a persistent volume so that they are available 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.
 
@@ -57,17 +57,16 @@ Perform these steps to prepare your Kubernetes cluster to run a WebLogic domain:
 Please be aware of the following important considerations for WebLogic domains
 running in Kubernetes.
 
-* _Domain Home Location:_ The WebLogic domain home location is determined by the domain resource `domainHome` if set,
-  and otherwise a default location is determined by the `domainHomeInImage` setting. If a domain resource `domainHome` field is not set
-  and `domainHomeInImage` is `true` (the default), the operator will
+* _Domain Home Location:_ The WebLogic domain home location is determined by the domain resource `domainHome` if set; otherwise, a default location is determined by the `domainHomeInImage` setting. If a domain resource `domainHome` field is not set
+  and `domainHomeInImage` is `true` (the default), then the operator will
   assume that the domain home is a directory under `/u01/oracle/user_projects/domains/` and report an error if no domain is found
-  or more than one domain is found.  If a domain resource `domainHome` field is not set and `domainHomeInImage` is `false`, the operator will
+  or more than one domain is found.  If a domain resource `domainHome` field is not set and `domainHomeInImage` is `false`, then the operator will
   assume that the domain home is `/shared/domains/DOMAIN_UID`.
-* _Log File Locations:_ The operator can automatically override Weblogic domain and server log locations using situational
+* _Log File Locations:_ The operator can automatically override WebLogic domain and server log locations using situational
   configuration overrides.  This occurs if the domain resource `logHomeEnabled` field is explicitly set to `true`, or if `logHomeEnabled` isn't set
   and `domainHomeInImage` is explicitly set to `false`.   When overriding, the log location will be the location specified by the `logHome` setting.
 * _Listen Address Configuration:_  Channel listen addresses in a configuration either must be left completely unset (for example, 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 hyphens).  For example `domain1-admin-server`. This includes default, SSL, admin, and custom channels.
+  followed by a hyphen and then the server name (with all lower case, underscores converted to hyphens), for example, `domain1-admin-server`. This includes default, SSL, admin, and custom channels.
 * _Listen Address Overrides:_  The operator will automatically override all WebLogic domain default,
   SSL, admin, or custom channel listen addresses (using situational configuration overrides).  These will become `domainUID` followed by a
   hyphen and then the server name, all lower case, and underscores converted to hyphens.  For example, if `domainUID=domain1` and
@@ -105,7 +104,7 @@ Please consult My Oracle Support Doc ID 2349228.1 for up-to-date information abo
 In this version of the operator, a WebLogic domain can be located either in a persistent volume (PV) or in a Docker image.
 For examples of each, see the [WebLogic operator samples](../kubernetes/samples/README.md).
 
-If you wish to create your own Docker images, for example to choose a specific set of patches, or to create a domain
+If you want to create your own Docker images, for example, to choose a specific set of patches or to create a domain
 with a specific configuration and/or applications deployed, then you can create the domain custom resource
 manually to deploy your domain.  This process is documented in [this
 sample](../kubernetes/samples/scripts/create-weblogic-domain/manually-create-domain/README.md).
@@ -115,15 +114,15 @@ sample](../kubernetes/samples/scripts/create-weblogic-domain/manually-create-dom
 You can modify the WebLogic domain configuration for both the "domain in persistent volume" and the "domain in image" options before deploying a domain resource:
 
 * When the domain is in a persistent volume, you can use WLST or WDT to change the configuration.
-* For either case you can use [configuration overrides](config-overrides.md).   
+* For either case, you can use [configuration overrides](config-overrides.md).   
 
 Configuration overrides allow changing a configuration without modifying its original `config.xml` or system resource XML files, and also support parameterizing overrides so that you can inject values into them from Kubernetes secrets.   For example, you can inject database user names, passwords, and URLs that are stored in a secret.
 
-### About the Domain resource
+### About the domain resource
 
-More information about the Domain resource can be found [here](domain-resource.md).
+For information about the domain resource, see [Domain resource](domain-resource.md).
 
-### Managing lifecycle operations including shutting down and deleting domains
+### Managing lifecycle operations
 
 In Operator 2.0, you can perform lifecycle operations on WebLogic servers, clusters, or domains.
 See [Starting, stopping, and restarting servers](server-lifecycle.md) and [Restarting WebLogic servers](restart.md).