Sample

Contents

Before you begin: Perform the steps in Prerequisites and then build a Domain on PV domain creation image by completing the steps in Build the domain creation image. If you are taking the JRF path through the sample, then substitute JRF for WLS in your image names and directory paths. Also note that the JRF-v1 model YAML file differs from the WLS-v1 YAML file (it contains an additional domainInfo -> RCUDbInfo stanza).

Overview

The sample demonstrates setting up a WebLogic domain with a domain home on a Kubernetes PersistentVolume (PV) (Domain on PV). This involves:

  • Using the domain creation image that you previously built.
  • Creating secrets for the domain.
  • Creating a Domain resource YAML file for the domain that:
    • References your Secrets and a WebLogic image.
    • References the domain creation image in the spec.configuration.initializeDomainOnPV section for the initial Domain on PV configuration defined using WDT model YAML.
    • Defines PV and PVC metadata and specifications in the spec.configuration.initializeDomainOnPV section to create a PV and PVC (optional).

PV and PVC Notes:

  • The specifications of PersistentVolume and PersistentVolumeClaim defined in the spec.configuration.initializeDomainOnPV section of the Domain resource YAML file are environment specific and often require information from your Kubernetes cluster administrator to provide the information. See Persistent volume and Persistent Volume Claim in the user documentation for more details.
  • You must use a storage provider that supports the ReadWriteMany option.
  • This sample will automatically set the owner of all files in the domain home on the persistent volume to uid 1000. If you want to use a different user, configure the desired runAsUser and runAsGroup in the security context under the spec.serverPod.podSecurityContext section of the Domain YAML file. The operator will use these values when setting the owner for files in the domain home directory.

After the Domain is deployed, the operator creates the PV and PVC (if they are configured and do not already exist) and starts an ‘introspector job’ that converts your models included in the domain creation image and config map into a WebLogic configuration to initialize the Domain on PV.

Domain creation image

The sample uses a domain creation image with the name wdt-domain-image:WLS-v1 that you created in the Build the domain creation image step. The WDT model files in this image define the initial WebLogic Domain on PV configuration. The image contains:

  • The directory where the WebLogic Deploy Tooling software is installed (also known as WDT Home), expected in an image’s /auxiliary/weblogic-deploy directory, by default.
  • WDT model YAML, property, and archive files, expected in the directory /auxiliary/models, by default.

Deploy resources - Introduction

In this section, you will define the PV and PVC configuration and reference the domain creation image created earlier in the domain resource YAML file. You will then deploy the domain resource YAML file to the namespace sample-domain1-ns, including the following steps:

  • Create a Secret containing your WebLogic administrator user name and password.
  • If your domain type is JRF, create secrets containing your RCU access URL, credentials, and prefix.
  • Deploy a Domain YAML file that references the PV/PVC configuration and a domain creation image under the spec.configuration.initializeDomainOnPV section.
  • Wait for the PV and PVC to be created if they do not already exist.
  • Wait for domain’s Pods to start and reach their ready state.

Secrets

First, create the secrets needed by both WLS and JRF type model domains. You have to create the “WebLogic credentials secret” and any other secrets that are referenced from the macros in the WDT model file. For more details about using macros in the WDT model files, see Working with the WDT model files.

Run the following kubectl commands to deploy the required secrets:

NOTE: Substitute a password of your choice for MY_WEBLOGIC_ADMIN_PASSWORD. This password should contain at least seven letters plus one digit.

$ kubectl -n sample-domain1-ns create secret generic \
  sample-domain1-weblogic-credentials \
   --from-literal=username=weblogic --from-literal=password=MY_WEBLOGIC_ADMIN_PASSWORD

$ kubectl -n sample-domain1-ns label  secret \
  sample-domain1-weblogic-credentials \
  weblogic.domainUID=sample-domain1

Some important details about these secrets:

  • The WebLogic credentials secret is required and must contain username and password fields. You reference it in spec.webLogicCredentialsSecret field of Domain YAML file and macros in the domainInfo.AdminUserName and domainInfo.AdminPassWord fields your model YAML file.
  • Delete a secret before creating it, otherwise the create command will fail if the secret already exists..
  • Name and label the secrets using their associated domain UID to clarify which secrets belong to which domains and make it easier to clean up a domain.

If you’re following the JRF path through the sample, then you also need to deploy the additional secret referenced by macros in the JRF model RCUDbInfo clause, plus an OPSS wallet password secret. For details about the uses of these secrets, see the Domain on PV user documentation.

Click here for the commands for deploying additional secrets for JRF.

Domain resource

Now, you deploy a sample-domain1 domain resource and an associated sample-domain1-cluster-1 cluster resource using a single YAML resource file which defines both resources. The domain resource and cluster resource tells the operator how to deploy a WebLogic domain. They do not replace the traditional WebLogic configuration files, but instead cooperate with those files to describe the Kubernetes artifacts of the corresponding domain.

Copy the contents of the WLS domain resource YAML file file that is included in the sample source to a file called /tmp/sample/domain-resource.yaml or similar.

Click here to view the WLS Domain YAML file.

Click here to view the JRF Domain YAML file.

Modify the PV and PVC specifications defined in the spec.configuration.initializeDomainOnPV section of the Domain resource YAML file based on your environment. These specifications often require your Kubernetes cluster administrator to provide the information. See Persistent volume and Persistent Volume Claim in the user documentation for more details.

By default, this sample creates a Persistent Volume (PV) of type hostPath. This works only for a single node Kubernetes cluster for testing or proof of concept activities. In a multinode Kubernetes cluster, consider using a Kubernetes StorageClass, or PV of nfs type. If you use Oracle Container Engine for Kubernetes (OKE) and plan to use Oracle Cloud Infrastructure File Storage (FSS) for PV, then Oracle recommends creating a StorageClass and specifying the name of the StorageClass in your PersistentVolumeClaim (PVC) configuration in the initializeDomainOnPV section. See Provisioning PVCs on the File Storage Service (FSS) in the OCI documentation for more details.

NOTE: Before you deploy the domain custom resource, ensure all nodes in your Kubernetes cluster can access domain-creation-image and other images.

Run the following command to apply the two sample resources.

$ kubectl apply -f /tmp/sample/domain-resource.yaml

The domain resource references the cluster resource, a WebLogic Server installation image, the secrets you defined, PV and PVC configuration details, and a sample domain creation image, which contains a traditional WebLogic configuration and a WebLogic application. For detailed information, see Domain and cluster resources.

Verify the PV, PVC, and domain

To confirm that the PV, PVC, and domain were created, use the following instructions.

Verify the persistent volume

If the spec.configuration.initializeDomainOnPV.persistentVolume is configured for the operator to create the PV, then verify that a PV with the given name is created and is in Bound status. If the PV already exists, then ensure that the existing PV is in Bound status.

$ kubectl get pv

Here is an example output of this command:

NAME                                CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM                                                  STORAGECLASS   REASON   AGE
sample-domain1-weblogic-sample-pv   5Gi        RWX            Retain           Bound    sample-domain1-ns/sample-domain1-weblogic-sample-pvc   manual                  14m

Verify the persistent volume claim

If the spec.configuration.initializeDomainOnPV.persistentVolumeClaim is configured for the operator to create the PVC, then verify that the PVC with the given name is created and is in Bound status. If the PVC already exists, then ensure that the existing PVC is in Bound status.

$ kubectl get pvc -n sample-domain1-ns

Here is an example output of this command:

NAME                                 STATUS   VOLUME                              CAPACITY   ACCESS MODES   STORAGECLASS   AGE
sample-domain1-weblogic-sample-pvc   Bound    sample-domain1-weblogic-sample-pv   5Gi        RWX            manual         11m

Verify the domain

Run the following kubectl describe domain command to check the status and events for the created domain.

$ kubectl describe domain sample-domain1 -n sample-domain1-ns
Click here to see an example of the output of this command.

In the Status section of the output, the available servers and clusters are listed. Note that if this command is issued very soon after the domain resource is applied, there may be no servers available yet, or perhaps only the Administration Server but no Managed Servers. The operator will start up the Administration Server first and wait for it to become ready before starting the Managed Servers.

Verify the pods

If you run kubectl get pods -n sample-domain1-ns --watch, then you will see the introspector job run and your WebLogic Server pods start. The output will look something like this:

Click here to expand.

For a more detailed view of this activity, you can use the waitForDomain.sh sample lifecycle script. This script provides useful information about a domain’s pods and optionally waits for its Completed status condition to become True. A Completed domain indicates that all of its expected pods have reached a ready state plus their target restartVersion, introspectVersion, and image. For example:

$ cd /tmp/weblogic-kubernetes-operator/kubernetes/samples/scripts/domain-lifecycle
$ ./waitForDomain.sh -n sample-domain1-ns -d sample-domain1 -p Completed

If you see an error, then consult Debugging.

Verify the services

Use the following command to see the services for the domain:

$ kubectl get services -n sample-domain1-ns

Here is an example output of this command:

NAME                               TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
sample-domain1-admin-server        ClusterIP   None             <none>        7001/TCP   10m
sample-domain1-cluster-cluster-1   ClusterIP   10.107.178.255   <none>        8001/TCP   9m49s
sample-domain1-managed-server1     ClusterIP   None             <none>        8001/TCP   9m49s
sample-domain1-managed-server2     ClusterIP   None             <none>        8001/TCP   9m43s

Invoke the web application

Now that all the sample resources have been deployed, you can invoke the sample web application through the Traefik ingress controller’s NodePort.

  • Send a web application request to the load balancer URL for the application, as shown in the following example.

        $ curl -s -S -m 10 -H 'host: sample-domain1-cluster-cluster-1.sample.org' http://localhost:30305/myapp_war/index.jsp

        $ K8S_CLUSTER_ADDRESS=$(kubectl cluster-info | grep DNS | sed 's/^.*https:\/\///g' | sed 's/:.*$//g')

    $ curl -s -S -m 10 -H 'host: sample-domain1-cluster-cluster-1.sample.org' http://${K8S_CLUSTER_ADDRESS}:30305/myapp_war/index.jsp

  • You will see output like the following:

       <html><body><pre>
   *****************************************************************

   Hello World! This is version 'v1' of the sample JSP web-app.

   Welcome to WebLogic Server 'managed-server2'!

     domain UID  = 'sample-domain1'
     domain name = 'domain1'

   Found 1 local cluster runtime:
     Cluster 'cluster-1'

   Found min threads constraint runtime named 'SampleMinThreads' with configured count: 1

   Found max threads constraint runtime named 'SampleMaxThreads' with configured count: 10

   Found 0 local data sources:

   *****************************************************************
   </pre></body></html>

Clean up resources and remove the generated domain home

Follow the cleanup instructions here to remove the domain, cluster and other associated resources.

Sometimes in production, but most likely in testing environments, you might also want to remove the Domain on PV contents that are generated using this sample. You can use the pv-pvc-helper.sh helper script in the domain lifecycle directory for this. The script launches a Kubernetes pod named pvhelper using the provided persistent volume claim name and the mount path. You can run kubectl exec to get a shell to the running pod container and run commands to examine or clean up the contents of shared directories on the persistent volume. For example:

$ cd /tmp/weblogic-kubernetes-operator/kubernetes/samples/scripts/domain-lifecycle
$ ./pv-pvc-helper.sh -n sample-domain1-ns -r -c sample-domain1-weblogic-sample-pvc -m /shared
Click here to see the output.

After you get a shell to the running pod container, you can recursively delete the contents of the domain home and applications directories using rm -rf /shared/domains/sample-domain1 and rm -rf /shared/applications/sample-domain1 commands. Since these commands will actually delete files on the persistent storage, we recommend that you understand and execute these commands carefully.

Remove the PVC and PV

If the PVC and PV were created by the operator and you don’t want to preserve them, then run following command to delete PVC and PV.

$ kubectl delete pvc sample-domain1-weblogic-sample-pvc -n sample-domain1-ns
$ kubectl delete pv sample-domain1-weblogic-sample-pv

Delete the domain namespace.

$ kubectl delete namespace sample-domain1-ns