Merge branch '2.0-rc1-final-doc-review' into develop

Author: markxnelson

README.md

@@ -20,6 +20,24 @@ Oracle is finding ways for organizations using WebLogic Server to run important
 
 The fastest way to experience the operator is to follow the [Quick start guide](site/quickstart.md), or you can peruse our [documentation](site), read our [blogs](https://blogs.oracle.com/weblogicserver/how-to-weblogic-server-on-kubernetes), or try out the [samples](kubernetes/samples/README.md).
 
+```diff
++ The current release of the operator is 2.0-rc1, a release candidate for our 2.0 release. 
++ This release candidate was published on Dec 20, 2018. 
++ We expect to publish the final 2.0 release in January 2019.
++ We expect that there will be some minor changes to documentation and samples in the final 2.0 release,
++ however, this release candidate is suitable for testing and early adopters.
+```
+
+# Backward Compatibility Guidelines
+
+The 2.0 release introduces some breaking changes and does not maintain compatibility with previous releases.
+
+Starting with the 2.0 release, future operator releases are intended to be backwards-compatible with respect to the Domain 
+resource schema, operator Helm chart input values, configuration overrides template, Kubernetes resources created 
+by the operator Helm chart, Kubernetes resources created by the operator, and the operator REST interface. We intend to 
+maintain compatibility for three releases, excepting a clearly communicated deprecated feature, which will be 
+maintained for one release after a replacement is available.
+
 # About this documentation
 
 This documentation includes sections aimed at different audiences.  To help you find what you are looking for more easily,

kubernetes/samples/charts/apache-samples/custom-sample/README.md

@@ -8,7 +8,7 @@ $ kubectl create namespace apache-sample
 ```
 
 ## 2. Create WebLogic domains
-We need to prepare some backend domains for load balancing by the Apache webtier. Refer to the sample, https://github.com/oracle/weblogic-kubernetes-operator/tree/develop/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv, to create two WebLogic domains under the namespace `apache-sample`.
+We need to prepare some backend domains for load balancing by the Apache webtier. Refer to the [sample](/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/README.md), to create two WebLogic domains under the namespace `apache-sample`.
 
 The first domain uses the following custom configuration parameters:
 - namespace: `apache-sample`
@@ -31,7 +31,7 @@ The second domain uses the following custom configuration parameters:
 After the domains are successfully created, deploy the sample web application, `testwebapp.war`, on each domain cluster using the WLS Administration Console. The sample web application is located in the `kubernetes/samples/charts/application` directory.
 
 ## 3. Build the Apache webtier Docker image
-Refer to the sample, https://github.com/oracle/docker-images/tree/master/OracleWebLogic/samples/12213-webtier-apache, to build the Apache webtier Docker image.
+Refer to the [sample](https://github.com/oracle/docker-images/tree/master/OracleWebLogic/samples/12213-webtier-apache), to build the Apache webtier Docker image.
 
 ## 4. Provide the custom Apache plugin configuration
 In this sample, we will provide a custom Apache plugin configuration to fine tune the behavior of Apache.

kubernetes/samples/charts/apache-samples/default-sample/README.md

@@ -2,7 +2,7 @@
 In this sample, we will configure the Apache webtier as a load balancer for a WebLogic domain using the default configuration. We will demonstrate how to use the Apache webtier to handle traffic to a backend WebLogic domain.
 
 ## 1. Create a WebLogic domain
-We need to prepare a backend domain for load balancing by the Apache webtier. Refer to the sample, https://github.com/oracle/weblogic-kubernetes-operator/tree/develop/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv, to create a WebLogic domain. Keep the default values for the following configuration parameters:
+We need to prepare a backend domain for load balancing by the Apache webtier. Refer to the [sample](/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/README.md), to create a WebLogic domain. Keep the default values for the following configuration parameters:
 - namespace: `default`
 - domainUID: `domain1`
 - clusterName: `cluster-1`
@@ -13,10 +13,10 @@ We need to prepare a backend domain for load balancing by the Apache webtier. Re
 After the domain is successfully created, deploy the sample web application, `testwebapp.war`, on the domain cluster using the WLS Administration Console. The sample web application is located in the `kubernetes/samples/charts/application` directory.
 
 ## 2. Build the Apache webtier Docker image
-Refer to the sample, https://github.com/oracle/docker-images/tree/master/OracleWebLogic/samples/12213-webtier-apache, to build the Apache webtier Docker image.
+Refer to the [sample](https://github.com/oracle/docker-images/tree/master/OracleWebLogic/samples/12213-webtier-apache), to build the Apache webtier Docker image.
 
 ## 3. Install the Apache webtier with a Helm chart
-The Apache webtier Helm chart is located at https://github.com/oracle/weblogic-kubernetes-operator/blob/develop/kubernetes/samples/charts/apache-webtier.
+The Apache webtier Helm chart [is located here](kubernetes/samples/charts/apache-webtier).
 Install the Apache webtier Helm chart into the default namespace with the default settings:
 ```
 $ cd kubernetes/samples/charts

kubernetes/samples/charts/apache-webtier/README.md

@@ -6,12 +6,8 @@ The chart depends on the Docker image for the Apache HTTP Server with the 12.2.1
 
 ## Prerequisites
 
-- Kubernetes 1.8+
-
-```console
-$ docker pull wlsldi-v2.docker.oraclecorp.com/weblogic-webtier-apache-12.2.1.3.0:latest
-$ docker tag wlsldi-v2.docker.oraclecorp.com/weblogic-webtier-apache-12.2.1.3.0:latest store/oracle/apache:12.2.1.3
-```
+You will need to build a Docker image with the Apache webtier in it using the sample provided [here](https://github.com/oracle/docker-images/tree/master/OracleWebLogic/samples/12213-webtier-apache)
+in order to use this load balancer.
 
 ## Installing the Chart
 To install the chart with the release name `my-release`:

kubernetes/samples/charts/traefik/README.md

@@ -13,15 +13,15 @@ The chart is in the default repository for Helm.
 
 To install the Traefik operator in the `traefik` namespace with default settings:
 ```
-helm install --name traefik-operator --namespace traefik stable/traefik
+$ helm install --name traefik-operator --namespace traefik stable/traefik
 ```
 Or, with a given `values.yaml`:
 ```
-helm install --name traefik-operator --namespace traefik --values values.yaml stable/traefik
+$ helm install --name traefik-operator --namespace traefik --values values.yaml stable/traefik
 ```
 With the dashboard enabled, you can access the Traefik dashboard with the URL `http://${HOSTNAME}:30305`, with the HTTP host `traefik.example.com`.
 ```
-curl -H 'host: traefik.example.com' http://${HOSTNAME}:30305/
+$ curl -H 'host: traefik.example.com' http://${HOSTNAME}:30305/
 ```
 
 ## Optionally, download the Traefik Helm chart
@@ -94,7 +94,7 @@ $ curl -k -H 'host: domain2.org' https://${HOSTNAME}:30443/testwebapp/
 ## Uninstall the Traefik operator
 After removing all the Ingress resources, uninstall the Traefik operator:
 ```
-helm delete --purge traefik-operator
+$ helm delete --purge traefik-operator
 ```
 ## Install and uninstall the Traefik operator with setup.sh
 Alternatively, you can run the helper script `setup.sh`, under the `kubernetes/samples/charts/util` folder, to install and uninstall Traefik.

kubernetes/samples/charts/voyager/README.md

@@ -103,7 +103,7 @@ $ curl -k -H 'host: domain2.org' https://${HOSTNAME}:30307/testwebapp/
 ## Uninstall the Voyager Operator
 After removing all the Voyager Ingress resources, uninstall the Voyager operator:
 ```
-helm delete --purge voyager-operator
+$ helm delete --purge voyager-operator
 ```
 
 ## Install and uninstall the Voyager operator with setup.sh

kubernetes/samples/scripts/create-weblogic-domain-pv-pvc/README.md

@@ -16,16 +16,16 @@ Prior to running the `create-pv-pvc.sh` script, make a copy of the `create-pv-pv
 Run the create script, pointing it at your inputs file and an output directory:
 
 ```
-  ./create-pv-pvc.sh \
+$ ./create-pv-pvc.sh \
   -i create-pv-pvc-inputs.yaml \
   -o /path/to/output-directory
 ```
 
-The `create-pv-pvc.sh` script will create a subdirectory `pv-pvcs` under the given `/path/to/output-directory` directory. By default, the script generates two YAML files, namely `weblogic-sample-pv.yaml` and `weblogic-sample-pvc.yaml`, in the `/path/to/output-directory` `directory/pv-pvcs`. These two YAML files can be used to create the Kubernetes resources using the `kubectl create -f` command.
+The `create-pv-pvc.sh` script will create a subdirectory `pv-pvcs` under the given `/path/to/output-directory` directory. By default, the script generates two YAML files, namely `weblogic-sample-pv.yaml` and `weblogic-sample-pvc.yaml`, in the `/path/to/output-directory/pv-pvcs`. These two YAML files can be used to create the Kubernetes resources using the `kubectl create -f` command.
 
 ```
-  kubectl create -f weblogic-sample-pv.yaml
-  kubectl create -f weblogic-sample-pvc.yaml
+$ kubectl create -f weblogic-sample-pv.yaml
+$ kubectl create -f weblogic-sample-pvc.yaml
 
 ```
 
@@ -173,6 +173,9 @@ spec:
 
 ### Verify the PV and PVC objects
 
+You can use this command to verify the persistent volume was created, note that the `Status` field
+should have the value `Bound`, indicating the that persistent volume has been claimed:
+
 ```
 $ kubectl describe pv weblogic-sample-pv
 Name:            weblogic-sample-pv
@@ -193,6 +196,8 @@ Events:            <none>
 
 ```
 
+You can use this command to verify the persistent volume claim was created:
+
 ```
 $ kubectl describe pvc weblogic-sample-pvc
 Name:          weblogic-sample-pvc

kubernetes/samples/scripts/create-weblogic-domain/domain-home-in-image/README.md

@@ -16,7 +16,7 @@ The following prerequisites must be handled prior to running the create domain s
 Make a copy of the `create-domain-inputs.yaml` file, and run the create script, pointing it at your inputs file and an output directory:
 
 ```
-  ./create-domain.sh \
+$ ./create-domain.sh \
   -u <username> \
   -p <password> \
   -i create-domain-inputs.yaml \
@@ -177,7 +177,7 @@ spec:
 To confirm that the domain was created, use this command:
 
 ```
-kubectl describe domain DOMAINUID -n NAMESPACE
+$ kubectl describe domain DOMAINUID -n NAMESPACE
 ```
 
 Replace `DOMAINUID` with the `domainUID` and `NAMESPACE` with the actual namespace.
@@ -312,7 +312,7 @@ In the `Status` section of the output, the available servers and clusters are li
 Use the following command to see the pods running the servers:
 
 ```
-kubectl get pods -n NAMESPACE
+$ kubectl get pods -n NAMESPACE
 ```
 
 Here is an example of the output of this command:
@@ -330,7 +330,7 @@ domain1-managed-server2                      1/1       Running   0          29m
 Use the following command to see the services for the domain:
 
 ```
-kubectl get services -n NAMESPACE
+$ kubectl get services -n NAMESPACE
 ```
 
 Here is an example of the output of this command:

kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/README.md

@@ -8,7 +8,7 @@ Before you begin, read this guide, [Domain Resource](../../../../../site/domain-
 
 The following prerequisites must be handled prior to running the create domain script:
 * Make sure the WebLogic operator is running.
-* The operator requires WebLogic Server 12.2.1.3.0 with patch 28076014 applied. Refer to [Weblogic docker images](../../../../../site/weblogic-docker-images.md) for details on how to create one.
+* The operator requires WebLogic Server 12.2.1.3.0 with patch 28076014 applied. Refer to [WebLogic docker images](../../../../../site/weblogic-docker-images.md) for details on how to create one.
 * Create a Kubernetes namespace for the domain unless the intention is to use the default namespace.
 * In the same Kubernetes namespace, create the Kubernetes persistent volume where the domain home will be hosted, and the Kubernetes persistent volume claim for the domain. For samples to create a PV and PVC, see [Create sample PV and PVC](../../create-weblogic-domain-pv-pvc/README.md).
 * Create the Kubernetes secrets `username` and `password` of the admin account in the same Kubernetes namespace as the domain.
@@ -18,19 +18,19 @@ The following prerequisites must be handled prior to running the create domain s
 Make a copy of the `create-domain-inputs.yaml` file, and run the create script, pointing it at your inputs file and an output directory:
 
 ```
-  ./create-domain.sh \
+$ ./create-domain.sh \
   -i create-domain-inputs.yaml \
   -o /path/to/output-directory
 ```
 
 The script will perform the following steps:
 
-* Create a directory for the generated Kubernetes YAML files for this domain if it does not already exist.  The pathname is `/path/to/weblogic-operator-output-directory/weblogic-domains/<domainUID>`. If the directory already exists, its contents will be removed.
+* Create a directory for the generated Kubernetes YAML files for this domain if it does not already exist.  The pathname is `/path/to/weblogic-operator-output-directory/weblogic-domains/<domainUID>`. If the directory already exists, its contents must be removed before using this script.
 * Create a Kubernetes job that will start up a utility WebLogic Server container and run offline WLST scripts, or WebLogic Deploy Tool (WDT) scripts, to create the domain on the shared storage.
 * Run and wait for the job to finish.
 * Create a Kubernetes domain YAML file, `domain.yaml`, in the directory that is created above. This YAML file can be used to create the Kubernetes resource using the `kubectl create -f` or `kubectl apply -f` command:
 ```
-kubectl apply -f /path/to/output-directory/weblogic-domains/<domainUID>/domain.yaml
+$ kubectl apply -f /path/to/output-directory/weblogic-domains/<domainUID>/domain.yaml
 ```
 
 * Create a convenient utility script, `delete-domain-job.yaml`, to clean up the domain home created by the create script.
@@ -206,7 +206,7 @@ spec:
 To confirm that the domain was created, use this command:
 
 ```
-kubectl describe domain DOMAINUID -n NAMESPACE
+$ kubectl describe domain DOMAINUID -n NAMESPACE
 ```
 
 Replace `DOMAINUID` with the `domainUID` and `NAMESPACE` with the actual namespace.
@@ -321,7 +321,7 @@ In the `Status` section of the output, the available servers and clusters are li
 Use the following command to see the pods running the servers:
 
 ```
-kubectl get pods -n NAMESPACE
+$ kubectl get pods -n NAMESPACE
 ```
 
 Here is an example of the output of this command:
@@ -339,7 +339,7 @@ domain1-managed-server2                      1/1       Running   0          8m
 Use the following command to see the services for the domain:
 
 ```
-kubectl get services -n NAMESPACE
+$ kubectl get services -n NAMESPACE
 ```
 
 Here is an example of the output of this command:

kubernetes/samples/scripts/elasticsearch-and-kibana/README.md

@@ -15,14 +15,14 @@ have them configured.
 
 It runs Elasticstack on the same host and port that the operator's Helm chart defaults
 to, therefore, the customer only needs to set `elkIntegrationEnabled` to `true` in their
-`values.yaml` file.``
+`values.yaml` file.
 
 To install ElasticSearch and Kibana, use:
 ```
-  kubectl apply -f kubernetes/samples/scripts/elasticsearch-and-kibana/elasticsearch_and_kibana.yaml
+$  kubectl apply -f kubernetes/samples/scripts/elasticsearch-and-kibana/elasticsearch_and_kibana.yaml
 ```
 
 To remove them, use:
 ```
-  kubectl delete -f kubernetes/samples/scripts/elasticsearch-and-kibana/elasticsearch_and_kibana.yaml
+$  kubectl delete -f kubernetes/samples/scripts/elasticsearch-and-kibana/elasticsearch_and_kibana.yaml
 ```