reorganizing doc structure and adding TODOs all over the place (#632)

markxnelson · web-flow · commit 068b9fb6e323 · 2018-12-13T13:47:46.000-05:00
* doc reorg

* updates
diff --git a/README.md b/README.md
@@ -52,7 +52,7 @@ The [User guide](site/user-guide.md) provides detailed information about all asp
 
 # Samples
 
-**TODO** put a list of samples here with a summary and links
+Please refer to our [samples](kubernetes/samples/README.md) for information about the available sample code we provide.
 
 # Developer guide
 
diff --git a/kubernetes/samples/README.md b/kubernetes/samples/README.md
@@ -1,12 +1,15 @@
 # WebLogic operator samples
 
+**TODO** write intro
+
 ## Sample scripts
 
-* [Sample for creating a Kubernetes secret](scripts/create-weblogic-domain/create-weblogic-credentials.sh) that contains the Administration Server credentials. This secret can be used in creating a WebLogic domain resource.
+* [Sample for creating a Kubernetes secret](scripts/create-weblogic-domain/README.md) that contains the Administration Server credentials. This secret can be used in creating a WebLogic domain resource.
 * [Sample for creating a PV or PVC](scripts/create-weblogic-domain-pv-pvc/README.md) that can be used by a domain resource as the persistent storage for the WebLogic domain home or log files.
 * [Sample for creating a WebLogic domain home on an existing PV or PVC](scripts/create-weblogic-domain/domain-home-on-pv/README.md), and the domain resource YAML file for deploying the generated WebLogic domain.
-* [Sample for configuring the Elasticsearch and Kibana](scripts/elasticsearch_and_kibana.yaml) deployments and services for the operator's logs.
-* [Sample for generating a self-signed certificate and private key](scripts/generate-external-rest-identity.sh) that can be used for the operator's external REST API.
+* [Sample for creating a WebLogic domain home inside a Docker image](scripts/create-weblogic-domain/domain-home-in-image/README.md), and the domain resource YAML file for deploying the generated WebLogic domain.
+* [Sample for configuring the Elasticsearch and Kibana](scripts/elasticsearch-and-kibana/README.md) deployments and services for the operator's logs.
+* [Sample for generating a self-signed certificate and private key](scripts/rest/README.md) that can be used for the operator's external REST API.
 
 ## Sample Helm charts
 
diff --git a/kubernetes/samples/scripts/create-weblogic-domain-credentials/README.md b/kubernetes/samples/scripts/create-weblogic-domain-credentials/README.md
@@ -0,0 +1,3 @@
+# Ceating credentials for a WebLogic domain
+
+**TODO** write me 
diff --git a/kubernetes/samples/scripts/create-weblogic-domain-credentials/create-weblogic-credentials.sh b/kubernetes/samples/scripts/create-weblogic-domain-credentials/create-weblogic-credentials.sh
diff --git a/kubernetes/samples/scripts/delete-domain/README.md b/kubernetes/samples/scripts/delete-domain/README.md
@@ -0,0 +1 @@
+**TODO** write me 
diff --git a/kubernetes/samples/scripts/delete-domain/delete-weblogic-domain-resources.sh b/kubernetes/samples/scripts/delete-domain/delete-weblogic-domain-resources.sh
diff --git a/kubernetes/samples/scripts/elasticsearch-and-kibana/README.md b/kubernetes/samples/scripts/elasticsearch-and-kibana/README.md
@@ -0,0 +1 @@
+**TODO** write me
diff --git a/kubernetes/samples/scripts/elasticsearch-and-kibana/elasticsearch_and_kibana.yaml b/kubernetes/samples/scripts/elasticsearch-and-kibana/elasticsearch_and_kibana.yaml
diff --git a/kubernetes/samples/scripts/rest/README.md b/kubernetes/samples/scripts/rest/README.md
@@ -0,0 +1 @@
+**TODO** write me
diff --git a/kubernetes/samples/scripts/rest/generate-external-rest-identity.sh b/kubernetes/samples/scripts/rest/generate-external-rest-identity.sh
diff --git a/site/additional-integrations.md b/site/additional-integrations.md
@@ -0,0 +1,9 @@
+**TODO** write me
+
+## Additional integrations
+
+**TODO** write me
+
+### Sending WebLogic metrics to Prometheus
+
+**TODO** write me 
diff --git a/site/apache.md b/site/apache.md
@@ -1,3 +1,5 @@
+**TODO** review, update if necessary
+
 # Load balancing with the Apache HTTP Server
 
 This document describes how to set up and start an Apache HTTP Server for load balancing inside a Kubernetes cluster. 
diff --git a/site/architecture.md b/site/architecture.md
@@ -1,3 +1,5 @@
+**TODO** review and update
+
 # Architectural overview
 
 The operator consists of the following two main parts:
diff --git a/site/creating-domain.md b/site/creating-domain.md
@@ -1,3 +1,5 @@
+**TODO** review and update
+
 # Creating a WebLogic domain
 
 The WebLogic domain must be installed into the folder that will be mounted as `/shared/domain`. The recommended approach is to use the provided `create-weblogic-domain.sh` script; however, instructions are also provided for manually installing and configuring a WebLogic domain (see [Manually creating a domain](manually-creating-domain.md)).
diff --git a/site/database.md b/site/database.md
@@ -1,3 +1,7 @@
+**TODO** finish this page - make sure we tell people how to run 
+a db in a pod with persistent storage, and how to configure the 
+persistent store/leases etc in there
+
 # Running the Oracle Database in Kubernetes
 
 **PLEASE NOTE**:  This page is a work in progress.  We will update this with either better details about how to put the data files onto a persistent volume, or a pointer to the official Oracle Database Kubernetes pages, or both.
diff --git a/site/design.md b/site/design.md
@@ -1,3 +1,4 @@
+**TODO** review and update, links to schema resources in particular
 
 # Design philosophy
 
diff --git a/site/developer.md b/site/developer.md
@@ -1,3 +1,5 @@
+**TODO** review and update
+
 # Developer guide
 
 This guide provides information for developers who wish to understand or contribute to the code.
@@ -96,7 +98,7 @@ To create them, first, make a copy of the inputs file (`create-weblogic-operator
 
 Next, choose and create a directory that generated operator-related files will be stored in, for example, `/path/to/weblogic-operator-output-directory`.
 
-Finally, run the operator installation script with the "generate only" option as shown below, pointing it at your inputs file and your output directory.  (See the [installation](installation.md) page for details about this script and the inputs):
+Finally, run the operator installation script with the "generate only" option as shown below, pointing it at your inputs file and your output directory.  (See the [installation](manual-installation.md) page for details about this script and the inputs):
 
 ```
 ./create-weblogic-operator.sh -g \
diff --git a/site/domain-resource.md b/site/domain-resource.md
@@ -1,3 +1,4 @@
+**TODO** review and update
 
 # Domain resource
 
diff --git a/site/domains.md b/site/domains.md
@@ -0,0 +1,48 @@
+**TODO** write me
+
+## 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)
diff --git a/site/elk.md b/site/elk.md
@@ -1,3 +1,5 @@
+**TODO** finish writing this
+
 # Elastic Stack integration
 
 **PLEASE NOTE**: This page is a work in progress. We have some rough notes in here and are working on writing better documentation for how to set up this integration.
diff --git a/site/ingress.md b/site/ingress.md
@@ -1,3 +1,5 @@
+**TODO** review and udpate - link into [lb](load-balancing.md)
+
 # Load balancing with Ingress
 Ingress is a approach provided by k8s to hook up and run a load balancer. Pls see detail in [the Ingress doc](https://kubernetes.io/docs/concepts/services-networking/ingress/).  
 
diff --git a/site/install.md b/site/install.md
@@ -0,0 +1,23 @@
+**TODO** write me -- richard is working on helm install docs too
+
+
+## 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.)
+
diff --git a/site/k8s_setup.md b/site/k8s_setup.md
@@ -1,3 +1,5 @@
+**TODO** review and update
+
 [Terraform]: https://terraform.io
 [OCI]: https://cloud.oracle.com/cloud-infrastructure
 [OCI provider]: https://github.com/oracle/terraform-provider-oci/releases
diff --git a/site/load-balancing.md b/site/load-balancing.md
@@ -0,0 +1,20 @@
+**TODO** review
+
+# Load Balancing
+
+There are several different types of load balancers available, and the 
+options vary depending on which flavor of Kubernetes you are running 
+and on your cloud provider (if any). 
+
+The Oracle WebLogic Server Kubernetes Operator is tested with a number
+of load balancers.  The following pages provide details about how 
+to configure some common load balancers for use with the operator:
+
+* [Apache HTTP Server](apache.md)
+* [Traefik](traefik.md)
+* [HAProxy/Voyager](voyager.md)
+
+
+### Set up load balancers
+
+Use these [scripts and Helm charts](kubernetes/samples/README.md) to install Traefik, Apache, or Voyager load balancers.
diff --git a/site/manual-installation.md b/site/manual-installation.md
@@ -1,4 +1,14 @@
-# Installation
+**TODO** update 
+
+# Manual Installation
+
+The normal method of installation is the use the provided Helm charts, 
+please [see here](#) for detailed instructions. 
+
+If you are unable to or prefer not to use Helm, or you want to customize the process, you 
+should refer to the manual instructions below. 
+
+**TODO** update video links 
 
 Note that there is a short video demonstration of the installation process available [here](https://youtu.be/B5UmY2xAJnk).
 
@@ -11,7 +21,17 @@ Note that there is a short video demonstration of the installation process avail
 [comment]: # ( Note that you *must* create the `docker-registry` secret in the `weblogic-operator` namespace, so you will need to create the namespace first. )
 [comment]: # ( In this command, replace the uppercase items with the appropriate values. The `SECRET_NAME` will be needed in later parameter files.  The `NAMESPACE` must match the namespace where the operator will be deployed. )
 
-## Build the Docker image for the operator using Wercker
+## Build the Docker image
+
+There are two main ways to build the operator Docker image: 
+
+* [Using Wercker](#build-the-docker-image-for-the-operator-using-wercker), or 
+* [Locally, on your machine](#build-the-docker-image-for-the-operator-locally)
+
+The image is also published in Docker Store if you prefer to use a pre-built imaage.
+**TODO** add details of how to get it
+
+### Build the Docker image for the operator using Wercker
 
 You can build, test, and publish the Docker image for the operator directly from Wercker using the ```wercker.yml``` from this repository.
 
@@ -50,7 +70,7 @@ Select the "Runs" tab.  Scroll to the bottom and click "Trigger your first build
 
 When the run completes successfully, the Docker image for the operator will be built and published to your repository.
 
-## Build the Docker image for the operator locally
+### Build the Docker image for the operator locally
 
 In addition to the requirements listed in [README](../README.md#prerequisites), the following software is also required to obtain and build the operator:
 
diff --git a/site/manually-creating-domain.md b/site/manually-creating-domain.md
@@ -1,3 +1,5 @@
+**TODO** finish this
+
 # Manually creating a WebLogic domain
 
 **PLEASE NOTE**: This page is a work in progress. We have some rough notes here and are working on writing better documentation for how to set up this procedure.
diff --git a/site/persistent-volumes.md b/site/persistent-volumes.md
@@ -1,3 +1,4 @@
+**TODO** review 
 
 # Persistent volumes
 
diff --git a/site/prepare-k8s.md b/site/prepare-k8s.md
@@ -0,0 +1,17 @@
+**TODO** write me
+
+## Preparing your Kubernetes environment
+
+**TODO** write intro 
+
+### Set up your Kubernetes cluster
+
+If you need help setting up a Kubernetes environment, check our [cheat sheet](site/k8s_setup.md).
+
+After creating Kubernetes clusters, you can optionally:
+* Create load balancers to direct traffic to backend domains.
+* Configure Kibana and Elasticsearch for your operator logs.
+
+### 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.
diff --git a/site/rbac.md b/site/rbac.md
@@ -1,3 +1,5 @@
+**TODO** review and update
+
 # Role-Based Access Control (RBAC)
 
 The operator assumes that certain roles and role bindings are created on the Kubernetes cluster.  The operator installation scripts create these, and the operator verifies that they are correct when the cluster starts up.  This document lists the [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) definitions that are created.
diff --git a/site/recent-changes.md b/site/recent-changes.md
@@ -1,3 +1,5 @@
+**TODO** update for 2.0
+
 # Recent changes to the Oracle WebLogic Server Kubernetes Operator
 
 This document tracks recent changes to the operator, especially ones that introduce backward incompatibilities.
diff --git a/site/rest.md b/site/rest.md
@@ -1,3 +1,5 @@
+**TODO** review and update
+
 # Using the operator's REST services
 
 The operator provides a REST server which can be used to get a list of WebLogic domains and clusters and to initiate scaling operations.  Swagger documentation for the REST API is available [here](https://oracle.github.io/weblogic-kubernetes-operator/swagger/index.html).
diff --git a/site/scaling.md b/site/scaling.md
@@ -1,3 +1,5 @@
+**TODO** review and update
+
 # Scaling a WebLogic cluster
 
 WebLogic Server supports two types of clustering configurations, configured and dynamic. Configured clusters are created by manually configuring each individual Managed Server instance. In dynamic clusters, the Managed Server configurations are generated from a single, shared template.  With dynamic clusters, when additional server capacity is needed, new server instances can be added to the cluster without having to manually configure them individually. Also, unlike configured clusters, scaling up of dynamic clusters is not restricted to the set of servers defined in the cluster but can be increased based on runtime demands. For more information on how to create, configure, and use dynamic clusters in WebLogic Server, see [Dynamic Clusters](https://docs.oracle.com/middleware/1221/wls/CLUST/dynamic_clusters.htm#CLUST678).
diff --git a/site/shutdown-domain.md b/site/shutdown-domain.md
@@ -1,3 +1,5 @@
+**TODO** review and update - should use helm now
+
 # Shutting down a domain
 
 To shut down a domain, issue the following command:
diff --git a/site/starting-domain.md b/site/starting-domain.md
@@ -1,3 +1,5 @@
+**TODO** review and update
+
 # Starting a WebLogic domain
 
 Startup of the domain is controlled by settings in the domain resource.  If used, the domain creation job will have created a domain resource YAML file. If the domain was created manually, this YAML file will also need to be created manually.
diff --git a/site/traefik.md b/site/traefik.md
@@ -0,0 +1,3 @@
+**TODO** write me
+
+# Load balancing with Traefik
diff --git a/site/user-guide.md b/site/user-guide.md
diff --git a/site/voyager.md b/site/voyager.md
diff --git a/site/weblogic-docker-images.md b/site/weblogic-docker-images.md
diff --git a/site/wlst.md b/site/wlst.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Ceating credentials for a WebLogic domain`
	`2`	`+`
	`3`	`+TODO write me`