Docs merge to master for 3.0.0-rc1 (#1634)

* init branch

* wip - preparing 3.0.0-rc1 docs for release

* release notes, home page updates, review feedback

* update prereqs; link from home page to MII doc and samples:

* updates based on review feedback

* updates based on review feedback

* updates based on review feedback

* updates based on review feedback

* pick up helm charts for 3.0.0-rc1

Author: markxnelson

docs-source/content/_index.md

@@ -21,28 +21,33 @@ using the operator to deploy and run a WebLogic domain container-packaged web ap
 {{% /notice %}}
 
 ***
-#### Current release
+#### Current production release
 
-The [current release of the operator](https://github.com/oracle/weblogic-kubernetes-operator/releases) is 2.5.0.
+The [current production release of the operator](https://github.com/oracle/weblogic-kubernetes-operator/releases) is 2.5.0.
 This release was published on February 26, 2020. See the operator prerequisites and supported environments [here]({{< relref "/userguide/introduction/introduction#operator-prerequisites" >}}).
 
-##### Preview of next planned release
+#### Preview of next major release
 
-The next planned release is 3.0.0-rc1 (release candidate).  This release candidate will
-be suitable for use by early adopters who wish to test 3.0.0 features and provide
-feedback.  
+The [current preview release of the operator](https://github.com/oracle/weblogic-kubernetes-operator/releases) is 3.0.0-rc1 (release candidate).
+This release candidate is suitable for use by early adopters who wish to test 3.0.0 features and provide feedback.
+This release candidate was published on May 8, 2020.  There may be additional release candidates before the final 3.0.0 release.
 
-This release is planned for April 2020, subject to change.
+This release candidate introduces _non-backward compatible_ changes.  This release candidate cannot be run in the same
+cluster as another release of the operator.  You can upgrade from 2.5.0 to 3.0.0-rc1 without needing to restart or recreate
+any existing domains. However, please note that we do plan to support running the final 3.0.0
+release in the same cluster with at least one 2.x release of the operator to allow for staged migration.
 
-The planned feature changes in 3.0.0-rc1 are:
+The feature changes in 3.0.0-rc1 are:
 
-* Introduction of a new "Model In Image" feature which allows you to have a domain
+* Introduction of a new ["Model In Image"]({{% relref "/userguide/managing-domains/model-in-image" %}}) feature which allows you to have a domain
   created at pod startup time from a WebLogic Deploy Tool model and archive.
   This supports user-requested use cases like creating multiple domains from
   the same model and automated updating of the domain based on model changes.
   The operator automates management of the domain encryption keys to ensure
   that they are not changed during domain updates.
-* Support for running the operator on Kubernetes 1.16, 1.17 and 1.18.
+  A [sample]({{% relref "/samples/simple/domains/model-in-image" %}}) is also provided that
+  demonstrates the key use cases for this feature.
+* Support for running the operator on Kubernetes 1.16.
 * Deprecation and removal of support for running the operator on Kubernetes 1.13
   and earlier versions.
 * Deprecation and removal of support for Helm 2.x.  Helm 2.x uses the "tiller" pod
@@ -105,13 +110,11 @@ Please refer to our [samples]({{< relref "/samples/_index.md" >}}) for informati
 
 Developers interested in this project are encouraged to read the [Developer guide]({{< relref "/developerguide/_index.md" >}}) to learn how to build the project, run tests, and so on.  The Developer guide also provides details about the structure of the code, coding standards, and the Asynchronous Call facility used in the code to manage calls to the Kubernetes API.
 
-Please take a look at our [wish list](https://github.com/oracle/weblogic-kubernetes-operator/wiki/Wish-list) to get an idea of the kind of features we would like to add to the operator.  Maybe you will see something to which you would like to contribute!
-
 ### API documentation
 
 Documentation for APIs:
 
-* The operator provides a REST API that you can use to obtain configuration information and to initiate scaling actions. For details about how to use the REST APIs, see [Use the operator's REST services]({{< relref "/userguide/managing-operators/using-the-operator/the-rest-api.md#use-the-operator-s-rest-services" >}}).
+* The operator provides a REST API that you can use to obtain configuration information and to initiate scaling actions. For details about how to use the REST APIs, see [Use the operator's REST services]({{< relref "/userguide/managing-operators/using-the-operator/the-rest-api#use-the-operators-rest-services" >}}).
 
 * See the [Swagger](https://oracle.github.io/weblogic-kubernetes-operator/swagger/index.html) documentation for the operator's REST interface.
 

docs-source/content/developerguide/code-structure.md

@@ -16,7 +16,7 @@ This project has the following directory structure:
 * `model`: Domain resource Java model
 * `operator`: Operator runtime
 * `site`: This documentation
-* `src/scripts`: Scripts operator injects into WebLogic server instance Pods
+* `src/scripts`: Scripts operator injects into WebLogic Server instance Pods
 * `swagger`: Swagger files for the Kubernetes API server and domain resource
 
 ### Watch package

docs-source/content/developerguide/requirements.md

@@ -5,15 +5,15 @@ draft: false
 weight: 1
 ---
 
-In addition to the requirements listed in the [User guide]({{< relref "/userguide/introduction/introduction.md#prerequisites" >}}), the following software is also required to obtain and build the operator:
+In addition to the requirements listed in the [User guide]({{< relref "/userguide/introduction/introduction#operator-prerequisites" >}}), the following software is also required to obtain and build the operator:
 
 * Git (1.8 or later recommended)
 * Java Developer Kit (11 required, 11.0.2 recommended)
 * Apache Maven (3.5.3 min, 3.6 recommended)
 
 The operator is written primarily in Java, BASH shell scripts, and WLST scripts.  
 
-Because the target runtime environment for the operator is Oracle Linux, no particular effort has been made to ensure the build or tests run on any other operating system.  Please be aware that Oracle will not provide support, or accept pull requests to add support, for other operating systems.
+Because the target runtime environment for the operator is Oracle Linux, no particular effort has been made to ensure the build or tests run on any other operating system.  Please be aware that Oracle will not provide support, or accept pull requests to add support for other operating systems.
 
 #### Obtaining the operator source code
 

docs-source/content/faq/boot-identity-not-valid.md

@@ -11,8 +11,8 @@ weight: 20
 
 When you see these kinds of errors, it means that the user name and password provided in the `weblogicCredentialsSecret` are incorrect. Prior to operator version 2.5.0, this error could
 have also indicated that the WebLogic domain directory's security configuration files have changed in an incompatible way between when the operator scanned
-the domain directory, which occurs during the "introspection" phase, and when the server instance attempted to start. There is now a separate validation for that condition described in the [domain secret mismatch FAQ entry](../domain-secret-mismatch/).
+the domain directory, which occurs during the "introspection" phase, and when the server instance attempted to start. There is now a separate validation for that condition described in the [Domain secret mismatch](../domain-secret-mismatch/) FAQ entry.
 
 Check that the user name and password credentials stored in the Kubernetes secret referenced by `weblogicCredentialsSecret` contain the expected values for an account with administrative privilege for the WebLogic domain.
-Then [stop all WebLogic server instances](https://oracle.github.io/weblogic-kubernetes-operator/userguide/managing-domains/domain-lifecycle/startup/#starting-and-stopping-servers)
-in the domain before restarting so that the operator will repeat its introspection and generate the corrected "boot.properites" files.
+Then [stop all WebLogic Server instances](https://oracle.github.io/weblogic-kubernetes-operator/userguide/managing-domains/domain-lifecycle/startup/#starting-and-stopping-servers)
+in the domain before restarting so that the operator will repeat its introspection and generate the corrected `boot.properties` files.

docs-source/content/faq/cannot-pull-image.md

@@ -37,7 +37,7 @@ The Docker tag `latest` is confusing - it does not actually mean the latest vers
 the image that was created or published in the registry; it just literally means
 whichever version the owner decided to call "latest".  Docker and Kubernetes make
 some assumptions about latest, and it is generally recommended to avoid using it and instead
-specify the actual version/tag that you really want.
+specify the actual version or tag that you really want.
 {{% /notice %}}
 
 First, Kubernetes will check to see if the requested image is available in the local
@@ -80,7 +80,7 @@ use the image.
 
 {{% notice note %}}
 Some registries may need a suffix making the `docker-server` something like `some.registry.com/v2`
-for example.  You will need to check with your registry provider's documentation to see if this is needed.
+for example.  You will need to check with your registry provider's documentation to determine if this is needed.
 {{% /notice %}}
 
 After the secret is created, you need to tell Kubernetes to use it.  This is done by adding
@@ -101,7 +101,7 @@ metadata:
     weblogic.domainUID: domain1
 spec:
   domainHome: /u01/oracle/user_projects/domains/domain1
-  domainHomeInImage: true
+  domainHomeSourceType: Image
   image: "some.registry.com/owner/domain1:1.0"
   imagePullPolicy: "IfNotPresent"
   imagePullSecrets:
@@ -124,8 +124,7 @@ kubectl patch serviceaccount default \
 {{% notice note %}}
 You can provide mutliple `imagePullSecrets` if you need to pull Docker images from multiple
 remote Docker registries or if your images require different authentication credentials.
-For more information, see [Docker Image Protection]({{<relref "/security/domain-security/image-protection.md#weblogic-domain-in-docker-image-protection">}})
-under **Security**.
+For more information, see [Docker Image Protection]({{<relref "/security/domain-security/image-protection#weblogic-domain-in-docker-image-protection">}}).
 {{% /notice %}}
 
 #### Manually copying the image to your worker nodes
@@ -134,13 +133,13 @@ If you are not able to use a remote Docker registry, for example if your Kuberne
 in a secure network with no external access, you can manually copy the Docker images to the
 cluster instead.
 
-On the machine where you created the image, export it into a tar file using this command:
+On the machine where you created the image, export it into a TAR file using this command:
 
 ```
 docker save domain1:1.0 > domain1.tar
 ```
 
-Then copy that tar file to each worker node in your Kubernetes cluster and run this command
+Then copy that TAR file to each worker node in your Kubernetes cluster and run this command
 on each node:
 
 ```

docs-source/content/faq/coherence-requirements.md

@@ -7,46 +7,45 @@ weight: 90
 
 If you are running Coherence on Kubernetes, either inside a WebLogic domain
 or standalone, then there are some additional requirements to make sure
-that Coherence can form clusters. 
+that Coherence can form clusters.
 
 Note that some Fusion Middleware products, like SOA Suite, use Coherence
 and so these requirements apply to them.
 
-#### Unicast and Well Known Address 
+#### Unicast and Well Known Address
 When the first Coherence process starts, it will form a cluster.  The next
-Coherence process to start (i.e. in a different pod) will use UDP to try
+Coherence process to start (for example, in a different pod), will use UDP to try
 to contact the senior member.  
 
 If you create a WebLogic domain which contains a Coherence cluster
 using the samples provided in this project, then that cluster will
-be configured correctly so that it is able to form; 
+be configured correctly so that it is able to form;
 you do not need to do any additional manual configuration.
 
-If you are running Coherence standalone (outside a 
-WebLogic domain) you should configure Coherence to use unicast and 
+If you are running Coherence standalone (outside a
+WebLogic domain), then you should configure Coherence to use unicast and
 provide a "well known address (WKA)" so that all members can find the senior
 member.  Most Kubernetes overlay network providers do not
 support multicast.  
 
-This is done by specifying the Coherence well known addresses in a variable named
-`coherence.wka` as shown in the example below:
+This is done by specifying Coherence well known addresses in a variable named
+`coherence.wka` as shown in the following example:
 
 ```
 -Dcoherence.wka=my-cluster-service
 ```
 
-In this example `my-cluster-service` should be the name of the Kubernetes 
+In this example `my-cluster-service` should be the name of the Kubernetes
 service that is pointing to all of the members of that Coherence cluster.
 
-Please refer to the [Coherence operator documentation](https://oracle.github.io/coherence-operator/)
-for more information about running Coherence in Kubernetes outside of 
-a WebLogic domain.
+For more information about running Coherence in Kubernetes outside of
+a WebLogic domain, refer to the [Coherence operator documentation](https://oracle.github.io/coherence-operator/).
 
 #### Operating system library requirements
 
 In order for Coherence clusters to form correctly, the `conntrack` library
 must be installed.  Most Kubernetes distributions will do this for you.
-If you have issues with clusters not forming, you should check that 
+If you have issues with clusters not forming, then you should check that
 `conntrack` is installed using this command (or equivalent):
 
 ```
@@ -62,7 +61,7 @@ should install `conntrack` using your operating system tools.
 
 Some Kubernetes distributions create `iptables` rules that block some
 types of traffic that Coherence requires to form clusters.  If you are
-not able to form clusters, you can check for this issue using the
+not able to form clusters, then you can check for this issue using the
 following command:
 
 ```
@@ -73,7 +72,7 @@ pkts bytes target     prot opt in     out     source               destination
    0     0 MASQUERADE  all  --  *      !lo     0.0.0.0/0            0.0.0.0/0
 ```
 
-If you see output similar to the example above, i.e. if you see any entries 
+If you see output similar to the example above, for example, if you see any entries
 in this chain, then you need to remove them.  You can remove the entries
 using this command:
 
@@ -82,45 +81,45 @@ using this command:
 ```
 
 Note that you will need to run that command for each line. So in the example
-above, you would need to run it twice. 
+above, you would need to run it twice.
 
 After you are done, you can run the previous command again and verify that
 the output is now an empty list.
 
-After making this change, restart your domain(s) and the Coherence cluster
-should now form correctly. 
+After making this change, restart your domains and the Coherence cluster
+should now form correctly.
 
 #### Make iptables updates permanent across reboots
 
-The recommended way to make `iptables` updates permanent across reboots is 
-to create a `systemd` service that applies the necessary updates during 
+The recommended way to make `iptables` updates permanent across reboots is
+to create a `systemd` service that applies the necessary updates during
 the startup process.
 
-Here is an example, but you may need to adjust this to suit your own 
+Here is an example; you may need to adjust this to suit your own
 environment:
 
 * Create a `systemd` service:
 
-    ```bash 
+    ```bash
     echo 'Set up systemd service to fix iptables nat chain at each reboot (so Coherence will work)...'
     mkdir -p /etc/systemd/system/
     cat > /etc/systemd/system/fix-iptables.service << EOF
     [Unit]
     Description=Fix iptables
     After=firewalld.service
     After=docker.service
-    
+
     [Service]
     ExecStart=/sbin/fix-iptables.sh
-    
+
     [Install]
     WantedBy=multi-user.target
     EOF
     ```
 
 * Create the script to update `iptables`:
 
-    ```bash 
+    ```bash
     cat > /sbin/fix-iptables.sh << EOF
     #!/bin/bash
     echo 'Fixing iptables rules for Coherence issue...'
@@ -138,4 +137,4 @@ environment:
     ```bash
     echo 'Start the systemd service to fix iptables nat chain...'
     systemctl enable --now fix-iptables
-    ```
+    ```