Namespace management enhancements

buildtime-reports/pom.xml

@@ -8,7 +8,7 @@
     <parent>
         <artifactId>operator-parent</artifactId>
         <groupId>oracle.kubernetes</groupId>
-        <version>3.0.0</version>
+        <version>3.1.0</version>
     </parent>
 
     <artifactId>buildtime-reports</artifactId>

docs-source/content/_index.md

@@ -23,8 +23,8 @@ using the operator to deploy and run a WebLogic domain container-packaged web ap
 ***
 #### Current production release
 
-The [current release of the operator](https://github.com/oracle/weblogic-kubernetes-operator/releases) is 3.0.0.
-This release was published on July 17, 2020. See the operator prerequisites and supported environments [here]({{< relref "/userguide/introduction/introduction#operator-prerequisites" >}}).
+The [current release of the operator](https://github.com/oracle/weblogic-kubernetes-operator/releases) is 3.1.0.
+This release was published on August ?, 2020. See the operator prerequisites and supported environments [here]({{< relref "/userguide/introduction/introduction#operator-prerequisites" >}}).
 
 This release introduces _non-backward compatible_ changes; however, operators using this release can be run in the same
 Kubernetes cluster as operators using the 2.6.0 version allowing for staged migration. You can replace a 2.6.0 operator with a 3.x operator without needing to recreate any existing domains; however, you must delete the 2.6.0 Helm release and then install the 3.x version rather than using a Helm upgrade. When the 3.x operator starts, it will roll any running WebLogic Server instances

docs-source/content/faq/namespace-management.md

@@ -6,11 +6,11 @@ weight: 1
 description: "Considerations for managing namespaces while the operator is running."
 ---
 
-Each operator deployment manages a number of Kubernetes Namespaces. For more information, see [Operator Helm configuration values]({{< relref "/userguide/managing-operators/using-the-operator/using-helm#operator-helm-configuration-values" >}}). A number of Kubernetes resources
-must be present in a namespace before any WebLogic domain custom resources can be successfully
-deployed into it.
+Each operator deployment manages a number of Kubernetes namespaces. For more information, see [Operator Helm configuration values]({{< relref "/userguide/managing-operators/using-the-operator/using-helm#operator-helm-configuration-values" >}}). A number of Kubernetes resources
+must be present in a namespace before any WebLogic Server instances can be successfully
+started.
 Those Kubernetes resources are created either as part of the installation
-of the operator's Helm chart, or created by the operator at runtime.
+of a release of the operator's Helm chart, or created by the operator.
 
 This FAQ describes some considerations to be aware of when you manage the namespaces while the operator is running. For example:
 
@@ -22,12 +22,15 @@ This FAQ describes some considerations to be aware of when you manage the namesp
 For others, see [Common Mistakes and Solutions]({{< relref "/userguide/managing-operators/using-the-operator/using-helm#common-mistakes-and-solutions" >}}).
 
 {{% notice note %}}
-There can be multiple operators in a Kubernetes cluster, and in that case, you must ensure that their respective lists of `domainNamespaces` do not overlap.
+There can be multiple operators in a Kubernetes cluster, and in that case, you must ensure that the namespaces managed by these operators do not overlap.
 {{% /notice %}}
 
 #### Check the namespaces that the operator manages
-You can find the list of the namespaces that the operator manages using the `helm get values` command.
-For example, the following command shows all the values of the operator release `weblogic-operator`; the `domainNamespaces` list contains `default` and `ns1`.
+Prior to version 3.1.0, the operator supported specifying the namespaces that it would manage only through a list.
+Now, the operator supports a list of namespaces, a label selector, or a regular expression matching namespace names.
+
+For operators that specify namespaces by a list, you can find the list of the namespaces using the `helm get values` command.
+For example, the following command shows all the values of the operator release `weblogic-operator`; the `domainNamespaces` list contains `default` and `ns1`:
 
 ```
 $ helm get values weblogic-operator
@@ -49,7 +52,19 @@ logStashImage: logstash:6.6.0
 remoteDebugNodePortEnabled: false
 serviceAccount: default
 suspendOnDebugStartup: false
+```
+
+For operators that select namespaces with a selector, simply list namespaces using that selector:
+
+```
+$ kubectl get ns --selector="weblogic-operator=enabled"
+```
+
+For operators that select namespaces with a regular expression matching the name, you can use a combination of `kubectl`
+and any command-line tool that can process the regular expression, such as `grep`:
 
+```
+$ kubectl get ns -o go-template='{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}' | grep "^weblogic"
 ```
 
 If you don't know the release name of the operator, you can use `helm list` to list all the releases for a specified namespace or all namespaces:
@@ -59,30 +74,25 @@ $ helm list --namespace <namespace>
 $ helm list --all-namespaces
 ```
 
-#### Add a Kubernetes Namespace to the operator
-If you want an operator deployment to manage a namespace, you need to add the namespace to the operator's `domainNamespaces` list. Note that the namespace has to already exist, for example, using the `kubectl create` command.
+#### Add a Kubernetes namespace to the operator
+When the operator is configured to manage a list of namespaces and you want the operator to manage an additional namespace,
+you need to add the namespace to the operator's `domainNamespaces` list. Note that this namespace has to already exist, for example,
+using the `kubectl create` command.
 
-Adding a namespace to the `domainNamespaces` list tells the operator deployment or runtime
-to initialize the necessary Kubernetes resources for the namespace so that the operator is ready to run and monitor WebLogic Server instances in that namespace.
+Adding a namespace to the `domainNamespaces` list tells the operator to initialize the necessary
+Kubernetes resources so that the operator is ready to manage WebLogic Server instances in that namespace.
 
-When the operator is running and managing the `default` namespace, the following example Helm command adds the namespace `ns1` to the `domainNamespaces` list, where `weblogic-operator` is the release name of the operator, and `kubernetes/charts/weblogic-operator` is the location of the operator's Helm charts.
+When the operator is managing the `default` namespace, the following example Helm command adds the namespace `ns1` to the `domainNamespaces` list, where `weblogic-operator` is the release name of the operator, and `kubernetes/charts/weblogic-operator` is the location of the operator's Helm charts:
 
 ```
 $ helm upgrade \
+  weblogic-operator \
+  kubernetes/charts/weblogic-operator \
   --reuse-values \
   --set "domainNamespaces={default,ns1}" \
-  --wait \
-  --force \
-  weblogic-operator \
-  kubernetes/charts/weblogic-operator
+  --wait
 ```
 
-{{% notice note %}}
-Changes to the `domainNamespaces` list might not be picked up by the operator right away because the operator
-monitors the changes to the setting periodically. The operator becomes ready to manage Domains in
-a namespace only after the required `configmap` (namely `weblogic-scripts-cm`) is initialized in the namespace.
-{{% /notice %}}
-
 You can verify that the operator has initialized a namespace by confirming the existence of the required `configmap` resource.
 
 ```
@@ -99,14 +109,28 @@ NAME                 DATA      AGE
 weblogic-scripts-cm   14        12m
 ```
 
-####  Delete a Kubernetes Namespace from the operator
-When you no longer want a namespace to be managed by the operator, you need to remove it from
-the operator's `domainNamespaces` list, so that the corresponding Kubernetes resources that are
+For operators configured to select managed namespaces through the use of a label selector or regular expression,
+you simply need to create a namespace with the appropriate labels or with a name that matches the expression, respectively.
+
+If you did not choose to enable the value, `enableClusterRoleBinding`, then the operator will not have the necessary
+permissions to manage the namespace. You can do this by performing a `helm upgrade` with the values used when installing the 
+Helm release:
+
+```
+$ helm upgrade \
+  weblogic-operator \
+  kubernetes/charts/weblogic-operator \
+  --reuse-values
+```
+
+####  Delete a Kubernetes namespace from the operator
+When the operator is configured to manage a list of namespaces and you no longer want a namespace to be managed by the operator, you need to remove it from
+the operator's `domainNamespaces` list, so that the resources that are
 associated with the namespace can be cleaned up.
 
 While the operator is running and managing the `default` and `ns1` namespaces, the following example Helm
 command removes the namespace `ns1` from the `domainNamespaces` list, where `weblogic-operator` is the release
-name of the operator, and `kubernetes/charts/weblogic-operator` is the location of the operator Helm charts.
+name of the operator, and `kubernetes/charts/weblogic-operator` is the location of the operator Helm charts:
 
 ```
 $ helm upgrade \
@@ -116,24 +140,19 @@ $ helm upgrade \
   --force \
   weblogic-operator \
   kubernetes/charts/weblogic-operator
-
 ```
 
-#### Recreate a previously deleted Kubernetes Namespace
+For operators configured to select managed namespaces through the use of a label selector or regular expression,
+you simply need to delete the namespace. For the label selector option, you can also adjust the labels on the namespace
+so that the namespace no longer matches the selector.
+
+#### Recreate a previously deleted Kubernetes namespace
 
-If you need to delete a namespace (and the resources in it) and then recreate it,
+When the operator is configured to manage a list of namespaces and if you need to delete a namespace (and the resources in it) and then recreate it,
 remember to remove the namespace from the operator's `domainNamespaces` list
 after you delete the namespace, and add it back to the `domainNamespaces` list after you recreate the namespace
 using the `helm upgrade` commands that were illustrated previously.
 
-{{% notice note %}}
-Make sure that you wait a sufficient period of time between deleting and recreating the
-namespace because it takes time for the resources in a namespace to go away after the namespace is deleted.
-In addition, as mentioned above, changes to the `domainNamespaces` setting is monitored by the operator
-periodically, and the operator becomes ready to manage Domains only after the required domain
-`configmap` (namely `weblogic-scripts-cm`) is initialized in the namespace.
-{{% /notice %}}
-
 If a domain custom resource is created before the namespace is ready, you might see that the introspector job pod
 fails to start, with a warning like the following, when you review the description of the introspector pod.
 Note that `domain1` is the name of the domain in the following example output.

docs-source/content/quickstart/cleanup.md

@@ -28,7 +28,7 @@ weight: 7
     ```
 
 #### Remove the domain namespace.
-1.	Configure the Traefik load balancer to stop managing the ingresses in the domain namespace:
+1.	Configure the Traefik ingress controller to stop managing the ingresses in the domain namespace:
 
     ```bash
     $ helm upgrade traefik-operator traefik/traefik \
@@ -37,16 +37,6 @@ weight: 7
         --set "kubernetes.namespaces={traefik}" 
     ```
 
-1.	Configure the operator to stop managing the domain:
-
-    ```bash
-    $ helm upgrade  sample-weblogic-operator \
-                  kubernetes/charts/weblogic-operator \
-      --namespace sample-weblogic-operator-ns \
-      --reuse-values \
-      --set "domainNamespaces={}" \
-      --wait \
-    ```
 1.	Delete the domain namespace:
 
     ```bash
@@ -68,9 +58,9 @@ weight: 7
     $ kubectl delete namespace sample-weblogic-operator-ns
     ```
 
-#### Remove the load balancer.
+#### Remove the ingress controller.
 
-1.	Remove the Traefik load balancer:
+1.	Remove the Traefik ingress controller:
 
     ```bash
     $ helm uninstall traefik-operator -n traefik

docs-source/content/quickstart/create-domain.md

@@ -11,7 +11,7 @@ weight: 6
    * Select a user name and password, following the required rules for password creation (at least 8 alphanumeric characters with at least one number or special character).
    * Pick or create a directory to which you can write output.
 
-1. Create a Kubernetes Secret for the WebLogic administrator credentials containing the `username` and `password` for the domain, using the [create-weblogic-credentials](http://github.com/oracle/weblogic-kubernetes-operator/blob/master/kubernetes/samples/scripts/create-weblogic-domain-credentials/create-weblogic-credentials.sh) script:
+1. Create a Kubernetes Secret for the WebLogic domain administrator credentials containing the `username` and `password` for the domain, using the [create-weblogic-credentials](http://github.com/oracle/weblogic-kubernetes-operator/blob/master/kubernetes/samples/scripts/create-weblogic-domain-credentials/create-weblogic-credentials.sh) script:
 
     ```bash
     $ kubernetes/samples/scripts/create-weblogic-domain-credentials/create-weblogic-credentials.sh \
@@ -72,9 +72,9 @@ weight: 6
     ```
 
 
-1.	To confirm that the load balancer noticed the new ingress and is successfully routing to the domain's server pods,
+1.	To confirm that the ingress controller noticed the new ingress and is successfully routing to the domain's server pods,
     you can send a request to the URL for the "WebLogic ReadyApp framework", as
-    shown in the example below, which will return a HTTP 200 status code.   
+    shown in the example below, which will return an HTTP 200 status code.   
 
     ```
     $ curl -v -H 'host: sample-domain1.org' http://localhost:30305/weblogic/ready

docs-source/content/quickstart/get-images.md

@@ -7,10 +7,10 @@ weight: 3
 
 #### Get these images and put them into your local registry.
 
-1. If you don't already have one, obtain a Docker store account, log in to the Docker store,
+1. If you don't already have one, obtain a Docker Store account, log in to the Docker Store,
 and accept the license agreement for the [WebLogic Server image](https://hub.docker.com/_/oracle-weblogic-server-12c).
 
-1. Log in to the Docker store from your Docker client:
+1. Log in to the Docker Store from your Docker client:
 
     ```bash
     $ docker login
@@ -19,16 +19,16 @@ and accept the license agreement for the [WebLogic Server image](https://hub.doc
 1. Pull the operator image:
 
     ```bash
-    $ docker pull oracle/weblogic-kubernetes-operator:3.0.0
+    $ docker pull oracle/weblogic-kubernetes-operator:3.1.0
     ```
 
-1. Pull the Traefik load balancer image:
+1. Pull the Traefik ingress controller image:
 
     ```bash
     $ docker pull traefik:2.2.1
     ```
 
-1. Obtain the WebLogic image from the [Oracle Container Registry](https://container-registry.oracle.com).
+1. Obtain the WebLogic Server image from the [Oracle Container Registry](https://container-registry.oracle.com).
 
     a. First time users, follow these [directions]({{< relref "/userguide/managing-domains/domain-in-image/base-images/_index.md#obtaining-standard-images-from-the-oracle-container-registry" >}}).
 
@@ -38,7 +38,7 @@ and accept the license agreement for the [WebLogic Server image](https://hub.doc
      $ docker pull container-registry.oracle.com/middleware/weblogic:12.2.1.4
      ```
 
-    {{% notice note %}} The WebLogic Docker image, `weblogic:12.2.1.3`, has all the necessary patches applied. The WebLogic Docker image, `weblogic:12.2.1.4`, does not require any additional patches.
+    {{% notice note %}} The WebLogic Server Docker image, `weblogic:12.2.1.3`, has all the necessary patches applied. The WebLogic Server Docker image, `weblogic:12.2.1.4`, does not require any additional patches.
     {{% /notice %}}
 
 

docs-source/content/quickstart/install.md

@@ -1,30 +1,11 @@
 ---
-title: "Install the operator and load balancer"
+title: "Install the operator and ingress controller"
 date: 2019-02-22T15:44:42-05:00
 draft: false
 weight: 4
 ---
 
-#### Grant the Helm service account the `cluster-admin` role.
-
-```bash
-$ cat <<EOF | kubectl apply -f -
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRoleBinding
-metadata:
-  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
-EOF
-```
-
-#### Use Helm to install the operator and [Traefik](http://github.com/oracle/weblogic-kubernetes-operator/blob/master/kubernetes/samples/charts/traefik/README.md) load balancer.
+#### Use Helm to install the operator and [Traefik](http://github.com/oracle/weblogic-kubernetes-operator/blob/master/kubernetes/samples/charts/traefik/README.md) ingress controller.
 
 First, set up Helm:
 
@@ -33,9 +14,9 @@ $ helm repo add traefik https://containous.github.io/traefik-helm-chart/
 $ helm repo update
 ```
 
-#### Create a Traefik (ingress-based) load balancer.
+#### Create a Traefik ingress controller.
 
-Create a namespace for the load balancer.
+Create a namespace for the ingress controller.
 
 ```bash
 $ kubectl create namespace traefik
@@ -67,15 +48,20 @@ $ helm install traefik-operator traefik/traefik \
 
 3.  Use `helm` to install and start the operator from the directory you just cloned:	 
 
-
     ```bash
     $ helm install sample-weblogic-operator kubernetes/charts/weblogic-operator \
       --namespace sample-weblogic-operator-ns \
-      --set image=oracle/weblogic-kubernetes-operator:3.0.0 \
+      --set image=oracle/weblogic-kubernetes-operator:3.1.0 \
       --set serviceAccount=sample-weblogic-operator-sa \
-      --set "domainNamespaces={}" \
+      --set "enableClusterRoleBinding=true" \
+      --set "domainNamespaceSelectionStrategy=LabelSelector" \
+      --set "domainNamespaceLabelSelector=weblogic-operator\=enabled" \
       --wait
     ```
+
+    This Helm release deploys the operator and configures it to manage Domains in any Kubernetes namespace with the label, "weblogic-operator=enabled". Because of the "enableClusterRoleBinding" option, the operator will have privilege in all Kubernetes namespaces. This simplifies adding and removing managed namespaces as you will only have to adjust labels on those namespaces. If you want to limit the operator's privilege to just the set of namespaces that it will manage, then remove this option, but this will mean that the operator only has privilege in the set of namespaces that match the selection strategy at the time the Helm release was installed or upgraded.
+
+    **Note:** Prior to version 3.1.0, the operator's Helm chart only supported configuring the namespaces that the operator would manage using a list of namespaces. The chart now supports specifying namespaces using a label selector, regular expression, or list. Review the available [Helm configuration values]({{< relref "/userguide/managing-operators/using-the-operator/using-helm#operator-helm-configuration-values" >}}).
 
 4. Verify that the operator's pod is running, by listing the pods in the operator's namespace. You should see one
 for the operator.