Auxiliary images

Contents

Introduction

The auxiliary images feature is a work in progress and is currently unsupported. Its configuration or behavior may change between releases and it is disabled by default. If you want to enable this feature, then set your operator’s "featureGates" Helm configuration attribute to include "AuxiliaryImage=true". The "featureGates" attribute acknowledges use of an unsupported feature, will not be required after auxiliary images are fully supported, defaults to being unset, and accepts a comma-separated list.

Auxiliary images are an alternative approach for including Model in Image model files, application archive files, WebLogic Deploying Tooling installation files, or other types of files, in your pods. This feature eliminates the need to provide these files in the image specified in domain.spec.image.

Instead:

  • The domain resource’s domain.spec.image directly references a base image that needs to include only a WebLogic installation and a Java installation.
  • The domain resource’s auxiliary image related fields reference one or more smaller images that contain the desired Model in Image files.
  • The domain resource’s domain.spec.configuration.model.wdtInstallHome and domain.spec.configuration.model.modelHome fields are set to reference a directory that contains the files from the smaller images.

The advantages of auxiliary image for Model In Image domains are:

  • Use or patch a WebLogic installation image without needing to include a WDT installation, application archive, or model artifacts within the image.
  • Share one WebLogic installation image with multiple different model configurations that are supplied in specific images.
  • Distribute or update model files, application archives, and the WebLogic Deploy Tooling executable using specific images that do not contain a WebLogic installation.

Auxiliary images internally use a Kubernetes emptyDir volume and Kubernetes init containers to share files from additional images.

References

  • Run the kubectl explain domain.spec.auxiliaryImageVolumes and kubectl explain domain.spec.serverPod.auxiliaryImages commands.

  • See the spec.auxiliaryImageVolumes and serverPod.auxiliaryImages sections in the domain resource schema and documentation.

Configuration

This section describes a typical auxiliary image configuration for the Model in Image use case.

Auxiliary images

One or more auxiliary images can be configured on a domain resource serverPod. A serverPod can be defined at the domain scope, which applies to every pod in the domain, plus the introspector job’s pod, at a specific WebLogic cluster’s scope, or at a specific WebLogic Server pod’s scope. Typically, the domain scope is the most applicable for the Model in Image use case; for example:

spec:
  serverPod:
    auxiliaryImages:
    - image: model-in-image:v1
      imagePullPolicy: IfNotPresent
      volume: auxiliaryImageVolume1

If image pull secrets are required for pulling auxiliary images, then the secrets must be referenced using domain.spec.imagePullSecrets.

Auxiliary volumes and paths

The serverPod.auxiliaryImages.volume field refers to the name of an auxiliary image volume defined in the domain.spec.auxiliaryImageVolumes section, and an auxiliary image volume, in turn, defines a mountPath. The mountPath is the location of a directory in an auxiliary image, and is also the location in the main pod container (which will automatically contain a recursive copy of the auxiliary image directory). For example:

  spec:
    auxiliaryImageVolumes:
    - name: auxiliaryImageVolume1
      mountPath: /auxiliary

Model in Image paths

For the Model In Image auxiliary image use case, you also need to configure the domain.spec.configuration.model.modelHome and domain.spec.configuration.model.wdtInstallHome attributes to specify the location of the domain’s WebLogic Deploy Tool (WDT) model files and the domain’s WDT installation. These default to /u01/wdt/models and /u01/wdt/weblogic-deploy respectively, and must be changed to specify a directory in domain.spec.auxiliaryImageVolumes.mountPath. For example:

  configuration:
    model:
      modelHome: "/auxiliary/models"
      wdtInstallHome: "/auxiliary/weblogic-deploy"

Sample

This sample demonstrates deploying a Model in Image domain that uses auxiliary images to supply the domain’s WDT model files, application archive ZIP files, and WDT installation in a small, separate container image.

Step 1: Prerequisites

  • First, follow all of the steps in the Model in Image initial use case sample.

    This will:

    • Set up the operator and a namespace for the domain.
    • Download a WebLogic Deploy Tool ZIP installation.
    • Deploy a domain without auxiliary images.
  • Second, shut down the domain and wait for its pods to exit.

    • You can use the wl-pod-wait.sh script to wait.
    • For example, assuming that you have set up /tmp/mii-sample as your working directory:
      $ kubectl delete domain sample-domain1 -n sample-domain1-ns
      $ /tmp/mii-sample/utils/wl-pod-wait.sh -p 0
      

Step 2: Create the auxiliary image

Follow these steps to create a auxiliary image containing Model In Image model files, application archives, and the WDT installation files:

  1. Create a model ZIP application archive and place it in the same directory where the model YAML file and model properties files are already in place for the initial use case:

    $ rm -f /tmp/mii-sample/model-images/model-in-image__WLS-AI-v1/archive.zip
    $ cd /tmp/mii-sample/archives/archive-v1
    $ zip -r /tmp/mii-sample/model-images/model-in-image__WLS-AI-v1/archive.zip wlsdeploy
    

    The rm -f command is included in case there’s an old version of the archive ZIP from a previous run of this sample.

  2. Create a temporary directory for staging the auxiliary image’s files and cd to this directory:

    $ mkdir -p /tmp/mii-sample/ai-image/WLS-AI-v1
    $ cd /tmp/mii-sample/ai-image/WLS-AI-v1
    

    We call this directory WLS-AI-v1 to correspond with the image version tag that we plan to use for the auxiliary image.

  3. Install WDT in the staging directory and remove its weblogic-deploy/bin/*.cmd files, which are not used in UNIX environments:

    $ unzip /tmp/mii-sample/model-images/weblogic-deploy.zip -d .
    $ rm ./weblogic-deploy/bin/*.cmd
    

    In a later step, we will specify a domain resource domain.spec.configuration.model.wdtInstallHome attribute that references this WDT installation directory.

    If the weblogic-deploy.zip file is missing, then you have skipped a step in the prerequisites.

  4. Create a models directory in the staging directory and copy the model YAML file, properties, and archive into it:

    $ mkdir ./models
    $ cp /tmp/mii-sample/model-images/model-in-image__WLS-AI-v1/model.10.yaml ./models
    $ cp /tmp/mii-sample/model-images/model-in-image__WLS-AI-v1/model.10.properties ./models
    $ cp /tmp/mii-sample/model-images/model-in-image__WLS-AI-v1/archive.zip ./models
    

    In a later step, we will specify a domain resource domain.spec.configuration.model.modelHome attribute that references this directory.

  5. Run docker build using /tmp/mii-sample/ai-docker-file/Dockerfile to create your auxiliary image using a small busybox image as the base image.

    $ docker build -f /tmp/mii-sample/ai-docker-file/Dockerfile \
      --build-arg AUXILIARY_IMAGE_PATH=/auxiliary \
      --tag model-in-image:WLS-AI-v1 .
    

    See ./Dockerfile for an explanation of each build argument.

    Click here to view the Dockerfile.
  6. After the image is created, it should have the WDT executables in /auxiliary/weblogic-deploy, and WDT model, property, and archive files in /auxiliary/models. You can run ls in the Docker image to verify this:

    $ docker run -it --rm model-in-image:WLS-AI-v1 ls -l /auxiliary
      total 8
      drwxr-xr-x    1 oracle   root          4096 Jun  1 21:53 models
      drwxr-xr-x    1 oracle   root          4096 May 26 22:29 weblogic-deploy
    
    $ docker run -it --rm model-in-image:WLS-AI-v1 ls -l /auxiliary/models
      total 16
      -rw-rw-r--    1 oracle   root          5112 Jun  1 21:52 archive.zip
      -rw-rw-r--    1 oracle   root           173 Jun  1 21:59 model.10.properties
      -rw-rw-r--    1 oracle   root          1515 Jun  1 21:59 model.10.yaml
    
    $ docker run -it --rm model-in-image:WLS-AI-v1 ls -l /auxiliary/weblogic-deploy
      total 28
      -rw-r-----    1 oracle   root          4673 Oct 22  2019 LICENSE.txt
      -rw-r-----    1 oracle   root            30 May 25 11:40 VERSION.txt
      drwxr-x---    1 oracle   root          4096 May 26 22:29 bin
      drwxr-x---    1 oracle   root          4096 May 25 11:40 etc
      drwxr-x---    1 oracle   root          4096 May 25 11:40 lib
      drwxr-x---    1 oracle   root          4096 Jan 22  2019 samples
    
    

Step 3: Prepare and apply the domain resource

Copy the following to a file called /tmp/mii-sample/mii-initial.yaml or similar, or you can directly use the file /tmp/mii-sample/domain-resources/WLS-AI/mii-initial-d1-WLS-AI-v1.yaml that is included in the sample source.

Click here to view the WLS Domain YAML file using auxiliary images.

You can compare this domain resource YAML file with the domain resource YAML file from the original initial use case (/tmp/mii-sample/domain-resources/WLS/mii-initial-d1-WLS-v1.yaml) to see the changes required for auxiliary images. For example:

$ diff /tmp/mii-sample/domain-resources/WLS-AI/mii-initial-d1-WLS-AI-v1.yaml /tmp/mii-sample/domain-resources/WLS/mii-initial-d1-WLS-v1.yaml
1c1
< # Copyright (c) 2021, Oracle and/or its affiliates.
---
> # Copyright (c) 2020, 2021, Oracle and/or its affiliates.
23c23
<   image: "container-registry.oracle.com/middleware/weblogic:12.2.1.4"
---
>   image: "model-in-image:WLS-v1"
53,57d52
<   # Settings for auxiliary image volume(s), see also 'serverPod.auxiliaryImages'.
<   auxiliaryImageVolumes:
<   - name: auxiliaryImageVolume1
<     mountPath: "/auxiliary"
<
75,83d69
<     # Auxiliary image(s) containing WDT model, archives and install. See also:
<     #    'spec.auxiliaryImageVolumes'.
<     #    'spec.configuration.model.modelHome'
<     #    'spec.configuration.model.wdtInstallHome'
<     auxiliaryImages:
<     - image: "model-in-image:WLS-AI-v1"
<       imagePullPolicy: IfNotPresent
<       volume: auxiliaryImageVolume1
<
145,146d130
<       modelHome: "/auxiliary/models"
<       wdtInstallHome: "/auxiliary/weblogic-deploy"

Run the following command to deploy the domain custom resource:

$ kubectl apply -f /tmp/mii-sample/domain-resources/WLS-AI/mii-initial-d1-WLS-AI-v1.yaml

Note: If you are choosing not to use the predefined Domain YAML file and instead created your own Domain YAML file earlier, then substitute your custom file name in the above command. Previously, we suggested naming it /tmp/mii-sample/mii-initial.yaml.

Now, 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.

Alternatively, you can run /tmp/mii-sample/utils/wl-pod-wait.sh -p 3. This utility script exits successfully when the designated number of WebLogic Server pods reach a ready state and have restartVersion, introspectVersion, spec.image, and spec.serverPod.auxiliaryImages.image values that match their corresponding values in their domain resource.

Click here to display the `wl-pod-wait.sh` usage.
Click here to view sample output from `wl-pod-wait.sh`.

If you see an error, then consult Debugging in the Model in Image user guide.

Step 4: Invoke the web application

To invoke the web application, follow the same steps as described in the Invoke the web application section of the initial use case.