1. Cloud Native Deployment Guide
  2. Creating OSM Cloud Native Images

3 Creating OSM Cloud Native Images

OSM cloud native requires container images be made available to create and manage OSM cloud native instances. This chapter describes how to create those OSM cloud native images.

OSM cloud native requires two container images. The OSM DB Installer image is used to manage the OSM and Fusion MiddleWare schemas - create, delete, upgrade - as well as deploy and fast-undeploy OSM cartridges in the OSM schema. The other image is the OSM image itself. This image is the basis for all of the long running pods - the WebLogic admin server and all the Managed Servers that comprise an OSM cloud native instance. Each image is built on top of a Linux base image and adds Java, Fusion MiddleWare components and OSM product components on top.

OSM Cloud native images are created using the OSM cloud native builder toolkit and a dependency manifest file. The OSM cloud native Image Builder is intended to be run as part of a Continuous Integration process that generates images. It needs to run on Linux and have access to the local Docker daemon. The versions of these are as per the OSM statement of certification in the OSM documentation. The dependency manifest is a file that describes all the versions and patches required to build out the image.

See the following topics for further details:

Downloading the OSM Cloud Native Image Builder

You download the OSM cloud native image builder from My Oracle Support at: https://support.oracle.com

The OSM cloud native image builder is bundled with the following components:

  • An unpatched dependency manifest file.

    This file does not include any artifacts that require contract-driven access to Oracle download sites (for example, for Fusion MiddleWare patches). Use this unpatched manifest file for evaluation purposes only.

    For production use (and throughout the adoption lifecycle leading up to production), obtain the latest dependency manifest file. See OSM Compatibility Matrix for details about the latest recommended manifest file for your OSM release.

  • OSM cloud native builder kit. The kit contains:
    • The OSM Domain WDT Model.
    • The OSM DB Installer scripts and manifest files.
    • The WDT Deployment tool and the WebLogic Image tool.
  • Staging directory structure.

Prerequisites for Creating OSM Images

The minimum resource requirements for building OSM cloud native images are:

  • 2 CPUs
  • 4GB RAM
  • 40GB Disk Space
The following versions of Podman and Oracle Linux Server were used to obtain the requirements listed above:
  • Oracle Linux Server 8.8
  • Podman 4.4.1

See OSM Compatibility Matrix for more details about the required and supported versions of Podman, Oracle Linux Server, and the following components.

If Podman is used, the image build process might intermittently fail due to Podman's low open files default for image building. These build failures appear as Oracle OPatch failures in the build output. To workaround this, either switch to Docker or follow this procedure:
  1. Identify the location of podman using which podman. Say this is /usr/bin/podman.
  2. Introduce an intermediate script to invoke podman:
    mv /usr/bin/podman /usr/bin/podman.bin
cat > /usr/bin/podman <<EOF
#!/bin/bash
if [ "$1" == "build" ]; then
  shift
  /usr/bin/podman.bin build --ulimit=nofile=8192:8192 "$@"
else
  /usr/bin/podman.bin "$@"
fi
EOF
chmod +x /usr/bin/podman
    This sets the open files limit to 8192 instead of podman's default of 1024. This should eliminate the intermittent OPatch failure. If it does not, increase the values from 8192 to the output of ulimit -n -H on the build host. If this output is not a number but the string unlimited, use the value 1048576 instead.
  3. Invoke the image build process as usual.

Additional pre-requisites for building OSM cloud native images are:

Configuring the OSM Cloud Native Images

The dependency manifest file describes the input that goes into OSM images. It is consumed by the image build process. The default configuration in the latest manifest file provides all the necessary components and required patches for creating OSM cloud native images. Refer to the Compatibility Matrix to know more about the supported versions of various components.

You can also modify the manifest file to extend it to meet your requirements. This enables you to:

  • Specify any Linux image as the base, as long as its binary is compatible with Oracle Linux.
  • Upgrade the Oracle Enterprise Linux version to a newer version to uptake a quarterly CPU.
  • Upgrade the JDK version to a newer JDK version to uptake a quarterly CPU.
  • Upgrade the Fusion Middleware version to a newer version. For example, you upgrade the Fusion Middleware version to a newer version when you initiate the upgrade to pick up new PSU or when Oracle recommends a new update.
  • Change the set of patches applied on WebLogic Server, Coherence, Fusion Middleware, and OPatch to stay aligned with evolving OSM recommendations.
  • Change the OSM artifacts to newer artifacts to uptake a new OSM patch.
  • Choose a different userid and groupid for oracle:oracle user:group that the image specifies. The default is 1000:1000.

The breakdown of each section in the dependency manifest file is as follows:

Note:

The schemaVersion and date parameters are maintained by Oracle. Do not modify these parameters.

Version numbers provided here are only examples. The manifest file used specifies the actual versions currently recommended.

  • OSM Cloud Native Infrastructure Image

    While not required by OSM cloud native to create or manage OSM instances, this infrastructure image is a necessary building block of the final OSM container image.

    # Specify the details of the Linux base image for OSM.
 # Refer to the OSM documentation for certification statement on supported
 # types and versions.  This information is coded into the OSM image as a
 # LABEL, for tracking purposes.
 linux:
   vendor: Oracle
 # uncomment below two lines when selecting linux 7
 #  version: 7.9
 #  image: container-registry.oracle.com/os/oraclelinux:7-slim
 # comment below two lines when selecting linux 7
   version: 8.8
   image: container-registry.oracle.com/os/oraclelinux:8-slim

    OSM cloud native supports Linux 8 while continuing support of Linux 7. You can uncomment and modify the specification to choose which Linux version can be used as base image for OSM. The linux parameter specifies the base Linux image to be used as the base docker image. The version is the two-digit version from /etc/redhat-release.

    The vendor and version details are specified and used for:

    • Validation when an image is built.
    • Querying at run-time. To troubleshoot issues, Oracle support requires you to provide these details in the manifest file used to build the image.
    userGroup:
  username: oracle
  userid: 1000
  groupname: oracle
  groupid: 1000

    The userGroup parameter specifies the default userId and groupId for oracle. 

    jdk:
    vendor: Oracle
    version: 8u391
    path: $CN_BUILDER_STAGING/java/jdk-8u391-linux-x64.tar.gz

    The jdk parameter specifies the JDK vendor, version, and the staging path. 

    fmw:
    version: 12.2.1.4.0
    path: $CN_BUILDER_STAGING/fmw/install/fmw_12.2.1.4.0_infrastructure_Disk1_1of1.zip

    The fmw parameter specifies the Fusion Middleware version and staging path. 

    oPatch:
    description: Weblogic Opatch
    patchNumber: 28186730
    patchId: 28186730_13.9.4.2.14
    path: $CN_BUILDER_STAGING/fmw/patch/p28186730_1394214_Generic.zip

    The oPatch parameter specifies the Oracle Patch tool and staging path. 

    fmwPatch:
    - description: PSU for WLS (OCT 2023 CPU)
      patchNumber: 35893811
      patchId: 35893811_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p35893811_122140_Generic.zip
    - description: PSU Coherence 12.2.1.4.19 (OCT 2023 CPU)
      patchNumber: 35778804
      patchId: 35778804_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p35778804_122140_Generic.zip
    - description: ADF BUNDLE PATCH (OCT 2023 CPU)
      patchNumber: 35735469
      patchId: 35735469_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p35735469_122140_Generic.zip
    - description: FIX FOR CVE-2021-42575 IN ADF BUNDLE PATCH (OCT 2023 CPU)
      patchNumber: 34809489
      patchId: 34809489_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p34809489_122140_Generic.zip
    - description: ADR FOR WLS (OCT 2023 CPU)
      patchNumber: 35476067
      patchId: 35476067_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p35476067_122140_Linux-x86-64.zip
    - description: OPSS FOR WLS (OCT 2022 CPU)
      patchNumber: 33950717
      patchId: 33950717_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p33950717_122140_Generic.zip
    - description: FMW PLATFORM 12.2.1.4.0 SPU FOR WLS (APR 2022 CPU)
      patchNumber: 33093748
      patchId: 33093748_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p33093748_122140_Generic.zip
    - description: FMW THIRD PARTY BUNDLE PATCH (OCT 2023 CPU)
      patchNumber: 35882299
      patchId: 35882299_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p35882299_122140_Generic.zip
    - description: FMW Control SPU (OCT 2022 CPU)
      patchNumber: 34542329
      patchId: 34542329_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p34542329_122140_Generic.zip
    - description: FMW JDBC (MERGE PATCH FOR APR 2022 CPU AND 31372984)
      patchNumber: 33791062
      patchId: 33791062_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p33791062_122140_Generic.zip
    - description: Oracle Web Services Manager (OWSM) Bundle Patches (OCT 2023 CPU)
      patchNumber: 35868571
      patchId: 35868571_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p35868571_122140_Generic.zip
    - description: RDA Release for FMW 12.2.1.4.0  (OCT 2023 CPU)
      patchNumber: 35671137
      patchId: 35671137_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p35671137_122140_Generic.zip      
    - description: FMW COMPATIBILITY PATCH FOR JDK8 (APR 2022 CPU)
      patchNumber: 34065178
      patchId: 34065178_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p34065178_122140_Generic.zip
    - description: WEBCENTER CORE BUNDLE PATCH (OCT 2023 CPU)
      patchNumber: 35751917
      patchId: 35751917_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p35751917_122140_Generic.zip
    - description: Oracle Data Integrator (ODIMP) BUNDLE PATCH (OCT 2023 CPU)
      patchNumber: 35861909
      patchId: 35861909_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p35861909_122140_Generic.zip
    - description: DMS Metric table uses UUID for Keys
      patchNumber: 28334768
      patchId: 28334768_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p28334768_122140_Generic.zip
    - description: STUCK THREAD AT ORACLE.AS.JMX.FRAMEWORK.STANDARDMBEANS.SPI.ORACLESTANDARDEMITTER
      patchNumber: 27184424
      patchId: 27184424_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p27184424_122140_Generic.zip
    - description: user-group association bug fix
      patchNumber: 30319071
      patchId: 30319071_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p30319071_122140_Generic.zip
    - description: Export JMS for javax.jms.objectmessage
      patchNumber: 31169032
      patchId: 31169032_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p31169032_122140_Generic.zip
    - description: JMS Orphan destination routing
      patchNumber: 31569708
      patchId: 31569708_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p31569708_122140_Generic.zip
    - description: 3 JDBC STORE IN FUSION APPLICATIONS POD EDGF-TEST HAVE NO OWNER
      patchNumber: 32262098
      patchId: 32262098_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p32262098_122140_Generic.zip
    - description: ADB Wallet Dir Connection String Support
      patchNumber: 31676526
      patchId: 31676526_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p31676526_122140_Generic.zip
    - description: RCU Creation with RAC DB shows incorrect port warning
      patchNumber: 30540494
      patchId: 30540494_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p30540494_122140_Generic.zip
    - description: SQL issued by RCU can be changed for efficiency
      patchNumber: 30754186
      patchId: 30754186_12.2.1.4.0
      path: $CN_BUILDER_STAGING/fmw/patch/p30754186_122140_Generic.zip

    The fmwPatch parameter specifies additional patches and their staging paths.

  • OSM Cloud Native Image

    Note:

    Do not modify these parameters. These parameters are maintained by Oracle. 
    osmCnImage:
  name: osm-cn-base
  tag: 7.5.0
  wdt:
    version: 3.2.3
    path: $CN_BUILDER_STAGING/cnsdk/tools/weblogic-deploy.zip
  modelfiles: $CN_BUILDER_STAGING/cnsdk/osm-model/osm-domain-config/osm-base-domain.yaml,$CN_BUILDER_STAGING/cnsdk/osm-model/osm-domain-config/properties/docker-build/domain.properties
  application: $CN_BUILDER_STAGING/cnsdk/osm-model/osm-app-archive.zip
  uxwarapplication: $CN_BUILDER_STAGING/cnsdk/osm-model/osm-fallout-app-archive.zip
  dockerExtension: $CN_BUILDER_STAGING/cnsdk/osm-model/additionalBuildCommands.txt

    The osmCnImage section specifies details about the OSM artifacts required to build the OSM base image. These include the oms.ear, cartridge management WS ear file, default cartridge par file, job control cartridge par file, WDT and base model files.

  • OSM Cloud Native DB Installer Image

    osmCnDbInstallerImage:
  name: osm-cn-db-installer
  tag: 7.5.0

    The osmCnDbInstallerImage parameter specifies the DB Installer image name and version. This includes the transformed OSM DB model and Semele jar file. 

    oracleInstantClient:
    version: 19.21.0.0.0
    basic:
      path: $CN_BUILDER_STAGING/instant-client/oracle-instantclient19.21-basic-19.21.0.0.0-1.x86_64.rpm
    sqlplus:
      path: $CN_BUILDER_STAGING/instant-client/oracle-instantclient19.21-sqlplus-19.21.0.0.0-1.x86_64.rpm
    tools:
      path: $CN_BUILDER_STAGING/instant-client/oracle-instantclient19.21-tools-19.21.0.0.0-1.x86_64.rpm

    The oracleInstantClient parameter specifies details about the Oracle Instant Client required by the DB installer. 

    osmMsInfraStructure:
  jdk:
    vendor: Oracle
    version: 17.0.9
    path: $CN_BUILDER_STAGING/java/jdk-17.0.9_linux-x64_bin.tar.gz

    The osmMsInfraStructure parameter specifies details about the Microservice JDK version. 

    osmGwImage:
  name: osm-gateway
  tag: 7.5.0
rtuxMsImage:
  name: osm-runtime-ux-server
  tag: 7.5.0

    The osmGwImage and rtuxMsImage parameters specify details about the OSM Gateway and RTUX microservices respectively.

Creating OSM Cloud Native Images

To create the OSM image, the image builder does the following:

  • Starts with a base-level operating system image (for example, oraclelinux:7-slim).
  • Creates user and group (for example, oracle:oracle).
  • Updates the image with the necessary packages for installing Fusion Middleware.
  • Installs Java, Fusion Middleware and applies patches.
  • Installs the OSM application base on the WDT model.

To create the OSM DB Installer image, the image builder does the following:

  • Starts with a base-level operating system image (for example, oraclelinux:7-slim).
  • Creates a user and a group (for example, oracle:oracle)
  • Updates the image with the necessary packages for installing Fusion Middleware.
  • Installs Java, Fusion Middleware and applies the required patches.
  • Installs SQL Plus and SQL Loader and the supporting libraries.
  • Installs the OSM DB Installer.

You can specify any Linux image as the base, as long as its binary is compatible with Oracle Linux and conforms to the compatibility matrix. See OSM Compatibility Matrix for details about the supported software.

The following packages must be installed onto the given base image, or be already present:
  • gzip
  • tar
  • unzip

In addition to OSM and OSM DB installer images, OSM cloud native now enables you to create OSM Gateway and RTUX microservices images as well.

Creating the OSM and OSM DB Installer Images

To create the OSM and OSM DB Installer images:

  1. Create the workspace directory:
    mkdir workspace
  2. Obtain and untar the OSM image builder file: osm-image-builder.tar.gz to the workspace directory:
    tar -xf ./osm-image-builder.tar.gz --directory workspace
  3. (Optional) Download and copy the version of Oracle Instant Client in the manifest you are using to workspace/osm-image-builder/staging/instant-client directory and update the version and the file names.

    Note:

    Oracle Instant Client packages are included in the OSM Image Builder and can be used as-is without additional downloads. Also, follow your organization's standard for $http_proxy. 
    curl -x $http_proxy --output osm-image-builder/staging/instant-client/oracle-instantclient19.21-basic-19.21.0.0.0-1.x86_64.rpm
https://download.oracle.com/otn_software/linux/instantclient/1921000/oracle-instantclient19.21-basic-19.21.0.0.0-1.x86_64.rpm
 
curl -x $http_proxy --output osm-image-builder/staging/instant-client/oracle-instantclient19.21-sqlplus-19.21.0.0.0-1.x86_64.rpm
https://download.oracle.com/otn_software/linux/instantclient/1920000/oracle-instantclient19.21-sqlplus-19.21.0.0.0-1.x86_64.rpm
 
curl -x $http_proxy --output osm-image-builder/staging/instant-client/oracle-instantclient19.21-tools-19.21.0.0.0-1.x86_64.rpm
https://download.oracle.com/otn_software/linux/instantclient/1920000/oracle-instantclient19.21-tools-19.21.0.0.0-1.x86_64.rpm
  4. Download JDK to workspace.
    • Determine the JDK versions specified in the manifest - there will be JDK 8 and JDK 17.
    • Download each JDK version tar.gz into ./workspace/osm-image-builder/staging/java.
    • Amend the manifest for each JDK section to include the correct path and filename if they differ.
    #Example
cp jdk-8u251-linux-x64.tar.gz ./workspace/osm-image-builder/staging/java/jdk-8u251-linux-x64.tar.gz

    Microservices require JDK 17. Specify JDK 17 in the manifest under each microservice section.

    Note:

    You can modify the manifest by substituting the default tags with tags that have relevance to your specific work. Specifying tags is not required, but it is recommended. 
    # Information about the OSM  m-s image
osmMsInfraStructure:
  jdk:
    vendor: Oracle
    version: 17.0.7
    path: $CN_BUILDER_STAGING/java/jdk-17.0.7_linux-x64_bin.tar.gz
       
# Information about the OSM Gateway image
osmGwImage:
  name: osm-gateway
  tag: 7.5.0-unpatched
      
# Information about the OSM rtux m-s image
rtuxMsImage:
  name: osm-runtime-ux-server
  tag: 7.5.0-unpatched
  5. From Oracle Software Delivery Cloud: https://edelivery.oracle.com, download Fusion Middleware Infrastructure installer and copy it to the workspace/osm-image-builder/staging/fmw/install directory. The Fusion Middleware Infrastructure installer version to be download is described in the dependency manifest file under the fmw section.
    cp fmw_12.2.1.4.0_infrastructure_Disk1_1of1.zip ./workspace/osm-image-builder/staging/fmw/install/fmw_12.2.1.4.0_infrastructure_Disk1_1of1.zip
  6. Download all the listed patches to the workspace/osm-image-builder/staging/fmw/patch directory. The list of required patches is in the dependency manifest file in the oPatch and fmwPatch sections.

    Note:

    This step is not required if osm_cn_ci_manifest_unpatched.yaml is the manifest used.
    You can download the patches using any of the following options:
    • (Recommended) Manually search for and download each OPatch/FMW patches from Oracle Support to the current working directory and then copy to the staging directory.
      cp pxxxxxx_xxxxx_Generic.zip ./workspace/osm-image-builder/staging/fmw/patch
    • Provide your My Oracle Support account credentials when invoking the build-osm-images.sh script, and let the builder download the patches automatically:

      Note:

      Some patches may not be retrievable in this manner. If the image build process fails with errors about a missing patch, use the recommended option. If the image build process fails with credential errors from My Oracle Support, retry in some time or switch to the recommended option. 
      ./workspace/osm-image-builder/bin/build-osm-images.sh -f $DMANIFEST -s $STAGING -c osm -u MOS_username -p MOS_password
  7. Run build-osm-images.sh and pass the dependency manifest file, staging path and the images to be created.
    export DMANIFEST=./workspace/osm-image-builder/bin/osm_cn_ci_manifest_unpatched.yaml
export STAGING=$(pwd)/workspace/osm-image-builder/staging
    • Select the images to create using the -c command-line argument. If you are specifying more than one image to create, provide a comma-separated list.

      Valid values are:

      • osm: OSM image.
      • dbinstaller: OSM DB Installer image
      • gateway: OSM Gateway microservice image
      • rtuxms: OSM Runtime microservice image
    • To build all images, for example: 
      ./workspace/osm-image-builder/bin/build-osm-images.sh -f $DMANIFEST -s $STAGING -c osm,dbinstaller,gateway,rtuxms

These steps can be included into your CI pipeline as long as the required components are already downloaded to the staging area.

Additional Considerations When Using the Unpatched Manifest File

When an OSM image is created by the image builder with the osm_cn_ci_manifest_unpatched.yaml file, the resulting image does not contain the Fusion Middleware patches that are required for proper OSM cloud native functioning. It is intended to be used only for evaluation purposes. One workaround is to manually establish the association between OSM users and groups.

OSM users and groups are not associated after the start up of the admin server, which results in OSM EJB failing to deploy to the managed server. You should manually associate users and the group before starting up the managed server.

To associate OSM users with a group when using the unpatched manifest file:

  1. Create a new instance with only the admin server running. In the instance specification, change the value for clusterSize manually. This change would ultimately be performed by an automated CI/CD pipeline.
    vi $SPEC_PATH/project-instance.yaml

# Change the cluster size to 0 
clusterSize: 0

    Create the OSM instance.

  2. Run the config-security.sh script passing the domain namespace and domain UID.
    $OSM_CNTK/scripts/config-security.sh project project-instance
  3. Start the managed servers.
    • In the instance specification, set clusterSize to the desired number of managed servers.
      vi $SPEC_PATH/project-instance.yaml 
# Change the cluster size to the desired number 
clusterSize: 8
    • Upgrade the OSM instance.

The associations are reset every time the Admin Server pod terminates or restarts. This can happen when the instance is deleted, or on an unexpected event (such as an hardware issue), or as a side-effect of an instance upgrade that involves a rolling restart. Regardless of the scenario that led to Admin Server pod being recreated, the associations must be set up afresh.

To recreate the user and group association:
  1. Stop all the managed servers by setting the cluster size to 0 in the instance specification and upgrade the instance.
  2. Run the config-security.sh script as described in step 2 in the above procedure.
  3. Start the managed servers as described in step 3 in the above procedure.

Post-build Image Management

The OSM cloud native image builder creates images with names and tags based on the settings in the manifest file. By default, this results in the following images:
  • osm-cn-base: 7.5.0
  • osm-cn-db-installer: 7.5.0
  • osm-gateway: 7.5.0
  • osm-runtime-ux-server: 7.5.0

Once images are built in a CI pipeline, the pipeline uniquely tags the images and pushes them to an internal Docker repository. An uptake process can then be triggered for the new images:

  • Sanity Test
  • Development Test (for explicit retesting of scenarios that triggered the rebuild, if any)
  • System Test
  • Integration Test
  • Pre-Production Test
  • Production