Merge remote-tracking branch 'origin/master' into develop

Author: rjeberhard

docs-source/content/samples/simple/azure-kubernetes-service/_index.md

@@ -0,0 +1,13 @@
+The output from the `create-domain-on-aks.sh` script includes a statement about the Azure resources created by the script.  To delete the cluster and free all related resources, simply delete the resource groups.  The output will list the resource groups, such as.
+
+```bash
+The following Azure resouces have been created:
+  Resource groups: ejb8191resourcegroup1597641911, MC_ejb8191resourcegroup1597641911_ejb8191akscluster1597641911_eastus
+```
+
+Given the above output, the following Azure CLI commands will delete the resource groups.
+
+```bash
+az group delete --yes --no-wait --name ejb8191resourcegroup1597641911
+az group delete --yes --no-wait --name MC_ejb8191resourcegroup1597641911_ejb8191akscluster1597641911_eastus
+```

docs-source/content/samples/simple/azure-kubernetes-service/domain-on-pv.md

@@ -0,0 +1,6 @@
+```bash
+$ az group delete --yes --no-wait --name $AKS_PERS_RESOURCE_GROUP
+$ az group delete --yes --no-wait --name "MC_$AKS_PERS_RESOURCE_GROUP"_"$AKS_CLUSTER_NAME"_"$AKS_PERS_LOCATION"
+$ az ad sp delete --id $SP_APP_ID
+```
+

docs-source/content/samples/simple/azure-kubernetes-service/includes/clean-up-resources-body-01.txt

@@ -0,0 +1,82 @@
+##### Create a Service Principal for AKS
+
+An AKS cluster requires either an [Azure Active Directory (AD) service principal](https://docs.microsoft.com/azure/active-directory/develop/app-objects-and-service-principals) or a [managed identity](https://docs.microsoft.com/azure/aks/use-managed-identity) to interact with Azure resources.
+
+We will use a service principal to create an AKS cluster. Follow the commands below to create a new service principal.
+
+Please run `az login` first. Do set the subscription you want to work with. You can get a list of your subscriptions by running `az account list`.
+
+```bash
+# Login
+$ az login
+
+# Set your working subscription
+$ export SUBSCRIPTION_ID=<your-subscription-id>
+$ az account set -s $SUBSCRIPTION_ID
+```
+
+Create the new service principal with the following commands:
+
+```bash
+# Create Service Principal
+$ export SP_NAME=myAKSClusterServicePrincipal
+$ az ad sp create-for-rbac --skip-assignment --name $SP_NAME
+
+# Copy the output to a file, we will use it later.
+```
+
+If you see an error similar to the following:
+
+```bash
+Found an existing application instance of "5pn2s201-nq4q-43n1-z942-p9r9571qr3rp". We will patch it
+Insufficient privileges to complete the operation.
+```
+
+The problem may be a pre-existing service principal with the same name.  Either delete the other Service Principal or pick a different name.
+
+Successful output will look like the following:
+
+```json
+{
+  "appId": "r3qnq743-61s9-4758-8163-4qpo87s72s54",
+  "displayName": "myAKSClusterServicePrincipal",
+  "name": "http://myAKSClusterServicePrincipal",
+  "password": "TfhR~uOJ1C1ftD5NS_LzJJj6UOjS2OwXfz",
+  "tenant": "82sr215n-0ns5-404e-9161-206r0oqyq999"
+}
+```
+
+Grant your service principal with a contributor role to create AKS resources.
+
+```bash
+# Use the <appId> from the output of the last command
+$ export SP_APP_ID=r3qnq743-61s9-4758-8163-4qpo87s72s54
+$ az role assignment create --assignee $SP_APP_ID --role Contributor
+```
+
+Successful output will look like the following:
+
+```json
+{
+  "canDelegate": null,
+  "id": "/subscriptions/p7844r91-o11q-4n7s-np6s-996308sopqo9/providers/Microsoft.Authorization/roleAssignments/4oq396os-rs95-4n6s-n3qo-sqqpnpo91035",
+  "name": "4oq396os-rs95-4n6s-n3qo-sqqpnpo91035",
+  "principalId": "952551r8-n129-4on3-oqo9-231n0s6011n3",
+  "principalType": "ServicePrincipal",
+  "roleDefinitionId": "/subscriptions/p7844r91-o11q-4n7s-np6s-996308sopqo9/providers/Microsoft.Authorization/roleDefinitions/o24988np-6180-42n0-no88-20s7382qq24p",
+  "scope": "/subscriptions/p7844r91-o11q-4n7s-np6s-996308sopqo9",
+}
+```
+
+##### Oracle Container Registry
+
+You will need an Oracle account. The following steps will direct you to accept the license agreement for WebLogic Server.  Make note of your Oracle Account password and email.  This sample pertains to 12.2.1.4, but other versions may work as well.
+
+  - In a web browser, navigate to https://container-registry.oracle.com and log in using the Oracle Single Sign-On authentication service. If you do not already have SSO credentials, at the top of the page, click the **Sign In** link to create them.
+  - The Oracle Container Registry provides a WebLogic Server 12.2.1.4.0 Docker image, which already has the necessary patches applied, and the Oracle WebLogic Server 12.2.1.4.0 and 14.1.1.0.0 images, which do not require any patches.
+  - Ensure Docker desktop is running.  Find and then pull the WebLogic 12.2.1.4 install image:
+     ```bash
+     $ docker pull container-registry.oracle.com/middleware/weblogic:12.2.1.4
+     ```
+
+   If you have problems accessing the Oracle Container Registry, you can build your own docker images from the [Oracle GitHub repository](https://github.com/oracle/docker-images/tree/main/OracleWebLogic/dockerfiles).

docs-source/content/samples/simple/azure-kubernetes-service/includes/clean-up-resources-body-02.txt

@@ -0,0 +1,54 @@
+#### Create the AKS cluster
+
+This sample requires that you disable the AKS addon `http_application_routing` by default.  If you want to enable  `http_application_routing`, please follow [HTTP application routing](https://docs.microsoft.com/azure/aks/http-application-routing).
+
+Run the following commands to create the AKS cluster instance.
+
+```bash
+# Change these parameters as needed for your own environment
+# Specify a prefix to name resources, only allow lowercase letters and numbers, between 1 and 7 characters
+$ export NAME_PREFIX=wls
+# Used to generate resource names.
+$ export TIMESTAMP=`date +%s`
+$ export AKS_CLUSTER_NAME="${NAME_PREFIX}aks${TIMESTAMP}"
+$ export AKS_PERS_RESOURCE_GROUP="${NAME_PREFIX}resourcegroup${TIMESTAMP}"
+$ export AKS_PERS_LOCATION=eastus
+$ export SP_APP_ID=<appId from the az ad sp create-for-rbac command>
+$ export SP_CLIENT_SECRET=<password from the az ad sp create-for-rbac command>
+
+$ az group create --name $AKS_PERS_RESOURCE_GROUP --location $AKS_PERS_LOCATION
+$ az aks create \
+   --resource-group $AKS_PERS_RESOURCE_GROUP \
+   --name $AKS_CLUSTER_NAME \
+   --node-count 2 \
+   --generate-ssh-keys \
+   --nodepool-name nodepool1 \
+   --node-vm-size Standard_DS2_v2 \
+   --location $AKS_PERS_LOCATION \
+   --service-principal $SP_APP_ID \
+   --client-secret $SP_CLIENT_SECRET
+```
+
+Successful output will be a JSON object with the entry `"type": "Microsoft.ContainerService/ManagedClusters"`.
+
+After the deployment finishes, run the following command to connect to the AKS cluster. This command updates your local `~/.kube/config` so that subsequent `kubectl` commands interact with the named AKS cluster.
+
+```bash
+$ az aks get-credentials --resource-group $AKS_PERS_RESOURCE_GROUP --name $AKS_CLUSTER_NAME
+```
+
+Successful output will look similar to:
+
+```bash
+Merged "wlsaks1596087429" as current context in /home/username/.kube/config
+```
+
+After your Kubernetes cluster is up and running, run the following commands to make sure kubectl can access the Kubernetes cluster:
+
+```shell
+$ kubectl get nodes -o wide
+NAME                                  STATUS   ROLES   AGE     VERSION    INTERNAL-IP   EXTERNAL-IP   OS-IMAGE             KERNEL-VERSION      CONTAINER-RUNTIME
+aks-pool1haiche-33688868-vmss000000   Ready    agent   4m25s   v1.17.13   10.240.0.4    <none>        Ubuntu 16.04.7 LTS   4.15.0-1098-azure   docker://19.3.12
+aks-pool1haiche-33688868-vmss000001   Ready    agent   4m12s   v1.17.13   10.240.0.5    <none>        Ubuntu 16.04.7 LTS   4.15.0-1098-azure   docker://19.3.12
+```
+

docs-source/content/samples/simple/azure-kubernetes-service/includes/create-aks-cluster-body-01.txt

@@ -0,0 +1,182 @@
+#### Create storage and set up file share
+
+Our usage pattern for the operator involves creating Kubernetes "persistent volumes" to allow the WebLogic Server to persist its configuration and data separately from the Kubernetes Pods that run WebLogic Server workloads.
+
+We will create an external data volume to access and persist data. There are several options for data sharing as described in [Storage options for applications in Azure Kubernetes Service (AKS)](https://docs.microsoft.com/azure/aks/concepts-storage).
+
+We will use Azure Files as a Kubernetes volume. Consult the [Azure Files Documentation](https://docs.microsoft.com/azure/aks/azure-files-volume) for details about this full featured cloud storage solution.
+
+##### Create an Azure Storage account
+
+Create a storage account using Azure CLI. Note that the storage account name can contain only lowercase letters and numbers, and must be between 3 and 24 characters in length:
+
+```bash
+# Change the value as needed for your own environment
+$ export AKS_PERS_STORAGE_ACCOUNT_NAME="${NAME_PREFIX}storage${TIMESTAMP}"
+
+$ az storage account create \
+   -n $AKS_PERS_STORAGE_ACCOUNT_NAME \
+   -g $AKS_PERS_RESOURCE_GROUP \
+   -l $AKS_PERS_LOCATION \
+   --sku Standard_LRS
+```
+
+Successful output will be a JSON object with the entry `"type": "Microsoft.Storage/storageAccounts"`.
+
+Now we need to create a file share. To create the file share, you need a storage connection string. Run the `show-connection-string` command to get connection string, then create the share with `az storage share create`, as shown here.
+
+```bash
+# Change value as needed for your own environment
+$ export AKS_PERS_SHARE_NAME="${NAME_PREFIX}-weblogic-${TIMESTAMP}"
+# Get connection string
+$ export AZURE_STORAGE_CONNECTION_STRING=$(az storage account show-connection-string -n $AKS_PERS_STORAGE_ACCOUNT_NAME -g $AKS_PERS_RESOURCE_GROUP -o tsv)
+# Create file share
+$ az storage share create -n $AKS_PERS_SHARE_NAME --connection-string $AZURE_STORAGE_CONNECTION_STRING
+```
+
+Successful output will be exactly the following:
+
+```bash
+{
+  "created": true
+}
+```
+
+The operator uses Kubernetes Secrets.  We need a storage key for the secret. These commands query the storage account to obtain the key, and then stores the storage account key as a Kubernetes secret.
+
+```bash
+$ export STORAGE_KEY=$(az storage account keys list --resource-group $AKS_PERS_RESOURCE_GROUP --account-name $AKS_PERS_STORAGE_ACCOUNT_NAME --query "[0].value" -o tsv)
+```
+
+Verify the successful output by examining the `STORAGE_KEY` environment variable.  It must not be empty.  It must be a long ASCII string.
+
+We will use the `kubernetes/samples/scripts/create-kuberetes-secrets/create-azure-storage-credentials-secret.sh` script to create the storage account key as a Kubernetes secret, naming the secret with value `${NAME_PREFIX}azure-secret`. Please run:
+
+```bash
+# Please change persistentVolumeClaimNameSuffix if you changed pre-defined value "regcred" before generating the configuration files.
+$ export SECRET_NAME_AZURE_FILE="${NAME_PREFIX}azure-secret"
+
+#cd kubernetes/samples/scripts/create-kuberetes-secrets
+$ ./create-azure-storage-credentials-secret.sh -s $SECRET_NAME_AZURE_FILE -a $AKS_PERS_STORAGE_ACCOUNT_NAME -k $STORAGE_KEY
+```
+
+You will see the following output:
+
+```text
+secret/wlsazure-secret created
+The secret wlsazure-secret has been successfully created in the default namespace.
+```
+
+##### Create PV and PVC
+
+This sample uses Kubernetes Persistent Volume Claims (PVC) as storage resource.  These features are passed to Kubernetes using YAML files.  The script `kubernetes/samples/scripts/create-weblogic-domain-on-azure-kubernetes-service/create-domain-on-aks.sh` generates the required configuration files automatically, given an input file containing the parameters.  A parameters file is provided at `kubernetes/samples/scripts/create-weblogic-domain-on-azure-kubernetes-service/create-domain-on-aks-inputs.yaml`.  Copy and customize this file for your needs.
+
+To generate YAML files to create PV and PVC in the AKS cluster, the following values must be substituted in your copy of the input file.
+
+| Name in YAML file | Example value | Notes |
+|-------------------|---------------|-------|
+| `azureServicePrincipalAppId` | `nr086o75-pn59-4782-no5n-nq2op0rsr1q6` | Application ID of your service principal; refer to the application ID in the [Create Service Principal]({{< relref "/samples/simple/azure-kubernetes-service/domain-on-pv#create-a-service-principal-for-aks" >}}) section. |
+| `azureServicePrincipalClientSecret` | `8693089o-q190-45ps-9319-or36252s3s90` | A client secret of your service principal; refer to the client secret in the [Create Service Principal]({{< relref "/samples/simple/azure-kubernetes-service/domain-on-pv#create-a-service-principal-for-aks" >}}) section. |
+| `azureServicePrincipalTenantId` | `72s988os-86s1-cafe-babe-2q7pq011qo47` | Tenant (Directory ) ID of your service principal; refer to the client secret in the [Create Service Principal]({{< relref "/samples/simple/azure-kubernetes-service/domain-on-pv#create-a-service-principal-for-aks" >}}) section. |
+| `dockerEmail` | `yourDockerEmail` | Oracle Single Sign-On (SSO) account email, used to pull the WebLogic Server Docker image. |
+| `dockerPassword` | `yourDockerPassword`| Password for Oracle SSO account, used to pull the WebLogic Server Docker image.  In clear text. |
+| `dockerUserName` | `yourDockerId` | The same value as `dockerEmail`.  |
+| `namePrefix` | `wls` | Alphanumeric value used as a disambiguation prefix for several Kubernetes resources. Make sure the value matches the value of `${NAME_PREFIX}` to keep names in step-by-step commands the same with those in configuration files. |
+
+Use the following command to generate configuration files, assuming the output directory is `~/azure`.  The script will overwrite any files generated by a previous invocation.
+
+```bash
+#cd kubernetes/samples/scripts/create-weblogic-domain-on-azure-kubernetes-service
+$ cp create-domain-on-aks-inputs.yaml my-create-domain-on-aks-inputs.yaml
+$ ./create-domain-on-aks.sh -i my-create-domain-on-aks-inputs.yaml -o ~/azure -u ${TIMESTAMP}
+```
+
+After running the command, all needed configuration files are generated and output to `~/azure/weblogic-on-aks`:
+
+```bash
+The following files were generated:
+  /home/username/azure/weblogic-on-aks/pv.yaml
+  /home/username/azure/weblogic-on-aks/pvc.yaml
+  /home/username/azure/weblogic-on-aks/admin-lb.yaml
+  /home/username/azure/weblogic-on-aks/cluster-lb.yaml
+  /home/username/azure/weblogic-on-aks/domain1.yaml
+  /home/username/azure/weblogic-on-aks/cluster-admin-role.yaml
+
+Completed
+```
+
+**Note:** Beyond the required and default configurations generated by the command, you can modify the generated YAML files to further customize your deployment. Please consult the operator documentation, [AKS documentation](https://docs.microsoft.com/en-us/azure/aks/) and Kubernetes references for further information about customizing your deployment.
+
+##### Apply generated configuration files
+
+In order to mount the file share as a persistent volume, we have provided a configuration file `pv.yaml`. You can find it in your output directory. The following content is an example that uses the value `wls-weblogic` as "shareName", `wlsazure-secret` as "secretName", and the persistent volume name is `wls-azurefile`.
+
+We will use the storage class `azurefile`. If you want to create a new class, follow this document [Create a storage class](https://docs.microsoft.com/en-us/azure/aks/azure-files-dynamic-pv#create-a-storage-class). For more information, see the page [Storage options for applications in Azure Kubernetes Service (AKS)](https://docs.microsoft.com/en-us/azure/aks/concepts-storage#storage-classes).
+
+```yaml
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: wls-azurefile
+spec:
+  capacity:
+    storage: 5Gi
+  accessModes:
+    - ReadWriteMany
+  storageClassName: azurefile
+  azureFile:
+    secretName: wlsazure-secret
+    shareName: wls-weblogic-1597391432
+    readOnly: false
+  mountOptions:
+  - dir_mode=0777
+  - file_mode=0777
+  - uid=1000
+  - gid=1000
+  - mfsymlinks
+  - nobrl
+```
+
+We have provided another configuration file `pvc.yaml` for the PersistentVolumeClaim.  Both `pv.yaml` and `pvc.yaml` have exactly the same content for `storageClassName` attributes. This is required. We set the same value to the `metadata` property in both files. The following content is an example that uses the persistent volume claim name `wls-azurefile`.
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: wls-azurefile
+spec:
+  accessModes:
+    - ReadWriteMany
+  storageClassName: azurefile
+  resources:
+    requests:
+      storage: 5Gi
+```
+
+Use the `kubectl` command to create the persistent volume and persistent volume claim to `default` namespace.
+
+```bash
+$ kubectl apply -f ~/azure/weblogic-on-aks/pv.yaml
+persistentvolume/wls-azurefile created
+$ kubectl apply -f ~/azure/weblogic-on-aks/pvc.yaml
+persistentvolumeclaim/wls-azurefile created
+```
+
+Use the following command to verify:
+
+```bash
+$ kubectl get pv,pvc
+```
+
+Example output:
+
+```bash
+$ kubectl get pv,pvc
+NAME                                          CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM                                STORAGECLASS   REASON   AGE
+persistentvolume/wls-azurefile   5Gi        RWX            Retain           Bound    default/wls-azurefile   azurefile               16m
+
+NAME                                               STATUS   VOLUME                       CAPACITY   ACCESS MODES   STORAGECLASS   AGE
+persistentvolumeclaim/wls-azurefile   Bound    wls-azurefile   5Gi        RWX            azurefile      16m
+```
+
+> **Note**: Carefully inspect the output and verify it matches the above. `ACCESS MODES`, `CLAIM`, and `STORAGECLASS` are vital.

docs-source/content/samples/simple/azure-kubernetes-service/includes/create-aks-cluster-body-02.txt

@@ -0,0 +1,10 @@
+#### Prerequisites
+
+This sample assumes the following prerequisite environment.
+
+* Operating System: GNU/Linux, macOS or [WSL2 for Windows 10](https://docs.microsoft.com/windows/wsl/install-win10).
+* [Git](https://git-scm.com/downloads), use `git --version` to test if `git` works.  This document was tested with version 2.17.1.
+* [Azure CLI](https://docs.microsoft.com/cli/azure), use `az --version` to test if `az` works.  This document was tested with version 2.9.1.
+* [Docker for Desktop](https://www.docker.com/products/docker-desktop).  This document was tested with `Docker version 20.10.2, build 2291f61`
+* [kubectl](https://kubernetes-io-vnext-staging.netlify.com/docs/tasks/tools/install-kubectl/), use `kubectl version` to test if `kubectl` works.  This document was tested with version v1.16.3.
+* [helm](https://helm.sh/docs/intro/install/), version 3.1 and later, use `helm version` to check the `helm` version.  This document was tested with version v3.2.4.

docs-source/content/samples/simple/azure-kubernetes-service/includes/create-aks-cluster-storage.txt

@@ -0,0 +1,12 @@
+#### Prerequisites
+
+This sample assumes the following prerequisite environment.
+
+* Operating System: GNU/Linux, macOS or [WSL2 for Windows 10](https://docs.microsoft.com/windows/wsl/install-win10).
+* [Git](https://git-scm.com/downloads), use `git --version` to test if `git` works.  This document was tested with version 2.17.1.
+* [Azure CLI](https://docs.microsoft.com/cli/azure), use `az --version` to test if `az` works.  This document was tested with version 2.9.1.
+* [Docker for Desktop](https://www.docker.com/products/docker-desktop).  This document was tested with `Docker version 20.10.2, build 2291f61`
+* [kubectl](https://kubernetes-io-vnext-staging.netlify.com/docs/tasks/tools/install-kubectl/), use `kubectl version` to test if `kubectl` works.  This document was tested with version v1.16.3.
+* [Helm](https://helm.sh/docs/intro/install/), version 3.1 and later, use `helm version` to check the `helm` version.  This document was tested with version v3.2.4.
+* A Java JDK, Version 8 or 11. Azure recommends [Azul Zulu for Azure](https://www.azul.com/downloads/azure-only/zulu/). Ensure your `JAVA_HOME` environment variable is set correctly in the shells in which you run the commands.
+* Ensure you have the zip/unzip utility installed, use `zip/unzip -v` to test if `zip/unzip` works.