This document describes what’s needed to create and deploy a typical Model in Image domain.
Deploy the operator and ensure that it is monitoring the desired namespace for your Model in Image domain. See Manage operators and Quick Start.
Model in Image requires an image with a WebLogic Server installation.
You can start with a WebLogic Server 12.2.1.4 or later Oracle Container Registry pre-built base image such as container-registry.oracle.com/middleware/weblogic:12.2.1.4 for WLS domains or container-registry.oracle.com/middleware/fmw-infrastructure:12.2.1.4 for JRF domains.
The images in container-registry.oracle.com/middleware/weblogic and container-registry.oracle.com/middleware/fmw-infrastructure are unpatched images. You should always either use patched images from container-registry.oracle.com/middleware/weblogic_cpu and container-registry.oracle.com/middleware/fmw-infrastructure_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 for both WLS and JRF domains, 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 that any 12.2.1.3 image must also include patch 29135930 (the pre-built images already contain this patch).
NOTE: As of December, 2022, Oracle will continue 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.
Model in Image requires the following directory structure in its pods for its (optional) WDT model artifacts and (required) WDT binaries:
| 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 binaries (required). | Optional. Location of the WDT installation. 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 and installation files
that are copied from Auxiliary Images.
Model in Image minimally requires an image with a WebLogic installation (see WebLogic Server image), plus access to:
domain.spec.configuration.model.wdtInstallHome..yaml files that configure your domain in
the domain.spec.configuration.model.modelHome directory
or in the optional WDT model ConfigMap..properties files in the
domain.spec.configuration.model.modelHome directory
or in the optional WDT model ConfigMap..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 artifacts:
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 main image:
You can include the artifacts 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).
Use either of the following methods.
Use a Persistent Volume Claim (PVC):
This method is for advanced use cases only. Supply WDT model YAML, variable, 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 Model files.
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 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.
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 artifacts 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
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.
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. Valid values are WLS, JRF, and RestrictedJRF, where 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 installation. 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 and installation files
that are copied from Auxiliary Images.
Notes:
There are additional attributes that are common to all domain home source types, such as the image field. See the Domain Resource schema and documentation for a full list of Domain fields.
There are also additional fields that are specific to JRF domain types. For more information, see Requirements for JRF domain types.
For fully specified Model in Image Domain YAML file examples,
see the kubernetes/samples/scripts/create-weblogic-domain/model-in-image/domain-resources GitHub directory for the Model in Image sample.
The WLS and JRF subdirectories in this directory correspond to the configuration.model.domainType.
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:
This section applies only for a JRF domain type. Skip it if your domain type is WLS or RestrictedJRF.
A JRF domain requires an infrastructure database, initializing this database using RCU, and configuring your domain to access this database. All of these steps must occur before you first deploy your domain. When you first deploy your domain, the introspector job will initialize its OPSS schema tables in the database - a process that can take several minutes.
Furthermore, if you want to safely ensure that a restarted JRF domain can access updates to the infrastructure database that the domain made at an earlier time, the original domain’s wallet file must be safely saved as soon as practical, and the restarted domain must be supplied a wallet file that was obtained from a previous run of the domain.
Here are the required Domain YAML file and model YAML file settings for Model in Image JRF domains:
Set configuration.model.domainType to JRF.
Set configuration.opss.walletPasswordSecret to reference a secret that defines a walletPassword key. This is used to encrypt the domain’s OPSS wallet file. This is a required field for JRF domains.
Set configuration.opss.walletFileSecret to reference a secret that contains your domain’s OPSS wallet file in its walletFile key. This assumes you have an OPSS wallet file from a previous start of the same domain. It enables a restarted or migrated domain to access its database information. This is an optional field for JRF domains, but must always be set if you want a restarted or migrated domain to access its database information.
Set the configuration.introspectorJobActiveDeadlineSeconds introspection job timeout to at least 600 seconds. This is in an optional field but is needed because domain home creation takes a considerable amount of time the first time a JRF domain is created (due to initializing the domain’s database tables), and because Model in Image creates your domain home for you using the introspection job.
Define an RCUDbInfo stanza in your model. Access to an database requires defining a RCUDbInfo stanza in your model’s domainInfo stanza with the necessary information for accessing the domain’s schema within the database. Usually this information should be supplied using a secret that you deploy and reference in your Domain YAML file’s configuration.secrets field. Here’s an example RCUDbInfo stanza:
domainInfo:
RCUDbInfo:
rcu_prefix: '@@SECRET:sample-domain1-rcu-access:rcu_prefix@@'
rcu_schema_password: '@@SECRET:sample-domain1-rcu-access:rcu_schema_password@@'
rcu_db_conn_string: '@@SECRET:sample-domain1-rcu-access:rcu_db_conn_string@@'
It is important to save a JRF domain’s OPSS wallet password and wallet file so that you can restore them as needed. This ensures that a restart or migration of the domain can continue to access the domain’s FMW infrastructure database.
When you deploy a JRF domain for the first time, the domain will add itself to its RCU database tables, and also create a ‘wallet’ file in the domain’s home directory that enables access to the domain’s data in the RCU database. This wallet is encrypted using an OPSS key password that you supply to the domain using a Secret that is referenced by your Domain YAML file configuration.opss.walletPasswordSecret field.
For a domain that has been started by Model in Image, the operator will copy the wallet file from the domain home of a new JRF domain and store it in the domain’s introspector domain ConfigMap in file ewallet.p12. Here is how to export this wallet file from the introspector domain ConfigMap:
Option 1
$ kubectl -n MY_DOMAIN_NAMESPACE \
get configmap MY_DOMAIN_UID-weblogic-domain-introspect-cm \
-o jsonpath='{.data.ewallet\.p12}' \
> ewallet.p12
Option 2
Alternatively, you can use the ./kubernetes/samples/scripts/create-weblogic-domain/model-in-image/utils/opss-wallet.sh -s command to export the wallet file (pass -? to this script’s command-line arguments and defaults).
Always back up your wallet file to a safe location that can be retrieved later. In addition, save your OPSS key password.
To reuse the wallet:
walletPassword that contains the same OPSS password that you specified in the original domain. For example, substitute
the password in place of MY_WALLET_PASSWORD below:
$ kubectl -n MY_DOMAIN_NAMESPACE \
create secret generic MY_DOMAIN_UID-my-opss-wallet-password-secret \
--from-literal=walletPassword=MY_WALLET_PASSWORD
$ kubectl -n MY_DOMAIN_NAMESPACE \
label secret MY_DOMAIN_UID-my-opss-wallet-password-secret \
weblogic.domainUID=sample-domain1
walletFile that contains the OPSS wallet file that you exported previously. For example, assuming the file is ewallet.p12:
$ kubectl -n MY_DOMAIN_NAMESPACE \
create secret generic MY_DOMAIN_UID-my-opss-wallet-file-secret \
--from-file=walletFile=ewallet.p12
$ kubectl -n sample-domain1-ns \
label secret MY_DOMAIN_UID-my-opss-wallet-file-secret \
weblogic.domainUID=sample-domain1
./kubernetes/samples/scripts/create-weblogic-domain/model-in-image/utils/opss-wallet.sh -r command to deploy a local wallet file as a secret (pass -? to get this script’s command-line arguments and defaults).configuration.opss.walletPasswordSecret field names the OPSS password Secret, and make sure that your Domain YAML file configuration.opss.walletFileSecret field names the OPSS wallet file secret.Follow these steps to ensure that a JRF domain can continue to access its RCU data after changing its database password.
Before changing the database password, shut down all domains that access the database schema. For example, set their serverStartPolicy to Never.
Update the password in the database.
Update the Kubernetes Secret that contains your RCUDbInfo.rcu_schema_password for each domain.
Restart the domains. For example, change their serverStartPolicy from Never to IfNeeded.
Save your wallet files again, as changing your password generates a different wallet.
For an example of using JRF in combination with Model in Image, see the Model in Image sample.
See also, Specifying RCU connection information in the model in the WDT documentation.