Create custom images

Contents

Use the WebLogic Image Tool to create custom images

You can use the WebLogic Image Tool (WIT) to build your own WebLogic Server or Fusion Middleware Infrastructure images (with the latest Oracle Linux images, Java updates, and WebLogic Server patches), apply one-off patches to existing OCR images, or overlay your own files and applications on top of an OCR image.

Download and install the WebLogic Image Tool (WIT) following the WIT Setup instructions. Also, refer to the WIT Quick Start Guide. The samples in this document assume that you have installed WIT in /tmp/imagetool; you can choose to install it in any location.

The WebLogic Image Tool create, update, or rebase commands supply three different ways to generate a custom WebLogic Server installation image from a base OS image (optionally, with WebLogic patches). In addition, the WIT createAuxImage command supports creating auxiliary images which do not contain a WebLogic Server installation, and instead, solely contain the WebLogic Deploy Tooling (WDT) installation and model files; this option is designed for the Model in Image domain home source type.

Finally, you can use the WIT inspect command to inspect images.

In detail:

  • WIT create command:

  • WIT rebase command:

    • The rebase command is used for Domain in Image domains.

      • Creates a new WebLogic image and copies an existing WebLogic domain home from an older image to the new image.
      • The created image is suitable for deploying to an already running domain with an older version of the domain home.

    • The new image can be created in one of two ways:

      • As a layer on an existing WebLogic image in the repository that doesn’t already have a domain home, such as an updated CPU image from OCR.
      • Or, as a new WebLogic image from a base OS image. NOTE: Oracle strongly recommends rebasing your images with the latest security patches by applying the --recommendedPatches option.
      • For more information, see Apply patched images to a running domain.

  • WIT update command:

    • Creates a new WebLogic image layered on an existing WebLogic image (specified in the WIT --fromImage parameter).
      • Note that if you specify the --pull parameter for WIT, and the --fromImage parameter refers to an image in a repository, and the repository image is newer than the locally cached version of the image, then the command will download the repository image to the local Docker cache and use it instead of using the outdated local image.
    • Optionally, generates a domain home in the new image using WDT or WLST (for Domain in Image domains).
    • Optionally, includes a WDT installation and model files in the image (for Model in Image domains).
    • Important:
      • Note: Patching an Oracle Home using the WIT update command results in a larger WebLogic Server image due to the immutable layering in container images. For small updates, such as a one-off patch, the increase in the image size may be negligible. However, for larger updates, the increase in size will be significant. Consider using rebase or create to reduce the size impact of applying patches.
      • The WIT update command is not suitable for updating an existing domain home in an existing Domain in Image image when the update is intended for a running domain. Use the WIT rebase command instead or shut down the running domain entirely before applying the new image. For more information, see Apply patched images to a running domain.
      • Optionally, includes a WDT installation and model files in the image (for Model in Image domains).

  • WIT createAuxImage command:

    • Supports creating auxiliary images for Model in Image domains only.
    • The auxiliary images solely contain WebLogic Deploy Tooling files for the Model in Image use case and are used in addition to the domain resource image that contains your WebLogic and Java installations.
    • For more information, see Auxiliary images.

  • WIT inspect command:

    • Inspects images created with the WebLogic Image Tool.
    • See Inspect images.

Create a custom image with patches applied

All domain home source types require a base image which contains JDK and WebLogic Server binaries. This base image is usually obtained directly from the Oracle Container Registry, but, as needed, you can also create your own custom base image.

If you are using the Domain in Image domain home source type, then you will additionally need to use the base image to create a custom image with your domain inside the image.

Or, if you are using the Model in Image domain home source type without auxiliary images, then you will additionally need to use the base image to create a custom image with your model inside the image.

Create a custom base image

This section describes using the WebLogic Image Tool (WIT) create command to build a custom base WebLogic Server image. This is sometimes necessary to build an image with a specific patch, and such, but most use cases can instead, obtain pre-built patched images directly from the Oracle Container Registry. See Obtain images from the Oracle Container Registry.

Here’s an example of using the WIT create command to create a base WebLogic Server image from a base Oracle Linux image, a WebLogic installer download, and a JRE installer download:

  1. First, install the WebLogic Image Tool. This sample assumes that you have installed WIT in /tmp/imagetool; you can choose to install it in any location.

  2. Download your desired JRE installer from the Oracle Technology Network Java downloads page or from the Oracle Software Delivery Cloud (OSDC).

  3. Download your desired WebLogic Server installer from the Oracle Technology Network WebLogic Server installers page or from the Oracle Software Delivery Cloud (OSDC).

    Note: The WebLogic Server installers will not be fully patched. In a subsequent step, you’ll use the WIT --patches or --recommendedPatches options to apply one-off and recommended Oracle patches.

  4. Add the installers to your WIT cache using the cache command. For example, assuming you downloaded the installers to the /home/acmeuser/wls-installers directory:

    $ /tmp/imagetool/bin/imagetool.sh cache addInstaller \
  --type=jdk \
  --version=8u291 \
  --path=/home/acmeuser/wls-installers/jre-8u291-linux-x64.tar.gz

    $ /tmp/imagetool/bin/imagetool.sh cache addInstaller \
  --type=wls \
  --version=12.2.1.4.0 \
  --path=/home/acmeuser/wls-installers/fmw_12.2.1.4.0_wls_Disk1_1of1.zip

    For details, see the WIT Quick Start guide.

  5. Use the create command to build the image using a default Oracle Linux image as its base, and download and apply the patches.

    For example, use the following command to create a WebLogic Server image named latest_weblogic:12.2.1.4 with:

    • The WebLogic Server 12.2.1.4.0 generic installer
    • JDK 8u291
    • The latest version of the Oracle Linux 7 slim container image
    • The latest quarterly Patch Set Update (PSU), which include security fixes, or with one-off patches
    $ /tmp/imagetool/bin/imagetool.sh create \
  --tag latest_weblogic:12.2.1.4 \
  --pull \
  --jdkVersion=8u291 \
  --type=wls \
  --version=12.2.1.4.0 \
  --recommendedPatches \
  --user myusername@mycompany.com \
  --passwordEnv=MYPWD

    As another example, if you want to create a WebLogic Server image named minimal_weblogic:12.2.1.3 with:

    • The WebLogic slim installer instead of the generic installer
    • JDK 8u291
    • The latest version of the Oracle Linux 7 slim container image
    • The minimal patches required for the operator to run a 12.2.1.3 image (patches 29135930 and 27117282) instead of the latest recommended patches

As of December, 2022, Fusion Middleware 12.2.1.3 is no longer supported. The last Critical Patch Updates (CPU) images for FMW Infrastructure 12.2.1.3 were published in October, 2022. Oracle has extended support of WebLogic Server 12.2.1.3, for six months only, for PSUs and security patches. CPU images for WebLogic Server 12.2.1.3 will be published in the January, 2023, and April, 2023, CPU cycles.

$ /tmp/imagetool/bin/imagetool.sh create \
  --tag minimal_weblogic:12.2.1.3 \
  --pull \
  --jdkVersion=8u291 \
  --type=wlsslim \
  --version=12.2.1.3.0 \
  --patches=29135930_12.2.1.3.0,27117282_12.2.1.3.0 \
  --user myusername@mycompany.com \
  --passwordEnv=MYPWD

Notes:

  • To enable WIT to download patches, you must supply your My Oracle Support (Oracle Single Sign-On) credentials using the --user and --passwordEnv parameters (or one of the other password CLA options). This example assumes that you have set the MYPWD shell environment variable so that it contains your password.
  • The --type parameter designates the Oracle product installation, such as WebLogic Server, Fusion Middleware (FMW) Infrastructure, and such, to include in the generated image. For example, the wls type corresponds to the WebLogic Server (WLS) generic installation, the wlsslim type to the WLS slim installation, and the wlsdev type to the WLS developer installation. For a description of each installation type, see WebLogic distribution installer type.
  • The --recommendedPatches parameter finds and applies the latest PatchSet Update (PSU) and recommended patches for each of the products included in the installer. For example, for WebLogic Server, the recommended patches for Coherence and TopLink are included.
  • These sample commands use a default base image, which is an Oracle Linux OS image, and downloads (pulls) this image only if it is not already cached locally. You can use docker images to view your image cache.
  • The --pull parameter for WIT is passed to the container build engine which forces a check to the remote repository, if applicable, prior to the build execution of the new image to update any image used during the build (updates dependencies).
  • For details about each parameter, see the WebLogic Image Tool User Guide.

  1. After the tool creates the image, verify that the image is in your local repository:

    $ docker images

    You can also inspect the contents of the image.

Create a custom image with your domain inside the image

Oracle strongly recommends storing Domain in Image images in a private registry. A container image that contains a WebLogic domain home has sensitive information including credentials that are used to access external resources (for example, a data source password), and decryption keys (for example, the DOMAIN_HOME/security/SerializedSystemIni.dat domain secret file). For more information, see Container image protection.

The sample scripts in this section reference base image container-registry.oracle.com/middleware/weblogic:12.2.1.4. This is an OCR General Availability (GA) image which does not include the latest security patches for WebLogic Server. GA images are intended for single desktop demonstration and development purposes only. For all other purposes, Oracle strongly recommends using only images with the latest set of recommended patches applied, such as OCR Critical Patch Updates (CPU) images or custom generated images. See Ensure you are using recently patched images.

This section provides guidance for creating a new Domain in Image image. This type of image cannot be used in pods that must join the pods in an already running domain. If you need to create a Domain in Image image that is meant for updating an already running domain, then see Apply patched images to a running domain.

NOTE: The Domain in Image domain home source type is deprecated in WebLogic Kubernetes Operator version 4.0. Oracle recommends that you choose either Domain in PV or Model in Image, depending on your needs.

For Domain in Image domains, you must create an image with the WebLogic domain inside the image. Samples are provided that demonstrate how to create the image using either WLST to define the domain or WebLogic Deploy Tooling models to define the domain. In these samples, you will see a reference to a “base” or --fromImage image. You should use an image with the recommended security patches installed as this base image, where this image could be an OCR image or a custom image. See Obtain images from the Oracle Container Registry and Create a custom image with patches applied.

The samples perform multiple steps for you using a single provided script and are not intended for production use. To help understand the individual steps, use the following step-by-step guidance for using WLST or WDT to create the domain home in Domain in Image.

  • Domain in Image using WDT:

    Here we explore a step-by-step approach for Domain in Image using WebLogic Deploy Tooling models to create the domain home. These steps stage files to /tmp/dii-wdt-stage, assume the operator source is in /tmp/weblogic-kubernetes-operator, assume you have installed WIT in /tmp/imagetool, and generate a Domain in Image image named my-dii-wdt:v1.

    Click here to view the script.

  • Domain in Image using WLST:

    Here is a step-by-step approach for Domain in Image images using WLST. These steps stage files to dii-wlst-stage, put the domain home inside the image at /u01/oracle/user_projects/domains/dii-wlst, assume the operator source is in /tmp/weblogic-kubernetes-operator, assume you have installed WIT in /tmp/imagetool, and name the final image my-dii-wlst:v1.

    Click here to view the script.

Notes:

  • The sample script and its domain.properties file include a sample WebLogic administration password. These files must be protected and the sample password must be changed.
  • The sample scripts, sample properties, the files provided in --additionalBuildCommands and --additionalBuildFiles parameters for the WLST approach, or the sample WDT model files provided in the WDT approach, are not intended for production use. These files can all change substantially in new versions of the operator and must all be copied, preserved, and customized to suite your particular use case.

Create a custom image with your model inside the image

NOTE: Model in Image without auxiliary images (the WDT model and installation files are included in the same image with the WebLogic Server installation) will be deprecated in WebLogic Kubernetes Operator version 4.0.7. Oracle recommends that you use Model in Image with auxiliary images. See Auxiliary images.

The example in this section references a base image, container-registry.oracle.com/middleware/weblogic:12.2.1.4. This is an OCR General Availability (GA) image which does not include the latest security patches for WebLogic Server. GA images are intended for single desktop demonstration and development purposes only. For all other purposes, Oracle strongly recommends using only images with the latest set of recommended patches applied, such as OCR Critical Patch Updates (CPU) images or custom generated images. See Ensure you are using recently patched images.

Example steps for creating a custom WebLogic image with a Model in Image file layer (using files from the Model in Image sample):

  1. To gain an overall understanding of Model in Image domains, read the Model in Image User Guide and the Model in Image Sample. Note that the sample uses the recommended best approach, auxiliary images, instead of the alternative approach, which is used in this example.

  2. Follow the prerequisite steps in the Model in Image Sample that describe how to:

    • Download the operator source and its Model in Image sample (including copying the sample to the suggested location, /tmp/mii-sample).
    • Download the latest WebLogic Deploy Tooling (WDT) and WebLogic Image Tool (WIT) installer ZIP files to your /tmp/mii-sample/model-images directory. Both WDT and WIT are required to create your Model in Image container images.
    • Install (unzip) the WebLogic Image Tool and configure its cache to reference your WebLogic Deploy Tooling download.

  3. Locate or create a base WebLogic image.

    See Obtain images from the Oracle Container Registry or Create a custom image with patches applied.

    In the following step, you will use the container-registry.oracle.com/middleware/weblogic:12.2.1.4 GA image.

  4. Build the final image using WIT while specifying the base image, target image tag, WDT installation location, and WDT model file locations. For example:

    First, create a model ZIP file application archive and place it in the same directory where the sample model YAML file and model properties files are already staged:

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

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

    Second, run the following WIT command:

    $ cd /tmp/mii-sample/model-images

    $ ./imagetool/bin/imagetool.sh update \
  --tag model-in-image:WLS-v1 \
  --fromImage container-registry.oracle.com/middleware/weblogic:12.2.1.4 \
  --wdtModel      ./model-in-image__WLS-v1/model.10.yaml \
  --wdtVariables  ./model-in-image__WLS-v1/model.10.properties \
  --wdtArchive    ./model-in-image__WLS-v1/archive.zip \
  --wdtModelOnly \
  --wdtDomainType WLS \
  --chown oracle:root

    Note: If using a Fusion Middleware Infrastructure base image, then specify a --wdtDomainType of JRF or RestrictedJRF, JRF-v1 instead of WLS-v1 for the image tag, and substitute each occurrence of model-in-image__WLS-v1 with model-in-image__JRF-v1.

  5. For an example Domain YAML file that sets up Model in Image to reference the image, see /tmp/mii-sample/domain-resources/WLS/mii-initial-d1-WLS-v1.yaml (or ./JRF/mii-initial-d1-JRF-v1.yaml if using Fusion Middleware Infrastructure JRF mode).

    Notes:

    • The default values for domain.spec.configuration.model.wdtInstallHome and .modelHome reference the location of the WDT installation and model files that WIT copied into the image.

    • The domain type specified in domain.spec.configuration.model.domainType must correspond with the --wdtDomainType specified on the WIT command line when creating the image.

    • To compare this example with an equivalent auxiliary image domain:

      $ 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