Skip to content

Home

Jump to bottom
Leo Christy Jesuraj edited this page Mar 17, 2026 · 93 revisions

Install WebSphere Liberty Operator Development driver (for testing and demo purposes only)

Note: This driver is for testing and demo purposes only. Use the instructions at https://ibm.biz/wlo-docs for installing production-ready versions of WebSphere Liberty Operator that are available from the IBM Operators Catalog.

  1. Update your OpenShift cluster with a global pull secret for the cp.stg.icr.io entitled registry:
  • Get an entitlement key to the IBM Entitled Container Fulfillment Registry. Log in to MyIBM Container Software Library with the IBMid and password that are associated with the entitled software. Click on 'Container software library' on the left and expand the listed item. It should show that you have entitlement for 'all' IBM software. If you are not able to access the library or you don't have entitlement to 'all' IBM software then follow the process under Obtaining a staging entitlement key .
  • In the Entitlement keys section, pick an existing key or generate a new key. Select Copy key to copy the entitlement key to the clipboard.
  • Use the OpenShift cluster UI to configure the global pull secret with entitled registry (cp.stg.icr.io) credentials.
  • In the OpenShift cluster UI, click Workloads > Secrets and select the openshift-config namespace.
  • Find the existing pull-secret secret.
  • Select Edit Secret.
  • Click Add Credentials to add an entry for the entitled registry. Specify cp.stg.icr.io as the registry server address, cp as the username, and the entitlement key that you obtained in the previous step as the password.
  1. Install the Operator by using the following steps. If you want to use the kubectl or kustomize-based install options then skip steps 2.* and proceed to step 3:

2.1. Create ImageContentSourcePolicy for mirroring (this is needed because Operator artifacts are built with production registry reference, but until we GA the images would only be in the staging registry. The entry with icr.io/appcafe is not needed for WLO, but it's needed for OLO and RCO, hence included here as well.):

apiVersion: operator.openshift.io/v1alpha1
kind: ImageContentSourcePolicy
metadata:
   name: mirror-config
spec:
   repositoryDigestMirrors:
   - mirrors:
     - cp.stg.icr.io/cp
     source: cp.icr.io/cp
   - mirrors:
     - cp.stg.icr.io/cp
     source: icr.io/cpopen
   - mirrors:
     - cp.stg.icr.io/cp
     source: icr.io/appcafe

(To apply the resources, create a file and then copy and paste the contents above on your oc enabled system and run oc apply -f <fileName>)

2.2. Add the CatalogSource for WebSphere Liberty Operator:

apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: wlo-catalog
  namespace: openshift-marketplace
spec:
  displayName: WebSphere Liberty Catalog 1.6.0-rc.3
  image: 'icr.io/cpopen/websphere-liberty-operator-catalog@sha256:5bf16439ed2ecd232db86802e9b309451c5503a6dfa2886a075ca6f5d9839530'
  sourceType: grpc

2.3. Install or Upgrade the WebSphere Liberty Operator via OperatorHub:

2.3.1. To Install the WebSphere Liberty Operator:

  • From the OpenShift UI, click on Operators and then OperatorHub
  • In the search box type websphere liberty. Sometimes it takes a few minutes for the CatalogSource to be loaded by OCP. The operator won't show up until the CatalogSource is loaded.
  • Select the WebSphere Liberty operator and click Install
  • Complete the install with the default options

2.3.2. To Upgrade the WebSphere Liberty Operator:

  • Uninstall the WLO Operator
  • Go to Administration > CustomResourceDefinitions
  • Find CatalogSource
  • Click on Instances and find wlo-catalog
  • Either update image SHA value from wiki or delete wlo-catalog instance and recreate from the wiki page with the latest sha value
  • Complete the install with the default options
  1. Alternative install options:
  1. Create custom resources (CRs) to deploy applications and to gather trace, dump and performance data:
  • Sample CRs are available from the OpenShift UI as well as in this folder
  • Configuration options within the CRs are the same as Open Liberty Operator.

Follow the documentation at https://www.ibm.com/docs/en/was-liberty/base?topic=operator-using-websphere-liberty

New features in 1.6.0

Note: Known issues with the pre-release driver are listed at the bottom. Please review them before opening new issues.

Bring Your Own AES-256 Key

Support for specifying your own AES key for password encryption (i.e. LTPA) is added in WLO 1.6.0. This feature is specific to Liberty, hence only supported by OLO and WLO, but not RCO.

You can generate a random AES key using securityUtility generateAESKey. Then, you need to create a Secret named wlp-aes-encryption-key in the same namespaces as the corresponding WebSphereLibertyApplication CR. The Secret must include the AES key by including a key-value pair with aesEncryptionKey - as shown below.

Example:

apiVersion: v1
kind: Secret
metadata:
  name: wlp-aes-encryption-key
stringData:
  aesEncryptionKey: <your-aes-key>

Note: Secret wlp-aes-encryption-key with the AES key takes precedence over the Secret wlp-password-encryption-key. Operator will throw a warning when both Secrets are specified.

Liberty Operator handles setting up the server config to provide that AES key to Liberty runtime (in the application Pod). You shouldn't add that yourself.

If you have any passwords in your server config, then you must encrypt those passwords using securityUtility encode --encoding=aes --base64Key=<your_base64_key> <password>.

Liberty runtime blog with more info on AES key support: https://openliberty.io/blog/2025/12/02/25.0.0.12.html#aes256

Then, enable password encryption in CR by setting .spec.managePasswordEncryption to true.

More info on 'Managing Password Encryption' is at https://www.ibm.com/docs/en/was-liberty/base?topic=applications-managing-password-encryption. But it doesn't include the AES key support at this time. We'll work with ID to update it.

AES password encryption, when enabled, would apply to LTPA keys and config, when enabled by setting .spec.manageLTPA to true.

More info on LTPA support is at https://www.ibm.com/docs/en/was-liberty/base?topic=applications-configuring-lightweight-third-party-authentication-ltpa.

Host Alias

Specify host aliases using .spec.hostAliases in CR. More info on host aliases: https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/

Example:

spec:
  applicationImage: APP_IMAGE
  hostAliases:
  - ip: "10.10.10.1"
    hostnames:
    - test1.ibm.com
  - ip: "10.10.10.2"
    hostnames:
    - test2.ibm.com

Multiple Pull Secrets

Specify one or more pull secrets using the existing .spec.pullSecret field in CR. Separate the multiple values using ,.

Example:

spec:
  applicationImage: APP_IMAGE
  pullSecret: scorecard-staging-registry-1,scorecard-staging-registry-2

Known issues

  • Issue: Additional or duplicate warnings are added to Status. Warnings are not cleaned up in some cases.
    • Status: We are working on a fix. A new driver will be provided once the fix is delivered. Fixed in 1.6.0-rc.2.
  • Issue: Probes failing on Knative
    • Status: We believe this is due to the Knative API and are looking to update it. A new driver will be provided once the fix is delivered. Fixed in 1.6.0-rc.2.

Clone this wiki locally