Merge pull request #1136 from oracle/cluster-template

Pod templates at the domain, cluster, and server level + New domain resource doc.

Author: rjeberhard

docs-source/content/userguide/managing-domains/domain-resource.md

@@ -8,7 +8,9 @@ pre = "<b> </b>"
 
 
 
-Use this document to set up and configure your own [domain resource](https://github.com/oracle/weblogic-kubernetes-operator/blob/master/docs/domains/Domain.md) which can be used to configure your WLS domain. Then, you can use the domain resource to start the Kubernetes artifacts of the corresponding domain.
+Use this document to set up and configure your own [domain resource](https://github.com/oracle/weblogic-kubernetes-operator/blob/master/docs/domains/Domain.md) which can be used to configure the operation of your WebLogic domain. The domain resource does not replace the traditional configuration of WebLogic domains found in the domain configuration files, but instead cooperates with those files to describe the Kubernetes artifacts of the corresponding domain.  For instance, the WebLogic domain configuration will still specify deployed applications, data sources, and most other details about the domain while the domain resource will specify the number of cluster members currently running or the persistent volumes that will be mounted into the containers running WebLogic Server instances.
+
+Many of the samples accompanying the operator project include scripts to generate an initial domain resource from a set of simplified inputs; however, the domain resource is the actual source of truth for how the WebLogic operator will manage each WebLogic domain.  You are encouraged to either start with the domain resource YAML files generated by the various samples or create domain resources manually or by using other tools based on the schema referenced here or this documentation.
 
 Swagger documentation is available [here](https://oracle.github.io/weblogic-kubernetes-operator/swagger/index.html).
 
@@ -41,3 +43,66 @@ To confirm that the domain resource was created, use this command:
 ```
 $ kubectl describe domain [domain name] -n [namespace]
 ```
+
+#### Domain resource overview
+
+The domain resource, like all [Kubernetes objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/), is described by three sections: `metadata`, `spec`, and `status`.  
+
+The `metadata` section names the domain resource and its namespace.  The name of the domain resource is the default value for the "domain UID" which is used by the operator to distinguish domains running in the Kubernetes cluster that may have the same domain name.  The domain resource name is required to be unique in the namespace and the domain UID should be unique across the cluster.  The domain UID, domain resource name, and domain name (from the WebLogic domain configuration) may all be different.
+
+The `spec` section describes the intended running state of the domain, including intended runtime state of server instances, number of cluster members started, and details about Kubernetes pod or service generation, such as resource constraints, scheduling requirements, or volume mounts.
+
+The `status` section is updated by the operator and describes the actual running state of the domain, including WebLogic Server instance runtime states and current health.
+
+#### Domain resource spec elements
+
+The domain resource `spec` section contains elements for configuring the domain operation and sub-sections specific to the Administration Server, specific clusters or specific Managed Servers.
+
+Elements related to domain identification, Docker image, and domain home:
+* `domainUID`: The domain unique identifier. Must be unique across the Kubernetes cluster. Not required. Defaults to the value of `metadata.name`.
+* `image`: The WebLogic Docker image. Required when `domainHomeInImage` is true; otherwise, defaults to "container-registry.oracle.com/middleware/weblogic:12.2.1.3".
+* `imagePullPolicy`: The image pull policy for the WebLogic Docker image. Legal values are `Always`, `Never` and `IfNotPresent`. Defaults to `Always` if image ends in ":latest", `IfNotPresent` otherwise.
+* `imagePullSecrets`: A list of image pull secrets for the WebLogic Docker image.
+* `domainHome`: The folder for the WebLogic Domain. Not required. Defaults to "/shared/domains/domains/domainUID" if `domainHomeInImage` is false. Defaults to "/u01/oracle/user_projects/domains/" if `domainHomeInImage` is true.
+* `domainHomeInImage`: True if this domain's home is defined in the Docker image for the domain. Defaults to true.
+
+Elements related to logging:
+* `includeServerOutInPodLog`: If true (the default), the server ".out" file will be included in the pod's stdout.
+* `logHome`: The in-pod name of the directory in which to store the domain, Node Manager, server logs, and server ".out" files.
+* `logHomeEnabled`: Specifies whether the log home folder is enabled. Not required. Defaults to true if `domainHomeInImage` is false. Defaults to false if `domainHomeInImage` is true.
+
+Elements related to security:
+* `webLogicCredentialsSecret`: The name of a pre-created Kubernetes secret, in the domain resource's namespace, that holds the user name and password needed to boot WebLogic Server under the 'username' and 'password' fields.
+
+Elements related to domain [startup and shutdown](domain-lifecycle/startup.md):
+* `serverStartPolicy`: The strategy for deciding whether to start a server. Legal values are `ADMIN_ONLY`, `NEVER`, or `IF_NEEDED`.
+* `serverStartState`: The state in which the server is to be started. Use `ADMIN` if server should start in the admin state. Defaults to `RUNNING`.
+* `restartVersion`: If present, every time this value is updated, the operator will restart the required servers.
+* `replicas`: The number of Managed Servers to run in any cluster that does not specify a `replicas` count.
+
+Elements related to overriding WebLogic domain configuration:
+* `configOverrides`: The name of the config map for optional WebLogic configuration overrides.
+* `configOverrideSecrets`: A list of names of the secrets for optional WebLogic configuration overrides.
+
+Elements related to Kubernetes pod and service generation:
+* `serverPod`: Configuration affecting server pods.
+* `serverService`: Customization affecting ClusterIP Kubernetes services for WebLogic Server instances.
+
+Sub-sections related to the Administration Server, specific clusters or specific Managed Servers:
+* `adminServer`: Configuration for the Administration Server.
+* `clusters`: Configuration for specific clusters.
+* `managedServers`: Configuration for specific Managed Servers.
+
+The elements `serverStartPolicy`, `serverStartState`, `serverPod` and `serverService` are repeated under `adminServer` and under each entry of `clusters` or `managedServers`.  The values directly under `spec` set the defaults for the entire domain.  The values under a specific entry under `clusters` set the defaults for cluster members of that cluster.  The values under `adminServer` or an entry under `managedServers` set the values for that specific server.  Values from the domain scope and values from the cluster (for cluster members) are merged with or overridden by the setting for the specific server depending on the element.  See the [startup and shutdown](domain-lifecycle/startup.md) documentation for details about `serverStartPolicy` combination.
+
+### Pod generation
+
+The operator creates a pod for each running WebLogic Server instance.  This pod will have a container based on the Docker image specified by the `image` field.  Additional pod or container content can be specified using the elements under `serverPod`.  This includes Kubernetes labels and annotations, additional volumes on the pod or volume mounts on the container, [resource requirements](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/) or [security context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/).
+
+Prior to creating a pod, the operator replaces variable references allowing the pod content to be templates.  The format of these variable references is `$(VARIABLE_NAME)` where *VARIABLE_NAME* is one of the variable names available in the container for the WebLogic Server instance.  The default set of environment variables includes:
+* DOMAIN_NAME: The WebLogic domain name
+* DOMAIN_UID: The domain unique identifier
+* DOMAIN_HOME: The domain home location as a file system path within the container
+* SERVER_NAME: The WebLogic Server name
+* CLUSTER_NAME: The WebLogic cluster name, if this is a cluster member
+* LOG_HOME: The WebLogic log location as a file system path within the container

integration-tests/USECASES.MD

@@ -144,3 +144,7 @@ Configuration Overrides Usecases
 | Upgrade 2.1 operator to develop | Upgrade the 2.1 operator running a Weblogic domain to develop version of the Operator and verify apiVersion of the domain CRD shows latest version |
 | Upgrade 2.2.0 operator to develop | Upgrade the 2.2.0 operator running a Weblogic domain to develop version of the Operator and verify apiVersion of the domain CRD shows latest version |
 | Upgrade 2.2.1 operator to develop | Upgrade the 2.2.1 operator running a Weblogic domain to develop version of the Operator and verify apiVersion of the domain CRD shows latest version |
+
+| Pod Templates | Use Case |
+| --- | --- |
+| Using pod templates/variables | Use DOMAIN_UID, DOMAIN_NAME, DOMAIN_HOME, SERVER_NAME, LOG_HOME variables at domain level and CLUSTER_NAME at cluster level. Bring up the domain and make sure domain started successfully when pod templates are used |

integration-tests/src/test/java/oracle/kubernetes/operator/BaseTest.java

@@ -14,6 +14,7 @@
 import java.util.logging.SimpleFormatter;
 import javax.jms.Connection;
 import javax.jms.ConnectionFactory;
+
 import oracle.kubernetes.operator.utils.Domain;
 import oracle.kubernetes.operator.utils.ExecCommand;
 import oracle.kubernetes.operator.utils.ExecResult;

integration-tests/src/test/java/oracle/kubernetes/operator/ItElasticLogging.java

@@ -227,12 +227,12 @@ public void testWeblogicLogSearch() throws Exception {
     String testMethodName = new Object() {}.getClass().getEnclosingMethod().getName();
     logTestBegin(testMethodName);
 
-    Map<String, Object> domainMap = domain.getDomainMap();
-    String domainUid = domain.getDomainUid();
-    String adminServerName = (String) domainMap.get("adminServerName");
-    String adminServerPodName = domainUid + "-" + adminServerName;
-    String managedServerNameBase = domainMap.get("managedServerNameBase").toString();
-    String managedServerPodName = domainUid + "-" + managedServerNameBase + "1";
+    final Map<String, Object> domainMap = domain.getDomainMap();
+    final String domainUid = domain.getDomainUid();
+    final String adminServerName = (String) domainMap.get("adminServerName");
+    final String adminServerPodName = domainUid + "-" + adminServerName;
+    final String managedServerNameBase = domainMap.get("managedServerNameBase").toString();
+    final String managedServerPodName = domainUid + "-" + managedServerNameBase + "1";
 
     // Wait 30 seconds for WLS log to be pushed to ELK Stack
     logger.info("Wait 30 seconds for WLS log to be pushed to ELK Stack");

integration-tests/src/test/java/oracle/kubernetes/operator/ItMonitoringExporter.java

@@ -4,17 +4,6 @@
 
 package oracle.kubernetes.operator;
 
-import static org.junit.Assert.assertFalse;
-import static org.junit.Assert.assertNotNull;
-import static org.junit.Assert.assertTrue;
-
-import com.gargoylesoftware.htmlunit.FailingHttpStatusCodeException;
-import com.gargoylesoftware.htmlunit.WebClient;
-import com.gargoylesoftware.htmlunit.html.HtmlFileInput;
-import com.gargoylesoftware.htmlunit.html.HtmlForm;
-import com.gargoylesoftware.htmlunit.html.HtmlPage;
-import com.gargoylesoftware.htmlunit.html.HtmlRadioButtonInput;
-import com.gargoylesoftware.htmlunit.html.HtmlSubmitInput;
 import java.io.File;
 import java.io.IOException;
 import java.nio.charset.Charset;
@@ -26,6 +15,14 @@
 import java.util.Map;
 import java.util.logging.Level;
 import javax.xml.bind.DatatypeConverter;
+
+import com.gargoylesoftware.htmlunit.FailingHttpStatusCodeException;
+import com.gargoylesoftware.htmlunit.WebClient;
+import com.gargoylesoftware.htmlunit.html.HtmlFileInput;
+import com.gargoylesoftware.htmlunit.html.HtmlForm;
+import com.gargoylesoftware.htmlunit.html.HtmlPage;
+import com.gargoylesoftware.htmlunit.html.HtmlRadioButtonInput;
+import com.gargoylesoftware.htmlunit.html.HtmlSubmitInput;
 import oracle.kubernetes.operator.utils.Domain;
 import oracle.kubernetes.operator.utils.ExecCommand;
 import oracle.kubernetes.operator.utils.ExecResult;
@@ -39,6 +36,10 @@
 import org.junit.Test;
 import org.junit.runners.MethodSorters;
 
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
 /** This test is used for testing Monitoring Exporter with Operator(s) . */
 @FixMethodOrder(MethodSorters.NAME_ASCENDING)
 public class ItMonitoringExporter extends BaseTest {
@@ -168,14 +169,14 @@ private static void gitCloneMonitoringExporter() throws Exception {
   }
 
   /**
-   * Build monitoring exporter app
+   * Build monitoring exporter app.
    *
    * @throws Exception if could not run the command successfully to clone from github
    */
   private static void buildMonitoringExporter() throws Exception {
     String monitoringExporterSrcDir = monitoringExporterDir + "/src";
     // target dir for monitoring exporter webapp
-    String monitoringExporterWar =
+    final String monitoringExporterWar =
         monitoringExporterDir + "/apps/monitoringexporter/wls-exporter.war";
 
     // build monitoring exporter project
@@ -797,7 +798,7 @@ public void test18_ChangeConfigEmptyPass() throws Exception {
   }
 
   /**
-   * Test End to End example from MonitoringExporter github project
+   * Test End to End example from MonitoringExporter github project.
    *
    * @throws Exception if test fails
    */
@@ -814,18 +815,18 @@ public void test19_EndToEndViaChart() throws Exception {
       }
       gitCloneMonitoringExporter();
       try {
-        setupPVMYSQL();
+        setupPvMysql();
       } catch (Exception ex) {
         deletePvDir();
         throw new RuntimeException("FAILURE: failed to install database ");
       }
-      createWLSImageAndDeploy();
+      createWlsImageAndDeploy();
       installWebHookAndAlertManager();
       installPrometheusGrafanaViaChart();
       fireAlert();
     } finally {
       uninstallWebHookPrometheusGrafanaViaChart();
-      uninstallMySQL();
+      uninstallMysql();
 
       String crdCmd =
           " kubectl delete -f " + monitoringExporterEndToEndDir + "/demo-domains/domain1.yaml";
@@ -857,7 +858,7 @@ private void fireAlert() throws Exception {
     String command = "kubectl -n webhook logs " + webhookPod;
     ExecResult webhookResult = TestUtils.exec(command);
     logger.info(" webhook log " + webhookResult.stdout());
-    assertTrue( webhookResult.stdout().contains("Some WLS cluster has only one running server for more than 1 minutes"));
+    assertTrue(webhookResult.stdout().contains("Some WLS cluster has only one running server for more than 1 minutes"));
   }
 
   private static String getPodName(String app, String namespace) throws Exception {
@@ -951,11 +952,11 @@ private HtmlPage submitConfigureForm(
 
   /**
    * Remove monitoring exporter directory if exists and clone latest from github for monitoring
-   * exporter code
+   * exporter code.
    *
    * @throws Exception if could not run the command successfully to install database
    */
-  private static void setupPVMYSQL() throws Exception {
+  private static void setupPvMysql() throws Exception {
     String pvDir = monitoringExporterEndToEndDir + "pvDir";
     if (new File(pvDir).exists()) {
       logger.info(" PV dir already exists , cleaning ");
@@ -1041,11 +1042,11 @@ private static void setupPVMYSQL() throws Exception {
   }
 
   /**
-   * Install wls image tool and update wls pods
+   * Install wls image tool and update wls pods.
    *
    * @throws Exception if could not run the command successfully to create WLSImage and deploy
    */
-  private static void createWLSImageAndDeploy() throws Exception {
+  private static void createWlsImageAndDeploy() throws Exception {
     operator1 = TestUtils.createOperator(OPERATOR1_YAML);
 
     String command =
@@ -1085,7 +1086,7 @@ private static void createWLSImageAndDeploy() throws Exception {
   }
 
   /**
-   * Install Prometheus and Grafana using helm chart
+   * Install Prometheus and Grafana using helm chart.
    *
    * @throws Exception if could not run the command successfully to install Prometheus and Grafana
    */
@@ -1111,7 +1112,8 @@ private static void installPrometheusGrafanaViaChart() throws Exception {
     crdCmd = "kubectl apply -f " + monitoringExporterEndToEndDir + "/grafana/persistence.yaml";
     TestUtils.exec(crdCmd);
     crdCmd =
-        "kubectl --namespace monitoring create secret generic grafana-secret --from-literal=username=admin --from-literal=password=12345678";
+        "kubectl --namespace monitoring create secret generic grafana-secret"
+            + " --from-literal=username=admin --from-literal=password=12345678";
     TestUtils.exec(crdCmd);
     logger.info("calling helm install for grafana");
     crdCmd =
@@ -1144,7 +1146,7 @@ private static void installPrometheusGrafanaViaChart() throws Exception {
   }
 
   /**
-   * Install Prometheus and Grafana using helm chart
+   * Install Prometheus and Grafana using helm chart.
    *
    * @throws Exception if could not run the command successfully to install webhook and alert manager
    */
@@ -1167,7 +1169,7 @@ private static void installWebHookAndAlertManager() throws Exception {
   }
 
   /**
-   * Uninstall Prometheus and Grafana using helm chart
+   * Uninstall Prometheus and Grafana using helm chart.
    *
    * @throws Exception if could not run the command successfully to uninstall deployments
    */
@@ -1204,11 +1206,11 @@ private static void uninstallWebHookPrometheusGrafanaViaChart() throws Exception
   }
 
   /**
-   * Unnstall MYSQL
+   * Uninstall MYSQL.
    *
    * @throws Exception if could not run the command successfully to uninstall MySQL
    */
-  private static void uninstallMySQL() throws Exception {
+  private static void uninstallMysql() throws Exception {
     String monitoringExporterEndToEndDir =
         monitoringExporterDir + "/src/samples/kubernetes/end2end/";
     // unnstall mysql
@@ -1223,7 +1225,7 @@ private static void uninstallMySQL() throws Exception {
   }
 
   /**
-   * Delete PvDir via docker
+   * Delete PvDir via docker.
    *
    * @throws Exception if could not run the command successfully to delete PV
    */
@@ -1243,7 +1245,7 @@ private static void deletePvDir() throws Exception {
   }
 
   /**
-   * A utility method to sed files
+   * A utility method to sed files.
    *
    * @throws IOException when copying files from source location to staging area fails
    */
@@ -1259,28 +1261,7 @@ private static void replaceStringInFile(String filePath, String oldValue, String
   }
 
   /**
-   * A utility method to copy Cross Namespaces RBAC yaml template file replacing the DOMAIN_NS,
-   * OPERATOR_NS
-   *
-   * @throws IOException when copying files from source location to staging area fails
-   */
-  private static void createCrossNSRBACFile(String domainNS, String operatorNS) throws IOException {
-    String samplesDir = monitoringExporterDir + "/src/samples/kubernetes/deployments/";
-    Path src = Paths.get(samplesDir + "/crossnsrbac.yaml");
-    Path dst = Paths.get(samplesDir + "/crossnsrbac_" + domainNS + "_" + operatorNS + ".yaml");
-    if (!dst.toFile().exists()) {
-      logger.log(Level.INFO, "Copying {0}", src.toString());
-      Charset charset = StandardCharsets.UTF_8;
-      String content = new String(Files.readAllBytes(src), charset);
-      content = content.replaceAll("weblogic-domain", domainNS);
-      content = content.replaceAll("weblogic-operator", operatorNS);
-      logger.log(Level.INFO, "to {0}", dst.toString());
-      Files.write(dst, content.getBytes(charset));
-    }
-  }
-
-  /**
-   * call operator to scale to specified number of replicas
+   * call operator to scale to specified number of replicas.
    *
    * @param replicas - number of managed servers
    * @throws Exception if scaling fails