Operator Utility overview

The Operator Utility is a command-line script that provides tools to manage installation, uninstallation, and image mirroring processes for the Operators.

This utility is designed to streamline the deployment of IBM® Sterling™ Order Management System Operator, IBM Sterling Intelligent Promising Operator, and IBM OMS Gateway Operator. It automates tasks such as pulling and mirroring images from the entitled IBM registry or a custom registry. The script streamlines the installation and uninstallation processes, supporting both online and airgap (offline) environments.

Features

Install Operators with optional rollback support for previous versions.
Uninstall Operators from specific namespaces.
Upgrade to a higher version of the IBM Sterling Order Management System Operator, IBM Sterling Intelligent Promising Operator, and IBM OMS Gateway Operator. The script first validates whether the upgrade path is correct before proceeding with an upgrade.
Mirror images to a target registry, including both Operator and application images if needed.

Availability of script

The Operator installation script is available in the latest cases and can be downloaded from the following repositories.

Available commands

The Operator installation script provides three commands - install, uninstall, and mirrror-images.

Note: The Operator currently supports only the Linux operating system on the amd64 architecture. Hence, the following commands uses linux_amd64.

install command

The install command is used to deploy the Operator in your environment. It supports both IBM entitled registry and custom registry. By default, the script uses IBM entitled registry that is icr.io for deployment. If any issue occurs during the installation process, the script automatically reverts previous changes to maintain system integrity. Review the following parameters when you use the IBM Sterling Order Management System Operator Utility.

Images registry
- By default, the images are pulled from the entitled IBM registry that is icr.io.
- For a custom registry, specify the registry and the repository details along with the authentication credentials. If the custom registry does not have the authentication, the credentials are ignored.
- If a custom registry is used, the script automatically mirrors the images unless the skip-mirror-images option is set.
Installation context
- If the script is run inside an extracted case, it automatically determines the version and edition from the case metadata and uses them for the deployment.
- If not inside a case, but a case file that is either extracted or archived exists in the working directory, the script uses it.
- If no local case is found, the script attempts to download the necessary files from IBM repository.
- In airgap environments without internet access, a local case file must be present, or the installation fails.
Installation namespace
- If a namespace is specified by using the --namespace option, the Operator is installed in that namespace.
- If no namespace is provided, the script defaults to the current Kubernetes context namespace.
Product-specific editions
- IBM Sterling Order Management System Operator requires an edition to be specified that is ent for enterprise and pro for professional, unless the script is running inside a case or a case file exists in the current directory.
- IBM Sterling Intelligent Promising Operator and IBM OMS Gateway Operator do not require an edition as they are only available in the Enterprise edition. Hence, for these two Operators, the --edition option is ignored.
Rollback and upgrade
- To upgrade to a newer version, specify the required case version during installation.
- The script supports rolling back to a previous version in IBM Sterling Order Management System.
- Rollback actions require user confirmation before proceeding.
- It is recommended to test installations in a lower environment before you deploy to production.
  Attention: The IBM Sterling Intelligent Promising and IBM OMS Gateway does not support rolling back to a specific version. Upgrading to higher versions is supported.

install usage

op_util_linux_amd64 install [Options]

install options

--case-version VERSION: It is the version of the case. It is optional if the script is run inside an extracted case or if an extracted or archived case is present in the current directory.

--edition EDITION: It is the edition, ent for enterprise and pro for professional, that you must specify forIBM Sterling Order Management System Operator. This option is ignored for IBM Sterling Intelligent Promising and IBM OMS Gateway, as they are only available in the Enterprise edition.

--registry REGISTRY: It is the custom image registry and defaults to icr.io which is an IBM Entitled Registry.

--repository REPO: It is a custom image repository and defaults to cpopen.

--registry-user USER: It is a registry username. It is mandatory for a custom registry and prompts if not provided.

--registry-pass PASS: It is a registry password. It is mandatory for a custom registry and prompts if not provided.

--namespace NAMESPACE: It is a Kubernetes namespace where the Operator is installed. It defaults to the current Kubernetes context namespace.

--skip-mirror-images: This option skips image mirroring if the images are already available in the target registry. Set this to true to bypass automatic mirroring. Defaults to false.

--force: This option allows installation of an older version or rolling back even when a newer version is already installed. Requires user confirmation before proceeding. Defaults to false.

install examples

Example 1: Install Sterling Order Management System Operator with a specific case version and edition.
```
op_util_linux_amd64 install oms --case-version 3.0.25 --edition pro
```

Example 2: Install Sterling Order Management System Operator with a specific case version and edition by using a custom registry. The following command mirrors the Operator images from icr.io to my.registry.com.

op_util_linux_amd64 install oms \
        --case-version 3.0.25 \
        --edition pro \
        --registry my.registry.com \
        --repository oms \
        --registry-user omsuser \
        --registry-pass omspass

For more information about steps for installation, see Installation with Operator Utility script.

uninstall command

The uninstall command removes the specified Operator from the target Kubernetes environment. The script ensures a clean removal of all associated resources within the specified namespace.

uninstall usage

op_util_linux_amd64 uninstall [Options]

uninstall options

--namespace NAMESPACE: Specify the Kubernetes namespace where the Operator should be uninstalled. It defaults to the current Kubernetes context namespace.

--force: Specify to force the uninstallation of the Operator, even if dependencies exist. Hence, use this option with caution.

uninstall examples

Example 1: Uninstalling IBM Sterling Order Management System Operator from the current namespace
```
op_util_linux_amd64 uninstall oms
```

For more information about using this script for uninstallation, see Uninstalling with the Operator Utility script.

mirror-images command

The mirror-images command copies Operator images from the IBM entitled registry that is icr.io to a custom target registry. This command ensures that the necessary images are available in environments with restricted internet access or private registries. Similar to the install mode, the case version and edition are optional if the script is running inside the case or there exists a case in the current directory.

By default, the script mirrors only the Operator images. You can override this behavior by specifying the --include-app-images option to mirror all the application images. With this option passed, you must provide the credentials to pull the application images from icr.io.

mirror-images usage

op_util_linux_amd64 mirror-images [Options]

mirror-images options

Define the mirror-images options as per the following list.

--case-version VERSION: Specify the case version. It is optional if the script is run inside an extracted case or if an extracted or archived case is present in the current directory.

--edition EDITION: Specify the required edition for IBM Sterling Order Management System Operator, that is ent for enterprise and pro for professional. This option is ignored for IBM Sterling Intelligent Promising Operator and IBM OMS Gateway Operator as they are only available in the Enterprise edition.

--src-registry-user USER: Specify the IBM entitlement registry user.

--src-registry-pass PASS: Specify the IBM entitlement registry password.

--tgt-registry REGISTRY: Specify the custom target registry.

--tgt-repository REPO: Specify the custom target repository

--tgt-registry-user USER: Specify the custom target registry username.

--tgt-registry-pass PASS: Specify the custom target registry password.

--include-app-images: Specify this option to include application images in the mirroring process. Defaults to false.

mirror-images examples

Example 1: Mirror the Operator images in Enterprise case 3.0.25 from the IBM entitlement registry that is icr.io to the target registry my.registry.com

op_util_linux_amd64 mirror-images \
        --case-version 3.0.25 \
        --edition ent \
        --tgt-registry my.registry.com \
        --tgt-repository oms \
        --tgt-registry-user omsuser

Example 2: Mirror the Operator and application images in Professional case 3.0.25 from the IBM entitlement registry that is icr.io to the target registry my.registry.com. When the --include-app-images option is passed, the --src-registry-user and --src-registry-pass must be provided.

op_util_linux_amd64 mirror-images \
      --case-version 3.0.25 \
      --edition pro \
      --tgt-registry my.registry.com \
      --tgt-repository oms \
      --tgt-registry-user omsuser \
      --src-registry-user iamapikey \
      --src-registry-pass <my-api-key> \
      --include-app-images

Migration from OLM to non-OLM installation

You can choose either OLM or non-OLM based installation, but you must continue using the same method once selected. Complete the following steps to migrate from OLM to non-OLM installation.

Uninstall the existing Operator installation for IBM Sterling Order Management System Operator.
Do not remove any existing custom resource definitions and custom resource instances for OMEnvironment, CallCenter, OrderHub, OrderService, and others.
Remove the catalog source for IBM Sterling Order Management System Operator.
Download the Operator Utility script from the case and use it for the installation. Ensure that the Operator you want to install in a non-OLM environment is compatible with the application service image versions which were previously deployed through OLM. For more information, see Installation with Operator Utility script.