Merge pull request #742 from oracle/quickstart-sample-updates

Quickstart doc and sample updates (based on internal early accepters experience)

Author: rjeberhard

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

@@ -30,9 +30,10 @@ The script will perform the following steps:
 * Clone the weblogic docker-images project into the current directory using `git clone https://github.com/oracle/docker-images.git`.
 * Replace the built-in user name and password in the `properties/docker-build/domain_security.properties` file with the `username` and `password` that are supplied on the command line using the `-u` and `-p` options. These credentials need to match the WebLogic domain admin credentials in the secret that is specified via the `weblogicCredentialsSecretName` property in the `create-domain-inputs.yaml` file.
 * Build a Docker image based on the Docker sample, [Example Image with a WebLogic Server Domain using the Oracle WebLogic Deploy Tooling (WDT)](https://github.com/oracle/docker-images/tree/master/OracleWebLogic/samples/12213-domain-home-in-image-wdt) and [Example Image with a WebLogic Server Domain using WLST](https://github.com/oracle/docker-images/tree/master/OracleWebLogic/samples/12213-domain-home-in-image). It will create a sample WebLogic Server domain in the Docker image. Also, you can run the Docker sample, [Example Image with a WebLogic Server Domain](https://github.com/oracle/docker-images/tree/master/OracleWebLogic/samples/12213-domain-home-in-image), manually with the generated `domain.properties` to create a domain home image. **Note**: Oracle recommends keeping the domain home image private in the local repository.
+* Create a tag that refers to the generated Docker image.
 * 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
 ```
 
 As a convenience, using the `-e` option, the script can optionally create the domain object, which in turn results in the creation of the corresponding WebLogic Server pods and services. This option should only be used in a single node Kubernetes cluster.
@@ -60,12 +61,21 @@ If you copy the sample scripts to a different location, make sure that you copy
 The default domain created by the script has the following characteristics:
 
 * An Administration Server named `admin-server` listening on port `7001`.
-* A dynamic cluster named `cluster-1` of size 2.
+* A dynamic cluster named `cluster-1` of size 5.
 * Two Managed Servers, named `managed-server1` and `managed-server2`, listening on port `8001`.
 * No applications deployed.
-* A Derby data source.
 * A T3 channel.
 
+If you run the sample from a machine that is remote to the Kubernetes cluster, and you need to push the new image to a registry that is local to the cluster, you need to do the following (also see the `image` property in the table in the next section):
+* Set the `image` property in the inputs file to the target image name (including the registry hostname/port and the tag if needed).
+* Run the `create-domain.sh` script without the `-e` option.
+* Push the `image` to the target registry.
+* Run the following command to create the domain.
+
+```
+$ kubectl apply -f /path/to/output-directory/weblogic-domains/<domainUID>/domain.yaml
+```
+
 The domain creation inputs can be customized by editing `create-domain-inputs.yaml`.
 
 ### Configuration parameters
@@ -84,7 +94,7 @@ The following parameters can be provided in the inputs file.
 | `domainUID` | Unique ID that will be used to identify this particular domain. Used as the name of the generated WebLogic domain as well as the name of the Kubernetes domain resource. This ID must be unique across all domains in a Kubernetes cluster. This ID cannot contain any character that is not valid in a Kubernetes service name. | `domain1` |
 | `exposeAdminNodePort` | Boolean indicating if the Administration Server is exposed outside of the Kubernetes cluster. | `false` |
 | `exposeAdminT3Channel` | Boolean indicating if the T3 administrative channel is exposed outside the Kubernetes cluster. | `false` |
-| `image` | WebLogic Docker image that the domain resource will pull if needed. You only need to specify this if you are going to push the generated image from the local Docker repository to another Docker repository. If not specified, the sample uses the internally generated image name, either "domain-home-in-image:latest" or "domain-home-in-image-wdt:latest". | |
+| `image` | WebLogic Docker image that the domain resource will pull if needed. You only need to specify this if you are going to tag the generated image to a different name. If you run the sample script from a machine that is remote to the Kubernetes cluster, you need to specify this to point to an image in a registry local to the cluster, and then push the generate image to that registry before starting the domain. If not specified, the sample uses the internally generated image name, either "domain-home-in-image:latest" or "domain-home-in-image-wdt:latest". | |
 | `imagePullPolicy` | WebLogic Docker image pull policy. Legal values are "IfNotPresent", "Always", or "Never" | `IfNotPresent` |
 | `imagePullSecretName` | Name of the Kubernetes secret to access the Docker Store to pull the WebLogic Server Docker image. The presence of the secret will be validated when this parameter is specified |  |
 | `includeServerOutInPodLog` | Boolean indicating whether to include server .out to the pod's stdout. | `true` |

kubernetes/samples/scripts/create-weblogic-domain/domain-home-in-image/create-domain-inputs.yaml

@@ -11,7 +11,8 @@ adminPort: 7001
 adminServerName: admin-server
 
 # Unique ID identifying a domain.
-# This ID must not contain an underscope ("_"), and must be lowercase and unique across all domains in a Kubernetes cluster.
+# This ID must not contain an underscope ("_"), and must be lowercase and unique across all domains 
+# in a Kubernetes cluster.
 domainUID: domain1
 
 # Type of WebLogic Cluster
@@ -41,11 +42,18 @@ managedServerPort: 8001
 productionModeEnabled: true
 
 # WebLogic Docker image that the domain resource will pull if needed.
-# You only need to specify this if you are going to push the generated image from the local Docker repository
-# to another Docker repository.
-# If not specified, the sample uses the internally generated image name, either "domain-home-in-image:latest"
-# or "domain-home-in-image-wdt:latest".
-# image: 
+#
+# You only need to specify this if you want to tag the generated image to a different name.
+#
+# If you are running the sample script from a machine that is remote to the Kubernetes cluster,
+# you need to specify this to point to an image in a registry local to the cluster. You
+# then need to push the generate image to that registry before starting the domain.
+#
+# If not specified, the sample uses the internally generated image name, 
+# either "domain-home-in-image-wdt:latest" or "domain-home-in-image-wlst:latest".
+#
+# See README.md for more help.
+#image: 
 
 # Image pull policy
 # Legal values are "IfNotPresent", "Always", or "Never"
@@ -89,13 +97,14 @@ namespace: default
 javaOptions: -Dweblogic.StdoutDebugEnabled=false
 
 # Base WebLogic binary image used to build the WebLogic domain image
-# The operator requires WebLogic Server 12.2.1.3.0 with patch 28076014 applied. See README.md for more help.
-# domainHomeImageBase: 
+# The operator requires WebLogic Server 12.2.1.3.0 with patch 28076014 applied. 
+# See README.md for more help.
+#domainHomeImageBase: 
 
 # Location of the WebLogic "domain home in image" Docker image sample in the 
 # `https://github.com/oracle/docker-images.git` project.
 # If not specified, use "./docker-images/OracleWebLogic/samples/12213-domain-home-in-image-wdt".
-# Another possible value is "./docker-images/OracleWebLogic/samples/12213-domain-home-in-image" which 
-# uses WLST script, instead of WDT, to generate the domain configuration.
+# Another possible value is "./docker-images/OracleWebLogic/samples/12213-domain-home-in-image",
+# which uses a WLST script, instead of WDT, to generate the domain configuration.
 domainHomeImageBuildPath: ./docker-images/OracleWebLogic/samples/12213-domain-home-in-image-wdt
 

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

@@ -289,6 +289,8 @@ function createDomainHome {
   # if use the default images, we tag it to a more generic name (without the release version numbers)
   if [ -z $image ]; then
     docker tag $imageNameOrigin:latest $imageName:latest
+  else
+    docker tag $imageNameOrigin:latest $image
   fi
 
   if [ "$?" != "0" ]; then

kubernetes/samples/scripts/create-weblogic-domain/domain-home-in-image/properties-template.properties

@@ -15,14 +15,3 @@ CLUSTER_TYPE=%CLUSTER_TYPE%
 JAVA_OPTIONS=%JAVA_OPTIONS%
 T3_CHANNEL_PORT=%T3_CHANNEL_PORT%
 T3_PUBLIC_ADDRESS=%T3_PUBLIC_ADDRESS%
-#Derby Data Source parameters
-dsname=DockerDS
-dsdbname=DerbyDB;create=true
-dsjndiname=/DockerDS
-dsdriver=org.apache.derby.jdbc.ClientXADataSource
-dsurl=jdbc:derby://localhost:1527/DerbyDB;ServerName=localhost;databaseName=DerbyDB;create=true
-dsusername=dbuser
-dspassword=dbpassword
-dstestquery=SQL SELECT 1 FROM SYS.SYSTABLES
-dsinitalcapacity=0
-dsmaxcapacity=15

site/quickstart.md

@@ -162,7 +162,9 @@ domain namespace (`sample-domain1-ns`) and the `domainHomeImageBase` (`oracle/we
 
 * Setting `weblogicCredentialsSecretName` to the name of the secret containing the WebLogic credentials.
   By convention, the secret will be named`domainUID-weblogic-credentials` (where `domainUID` is replaced with the
-  actual `domainUID` value).
+  actual `domainUID` value). 
+
+* Leaving the `image` empty unless you need to tag the new image that the script builds to a different name.
 
 For example, assuming you named your copy `my-inputs.yaml`:
 ```
@@ -175,6 +177,16 @@ respectively, as shown in the example.  If you specify the `-e` option, the scri
 Kubernetes YAML files *and* apply them to your cluster.  If you omit the `-e` option, the
 script will just generate the YAML files, but will not take any action on your cluster.
 
+If you run the sample from a machine that is remote to the Kubernetes cluster, and you need to push the new image to a registry that is local to the cluster, you need to do the following:
+* Set the `image` property in the inputs file to the target image name (including the registry hostname/port, and the tag if needed).
+* Run the `create-domain.sh` script without the `-e` option.
+* Push the `image` to the registry.
+* Run the following command to create the domain.
+
+```
+$ kubectl apply -f /some/output/directory/weblogic-domains/sample-domain1/domain.yaml
+```
+
 c.	Confirm that the operator started the servers for the domain:
 * Use `kubectl` to show that the domain resource was created:
 ```