new docs (#938)

Author: markxnelson

docs-source/archetypes/default.md

@@ -0,0 +1,6 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+draft: false
+---
+

docs-source/config.toml

@@ -0,0 +1,13 @@
+baseURL = "/weblogic-kubernetes-operator/"
+languageCode = "en-us"
+title = "WebLogic Kubernetes Operator"
+
+# Change the default theme to be use when building the site with Hugo
+theme = "hugo-theme-learn"
+
+publishDir = "docs"
+
+# For search functionality
+[outputs]
+home = [ "HTML", "RSS", "JSON"]
+

docs-source/content/_index.md

@@ -0,0 +1,166 @@
+### Oracle WebLogic Server Kubernetes Operator
+
+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 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.
+* 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.
+* 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]({{< relref "/quickstart/_index.md" >}}), or you can peruse our [documentation]({{< relref "/userguide/_index.md" >}}), read our [blogs](https://blogs.oracle.com/weblogicserver/updated-weblogic-kubernetes-support-with-operator-20), or try out the [samples]({{< relref "/samples/_index.md" >}}).
+
+***
+The [current release of the operator](https://github.com/oracle/weblogic-kubernetes-operator/releases) is 2.0.1.
+This release was published on March 4, 2019.
+***
+
+#### Known issues
+
+| Issue | Description |
+| --- | --- |
+| None currently |  |
+
+#### Operator earlier versions
+
+Documentation for prior releases of the operator is available [here](site/README.md).
+
+#### Backward compatibility guidelines
+
+Starting from the 2.0 release, operator releases are backward 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, except in the case of a clearly communicated deprecated feature, which will be
+maintained for one release after a replacement is available.
+
+### About this documentation
+
+This documentation includes sections targeted to different audiences.  To help you find what you are looking for more easily,
+please consult this table of contents:
+
+* The [Quick Start guide]({{< relref "/quickstart/_index.md" >}}) explains how to quickly get the operator running, using the defaults, nothing special.
+* The [User guide]({{< relref "/userguide/_index.md" >}}) contains detailed usage information, including how to install and configure the operator,
+  and how to use it to create and manage WebLogic domains.  
+* The [Samples]({{< relref "/samples/_index.md" >}}) provide detailed example code and instructions that show you how to perform
+  various tasks related to the operator.
+* The [Developer guide]({{< relref "/developerguide/_index.md" >}}) provides details for people who want to understand how the operator is built, tested, and so on. 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 contribution requirements.
+
+
+### User guide
+
+The [User guide]({{< relref "/userguide/_index.md" >}}) provides detailed information about all aspects of using the operator including:
+
+* 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!
+
+### Samples
+
+Please refer to our [samples]({{< relref "/samples/_index.md" >}}) for information about the available sample code.
+
+### Need more help? Have a suggestion? Come and say, "Hello!"
+
+We have a **public Slack channel** where you can get in touch with us to ask questions about using the operator or give us feedback
+or suggestions about what features and improvements you would like to see.  We would love to hear from you. To join our channel,
+please [visit this site to get an invitation](https://weblogic-slack-inviter.herokuapp.com/).  The invitation email will include
+details of how to access our Slack workspace.  After you are logged in, please come to `#operator` and say, "hello!"
+
+### Recent changes
+
+See [Recent changes]({{< relref "release-notes.md" >}})  for changes to the operator, including any backward incompatible changes.
+
+### Developer guide
+
+Developers interested in this project are encouraged to read the [Developer guide]({{< relref "/developerguide/_index.md" >}}) to learn how to build the project, run tests, and so on.  The Developer guide also provides details about the structure of the code, coding standards, and the Asynchronous Call facility used in the code to manage calls to the Kubernetes API.
+
+Please take a look at our [wish list](https://github.com/oracle/weblogic-kubernetes-operator/wiki/Wish-list) to get an idea of the kind of features we would like to add to the operator.  Maybe you will see something to which you would like to contribute!
+
+### API documentation
+
+Documentation for APIs:
+
+* The operator provides a REST API that you can use to obtain configuration information and to initiate scaling actions. For details about how to use the REST APIs, see [Use the operator's REST services]({{< relref "/userguide/managing-operators/using-the-operator/the-rest-api.md#use-the-operator-s-rest-services" >}}).
+
+* See the [Swagger](https://oracle.github.io/weblogic-kubernetes-operator/swagger/index.html) documentation for the operator's REST interface.
+
+* See the [Javadoc](https://oracle.github.io/weblogic-kubernetes-operator/apidocs/index.html) for the operator.
+
+### Contributing to the operator
+
+Oracle welcomes contributions to this project from anyone.  Contributions may be reporting an issue with the operator or submitting a pull request.  Before embarking on significant development that may result in a large pull request, it is recommended that you create an issue and discuss the proposed changes with the existing developers first.
+
+If you want to submit a pull request to fix a bug or enhance an existing feature, please first open an issue and link to that issue when you submit your pull request.
+
+If you have any questions about a possible submission, feel free to open an issue too.
+
+#### Contributing to the Oracle WebLogic Server Kubernetes Operator repository
+
+Pull requests can be made under The Oracle Contributor Agreement (OCA), which is available at [https://www.oracle.com/technetwork/community/oca-486395.html](https://www.oracle.com/technetwork/community/oca-486395.html).
+
+For pull requests to be accepted, the bottom of the commit message must have the following line, using the contributor’s name and e-mail address as it appears in the OCA Signatories list.
+
+```
+Signed-off-by: Your Name <[email protected]>
+```
+
+This can be automatically added to pull requests by committing with:
+
+```
+git commit --signoff
+```
+
+Only pull requests from committers that can be verified as having signed the OCA can be accepted.
+
+#### Pull request process
+
+*	Fork the repository.
+*	Create a branch in your fork to implement the changes. We recommend using the issue number as part of your branch name, for example, `1234-fixes`.
+*	Ensure that any documentation is updated with the changes that are required by your fix.
+*	Ensure that any samples are updated if the base image has been changed.
+*	Submit the pull request. Do not leave the pull request blank. Explain exactly what your changes are meant to do and provide simple steps on how to validate your changes. Ensure that you reference the issue you created as well. We will assign the pull request to 2-3 people for review before it is merged.
+
+#### Introducing a new dependency
+
+Please be aware that pull requests that seek to introduce a new dependency will be subject to additional review.  In general, contributors should avoid dependencies with incompatible licenses, and should try to use recent versions of dependencies.  Standard security vulnerability checklists will be consulted before accepting a new dependency.  Dependencies on closed-source code, including WebLogic Server, will most likely be rejected.
+
+### Use Helm chart from GitHub chart repository
+
+Add this repository to the Helm installation:
+
+```
+$ helm repo add weblogic-operator https://oracle.github.io/weblogic-kubernetes-operator/charts
+```
+
+Verify that the repository was added correctly:
+
+```
+$ helm repo list
+NAME           URL
+weblogic-operator    https://oracle.github.io/weblogic-kubernetes-operator/charts
+```
+
+Update with the latest information about charts from the chart repositories:
+
+```
+$ helm repo update
+```
+
+Install the operator from the repository:
+
+```
+$ helm install weblogic-operator/weblogic-operator --name weblogic-operator
+```

docs-source/content/developerguide/_index.md

@@ -0,0 +1,12 @@
++++
+title = "Developer Guide"
+date = 2019-02-22T15:27:54-05:00
+weight = 4
+chapter = true
+pre = "<b>4. </b>"
++++
+
+
+# Developer Guide
+
+The Developer Guide provides information for developers who want to understand or contribute to the code.

docs-source/content/developerguide/asynchronous-call-model.md

@@ -0,0 +1,146 @@
+---
+title: "Asynchronous call model"
+date: 2019-02-23T17:20:00-05:00
+draft: false
+weight: 7
+---
+
+
+Our expectation is that customers will task the operator with managing hundreds of WebLogic domains across dozens of Kubernetes namespaces.  Therefore, we have designed the operator with an efficient user-level threads pattern.  We've used that pattern to implement an asynchronous call model for Kubernetes API requests.  This call model has built-in support for timeouts, retries with exponential back-off, and lists that exceed the requested maximum size using the continuance functionality.
+
+#### User-level thread pattern
+
+The user-level thread pattern is implemented by the classes in the `oracle.kubernetes.operator.work` package.
+
+* `Engine`: The executor service and factory for `Fibers`.
+* `Fiber`: The user-level thread.  `Fibers` represent the execution of a single processing flow through a series of `Steps`.  `Fibers` may be suspended and later resumed, and do not consume a `Thread` while suspended.
+* `Step`: Individual CPU-bound activity in a processing flow.
+* `Packet`: Context of the processing flow.
+* `NextAction`: Used by a `Step` when it returns control to the `Fiber` to indicate what should happen next.  Common 'next actions' are to execute another `Step` or to suspend the `Fiber`.
+* `Component`: Provider of SPI's that may be useful to the processing flow.
+* `Container`: Represents the containing environment and is a `Component`.
+
+Each `Step` has a reference to the next `Step` in the processing flow; however, `Steps` are not required to indicate that the next `Step` be invoked by the `Fiber` when the `Step` returns a `NextAction` to the `Fiber`.  This leads to common use cases where `Fibers` invoke a series of `Steps` that are linked by the 'is-next' relationship, but just as commonly, use cases where the `Fiber` will invoke sets of `Steps` along a detour before returning to the normal flow.
+
+In this sample, the caller creates an `Engine`, `Fiber`, linked set of `Step` instances, and `Packet`.  The `Fiber` is then started.  The `Engine` would typically be a singleton, since it's backed by a `ScheduledExecutorService`.  The `Packet` would also typically be pre-loaded with values that the `Steps` would use in their `apply()` methods.
+
+```java
+static class SomeClass {
+  public static void main(String[] args) {
+    Engine engine = new Engine("worker-pool");
+
+    Fiber fiber = engine.createFiber();
+
+    Step step = new StepOne(new StepTwo(new StepThree(null)));
+      Packet packet = new Packet();
+
+    fiber.start(
+        step,
+        packet,
+        new CompletionCallback() {
+          @Override
+          public void onCompletion(Packet packet) {
+            // Fiber has completed successfully
+          }
+
+          @Override
+          public void onThrowable(Packet packet, Throwable throwable) {
+            // Fiber processing was terminated with an exception
+          }
+        });
+  }
+}
+```
+
+`Steps` must not invoke sleep or blocking calls from within `apply()`.  This prevents the worker threads from serving other `Fibers`.  Instead, use asynchronous calls and the `Fiber` suspend/resume pattern.  `Step` provides a method, `doDelay()`, which creates a `NextAction` to drive `Fiber` suspend/resume that is a better option than sleep precisely because the worker thread can serve other `Fibers` during the delay.  For asynchronous IO or similar patterns, suspend the `Fiber`.  In the callback as the `Fiber` suspends, initiate the asynchronous call.  Finally, when the call completes, resume the `Fiber`.  The suspend/resume functionality handles the case where resumed before the suspending callback completes.
+
+In this sample, the step uses asynchronous file IO and the suspend/resume `Fiber` pattern.
+
+```java
+    static class StepTwo extends Step {
+      public StepTwo(Step next) {
+        super(next);
+      }
+
+      @Override
+      public NextAction apply(Packet packet) {
+        return doSuspend((fiber) -> {
+          // The Fiber is now suspended
+          // Start the asynchronous call
+          try {
+            Path path = Paths.get(URI.create(this.getClass().getResource("/somefile.dat").toString()));
+            AsynchronousFileChannel fileChannel =
+                AsynchronousFileChannel.open(path, StandardOpenOption.READ);
+
+            ByteBuffer buffer = ByteBuffer.allocate(1024);
+            fileChannel.read(buffer, 0, buffer, new CompletionHandler<Integer, ByteBuffer>() {
+              @Override
+              void completed(Integer result, ByteBuffer attachment) {
+                // Store data in Packet and resume Fiber
+                packet.put("DATA_SIZE_READ", result);
+                packet.put("DATA_FROM_SOMEFILE", attachment);
+                fiber.resume(packet);
+              }
+
+              @Override
+              public void failed(Throwable exc, ByteBuffer attachment) {
+                // log exc
+                completed(0, null);
+              }
+            });
+          } catch (IOException e) {
+            // log exception
+            // If not resumed here, Fiber will never be resumed
+          }
+        });
+      }
+    }
+```
+
+#### Call builder pattern
+
+The asynchronous call model is implemented by classes in the `oracle.kubernetes.operator.helpers` package, including `CallBuilder` and `ResponseStep`.  The model is based on the `Fiber` suspend/resume pattern described above.  `CallBuilder` provides many methods having names ending with "Async", such as `listPodAsync()` or `deleteServiceAsync()`.  These methods return a `Step` that can be returned as part of a `NextAction`.  When creating these `Steps`, the developer must provide a `ResponseStep`.  Only `ResponseStep.onSuccess()` must be implemented; however, it is often useful to override `onFailure()` as Kubernetes treats `404 (Not Found)` as a failure.
+
+In this sample, the developer is using the pattern to list pods from the default namespace that are labeled as part of `cluster-1`.
+
+```java
+    static class StepOne extends Step {
+      public StepOne(Step next) {
+        super(next);
+      }
+
+      @Override
+      public NextAction apply(Packet packet) {
+        String namespace = "default";
+        Step step = CallBuilder.create().with($ -> {
+          $.labelSelector = "weblogic.clusterName=cluster-1";
+          $.limit = 50;
+          $.timeoutSeconds = 30;
+        }).listPodAsync(namespace, new ResponseStep<V1PodList>(next) {
+          @Override
+          public NextAction onFailure(Packet packet, ApiException e, int statusCode,
+              Map<String, List<String>> responseHeaders) {
+            if (statusCode == CallBuilder.NOT_FOUND) {
+              return onSuccess(packet, null, statusCode, responseHeaders);
+            }
+            return super.onFailure(packet, e, statusCode, responseHeaders);
+          }
+
+          @Override
+          NextAction onSuccess(Packet packet, V1PodList result, int statusCode,
+              Map<String, List<String>> responseHeaders) {
+            // do something with the result Pod, if not null
+            return doNext(packet);
+          }
+        });
+
+        return doNext(step, packet);
+      }
+    }
+```
+
+Notice that the required parameters, such as `namespace`, are method arguments, but optional parameters are designated using a simplified builder pattern using `with()` and a lambda.
+
+The default behavior of `onFailure()` will retry with an exponential backoff the request on status codes `429 (TooManyRequests)`, `500 (InternalServerError)`, `503 (ServiceUnavailable)`, `504 (ServerTimeout)` or a simple timeout with no response from the server.
+
+If the server responds with status code `409 (Conflict)`, then this indicates an optimistic locking failure.  Common use cases are that the code read a Kubernetes object in one asynchronous step, modified the object, and attempted to replace the object in another asynchronous step; however, another activity replaced that same object in the interim.  In this case, retrying the request would give the same result.  Therefore, developers may provide an "on conflict" step when calling `super.onFailure()`.  The conflict step will be invoked after an exponential backoff delay.  In this example, that conflict step should be the step that reads the existing Kubernetes object.

docs-source/content/developerguide/backwards-compatibility.md

@@ -0,0 +1,8 @@
+---
+title: "Backward compatibility"
+date: 2019-02-23T17:26:09-05:00
+draft: false
+weight: 9
+---
+
+Starting with the 2.0 release, future operator releases must be backward 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 will maintain compatibility for three releases, except in the case of a clearly communicated deprecated feature, which will be maintained for one release after a replacement is available.