Usage

This document describes what’s needed to create and deploy a typical Model in Image domain.

Contents

WebLogic Kubernetes Operator

Deploy the operator and ensure that it is monitoring the desired namespace for your Model in Image domain. See Manage operators and Quick Start.

WebLogic Server image

Model in Image requires an image with a WebLogic Server installation.

  • You can start with WebLogic Server 12.2.1.4 or later, an Oracle Container Registry pre-built base image, such as container-registry.oracle.com/middleware/weblogic:12.2.1.4.

    The images in container-registry.oracle.com/middleware/weblogic are unpatched images. You should always either use patched images from container-registry.oracle.com/middleware/weblogic_cpu or build your own patched images (see Create a custom image with patches applied).

    The example base images are GA images and are suitable for demonstration and development purposes only where the environments are not available from the public Internet; they are not acceptable for production use. In production, you should always use CPU (patched) images from OCR or create your images using the WebLogic Image Tool (WIT) with the --recommendedPatches option. For more guidance, see Apply the Latest Patches and Updates in Securing a Production Environment for Oracle WebLogic Server.

    For an example of this approach, see the Model in Image sample. For detailed instructions on how to log in to the Oracle Container Registry and accept the license agreement for an image (required to allow pulling an Oracle Container Registry image), see this document.

  • Or, you can manually build your own base image, as described in Create a custom image with patches applied. This is useful if you want your base images to include additional patches.

    NOTE: As of June, 2023, Oracle WebLogic Server 12.2.1.3 is no longer supported. The last Critical Patch Updates (CPU) images for WebLogic Server 12.2.1.3 were published in April, 2023.

Directory structure

Model in Image requires the following directory structure in its pods for its (optional) WDT model files and (required) WDT Home :

Domain resource attribute Contents Default directory
domain.spec.configuration.model.modelHome Zero or more model .yaml, .properties, and/or archive .zip files. Optional. Location of the WDT model home, which can include model YAML files, .properties files, and application .zip archives. Defaults to /u01/wdt/models if no Auxiliary Images are configured, and to /aux/models otherwise.
domain.spec.configuration.model.wdtInstallHome Unzipped WDT installation (required). Optional. Location of the WDT Home. Defaults to /u01/wdt/weblogic-deploy if no Auxiliary Images are configured, and to /aux/weblogic-deploy otherwise.

If you set modelHome and wdtInstallHome to a non-default value, then the operator will ignore WDT model files and WDT Home that are copied from Auxiliary Images.

Supplying initial WDT model files and WDT Home

Model in Image minimally requires an image with a WebLogic installation (see WebLogic Server image), plus access to:

  • A WDT installation in domain.spec.configuration.model.wdtInstallHome.
  • One or more WDT model .yaml files that configure your domain in the domain.spec.configuration.model.modelHome directory or in the optional WDT model ConfigMap.
  • Zero or more WDT model .properties files in the domain.spec.configuration.model.modelHome directory or in the optional WDT model ConfigMap.
  • Zero or more WDT model application .zip archives in the domain.spec.configuration.model.modelHome directory. Archives must be supplied in the model home because application archives are not supported in the optional WDT model ConfigMap.

There are multiple methods for supplying Model in Image WDT models files, WDT variables files, and WDT archive files (collectively known as WDT model files):

  • Use auxiliary images: Use auxiliary images to create one or more small images that contain the desired files.

    This is the recommended best approach. It automatically copies files from each of the small images into the /aux/models and /aux/weblogic-deploy directories in each pod’s file system so that the introspection job can find them.

  • Include in the main image: You can include the WDT model files in your domain resource domain.spec.image in its domain.spec.configuration.model.modelHome and domain.spec.configuration.model.wdtInstallHome directories as a layer on top of your base image (where the base image includes your WebLogic installation).

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

    Use either of the following methods.

    • Manual image creation uses Docker commands to layer the WDT models files, described in the previous table, on top of your base image into a new image.
    • The WebLogic Image Tool (WIT) has built-in options for layering WDT model files, WDT installation, WebLogic Server installation, and WebLogic Server patches in an image. See Create a custom image with your model inside the image.

  • Use a Persistent Volume Claim (PVC): This method is for advanced use cases only. Supply WDT model YAML, variables, or archive files in a Persistent Volume Claim and modify configuration.model.modelHome and configuration.model.wdtInstallHome to the corresponding directory within the PVC’s mount location.

  • Use a WDT model ConfigMap: Use the Optional WDT model ConfigMap for WDT model YAML and .properties files. This can be combined with any of the previously mentioned methods and is most often used to facilitate runtime updates to models supplied by one of these methods.

For more information about model file syntax, see Working with WDT model files.

Optional WDT model ConfigMap

You can create a WDT model ConfigMap that defines additional model .yaml and .properties files beyond what you’ve already supplied in your image, and then reference this ConfigMap using your Domain YAML file’s configuration.model.configMap attribute. This is optional if the supplied image already fully defines your model.

WDT model ConfigMap files will be merged with the WDT files defined in your image at runtime before your domain home is created. The ConfigMap files can add to, remove from, or alter the model configuration that you supplied within your image.

For example, place additional .yaml and .properties files in a directory called /home/acmeuser/wdtoverride and run the following commands:

$ kubectl -n MY-DOMAIN-NAMESPACE \
  create configmap MY-DOMAINUID-my-wdt-config-map \
  --from-file /home/acmeuser/wdtoverride

$ kubectl -n MY-DOMAIN-NAMESPACE \
  label  configmap MY-DOMAINUID-my-wdt-config-map \
  weblogic.domainUID=MY-DOMAINUID

See Working with WDT model files for a description of model file syntax and loading order, and see Runtime updates for a description of using WDT model ConfigMaps to update the model configuration of a running domain.

Required runtime encryption secret

Model in Image requires a runtime encryption secret with a secure password key. This secret is used by the operator to encrypt model and domain home files before it adds them to a runtime ConfigMap or log. You can safely change the password, at any time after you’ve fully shut down a domain, but it must remain the same for the life of a running domain. The runtime encryption secret that you create can be named anything, but note that it is a best practice to name and label secrets with their domain UID to help ensure that cleanup scripts can find and delete them.

NOTE: Because the runtime encryption password does not need to be shared and needs to exist only for the life of a domain, you may want to use a password generator.

Example:

$ kubectl -n MY-DOMAIN-NAMESPACE \
  create secret generic MY-DOMAINUID-runtime-encrypt-secret \
  --from-literal=password=MY-RUNTIME-PASSWORD

$ kubectl -n MY-DOMAIN-NAMESPACE \
  label secret MY-DOMAINUID-runtime-encrypt-secret \
  weblogic.domainUID=MY-DOMAINUID

Corresponding Domain YAML file snippet:

configuration:
  model:
    runtimeEncryptionSecret: MY-DOMAINUID-runtime-encrypt-secret

Secrets for model macros

Create additional secrets as needed by macros in your model files. For example, these can store database URLs and credentials that are accessed using @@SECRET macros in your model that reference the secrets. For a description of model macros, see Model files.

Domain fields

The following Domain fields are specific to Model in Image domains.

Domain Resource Attribute Notes
domainHomeSourceType Required. Set to FromModel.
domainHome Must reference an empty or non-existent directory within your image. Do not include the mount path of any persistent volume. Note that Model in Image recreates the domain home for a WebLogic Server pod every time the pod restarts.
configuration.model.configMap Optional. Set if you have stored additional models in a ConfigMap as per Optional WDT model ConfigMap.
configuration.secrets Optional. Set this array if your image or ConfigMap models contain macros that reference custom Kubernetes Secrets. For example, if your macros depend on secrets my-secret and my-other-secret, then set to [my-secret, my-other-secret].
configuration.model.runtimeEncryptionSecret Required. All Model in Image domains must specify a runtime encryption secret. See Required runtime encryption secret.
configuration.model.domainType Set the type of domain. WLS is the default. See WDT Domain Types.
configuration.model.runtimeEncryptionSecret Required. All Model in Image domains must specify a runtime encryption secret. See Required runtime encryption secret.
configuration.model.modelHome Optional. Location of the WDT model home, which can include model YAML files, .properties files, and application .zip archives. Defaults to /u01/wdt/models if no Auxiliary Images are configured, and to /aux/models otherwise.
configuration.model.wdtInstallHome Optional. Location of the WDT Home . Defaults to /aux/weblogic-deploy when Auxiliary Images are configured, otherwise to /u01/wdt/weblogic-deploy.

If you set modelHome and wdtInstallHome to a non-default value, then the operator will ignore WDT model files and WDT Home that are copied from Auxiliary Images.

NOTES:

Always use external state

Regardless of the domain home source type, we recommend that you always keep state outside the image. This includes cluster database leasing tables, JMS and transaction stores, EJB timers, and so on. This ensures that data will not be lost when a container is destroyed.

We recommend that state be kept in a database to take advantage of built-in database server high availability features, and the fact that disaster recovery of sites across all but the shortest distances, almost always requires using a single database server to consolidate and replicate data (DataGuard).

For more information see: