Merge branch '2.0-rc2' of https://github.com/oracle/weblogic-kubernetes-operator into rc2-doc-updates

markxnelson · markxnelson · commit d42ece8b4d0b · 2019-01-12T16:47:12.000-05:00
diff --git a/kubernetes/charts/weblogic-operator/values.yaml b/kubernetes/charts/weblogic-operator/values.yaml
@@ -20,7 +20,7 @@ domainNamespaces:
   - "default"
 
 # image specifies the docker image containing the operator code.
-image: "weblogic-kubernetes-operator:2.0"
+image: "oracle/weblogic-kubernetes-operator:2.0"
 
 # imagePullPolicy specifies the image pull policy for the operator docker image.
 imagePullPolicy: "IfNotPresent"
diff --git a/kubernetes/samples/scripts/common/domain-template.yaml b/kubernetes/samples/scripts/common/domain-template.yaml
@@ -30,12 +30,9 @@ spec:
     name: %WEBLOGIC_CREDENTIALS_SECRET_NAME%
   # Whether to include the server out file into the pod's stdout, default is true
   includeServerOutInPodLog: %INCLUDE_SERVER_OUT_IN_POD_LOG%
-  # Whether to enable log home 
+  # Whether to enable log home
   %LOG_HOME_ON_PV_PREFIX%logHomeEnabled: %LOG_HOME_ENABLED%
-  # The in-pod name of the directory to store the domain, node manager, server logs, and server .out
-  # files in.
-  # If not specified or empty, domain log file, server logs, server out, and node manager log files 
-  # will be stored in the default logHome location of /shared/logs/<domainUID>/.
+  # The in-pod location for domain log, server logs, server out, and node manager log files
   %LOG_HOME_ON_PV_PREFIX%logHome: %LOG_HOME%
   # serverStartPolicy legal values are "NEVER", "IF_NEEDED", or "ADMIN_ONLY"
   # This determines which WebLogic Servers the Operator will start up when it discovers this Domain
diff --git a/kubernetes/samples/scripts/common/validate.sh b/kubernetes/samples/scripts/common/validate.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Copyright 2018, Oracle Corporation and/or its affiliates.  All rights reserved.
+# Copyright 2018, 2019, Oracle Corporation and/or its affiliates.  All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at http://oss.oracle.com/licenses/upl.
 #
 # Description
diff --git a/kubernetes/samples/scripts/create-weblogic-domain/domain-home-in-image/README.md b/kubernetes/samples/scripts/create-weblogic-domain/domain-home-in-image/README.md
diff --git a/kubernetes/samples/scripts/create-weblogic-domain/domain-home-in-image/create-domain-inputs.yaml b/kubernetes/samples/scripts/create-weblogic-domain/domain-home-in-image/create-domain-inputs.yaml
@@ -1,4 +1,4 @@
-# Copyright 2018, Oracle Corporation and/or its affiliates.  All rights reserved.
+# Copyright 2018, 2019, Oracle Corporation and/or its affiliates.  All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at http://oss.oracle.com/licenses/upl.
 
 # The version of this inputs file.  Do not modify.
@@ -74,8 +74,7 @@ includeServerOutInPodLog: true
 # The default is false.
 logHomeOnPV: false
 
-# The in-pod name of the directory in which to store the domain, node manager, server logs,
-# and server .out files.
+# The in-pod location for domain log, server logs, server out, and node manager log files
 # If not specified, the value is derived from the domainUID as /shared/logs/<domainUID>
 # This parameter is required if 'logHomeOnPV' is true.
 # Otherwise, it is ignored.
diff --git a/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/README.md b/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/README.md
diff --git a/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/create-domain-inputs.yaml b/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/create-domain-inputs.yaml
@@ -1,4 +1,4 @@
-# Copyright 2018, Oracle Corporation and/or its affiliates.  All rights reserved.
+# Copyright 2018, 2019, Oracle Corporation and/or its affiliates.  All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at http://oss.oracle.com/licenses/upl.
 
 # The version of this inputs file.  Do not modify.
@@ -61,8 +61,7 @@ weblogicCredentialsSecretName: domain1-weblogic-credentials
 # The default is true.
 includeServerOutInPodLog: true
 
-# The in-pod name of the directory to store the domain, node manager, server logs, and server .out
-# files in.
+# The in-pod location for domain log, server logs, server out, and node manager log files
 # If not specified, the value is derived from the domainUID as /shared/logs/<domainUID>
 logHome: /shared/logs/domain1
 
@@ -97,14 +96,37 @@ persistentVolumeClaimName: domain1-weblogic-sample-pvc
 # Mount path of the domain persistent volume. 
 domainPVMountPath: /shared
 
-# Mount path of the directory where the create domain scripts are located inside the pod
+# Mount path where the create domain scripts are located inside a pod
+#
+# The `create-domain.sh` script creates a Kubernetes job to run the script (specified in the
+# `createDomainScriptName` property) in a Kubernetes pod to create a WebLogic home. Files
+# in the `createDomainFilesDir` directory are mounted to this location in the pod, so that
+# a Kubernetes pod can use the scripts and supporting files to create a domain home.
 createDomainScriptsMountPath: /u01/weblogic
 
-# Script that creates the domain. 
+# Script that the create domain script uses to create a WebLogic domain
+#
+# The `create-domain.sh` script creates a Kubernetes job to run this script to create a
+# domain home. The script is located in the in-pod directory that is specified in the
+# `createDomainScriptsMountPath` property.
+#
+# If you need to provide your own scripts to create the domain home, instead of using the 
+# built-it scripts, you must use this property to set the name of the script that you want
+# the create domain job to run.
 createDomainScriptName: create-domain-job.sh
 
-# Directory to get all the create domain scripts and supporting files, including 
-# the script that is specified by the createDomainScriptName property.
-# The default is the "wlst" subdirectory under the directory where the 
-# create-domain.sh script is located.
+# Directory on the host machine to locate all the files to create a WebLogic domain
+# It contains the script that is specified in the `createDomainScriptName` property.
+#
+# By default, this directory is set to the relative path `wlst`, and the create script will
+# use the built-in WLST offline scripts in the `wlst` directory to create the WebLogic domain.
+# It can also be set to the relative path `wdt`, and then the built-in WDT scripts will be
+# used instead.
+# 
+# An absolute path is also supported to point to an arbitrary directory in the file system.
+#
+# The built-in scripts can be replaced by the user-provided scripts or model files as long
+# as those files are in the specified directory. Files in this directory are put into a
+# Kubernetes config map, which in turn is mounted to the `createDomainScriptsMountPath`,
+# so that the Kubernetes pod can use the scripts and supporting files to create a domain home.
 createDomainFilesDir: wlst
diff --git a/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/create-domain-job-template.yaml b/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/create-domain-job-template.yaml
@@ -1,4 +1,4 @@
-# Copyright 2018, Oracle Corporation and/or its affiliates.  All rights reserved.
+# Copyright 2018, 2019, Oracle Corporation and/or its affiliates.  All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at http://oss.oracle.com/licenses/upl.
 apiVersion: batch/v1
 kind: Job
diff --git a/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/wdt/prepare.sh b/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/wdt/prepare.sh
@@ -1,5 +1,5 @@
 #!/bin/bash
-# Copyright 2018, Oracle Corporation and/or its affiliates.  All rights reserved.
+# Copyright 2018, 2019, Oracle Corporation and/or its affiliates.  All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at http://oss.oracle.com/licenses/upl.
 #
 
diff --git a/kubernetes/src/test/java/oracle/kubernetes/operator/helm/HelmOperatorValuesTest.java b/kubernetes/src/test/java/oracle/kubernetes/operator/helm/HelmOperatorValuesTest.java
@@ -476,7 +476,7 @@ private String getExpectedOperatorHelmChartDefaultValues() {
         .append("externalDebugHttpPort: 30999\n")
         .append("externalRestEnabled: false\n")
         .append("externalRestHttpsPort: 31001\n")
-        .append("image: weblogic-kubernetes-operator:2.0\n")
+        .append("image: oracle/weblogic-kubernetes-operator:2.0\n")
         .append("imagePullPolicy: IfNotPresent\n")
         .append("internalDebugHttpPort: 30999\n")
         .append("javaLoggingLevel: INFO\n")
diff --git a/site/config-overrides.md b/site/config-overrides.md
@@ -7,6 +7,9 @@
 * [Typical overrides](#typical-overrides)
 * [Unsupported overrides](#unsupported-overrides)
 * [Override template names and syntax](#override-template-names-and-syntax)
+  * [Override template names](#override-template-names)
+  * [Override template macros](#override-template-macros)
+  * [Override template samples](#override-template-samples)
 * [Step-by-step guide](#step-by-step-guide)
 * [Debugging](#debugging)
 * [Internal design flow](#internal-design-flow)
@@ -18,43 +21,33 @@
 
 Use configuration overrides (also called _situational configuration_) to customize a WebLogic domain home configuration without modifying the domain's actual `config.xml` or system resource files. For example, you may want to override a JDBC datasource XML module user name, password, and URL so that it references a local database.
 
+You can use overrides to customize domains as they are moved from QA to production, are deployed to different sites, or are even deployed multiple times at the same site.
+
 ## How do you specify overrides?
+
+* Make sure your domain home meets the prerequisites. See [Prerequisites](#prerequisites).
+* Make sure your overrides are supported. See [Typical overrides](#typical-overrides) and [Unsupported overrides](#unsupported-overrides).
 * Create a Kubernetes configuration map that contains:
-  * Override templates (also known as situational configuration templates).
+  * Override templates (also known as situational configuration templates), with names and syntax as described in [Override template names and syntax](#override-template-names-and-syntax).
   * A file named `version.txt` that contains the string `2.0`.
 * Set your domain resource `configOverrides` to the name of this configuration map.
 * Create Kubernetes secrets that contain template macro values.
-* Set your domain `configOverrideSecrets` to reference the aforementioned secrets. See the example below.
-* Start or restart your domain.
+* Set your domain `configOverrideSecrets` to reference the aforementioned secrets.
+* Stop all running WebLogic Server pods in your domain. (See [Server Lifecycle](server-lifecycle.md).)
+* Start or restart your domain. (See [Server Lifecycle](server-lifecycle.md).)
 
-Example:
-```
-apiVersion: "weblogic.oracle/v2"
-kind: Domain
-metadata:
-  name: domain1
-  namespace: default
-  labels:
-    weblogic.resourceVersion: domain-v2
-    weblogic.domainUID: domain1
-spec:
-  [ ... ]
-  webLogicCredentialsSecret:
-    name: domain1-wl-credentials-secret
-  configOverrides: domain1-overrides-config-map
-  configOverrideSecrets: [domain1-overrides-db1-secret, domain1-config-jms1-secret]
-  [ ... ]
-```
+For a detailed walk-through of these steps, see the [Step-by-step guide](#step-by-step-guide).
 
 ## How do overrides work during runtime?
-* When a domain is first deployed, or is restarted, the operator will:
+
+* When a domain is first deployed, or is restarted after shutting down all the WebLogic Server pods, the operator will:
   * Resolve any macros in your override templates.
   * Place expanded override templates in the `optconfig` directory located in each WebLogic domain home directory.  
 * When the WebLogic Servers start, they will:
   * Automatically load the override files from the `optconfig` directory.
   * Use the override values in the override files instead of the values specified in their `config.xml` or system resource XML files.
 
-You can use overrides to customize domains as they are moved from QA to production, are deployed to different sites, or are even deployed multiple times at the same site.
+For a detailed walk-through of the runtime flow, see the [Internal design flow](#internal-design-flow).
 
 ---
 # Prerequisites
@@ -178,7 +171,7 @@ Two types of macros are supported `environment variable macros` and `secret macr
 
 * Secret macros have the syntax `${secret:SECRETNAME.SECRETKEY}` and `${secret:SECRETNAME.SECRETKEY:encrypt}`.
 
-The secret macro `SECRETNAME` field must reference the name of a Kubernetes secret, and the `SECRETKEY` field must reference a key within that secret. For example, if you have created a secret named `dbuser` with a key named `username` that contains the value `scott`, then the macro `${secret:dbuser.username}` will be replaced with the word `scott` before the template is copied into its WebLogic server pod.
+The secret macro `SECRETNAME` field must reference the name of a Kubernetes secret, and the `SECRETKEY` field must reference a key within that secret. For example, if you have created a secret named `dbuser` with a key named `username` that contains the value `scott`, then the macro `${secret:dbuser.username}` will be replaced with the word `scott` before the template is copied into its WebLogic Server pod.
 
 **SECURITY NOTE: Use the `:encrypt` suffix in a secret macro to encrypt its replacement value with the WebLogic WLST `encrypt` command (instead of leaving it at its plain text value).  This is useful for overriding MBean attributes that expect encrypted values, such as the `password-encrypted` field of a data source, and is also useful for ensuring that a custom override situational configuration file the operator places in the domain home does not expose passwords in plain-text.**
 
@@ -237,6 +230,8 @@ The following `jdbc-testDS.xml` override template demonstrates setting the URL,
 ---
 # Step-by-step guide
 
+* Make sure your domain home meets the prerequisites. See [Prerequisites](#prerequisites).
+* Make sure your overrides are supported. See [Typical overrides](#typical-overrides) and [Unsupported overrides](#unsupported-overrides).
 * Create a directory containing (A) a set of situational configuration templates for overriding the MBean properties you want to replace and (B) a `version.txt` file.
   * This directory must not contain any other files.
   * The `version.txt` file must contain only the string `2.0`.
@@ -264,8 +259,34 @@ The following `jdbc-testDS.xml` override template demonstrates setting the URL,
 * Configure the names of each secret in domain CR.
   * If the secret contains the WebLogic admin `username` and `password` keys, set the domain CR `webLogicCredentialsSecret` field.
   * For all other secrets, add them to domain CR `configOverrideSecrets` field.
+* Stop all running WebLogic Server pods in your domain.  (See [Server Lifecycle](server-lifecycle.md).)
+* Start or restart your domain. (See [Server Lifecycle](server-lifecycle.md).)
 * See [Debugging](#debugging) for ways to check if the situational configuration is taking effect or if there are errors.
 
+**IMPORTANT: Custom override changes, such as updating an override configuration map, a secret, or a domain resource, will not take effect until all running WebLogic Server pods in your domain are shutdown (so no servers are left running), and the domain is subsequently restarted.**
+
+**IMPORTANT: Incorrectly formatted override files are 'somewhat' silently ignored. WebLogic Servers log errors or warnings when they detect an incorrectly formatted configuration override template file, but will still boot, and will skip overriding. So it is important to make sure that the template files are correct in a QA environment by checking your WebLogic pod logs for situational configuration errors and warnings, before attempting to use them in production.**
+
+
+Example domain resource yaml:
+```
+apiVersion: "weblogic.oracle/v2"
+kind: Domain
+metadata:
+  name: domain1
+  namespace: default
+  labels:
+    weblogic.resourceVersion: domain-v2
+    weblogic.domainUID: domain1
+spec:
+  [ ... ]
+  webLogicCredentialsSecret:
+    name: domain1-wl-credentials-secret
+  configOverrides: domain1-overrides-config-map
+  configOverrideSecrets: [my-secret, my-other-secret]
+  [ ... ]
+```
+
 ---
 # Debugging
 
@@ -307,9 +328,9 @@ The following `jdbc-testDS.xml` override template demonstrates setting the URL,
 -Dweblogic.debug.DebugSituationalConfigDumpXml=true
 ```
 
-**IMPORTANT: Custom override changes, such as updating an override configuration map, a secret, or a domain resource, will not take effect until your domain is restarted.**
+**IMPORTANT: Custom override changes, such as updating an override configuration map, a secret, or a domain resource, will not take effect until all running WebLogic Server pods in your domain are shutdown (so no servers are left running), and the domain is subsequently restarted.**
 
-**IMPORTANT: Incorrectly formatted override files are 'somewhat' silently ignored. WebLogic Servers log errors or warnings, but will still boot, and will skip overriding, when they detect an incorrectly formatted configuration override template file. So it is important to make sure template files are correct in a QA environment by checking your WebLogic pod logs for situational configuration errors and warnings, before attempting to use them in production.**
+**IMPORTANT: Incorrectly formatted override files are 'somewhat' silently ignored. WebLogic Servers log errors or warnings when they detect an incorrectly formatted configuration override template file, but will still boot, and will skip overriding. So it is important to make sure that the template files are correct in a QA environment by checking your WebLogic pod logs for situational configuration errors and warnings, before attempting to use them in production.**
 
 ---
 # Internal design flow
diff --git a/site/helm-charts.md b/site/helm-charts.md
@@ -16,24 +16,24 @@ The WebLogic Kubernetes Operator uses Helm to create and deploy any necessary re
 
 Helm has two parts: a client (Helm) and a server (Tiller). Tiller runs inside of your Kubernetes cluster, and manages releases (installations) of your charts.  See https://github.com/kubernetes/helm/blob/master/docs/install.md for detailed instructions on installing Helm and Tiller.
 
-In order to use Helm to install and manage the operator, you need to ensure that the Service Account that Tiller uses
-has the `cluster-admin` role.  The default would be `default` in namespace `kube-system`.  You can give that Service
-Account the necessary permissions with this command:
+In order to use Helm to install and manage the operator, you need to ensure that the service account that Tiller uses
+has the `cluster-admin` role.  The default would be `default` in namespace `kube-system`.  You can give that service
+account the necessary permissions with this command:
 
 ```
 cat << EOF | kubectl apply -f -
-apiVersion: rbac.authorization.k8s.io/v1beta1
+apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRoleBinding
 metadata:
-  name: tiller-cluster-admin
+  name: helm-user-cluster-admin-role
 roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
   name: cluster-admin
 subjects:
 - kind: ServiceAccount
   name: default
   namespace: kube-system
-userNames:
-- system:serviceaccount:kube-system:default
 EOF
 ```
 
@@ -119,7 +119,7 @@ or:
 ```
 $ helm install kubernetes/charts/weblogic-operator \
   --name weblogic-operator --namespace weblogic-operator-namespace \
-  --set "javaLoggingLevel:FINE" --wait
+  --set "javaLoggingLevel=FINE" --wait
 ```
 
 This creates a Helm release, named `weblogic-operator` in the `weblogic-operator-namespace` namespace, and configures a deployment and supporting resources for the operator.
@@ -179,7 +179,7 @@ Change one or more values in the operator Helm release. In this example, the `--
 $ helm upgrade \
   --reuse-values \
   --set "domainNamespaces={sample-domains-ns1}" \
-  --set "javaLoggingLevel:FINE" \
+  --set "javaLoggingLevel=FINE" \
   --wait \
   weblogic-operator \
   kubernetes/charts/weblogic-operator
diff --git a/site/quickstart.md b/site/quickstart.md

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`#!/usr/bin/env bash`
`2`		`-# Copyright 2018, Oracle Corporation and/or its affiliates. All rights reserved.`
	`2`	`+# Copyright 2018, 2019, Oracle Corporation and/or its affiliates. All rights reserved.`
`3`	`3`	`# Licensed under the Universal Permissive License v 1.0 as shown at http://oss.oracle.com/licenses/upl.`
`4`	`4`	`#`
`5`	`5`	`# Description`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Copyright 2018, Oracle Corporation and/or its affiliates. All rights reserved.`
	`1`	`+# Copyright 2018, 2019, Oracle Corporation and/or its affiliates. All rights reserved.`
`2`	`2`	`# Licensed under the Universal Permissive License v 1.0 as shown at http://oss.oracle.com/licenses/upl.`
`3`	`3`	`apiVersion: batch/v1`
`4`	`4`	`kind: Job`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`#!/bin/bash`
`2`		`-# Copyright 2018, Oracle Corporation and/or its affiliates. All rights reserved.`
	`2`	`+# Copyright 2018, 2019, Oracle Corporation and/or its affiliates. All rights reserved.`
`3`	`3`	`# Licensed under the Universal Permissive License v 1.0 as shown at http://oss.oracle.com/licenses/upl.`
`4`	`4`	`#`
`5`	`5`