Merge remote-tracking branch 'origin/develop' into thirdparty-dependencies

rjeberhard · rjeberhard · commit ec1a6fdd74b7 · 2018-12-12T12:19:28.000-05:00
diff --git a/README.md b/README.md
@@ -6,132 +6,53 @@ Built with [Wercker](http://www.wercker.com)
 
 Oracle is finding ways for organizations using WebLogic Server to run important workloads, to move those workloads into the cloud. By certifying on industry standards, such as Docker and Kubernetes, WebLogic now runs in a cloud neutral infrastructure. In addition, we've provided an open-source Oracle WebLogic Server Kubernetes Operator (the “operator”) which has several key features to assist you with deploying and managing WebLogic domains in a Kubernetes environment. You can:
 
-*	Create WebLogic domains on a Kubernetes persistent volume. This persistent volume can reside in an NFS.
+* Create WebLogic domains in a Kubernetes persistent volume. This persistent volume can reside in an NFS file system or other Kubernetes volume types.
 * Create a WebLogic domain in a Docker image.
 * Override certain aspects of the WebLogic domain configuration.
-*	Define WebLogic domains as a Kubernetes resource (using a Kubernetes custom resource definition).
-*	Start servers based on declarative startup parameters and desired states.
+* Define WebLogic domains as a Kubernetes resource (using a Kubernetes custom resource definition).
+* Start servers based on declarative startup parameters and desired states.
 * Manage WebLogic configured or dynamic clusters.
-*	Expose the WebLogic Server Administration Console outside the Kubernetes cluster, if desired.
-*	Expose T3 channels outside the Kubernetes domain, if desired.
-*	Expose HTTP paths on a WebLogic domain outside the Kubernetes domain with load balancing and update the load balancer when Managed Servers in the WebLogic domain are started or stopped.
+* Expose the WebLogic Server Administration Console outside the Kubernetes cluster, if desired.
+* Expose T3 channels outside the Kubernetes domain, if desired.
+* Expose HTTP paths on a WebLogic domain outside the Kubernetes domain with load balancing and update the load balancer when Managed Servers in the WebLogic domain are started or stopped.
 * Scale WebLogic domains by starting and stopping Managed Servers on demand, or by integrating with a REST API to initiate scaling based on WLDF, Prometheus, Grafana, or other rules.
 * Publish operator and WebLogic Server logs into Elasticsearch and interact with them in Kibana.
 
 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, or try out the [samples](kubernetes/samples/README.md).
 
+# About this documentation
 
-# Important terms
+This documentation includes sections aimed at different audiences.  To help you find what you are looking for more easily, 
+please consult this table of contents:
 
-This documentation uses several important terms which are intended to have a specific meaning.
+* The [Quick start guide](site/quickstart.md) explains how to just get the operator running quickly, using all the defaults, nothing special.
+* The [User guide](site/user-guide.md) contains detailed information for users of the operator, including how to install and configure it, 
+  and how to use it to create and manage WebLogic domains.  
+* Our [samples](#samples) provide detailed example code and instructions that show you how to perform 
+  various tasks related to the operator.
+* The [Developer guide](site/developer.md) provides details for people who want to understand how the operator is built, tested, and so on,
+  and those who wish to contribute to the operator code will find useful information here.  This section also includes
+  API documentation (JavaDoc) and Swagger/OpenAPI documentation for the REST APIs.
+* The [Contributing](#contributing-to-the-operator) section provides information about conribution requirements.
 
-|Term	| Definition |
-| --- | --- |
-| Cluster	| Because this term is ambiguous, it will be prefixed to indicate which type of cluster is meant.  A WebLogic cluster is a group of Managed Servers that together host some application or component and which are able to share load and state between them.  A Kubernetes cluster is a group of machines (“nodes”) that all host Kubernetes resources, like pods and services, and which appear to the external user as a single entity.  If the term “cluster” is not prefixed, it should be assumed to mean a Kubernetes cluster. |
-| Domain	| A WebLogic domain is a group of related applications and resources along with the configuration information necessary to run them. |
-| Ingress	| A Kubernetes Ingress provides access to applications and services in a Kubernetes environment to external clients.  An Ingress may also provide additional features like load balancing. |
-| Namespace	| A Kubernetes namespace is a named entity that can be used to group together related objects, for example, pods and services. |
-| Operator	| A Kubernetes operator is software that performs management of complex applications. |
-|Pod	| A Kubernetes pod contains one or more containers and is the object that provides the execution environment for an instance of an application component, such as a web server or database. |
-| Job	 | A Kubernetes job is a type of controller that creates one or more pods that run to completion to complete a specific task. |
-| Secret	| A Kubernetes secret is a named object that can store secret information like usernames, passwords, X.509 certificates, or any other arbitrary data. |
-|Service	| A Kubernetes service exposes application endpoints inside a pod to other pods, or outside the Kubernetes cluster.  A service may also provide additional features like load balancing. |
 
-# Getting started
+# User guide
 
-Before using the operator, you might want to read the [design philosophy](site/design.md) to develop an understanding of the operator's design, and the [architectural overview](site/architecture.md) to understand its architecture, including how WebLogic domains are deployed in Kubernetes using the operator. Also, worth reading are the details of the [Kubernetes RBAC definitions](site/rbac.md) required by the operator.
+The [User guide](site/user-guide.md) provides detailed information about all aspects of using the operator including:
 
-## Prerequisites
+* installing and configuring the operator,
+* using the operator to create and manage WebLogic domains,
+* manually creating WebLogic domains to be managed by the operator, 
+* scaling WebLogic clusters, 
+* configuring Kubernetes load balancers, 
+* configuring Elasticsearch and Kibana to access the operator's log files,
+* shutting down domains, 
+* removing/deleting domains, 
+* and much more! 
 
-*	Kubernetes 1.10.11+, 1.11.5+, and 1.12.3+  (check with `kubectl version`).
-*	Flannel networking v0.9.1-amd64 (check with `docker images | grep flannel`)
-*	Docker 18.03.1.ce (check with `docker version`)
-*	Oracle WebLogic Server 12.2.1.3.0
+# Samples
 
-## Set up your Kubernetes cluster
-
-If you need help setting up a Kubernetes environment, check our [cheat sheet](site/k8s_setup.md).
-
-## Manage your Kubernetes environment
-
-After creating Kubernetes clusters, you can optionally:
-* Create load balancers to direct traffic to backend domains.
-* Configure Kibana and Elasticsearch for your operator logs.
-
-### Creating load balancers
-
-Use these [scripts and Helm charts](kubernetes/samples/README.md) to install Traefik, Apache, or Voyager load balancers.
-
-### Configuring Kibana and Elasticsearch
-
-You can send the operator logs to Elasticsearch, to be displayed in Kibana. Use this [sample script](kubernetes/samples/scripts/elasticsearch_and_kibana.yaml) to configure Elasticsearch and Kibana deployments and services.
-
-## Create and manage the operator
-
-An operator is an application-specific controller that extends Kubernetes to create, configure, and manage instances of complex applications. The WebLogic Kubernetes Operator follows the standard Kubernetes Operator pattern, and simplifies the management and operation of WebLogic domains and deployments. You can find the operator image in [Docker Hub](https://hub.docker.com/r/oracle/weblogic-kubernetes-operator/).
-
-In your Kubernetes cluster you can have one or more operators that manage one or more WebLogic domains (running in a cluster). We provide a Helm chart to create the operator. (Point to the documentation and sample that describes how to do the steps below.)
-
-
-### Starting the operator
-
-* Create the namespace and service account for the operator (See the script and doc that describe how to do these.)
-* Edit the operator input YAML
-* Start the operator with a Helm chart
-
-### Modifying the operator
-
-(images, RBAC roles, ...)
-
-### Shutting down the operator
-(See the operator sample README section that describes how to shutdown and delete all resources for the operator.)
-
-## Create and manage WebLogic domains
-
-In this version of the operator, a WebLogic domain can be persisted either to a persistent volume (PV) or in a Docker image.
-(Describe the pros and cons of both these approaches.)
-
-* WebLogic binary image when domain is persisted to a PV (as in Operator v1.1)
-* WebLogic domain image where the domain is persisted to a Docker image (new for Operator v2.0).  The WebLogic domain image will contain the WebLogic binaries, domain configuration, and applications.
-
-You create the WebLogic domain inside of a Docker image or in a PV using WebLogic Scripting Tool (WLST) or WebLogic Deploy Tooling (WDT).  
-* (Describe the advantages of using WDT. See samples, Domain in image WDT, Domain in image WLST, Domain in PV WDT, Domain in PV WLST.)
-
-(What images do we need before we get started? Operator 2.0 requires you to patch your WebLogic image 12.2.1.3 with patch #.)
-
-### Preparing the Kubernetes cluster to run WebLogic domains
-
-Perform these steps to prepare your Kubernetes cluster to run a WebLogic domain:
-
-* Create the domain namespace.  One or more domains can share a namespace.
-* Define RBAC roles for the domain.
-* Create a Kubernetes secret for the Administration Server boot credentials.
-* Optionally, [create a PV & persistent volume claim (PVC)](kubernetes/samples/scripts/create-weblogic-domain-pv-pvc/README.md) which can hold the domain home, logs, and application binaries.
-* [Configure a load balancer](kubernetes/samples/charts/README.md) to manage the domains and ingresses.
-
-### Creating and managing WebLogic domains
-
-To create and manage a WebLogic domain in Kubernetes we create a deployment type, the domain custom resource.   The operator introspects the custom resource and manages the domain deployment to adjust to the definitions in the custom resource.   This custom resource can also be managed using the Kubernetes command-line interface `kubectl`.  
-* (Point to documentation how to edit the domain inputs YAML and how to create the domain custom resource.)
-* Create Ingress controllers if you are using a load balancer that supports them, such as Traefik or Voyager.
-
-### Managing lifecycle operations
-
-In Operator 2.0 you can perform lifecycle operations on WebLogic servers, clusters, or domains.
-* Point to the documentation on how to manage lifecycle operations.
-
-### Modifying domain configurations
-You can modify the WebLogic domain configuration for both the domain in PV and the domain in image:
-
-* When the domain is in a PV, use WLST or WDT to change the configuration.
-* Use configuration overrides when using the domain in image.(Check with Tom B, "The automatic and custom overrides apply to all domains - not just domain-in-image domains." Point to the documentation.)
-
-### Patching WebLogic and performing application updates
-
-###  Shutting down domains
-
-###  Deleting domains
-(Point to sample)
+**TODO** put a list of samples here with a summary and links
 
 # Developer guide
 
diff --git a/model/src/main/java/oracle/kubernetes/weblogic/domain/ClusterConfigurator.java b/model/src/main/java/oracle/kubernetes/weblogic/domain/ClusterConfigurator.java
@@ -28,14 +28,57 @@ ClusterConfigurator withReadinessProbeSettings(
   ClusterConfigurator withLivenessProbeSettings(
       Integer initialDelay, Integer timeout, Integer period);
 
+  /**
+   * Add a node label to the Cluster's node selector
+   *
+   * @param labelKey the pod label key
+   * @param labelValue the pod label value
+   * @return this object
+   */
   ClusterConfigurator withNodeSelector(String labelKey, String labelValue);
 
+  /**
+   * Add a resource requirement at cluster level. The requests for memory are measured in bytes. You
+   * can express memory as a plain integer or as a fixed-point integer using one of these suffixes:
+   * E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. The
+   * requests for cpu are mesured in cpu units and can be expressed in millicores i.e. 100m is the
+   * same as 0.1
+   *
+   * @param resource the resource to be added as requirement cpu or memory
+   * @param quantity the quantity required for the resource
+   * @return this object
+   */
   ClusterConfigurator withRequestRequirement(String resource, String quantity);
 
+  /**
+   * Add a resource limit at cluster level, the requests for memory are measured in bytes. You can
+   * express memory as a plain integer or as a fixed-point integer using one of these suffixes: E,
+   * P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. The
+   * requests for cpu are mesured in cpu units and can be expressed in millicores i.e. 100m is the
+   * same as 0.1
+   *
+   * @param resource the resource to be added as requirement cpu or memory
+   * @param quantity the quantity required for the resource
+   * @return this object
+   */
   ClusterConfigurator withLimitRequirement(String resource, String quantity);
 
+  /**
+   * Add security constraints at container level, if the same constraint is also defined at pod
+   * level then container constraint take precedence
+   *
+   * @param containerSecurityContext the security context object
+   * @return this object
+   */
   ClusterConfigurator withContainerSecurityContext(V1SecurityContext containerSecurityContext);
 
+  /**
+   * Add security constraints at container level, if the same constraint is also defined at pod
+   * level then container constraint take precedence
+   *
+   * @param podSecurityContext
+   * @return this object
+   */
   ClusterConfigurator withPodSecurityContext(V1PodSecurityContext podSecurityContext);
 
   ClusterConfigurator withAdditionalVolume(String name, String path);
@@ -50,5 +93,17 @@ ClusterConfigurator withLivenessProbeSettings(
 
   ClusterConfigurator withServiceAnnotation(String name, String value);
 
+  /**
+   * Tells the operator whether the customer wants to restart the server pods. The value can be any
+   * String and it can be defined on domain, cluster or server to restart the different pods. After
+   * the value is added, the corresponding pods will be terminated and created again. If customer
+   * modifies the value again after the pods were recreated, then the pods will again be terminated
+   * and recreated.
+   *
+   * @since 2.0
+   * @param restartVersion If preseent, every time this value is updated the operator will restart
+   *     the required servers
+   * @return this object
+   */
   ClusterConfigurator withRestartVersion(String restartVersion);
 }
diff --git a/model/src/main/java/oracle/kubernetes/weblogic/domain/DomainConfigurator.java b/model/src/main/java/oracle/kubernetes/weblogic/domain/DomainConfigurator.java
@@ -267,9 +267,15 @@ public abstract DomainConfigurator withPodSecurityContext(
       V1PodSecurityContext podSecurityContext);
 
   /**
-   * Set the restart version for the Domain
+   * Tells the operator whether the customer wants to restart the server pods. The value can be any
+   * String and it can be defined on domain, cluster or server to restart the different pods. After
+   * the value is added, the corresponding pods will be terminated and created again. If customer
+   * modifies the value again after the pods were recreated, then the pods will again be terminated
+   * and recreated.
    *
-   * @param restartVersion
+   * @since 2.0
+   * @param restartVersion If preseent, every time this value is updated the operator will restart
+   *     the required servers
    * @return this object
    */
   public abstract DomainConfigurator withRestartVersion(String restartVersion);
diff --git a/model/src/main/java/oracle/kubernetes/weblogic/domain/ServerConfigurator.java b/model/src/main/java/oracle/kubernetes/weblogic/domain/ServerConfigurator.java
@@ -24,14 +24,57 @@ ServerConfigurator withLivenessProbeSettings(
   ServerConfigurator withReadinessProbeSettings(
       Integer initialDelay, Integer timeout, Integer period);
 
+  /**
+   * Add a node label to the Servers's node selector
+   *
+   * @param labelKey the pod label key
+   * @param labelValue the pod label value
+   * @return this object
+   */
   ServerConfigurator withNodeSelector(String labelKey, String labelValue);
 
+  /**
+   * Add a resource requirement at server level. The requests for memory are measured in bytes. You
+   * can express memory as a plain integer or as a fixed-point integer using one of these suffixes:
+   * E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. The
+   * requests for cpu are mesured in cpu units and can be expressed in millicores i.e. 100m is the
+   * same as 0.1
+   *
+   * @param resource the resource to be added as requirement cpu or memory
+   * @param quantity the quantity required for the resource
+   * @return this object
+   */
   ServerConfigurator withRequestRequirement(String resource, String quantity);
 
+  /**
+   * Add a resource limit at server level, the requests for memory are measured in bytes. You can
+   * express memory as a plain integer or as a fixed-point integer using one of these suffixes: E,
+   * P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. The
+   * requests for cpu are mesured in cpu units and can be expressed in millicores i.e. 100m is the
+   * same as 0.1
+   *
+   * @param resource the resource to be added as requirement cpu or memory
+   * @param quantity the quantity required for the resource
+   * @return this object
+   */
   ServerConfigurator withLimitRequirement(String resource, String quantity);
 
+  /**
+   * Add security constraints at container level, if the same constraint is also defined at pod
+   * level then container constraint take precedence
+   *
+   * @param containerSecurityContext the security context object
+   * @return this object
+   */
   ServerConfigurator withContainerSecurityContext(V1SecurityContext containerSecurityContext);
 
+  /**
+   * Add security constraints at container level, if the same constraint is also defined at pod
+   * level then container constraint take precedence
+   *
+   * @param podSecurityContext
+   * @return this object
+   */
   ServerConfigurator withPodSecurityContext(V1PodSecurityContext podSecurityContext);
 
   ServerConfigurator withAdditionalVolume(String name, String path);
@@ -46,5 +89,17 @@ ServerConfigurator withReadinessProbeSettings(
 
   ServerConfigurator withServiceAnnotation(String name, String value);
 
+  /**
+   * Tells the operator whether the customer wants to restart the server pods. The value can be any
+   * String and it can be defined on domain, cluster or server to restart the different pods. After
+   * the value is added, the corresponding pods will be terminated and created again. If customer
+   * modifies the value again after the pods were recreated, then the pods will again be terminated
+   * and recreated.
+   *
+   * @since 2.0
+   * @param restartVersion If preseent, every time this value is updated the operator will restart
+   *     the required servers
+   * @return this object
+   */
   ServerConfigurator withRestartVersion(String restartVersion);
 }
diff --git a/model/src/main/java/oracle/kubernetes/weblogic/domain/v2/BaseConfiguration.java b/model/src/main/java/oracle/kubernetes/weblogic/domain/v2/BaseConfiguration.java
@@ -219,11 +219,11 @@ void addServiceAnnotations(String name, String value) {
     serverPod.addServiceAnnotations(name, value);
   }
 
-  public String getRestartVersion() {
+  String getRestartVersion() {
     return restartVersion;
   }
 
-  public void setRestartVersion(String restartVersion) {
+  void setRestartVersion(String restartVersion) {
     this.restartVersion = restartVersion;
   }
 
diff --git a/operator/src/main/java/oracle/kubernetes/operator/JobWatcher.java b/operator/src/main/java/oracle/kubernetes/operator/JobWatcher.java
@@ -46,6 +46,7 @@ public class JobWatcher extends Watcher<V1Job> implements WatchListener<V1Job> {
    * @param factory thread factory
    * @param ns Namespace
    * @param initialResourceVersion Initial resource version or empty string
+   * @param tuning Tuning parameters for the watch, for example watch lifetime
    * @param isStopping Stop signal
    * @return Job watcher for the namespace
    */
diff --git a/site/user-guide.md b/site/user-guide.md
diff --git a/src/scripts/scaling/scalingAction.sh b/src/scripts/scaling/scalingAction.sh

Original file line number	Diff line number	Diff line change
`@@ -219,11 +219,11 @@ void addServiceAnnotations(String name, String value) {`
`219`	`219`	`serverPod.addServiceAnnotations(name, value);`
`220`	`220`	`}`
`221`	`221`
`222`		`- public String getRestartVersion() {`
	`222`	`+ String getRestartVersion() {`
`223`	`223`	`return restartVersion;`
`224`	`224`	`}`
`225`	`225`
`226`		`- public void setRestartVersion(String restartVersion) {`
	`226`	`+ void setRestartVersion(String restartVersion) {`
`227`	`227`	`this.restartVersion = restartVersion;`
`228`	`228`	`}`
`229`	`229`