IBM i Modernization Engine for Lifecycle Integration

IBM
© Copyright IBM Corp. 2022.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Tables of Contents
Welcome 1

Overview 1
Architecture Introduction 1
Known limitations 2
Security considerations 3
Accessibility 9

Administrator Guide 9
OpenShift Administrator Guide 10
Install IBM i Modernization Engine for Lifecycle Integration 10
Install IBM i Modernization Engine for Lifecycle Integration online 11
Install IBM i Modernization Engine for Lifecycle Integration in airgap environment 17
Manage browser certificates 25
Upgrade MERLIN platform and tools 26
Backup and restore 27
Data Storage for Merlin 35
Tracking license consumption of Merlin 36
Merlin Administrator Guide 37
Manage connections 37
Manage Inventory 37
Manage Credentials 39
Manage Templates 41
Manage MERLIN users and authorities 43
Manage Rest APIs on IBM i 50
Monitor resources for MERLIN tools 50
Manage Vault 52
Enable Forgot Password 53

User guide 59
Manage browser certificates 25
Manage connections 37
Manage Inventory 37
Manage Credentials 39
Manage Templates 41
Manage IBM i Servers 66
Manage the lifecycle of MERLIN tools 69
Update Password 75
Tools 77
IBM i Developer Integrated Development Environment 77
Getting Started 78
Overview 79
Git Integration 89
IBM i Projects 91
Editing 100
Editing RPG 100
Editing SQL 105
Developer build 107
Settings 112
 CI/CD 114
Access IBM i CICD 114
Deploy and initialize IBM i CICD 115
Work with IBM i CICD profiles 118
Work with Jenkins 121

Resources 125
IBM i Modernization Engine for Lifecycle Integration
IBM i Modernization Engine for Lifecycle Integration is a set of tools run in OpenShift containers which guide
and assist software developers in the modernization of IBM i applications, allowing them to realize the value
of a hybrid cloud, multi-platform
DevOps implementation.

IBM i Modernization Engine for Lifecycle Integration

IBM i Modernization Engine for Lifecycle Integration (Merlin) is a set of tools run in OpenShift containers
which guide and assist software developers
in the modernization of IBM i applications, allowing them to
realize the value of a hybrid cloud, multi-platform DevOps implementation.

Understand IBM i Modernization Engine for Lifecycle

Integration Architecture

IBM i Modernization Engine for Lifecycle Integration 1

Limitations
IBM i Developer

2 IBM i Modernization Engine for Lifecycle Integration

 General
Terminal - che* terminals do not respond. Use theia* terminal.
Yellow workspace navigation button loses branding when switching to new workspace
Existing editor does not use updates from .ibmi.json. Close and reopen editor for
changes to take affect.
hosted-instance.log in Output view has some errors at startup.
Copy actions outside the editor may show message saying access to clipboard is denied.
For debugging, use Access Client Solutions.
For 5250, use Access Client Solutions or open a terminal, ssh to the IBM i, and install
tn5250.
IBM i Project Explorer
Branch Changes filter for Source only supports local tags. Perform a git pull to retrieve
any tags that exist in the remote repository before trying to use the Branch Changes filter.
IFS query collapses if child is expanded in some cases.
Source uploaded to IFS on IBM i 7.3 server is tagged as 819 but actually is encoded as
UTF-8.
Read-only empty IFS files can not be opened.
Project will be refreshed if iproj.json is open and a library is added to the library list in
IBM i Project Explorer view.
Editor
General
sequence numbers not supported
bidi not supported
iproj.json and .ibmi.json editors do not have content assist
RPGLE
external references are not resolved
fixed form limited support
content assist limited context awareness
Developer Build
Japanese CCSID 5026 and 290 not supported
IBM i CI/CD

After the installation of IBM i CI/CD finished, wait some more time and try again if meets 504 or
Application not found error when launching IBM i CI/CD.
Only Admin user can Initialize Jenkins and Enable ARCAD Integration.

Security considerations
There are several aspects that need to be considered to ensure operating in a secure environment.

This topic provides security recommendations for setting up Data In Motion Encryption (DIME), Data At Rest
Encryption (DARE), Network Policies and Certificates. It is intended to help you create a secure
implementation of the application.

Data at rest
All user sensitive data at rest is stored in Hashicorp Vault. Hashicorp Vault is used to secure, store and tightly
control access to tokens, passwords, certificates, encryption keys for protecting secrets and other sensitive
data using a UI, CLI,
or HTTP API. Merlin leverages HashiCorp Vault as the Active Encryption solution to store
sensitive data such as credentials. Users do not need to directly work with HashiCorp Vault. Vault encrypts

IBM i Modernization Engine for Lifecycle Integration 3

 data in transit (with TLS) and at rest (using
AES 256-bit CBC encryption). This protects sensitive data from
unauthorized access in two major ways: as it travels across the network as well as in storage in the cloud and
datacenters. But it is neccessary for OpenShift administrator to understand
that Vault is used underneath. For
more information, please read the content of the following link: https://learn.hashicorp.com/vault.

Data in motion
Data in motion is encrypted using transport layer security (TLS 1.2) to secure all inbound and outbound
requests from MERLIN.

Network Policies
Network Policies are an application-centric construct which allow Merlin to specify how a pod is allowed to
communicate with various network "entities" over the network. NetworkPolicies apply to a connection with a
pod on one or both ends,
and are not relevant to other connections.

Four Network Policies are created by MERLIN

engine - defines that 'engine-0' pod is only allowed to be accessed by other pods, which are in the
same namespace and owned by same MERLIN instance, and the workspaces created by the same
MERLIN instance.
postgres - defines that the 'postgres-0' can only be accessed by engine, vault, keycloak pods in the
same namespace.
keycloak - defines that the 'keycloak-0' can only be accessed by engine, vault pods in the same
namespace.
vault - defines that the 'vault-0' can only be accessed by engine pod in the same namespace.

Manage certificate for MERLIN

Merlin uses cert-manager to manage all the certifications. For more information refer to
https://www.ibm.com/docs/en/cloud-paks/cp-management/1.2.0?topic=management-certificate-manager-
cert-manager

Merlin first creates a SelfSigned issuer resource, the SelfSigned issuer is for initially bootstrapping a CA issuer.
Then issue a root certificate and use that root as a CA issuer. The CA issuer will sign Merlin services certificate
based on the
private key.

The CA certificate stored in secret merlin-ca-secret, and the Merlin services certificate stored in secret
merlin-https-cert.

Merlin external routes are re-encrypt secured routes, see https://docs.openshift.com/container-

platform/4.10/networking/routes/secured-routes.html for more detail about secured route. The route
resource is using the Openshift default ingress certificate and reencrypt TLS termination to destination CA
certificate to enable the Ingress Controller to trust the service’s certificate.

There 2 steps to do if you want to use custom certificate both for Merlin services and routes:

To use a custom certificate for Merlin services, manually create the merlin-ca-secret which contains
the TLS key and certificate under the same namespace within Merlin before installing the Merlin.

When installing Merlin, Merlin will not create the root CA but use the custom one as the root CA to sign the
Merlin services certificate.

4 IBM i Modernization Engine for Lifecycle Integration

 Use the following oc admin command to create the secret:

oc create secret tls merlin-ca-secret --cert=tls.crt --key=tls.key -n <merlin-

namespace>

Note: You should prepare the tls.crt and tls.key before run the command.

To use a custom certificate for Merlin routes, refer to Openshift documentation

https://docs.openshift.com/container-platform/4.10/security/certificates/replacing-default-ingress-
certificate.html

Note: This will replace the Opensift cluster default certificate.

Manage MERLIN secrets

There are several secrects created when Merlin platform has been deployed. The key secrects are listed as
follows:

merlin-ca-secret
merlin-credential-secret
merlin-https-cert
merlin-jks-pkcs12-secret
merlin-third-party-cert

Verifying container image security

Customer Image Verification
Important: Customer verification of container image signatures is not required at this point in time. This
documentation will provide a way for teams to enable their customers to verify the image signatures, but the
customer can chose not to run
the verification.

After the customer downloads the images to their Bastion server, they must do image signature verification
before they transfer the downloaded images to their disconnected network. Customers have the option to
disable image signature verification,
but this is a customer specific setting. There are a few different options
that can be used to verify the image signature, depending on the tooling the customer has, and this section
will provide some examples and guidance around verifying the
image signature. For more detailed signature
verification documentation visit the IBM CISO Code Sign Service Documentation.

Enabling Customers to Verify the Image Signature

The customer needs access to the public portion of the pgp key used to sign the image, in order to verify the
image signature of the downloaded image. The $ ucl pgp-key -n
command will export the pgp key to your gpg
key ring. The private portion of this key will be a pointer to the HSM where the actual key data is stored, and
the public portion will be readily available in the key ring. This public key data will
need to be provided to the
customer, in order for them to verify the image signature. The way a customer gets this public key data MUST
be declared in the product offering's README file or Knowledge Center.

Portieris
Portieris is the open source version of CISE, which is an admission controller for Kubernetes. Portieris is being
enhanced to support Red Hat signed image verification, and this will work out of the box on Red Hat
OpenShift. The admission controller
will be installed to the cluster, and only allow images it can verify to be
spun up and ran inside your cluster.  

IBM i Modernization Engine for Lifecycle Integration 5

 OCP Verification
OCP verification is verification using any tool that relies on the atomic framework like: skopeo, podman, or oc 

In OCP 4, signature validation for Red Hat signed images comes automatically when the image is pulled to the
platform.  The /etc/containers/policy.json file is what drives the verification of image signatures in OCP.  Follow
these steps to configure
automatic signature verification on OCP 4:

Note: If the customer wants to take advantage of this feature for oc image, then the public key for your offering
must be imported to the disk of the machines for the cluster

1. Configure client to read from the entitled registry

2. Create the necessary configuration files

a. /etc/containers/policy.json

b. Any connection info files for the registry pulling images from ex: us.icr.io.yaml

3. Base64 encode the files and export to the environment

4. Create a machine config that will write those files to disk on the worker nodes
5. Apply the machine config yaml to the cluster
6. Repeat for the master nodes
7. Verify the changes took place by describing themachine configs, refer to
https://docs.openshift.com/container-platform/4.9/security/container_security/security-container-
signature.html

Detail procedure Step 1: Edit 99-master-trust.bu

variant: openshift

version: 4.9.0

metadata:

name: 99-master-trust

labels:

machineconfiguration.openshift.io/role: master

storage:

files:

- path: /etc/pki/rpm-gpg/public.gpg

mode: 0644

overwrite: true

contents:

inline: |

-----BEGIN PGP PUBLIC KEY BLOCK-----

mQINBGJzE4ABEADKNTEbo7Ki1BjcaK8tU9TEA1ce8oracBAp3Z8JKbf+VPLtU5yK

972DkRSAxSohPNQZWuDgdmdxuamtEnXcVZLHpx6YM1YfGTP+DLoo2Cv42tXssZsU

TYDuSVlvpiKZHhpWgt/oPpkIWkd81QSO60iEZq9UdVEdaNGYJ321v8uFnC/sJPWJ

FTrEvTH4Veyt8XUJpE20rpNedwB4uVnSaMrkrxgGzG0HPPndQ6cpU8lgWsqicSk2

NhCqqHsVoGpaxQDkPyhOzM1P47TwREQ2NluwzizaNJiuWqouJH69pKIBhqxIWz6h

0J02EH5A6o0nrYbrX20TSiQX0Z/zQMyG+qHt85ijgXtilv0NUe3eTormeMi4YdpL

QsMbSkq1FUVv3mkR17kmEw+ZwM1rg45biJohwohYpBR8YCM3Z6U5zOawkQ70WVK3

LbsbghJJWJ2J6Hfx9t32ms6LJ8Lfy1Q1WuSqfG7v/bjCcNVYHqhOcmo6+a3O17cv

Vhlfd8ffwsBwn+Q4PizkVKDtJ+T2yydmEAgtVbg5l/X7g8TuLiIh1YZTN3f/+zgh

2GQgjfy/5t3FGiiPMxxTKA4M1q5fMSDeFAEfZ4352uTMp9B54X3cEzrgcRpRWn75

2TzMQBvtDrNp48W3a5uKZomlKNfgvm8aOXVSQ0eTFKFC3v7YyfA12ZkeGwARAQAB

tAZtZXJsaW6JAjkEEwEIACMFAmJzE4ACGy8HCwkIBwMCAQYVCAIJCgsEFgIDAQIe

AQIXgAAKCRB9W6yKcTS3rWLaD/9LwJdiaxJbVH02mAHV4Fz8XQuwR3Nnk6HL4nzi

zcEh1AFT5CqksnSl1NO2OSG3Jq+7b2BIb8m3s7bOqW0wxEi8xgEQEJvM7AnI6uv2

31LN77UlxnmWyM4NhVqqTyln4rRbR8Ot5bH+hk4N4gb/ZKYtp//4yYazzFsJO7Gr

WzqJiMbX9FKhx7c2UfApOxF8ct4V/vk9IdBJtZs/DfPu+eI1OCxuXYDDp5aPUhjG

Rs+yaJIioDkI2ncSgTjPIKyKDLPNm8ZoPjs/vSTLjqX6cJcjVvTslFlaSnqJC3qQ

UmnPweRNCTtoQ3uSopk2pwbBEaAusU+pvc3zaRyYiST80neiQPP5bjHLEWwDzlV2

6 IBM i Modernization Engine for Lifecycle Integration

 dgU/ag3GYWrgtI7M6H+TR7HtEV3uYW1a+Bl/BnEziFpdy72cjqwQxSaOiPEmPG7B

g6FJdQiap0PpX2owqTZdGK7oMxwWoTWp34ON1VzFyuJlJXCjhbBDyMELYON03Ns6

slsAdJLmW1r+knfpneFnon8srHxMe1ZgtBmVW0QKQN6x/ag/XX5poQyEPoChzzWV

dKWJbIodZkxkbN6dCkq1kCFcwh4n8UlsLuQjc+Kzwi6odFqayRukUwxZV4XdPMIH

UaL23WYfvVjI/S/xbaRYx+EMdGsshqISyc6zRZGvu+eB4CJRMkJ/1Ki7Xd+qoxpi

3a007g==

=RQuM

-----END PGP PUBLIC KEY BLOCK-----

- path: /etc/containers/policy.json

mode: 0644

overwrite: true

contents:

inline: |

"default": [

"type": "insecureAcceptAnything"

],

"transports": {

"docker": {

"cp.icr.io": [

"type": "signedBy",

"keyType": "GPGKeys",

"keyPath": "/etc/pki/rpm-gpg/public.gpg"

],

"icr.io": [

"type": "signedBy",

"keyType": "GPGKeys",

"keyPath": "/etc/pki/rpm-gpg/public.gpg"

},

"docker-daemon": {

"": [

"type": "insecureAcceptAnything"

Step2: curl https://mirror.openshift.com/pub/openshift-v4/clients/butane/latest/butane-ppc64le --

output butane chmod +x butane

Step3: butane 99-master-trust.bu -o 99-master-trust.yaml

Step4: oc apply -f 99-master-trust.yaml

Step5: oc describe mcp/master

Step6: redo the 1-5 steps for worker node

Step7: oc debug node/master-0 -- chroot /host cat /etc/containers/policy.json

oc debug node/master-0 -- chroot /host cat /etc/pki/rpm-gpg/public.gpg

verify the changes has been written to the nodes.

IBM i Modernization Engine for Lifecycle Integration 7

 Note: The butane resource refer to https://access.redhat.com/documentation/en-
us/openshift_container_platform/4.8/html/installing/installation-configuration

Configure client to read from the entitled registry

In order to configure the client binary to read from the entitled registry, there must be credentials provided to
the docker config file$HOME/.docker/config.json.

Note:If using podmanto do the image pull and verification, then a $podman login to the entitled registry is
all that is required to provide the necessary auth information.

"auths": {

"us.icr.io": {

"username": "<Username (cp, iamapikey, ekey)>",

"password": "<API Key>"

},

...

Example Policy JSON File for Entitled Registry:

/etc/containers/policy.json

"default": [

"type": "insecureAcceptAnything"

],

"transports": {

"docker": {

"cp.icr.io": [

"type": "signedBy",

"keyType": "GPGKeys",

"keyPath": "PATH_TO_PUBLIC_GPG_KEY_ON_MACHINE"

},

"docker-daemon": {

"": [

"type": "insecureAcceptAnything"

Disabling Image Signature Verification

To turn off image signature verification the /etc/containers/policy.json file must be updated.

"default": [

"type": "insecureAcceptAnything"

],

8 IBM i Modernization Engine for Lifecycle Integration

 "transports": {}

Accessibility
Accessibility features assist users who have a disability, such as restricted mobility or limited vision, to use
information technology content successfully.

Overview
To take advantage of accessibility features, use the latest release of your screen reader and the latest web
browser that is supported by IBM i Modernization Engine for Lifecycle Integration.

Keyboard navigation
This product uses standard navigation keys.

Interface information
The IBM i Modernization Engine for Lifecycle Integration online product documentation is available in IBM
Knowledge Center, which is viewable from a standard web browser.

To enable your screen reader to accurately read syntax diagrams, source code examples, and text that
contains period or comma symbols, you must set the screen reader to speak all punctuation.

Vendor software
IBM i Modernization Engine for Lifecycle Integration includes certain vendor software that is not covered
under the IBM license agreement. IBM makes no representation about the accessibility features of these
products. Contact the vendor for accessibility
information about its products.

Related accessibility information

In addition to standard IBM help desk and support websites, IBM has a TTY telephone service for use by deaf
or hard of hearing customers to access sales and support services:

TTY service 800-IBM-3383 (800-426-3383) (within North America) For more information about the
commitment that IBM has to accessibility, see IBM Accessibility.

IBM i Modernization Engine for Lifecycle Integration -

Platform
Centralized place to manage users, authentication, credentials, inventories, and so on for all the Merlin
Tools.

IBM i Modernization Engine for Lifecycle Integration 9

 Manage the lifecycle of IBM i virtual machines on prem or in IBM Cloud.
Create and deploy REST API services on target IBM i systems from programs and data.

Capabilities:

Tool Lifecycle
Authentication
Certification Management
User Management
Monitoring
Inventory Management
Credential Management
IBM i VM Management
IBM i Software Installer

OpenShift Administrator Guide

IBM i Modernization Engine for Lifecycle Integration is installed and managed in Red Hat® OpenShift®
Container Platform.

Install IBM i Modernization Engine for Lifecycle

Integration
IBM i Modernization Engine for Lifecycle Integration can be installed from either OpenShift web console, or oc
command line.

Install IBM i Modernization Engine for Lifecycle Integration online

Install IBM i Modernization Engine for Lifecycle Integration in airgap environment

Supported product versions

OpenShift Container Platform 4.8 and 4.9

IBM i 7.3, 7.4, 7.5

The resource needed for the setup

ComponentNa Memory
CPU Request CPULimit Memory Limit Note
me Request
Merlin 2.5 5 7Gi 15Gi
IBM i Developer 0.5 2.7 1.5 3Gi The resource is
Tool per each
instance
IBM i CI/CD 500m 1 1Gi 2Gi The resource is
per each
instance

10 IBM i Modernization Engine for Lifecycle Integration

Deploying IBM i Modernization Engine For Lifecycle
Integration
IBM i Modernization Engine For Lifecycle Integration can be ran on OpenShift® Container Platform that runs
on Power Host (ppc64le) and OpenShift Container Platform that runs on VMware (amd64).

Supported installation mode

OLM Own Namespace Mode

OLM All Namespace Mode

Installation Mode Coexistence

Operators must not be installed in a "mixed mode" with some in Own and some in All Namespace mode

Dangers to Installing an Operator more than once

One of the main inhibitors to installing an Operator more than once to a cluster is the lifecycle of the
CustomResourceDefinition (CRD) API. The CRD is an API interface that the Operator watches on the cluster.
New and emerging requirements will
cause this API to evolve over time. When this API evolves, it can lead to
the need to convert one version of the API to another, or to breaking API changes.

In Kubernetes, this is handled via a conversion webhook, which is a cluster scoped resource. This means that
if more than one version of an Operator is installed on a cluster and they have different conversion webhooks,
there is a leader election
problem. The Kubernetes control plane does not know which conversion webhook
version to pick. This can lead to many problems in an installation/upgrade for an Operator and the resources it
manages. Operators are designed to be extensions of the
control plane and not multi-tenant on the cluster.
The applications they manage can be multi-tenant on the cluster, but the Operator cannot.

The Custom Resource API Versioning page goes into more details on this and this page will call out some high
level topics to be aware of.

Install IBM i Modernization Engine for Lifecycle

Integration online
If the cluster is connected to the internet, IBM i Modernization Engine For Lifecycle Integration can be
installed in the cluster online.

Log in to the OpenShift cluster with oc login before performs any steps that use the Red Hat® OpenShift®
Container Platform command-line interface (CLI).

Preparation procedure
Complete these prerequisite tasks to prepare for the IBM i Modernization Engine For Lifecycle Integration
installation.

Install OpenShift
Install the OpenShift CLI
Configure storage
Create a custom project (namespace)

IBM i Modernization Engine for Lifecycle Integration 11

 Create the entitlement key secret
Configure network policies
Create the catalog source
Install the operator
Create the custom resource
Verify the installation
Access the Merlin console

Install OpenShift
IBM i Modernization Engine For Lifecycle Integration requires OpenShift to be installed and running. An
administrative access to the OpenShift cluster is required.

For information on supported versions of OpenShift, see Supported product versions.

Install OpenShift using the instructions in Installing Red Hat OpenShift Container Platform.

Install the OpenShift CLI

Install the OpenShift command line interface (oc) on the cluster's boot node and run oc login, using the
instructions in Getting started with the OpenShift CLI.

Configure storage
The storage configuration must satisfy the sizing requirements. For more information on the storage classes
that are needed for installing IBM i Modernization Engine For Lifecycle Integration, see Configure a default
storage class.

Create a custom project (namespace)

Create a project (namespace) to deploy IBM i Modernization Engine For Lifecycle Integration into.

A project is a Openshift namespace. a custom project (namespace) must be created and not use the default,
kube-system, kube-public, openshift-node, openshift-infra, or openshift projects (namespaces). This is
because IBM i Modernization Engine For
Lifecycle Integration uses Security Context Constraints (SCC), and
SCCs cannot be assigned to pods created in one of the default OpenShift projects (namespaces).

Create a project (namespace) with either of the following methods:

Option 1: Create a project with the OpenShift console

Option 2: Create a project with the OpenShift CLI

Option 1: Create a project with the OpenShift console

From the OpenShift console, click Home > Projects. Select Create Project, specify the Name of the project, for
example merlin and click Create.

12 IBM i Modernization Engine for Lifecycle Integration

 Option 2: Create a project with the OpenShift CLI
Run oc create namespace <namespace> where <namespace> is the name of the project
(namespace), for example **merlin**.

Create the entitlement key secret

Complete the following steps to create a docker-registry secret to enable the deployment to pull the IBM i
Modernization Engine For Lifecycle Integration images from the IBM® Entitled Registry.

Create the entitlement key secret with either of the following methods:
Obtain the entitlement key that is assigned to the IBMid. Log in to MyIBM Container Software Library Opens in
a new tab with the IBMid and password details that are associated with the entitled software. Then configure
the global image pull secret
on the Openshift environment.

Extract the current global image pull secret from the cluster into a file in the current directory named
.dockerconfigjson:

oc extract secret/pull-secret -n openshift-config --to=.

Create a base64 encoded string with entitled registry userid and password:

printf "cp:<entitlementkey>" | base64

Edit the .dockerconfigjson file and ADD a new JSON object to the auths object to it with the credentials
for the staging repository. For example:

"cp.icr.io": {

"auth": "Replace-With-The-Encoded-String-Got-In-Last-Step",

"email": "Replace-With-Your-Email"

Update the global image pull secret with the updated credentials:

oc set data secret/pull-secret -n openshift-config --from-

file=.dockerconfigjson

Monitor the node status using the command: oc get nodes

When the nodes are finish restarting, the cluster is now ready to pull images from the staging registry
with production image references.

Install IBM catalog source

IBM i Modernization Engine for Lifecycle Integration 13
 Add the IBM i Modernization Engine For Lifecycle Integration catalog source to the OpenShift cluster.

Create the catalog source with either of the following methods:

Option 1: Create the catalog source with the OpenShift console

Option 2: Create the catalog source with the OpenShift CLI

Option 1: Create the catalog source with the OpenShift console

Log in to the OpenShift cluster's console.
Add the IBM Operators CatalogSource.
Click the plus icon in the upper right corner to open the Import YAML dialog box, paste in the following
content, and then click Create.

apiVersion: operators.coreos.com/v1alpha1

kind: CatalogSource

metadata:

name: ibm-operator-catalog

namespace: openshift-marketplace

spec:

displayName: ibm-operator-catalog

publisher: IBM Content

sourceType: grpc

image: icr.io/cpopen/ibm-operator-catalog:latest

Go to Administration > Cluster Settings. Under Global Configuration > OperatorHub > Sources, verify
that the ibm-operator-catalog CatalogSource object is present.

Option 2: Create the catalog source with the OpenShift CLI

Add the IBM Operators CatalogSource by running the following command:

cat << EOF | oc apply -f -

apiVersion: operators.coreos.com/v1alpha1

kind: CatalogSource

metadata:

name: ibm-operator-catalog

namespace: openshift-marketplace

spec:

displayName: ibm-operator-catalog

publisher: IBM Content

sourceType: grpc

image: icr.io/cpopen/ibm-operator-catalog:latest

EOF

Verify that the ibm-operator-catalog CatalogSource object is present, and is returned by the following
command.

oc get CatalogSources ibm-operator-catalog -n openshift-marketplace

Example output:

oc get CatalogSources ibm-operator-catalog -n openshift-marketplace

NAME DISPLAY TYPE PUBLISHER AGE

ibm-operator-catalog IBM Operator Catalog grpc IBM 4h13m

Install the operator

Install Merlin operator with either of the following installation methods:

14 IBM i Modernization Engine for Lifecycle Integration

 Option 1: Install the operator with the OpenShift console
Option 2: Install the operator with the OpenShift CLI

Option 1: Install the operator with the OpenShift console

Log in to the OpenShift cluster's console.
Click Operators > OperatorHub. The OperatorHub page is displayed.
In the All Items field, enter IBM i Modernization Engine for Lifecycle Integration. The Merlin Operator is
displayed.
Click the IBM i Modernization Engine for Lifecycle Integration tile. The IBM i Modernization Engine for
Lifecycle Integration window is displayed.
Click Install. The Install Operator page is displayed.
Enter the following values:

* Set the Namespace to be the project (namespace) in which to install

the Operator, such as **merlin**.

* Set Update Channel to v1.0.

* Set Approval Strategy to Automatic.

Click Install and wait for the AI Manager operator to install.

Verify that the Merlin operator is successfully installed.
Navigate to Operators > Installed Operators, and select the project from the Projects dropdown. IBM i
Modernization Engine for Lifecycle Integration and its dependant operator in the project are listed with
a status of Succeeded.

Option 2: Install the operator with the OpenShift CLI

Create Operator Group.

Create an Operator group in the custom project (namespace), or the Merlin operator will not install. There
might be an Operator group for managing a namespace for given APIs. If there is an Operator group for the
namespace, do not create a second
one.

Create the Operator group by running the following command:

cat << EOF | oc apply -f -

apiVersion: operators.coreos.com/v1

kind: OperatorGroup

metadata:

name: merlin-operator-group

namespace: <namespace>

spec:

targetNamespaces:

- <namespace>

EOF

Where
is the project (namespace created earlier in Create a custom project (namespace).

Install the Merlin operator with the following command.

cat << EOF | oc apply -f -

apiVersion: operators.coreos.com/v1alpha1

kind: Subscription

metadata:

name: ibmi-merlin-operator

namespace: <namespace>

spec:

channel: v1.0

installPlanApproval: Automatic

IBM i Modernization Engine for Lifecycle Integration 15

 name: ibmi-merlin-operator

source: ibm-operator-catalog

sourceNamespace: openshift-marketplace

EOF

Where
is the project (namespace) created earlier, such as merlin.

After a few minutes, the operator is installed. Verify that the all components are in the Succeeded state by
running the following command:

oc get csv -n <namespace> | grep ibmi-merlin-operator

Where
is openshift-operators if using the AllNamespaces installation mode, or the project (namespace)
created earlier in Create a custom project (namespace) if using the OwnNamespace installation mode. For
more information about installation modes,
see Operator installation mode.

Deploy MERLIN instance

Once MERLIN operator has been installed into a specific project, MERLIN instance can be installed.

1. Click on 'Installed Operators' under 'Operators' section in the left navigation panel of OCP.
2. Two operators will be shown. Click the link of 'IBM i Modernization Engine for LifeCycle Integration'
operator.
3. Click on 'Details' tab of Operator details page.
4. Click on the link of 'Create Instance' of Merlin.
5. Fill in the following items

* Name

* Pull Policy

* StorageClassName

* ConfigurationProfileName

* License

* Version

6. Click on the 'Create' button.

7. Check the status of Merlin until the status turns into 'Conditions: DependenciesSatisfied, Reconciled'
by running 'oc describe merlins/merlin'.

Status:

Application URL: https://merlin-zhulj-new-catalog.apps.amp-fb35.nip.io/merlin

Conditions:

Last Transition Time: 2022-04-27T14:58:19Z

Last Update Time: 2022-04-27T15:01:25Z

Status: True

Type: DependenciesSatisfied

Last Transition Time: 2022-04-27T14:59:44Z

Last Update Time: 2022-04-27T15:02:53Z

Status: True

Type: Reconciled

Keycloak URL: https://keycloak-zhulj-new-catalog.apps.amp-fb35.nip.io

Op Version: 1.0.0

* Application URL: The 'Application URL' status property is a string flag that
stands for the URL of Merlin install.

* Conditions:

The 'DependenciesSatisfied' condition will be set 'True' when the

CustomResourceDefinition merlins.merlin.ibm.com is ready.

The 'Reconciled' condition, for example, will be set 'True' when all of the Pods
are 'Ready'.

16 IBM i Modernization Engine for Lifecycle Integration

 * Keycloak URL: it is a string that stands for the URL of Keycloak install.

* Op Version: it is a string that stands for the version of Operator.

1. After Merlin has been deployed, the Merlin URL can be obtained from the Networking->Routes.

Check Pods' status

The below Pods are created after the deployment of MERLIN instance.

* engine

* keycloak

* merlin

* postgres

* vault

Check MERLIN routes

Three routes are created for MERLIN platform

* merlin

* keycloak

* rest

Check MERLIN network policies

Run 'oc get networkpolicy'

oc get networkpolicy

NAME POD-SELECTOR AGE

engine app.kubernetes.io/component=engine 11m

keycloak app.kubernetes.io/component=keycloak 11m

postgres app.kubernetes.io/component=postgres 11m

vault app.kubernetes.io/component=vault 11m

Obtain MERLIN platform initial password

Go to Workloads->Secrets. Find merlin-credential-secret. The initial user name and password of Merlin
Platform are stored in this secret. The user name is stored in ADMIN_USERNAME, and the password is stored
in ADMIN_PASSWORD.

Install IBM i Modernization Engine for Lifecycle

Integration in AirGap environment
IBM i Modernization Engine for Lifecycle Integration can be installed on a RedHatOpenShift Container
Platform in that has no internet connectivity.

Prerequisites
Prepare a bastion host
Prepare a local Docker registry
Prepare the multi-architecture registry
Configure the registry

IBM i Modernization Engine for Lifecycle Integration 17

 Prepare to install IBM i Modernization Engine for Lifecycle Integration
Create environment variables for the installer and image inventory
Download the CASE installer
Log in to the OpenShift Container Platform as a cluster administrator
Create a Kubernetes namespace for IBM i Modernization Engine for Lifecycle Integration
Obtain the entitlement key
Mirror the images and configure the cluster
Create the IBM i Modernization Engine for Lifecycle Integration catalog source
Install IBM i Modernization Engine for Lifecycle Integration
Install by using the CLI
Install by using the OpenShift Container Platform console

Prerequisites
An OpenShift Container Platform cluster must be installed. For the supported OpenShift Container Platform
versions, see Supported OpenShift versions and platforms.

The cluster must meet the resource requirements, see Supported OpenShift versions and platforms.

A bastion server must be configured. For more information, see Prepare a bastion host.

A local Docker registry that is accessible from both the bastion server and the OpenShift Container Platform
cluster nodes must be available. For more information, see Prepare a Docker registry.

Prepare a bastion host

Prepare a bastion host that can access the OpenShift Container Platform cluster, the local Docker registry, and
the internet. The bastion host must be on a Linux® platform with any operating system that the IBM Cloud
Pak® CLI and the OpenShift Container
Platform CLI support.

Complete these steps on the bastion node:

Install Docker or Podman. To install Docker, run these commands:

yum check-update

yum install docker

Start the Docker service.

systemctl enable docker

systemctl start docker

Install httpd-tools.

yum install httpd-tools

Install the IBM Cloud Pak® CLI. Install the latest version of the binary file for the platform. For more
information, see cloud-pak-cli Opens in a new tab. Download the binary file.

wget https://github.com/IBM/cloud-pak-cli/releases/download/v<version-
number>/<binary-file-name>

For example, wget https://github.com/IBM/cloud-pak-cli/releases/latest/download/cloudctl-linux-

amd64.tar.gz.

Extract the binary file.

18 IBM i Modernization Engine for Lifecycle Integration

tar -xf <binary-file-name>

Run the following commands to modify and move the file.

chmod 755 <file-name>

mv <file-name> /usr/local/bin/cloudctl

Confirm that cloudctl is installed:

cloudctl --help

Install the oc OpenShift Container Platform CLI tool. For more information, see OpenShift Container
Platform CLI tools.

Create a directory that serves as the offline store. Following is an example directory. This example is
used in the subsequent steps.

mkdir $HOME/offline

Note: This offline store must be persistent to avoid transferring data more than once. The persistence
also helps to run the mirroring process multiple times or on a schedule.

Prepare a local Docker registry

A local, Docker registry must be created to mirror all images in the local environment. The registry must meet
the following requirements:

Support Docker Manifest V2, Schema 2 Opens in a new tab.

Support multi-architecture images. Note: Do not use OpenShift image registry as the local registry. The
OpenShift registry does not support multi-architecture images.
Is accessible from both the bastion server and the OpenShift Container Platform cluster nodes.
Has the username and password of a user who can write to the target registry from the bastion host.
Has the username and password of a user who can read from the target registry that is on the
OpenShift cluster nodes.
Allow path separators in the image name.

Below are the steps in Prepare the multi-architecture registry to create a multi-architecture registry.

Docker Prerequisites
A Red Hat® Enterprise Linux® (RHEL) server must be used as the registry host.

The registry host must have access to the internet.

Create the Docker registry

Complete these steps to create the Docker registry.

Install the required packages.

yum -y install docker httpd-tools

Start the Docker service.

systemctl enable docker

systemctl start docker

Create folders for the registry.

mkdir -p /opt/registry/{auth,certs,data}

IBM i Modernization Engine for Lifecycle Integration 19

 Provide a certificate for the registry. If there is a certificate from a trusted certificate authority (CA), proceed
with the next step. Otherwise, a self-signed certificate should be generated.

Change to the /opt/registry/certs directory.

cd /opt/registry/certs

Generate a certificate.

openssl req -newkey rsa:4096 -nodes -sha256 -keyout domain.key -x509 -days 365 -
out domain.crt

At the prompts, provide the required values for the certificate:

Country Name (two-letter code)

Specify the two-letter ISO country code for the location. See the ISO 3166 country
codes standard.

State or Province Name (full name)

Enter the full name of the state or province.

Locality Name (for example, city)

Enter the name of the city.

Organization Name (for example, company)

Enter the company name.

Organizational Unit Name (for example, section)

Enter the department name.

Common Name (for example, the name or the hostname of the server)

Enter the hostname for the registry host. Ensure that the hostname is in DNS and
that it resolves to the expected IP address.

Email Address

Enter the email address. For more information, see the req description in the
OpenSSL documentation.

Note: For the common name, make sure to enter a hostname that can be resolved to an IP address when log
in to the Docker registry.

Generate a username and a password in the bcrpt format for the registry.

htpasswd -bBc /opt/registry/auth/htpasswd <registry_user_name> <registry_password>

Create the Docker registry container to host the registry.

docker run --name mirror-registry -p <the_registry_host_port>:5000 \

-v /opt/registry/data:/var/lib/registry:z \

-v /opt/registry/auth:/auth:z \

-e "REGISTRY_AUTH=htpasswd" \

-e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \

-e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \

-v /opt/registry/certs:/certs:z \

-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \

-e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \

-e REGISTRY_COMPATIBILITY_SCHEMA1_ENABLED=true \

-d docker.io/library/registry:2

Note: For the_registry_host_port, specify the port that the Docker registry uses to serve content.

If the registry is behind a firewall, open the ports that the registry requires.

firewall-cmd --add-port=<the_registry_host_port>/tcp --zone=internal --permanent

firewall-cmd --add-port=<the_registry_host_port>/tcp --zone=public --permanent

firewall-cmd --reload

20 IBM i Modernization Engine for Lifecycle Integration

If a self-signed certificate is being use, add it to the list of trusted certificates.

cp /opt/registry/certs/domain.crt /etc/pki/ca-trust/source/anchors/

update-ca-trust

Verify that the registry is available.

curl -u <registry_user_name>:<registry_password> -k
https://<the_registry_host_name>:<the_registry_host_port>/v2/_catalog

See these parameter descriptions:

registry_user_name is the username to access the registry.

registry_password is the password of the registry user.

the_registry_host_nameis the registry domain name that was specified in the

certificate. For example, registry.example.com.

the_registry_host_port is the port that the Docker registry uses to serve content.

Following is a sample response:

{"repositories":[]}

Create a Docker certs folder and place the certificate in the folder.

mkdir -p /etc/docker/certs.d/<the_registry_host_name>:<the_registry_host_port>

cp /opt/registry/certs/domain.crt /etc/docker/certs.d/<the_registry_host_name>:
<the_registry_host_port>/ca.crt

Log in the Docker registry.

docker login <the_registry_host_name>:<the_registry_host_port> -u

<registry_user_name> -p <registry_password>

Configure the registry

After creates the registry, configure the Docker registry:

Create registry namespaces.

Create a separate registry namespace for each public registry source.
cpopen - Namespace to store all Operator images from the icr.io/cpopen namespace.
cp/ibmi-merlin - Namespace to store the IBM images from the cp.icr.io/cp/ibmi-merlin repository. The
cp/ibmi-merlin namespace is for the images in the IBM Entitled Registry that require a product
entitlement key and credentials to pully.

Verify that each namespace meets the following requirements:

Supports auto-repository creation.

Has credentials of a user who can write and create repositories. The bastion host uses these
credentials.
Has credentials of a user who can read all repositories. The OpenShift Container Platform cluster uses
these credentials.

Prepare to install IBM i Modernization Engine for Lifecycle Integration

Complete these steps on the bastion host.

Create environment variables for the installer and image inventory

Create the following environment variables with the installer CASE name and the image inventory.

IBM i Modernization Engine for Lifecycle Integration 21

 export CASE_ARCHIVE=ibm-merlin-1.0.0.tgz

export CASE_INVENTORY_SETUP=merlinOperatorSetup

Download the IBM i Modernization Engine for Lifecycle Integration installer and image
inventory to the bastion host.
cloudctl case save \

--case https://github.com/IBM/cloud-pak/raw/master/repo/case/ibm-merlin-
1.0.0.tgz \

--outputdir $HOME/offline/

cloudctl case save \

--case https://github.com/IBM/cloud-pak/raw/master/repo/case/ibm-merlin-cicd-
1.0.0.tgz \

--outputdir $HOME/offline/

cloudctl case save \

--case https://github.com/IBM/cloud-pak/raw/master/repo/case/ibm-merlin-
development-environment-1.0.0.tgz \

--outputdir $HOME/offline/

Log in to the OpenShift Container Platform cluster as a cluster administrator

Following is an example command to log in to the OpenShift Container Platform cluster:

oc login <cluster host:port> --username=<cluster admin user> --password=<cluster

admin password>

Create a Kubernetes namespace for the IBM i Modernization Engine for Lifecycle
Integration
export NAMESPACE=merlin

oc create namespace ${NAMESPACE}

Configure global pull secret with the entitlement key, see Create the entitlement key
secret

Complete these steps to mirror the images and configure the cluster:
Note: Do not use the tilde within double quotation marks in any command. For example, do not use args "--
registry
--user
--pass
--inputDir ~/offline". The tilde does not expand and the commands might fail.

Store authentication credentials for all source Docker registries.

The IBM i Modernization Engine for Lifecycle Integration installer is stored in a public registry and does
not require authentication. However, most of the components, require one or more authenticated
registries. The following registry requires
authentication: cp.icr.io
Run the following command to configure authentication credentials for the registry:

cloudctl case launch \

--case $HOME/offline/${CASE_ARCHIVE} \

--inventory ${CASE_INVENTORY_SETUP} \

--action configure-creds-airgap \

--namespace ${NAMESPACE} \

--args "--registry cp.icr.io --user cp --pass <the-entitlement-key>" \

--tolerance 1

The command stores and caches the registry credentials in a file on the file system in the
$HOME/.airgap/secrets location.

22 IBM i Modernization Engine for Lifecycle Integration

Create environment variables with the local Docker registry connection information.
export LOCAL_DOCKER_REGISTRY=<IP_or_FQDN_of_local_docker_registry>

export LOCAL_DOCKER_USER=<username>

export LOCAL_DOCKER_PASSWORD=<password>

Note: The Docker registry uses standard ports such as 80 or 443. If the Docker registry uses a non-standard
port, specify the port by using the syntax
:
. For example, export
LOCAL_DOCKER_REGISTRY=myregistry.local:5000.

Configure an authentication secret for the local Docker registry.

Note: This step needs to be done only one time.

cloudctl case launch \

--case $HOME/offline/${CASE_ARCHIVE} \

--inventory ${CASE_INVENTORY_SETUP} \

--action configure-creds-airgap \

--namespace ${NAMESPACE} \

--args "--registry ${LOCAL_DOCKER_REGISTRY} --user ${LOCAL_DOCKER_USER} --pass

${LOCAL_DOCKER_PASSWORD}" \

--tolerance 1

The command stores and caches the registry credentials in a file on the file system in the
$HOME/.airgap/secrets location.

Configure a global image pull secret and ImageContentSourcePolicy.

cloudctl case launch \

--case $HOME/offline/${CASE_ARCHIVE} \

--inventory ${CASE_INVENTORY_SETUP} \

--action configure-cluster-airgap \

--namespace ${NAMESPACE} \

--args "--registry ${LOCAL_DOCKER_REGISTRY} --user ${LOCAL_DOCKER_USER} --pass

${LOCAL_DOCKER_PASSWORD}" \

--tolerance 1

Verify that the ImageContentSourcePolicy resource is created.

oc get imageContentSourcePolicy

Optional: If an insecure registry is being used, the local registry must be added to the cluster
insecureRegistries list.

oc patch image.config.openshift.io/cluster --type=merge -p '{"spec":

{"registrySources":{"insecureRegistries":["'${LOCAL_DOCKER_REGISTRY}'"]}}}'

Verify the cluster node status.

oc get nodes

After the imageContentsourcePolicy and global image pull secret are applied, wait until all the nodes show a
Ready status.

Mirror the images to the local registry.

cloudctl case launch \

--case $HOME/offline/${CASE_ARCHIVE} \

--inventory ${CASE_INVENTORY_SETUP} \

--action mirror-images \

IBM i Modernization Engine for Lifecycle Integration 23

 --namespace ${NAMESPACE} \

--args "--registry ${LOCAL_DOCKER_REGISTRY} --inputDir $HOME/offline" \

--tolerance 1

cloudctl case launch \

--case $HOME/offline/ibm-merlin-cicd-1.0.0.tgz \

--inventory merlinCicdOperatorSetup \

--action mirror-images \

--namespace ${NAMESPACE} \

--args "--registry ${LOCAL_DOCKER_REGISTRY} --inputDir $HOME/offline" \

--tolerance 1

cloudctl case launch \

--case $HOME/offline/ibm-merlin-development-environment-1.0.0.tgz \

--inventory merlinDevelopmentEnvironmentOperatorSetup \

--action mirror-images \

--namespace ${NAMESPACE} \

--args "--registry ${LOCAL_DOCKER_REGISTRY} --inputDir $HOME/offline" \

--tolerance 1

Create the IBM i Modernization Engine for Lifecycle Integration catalog source

Create a catalog source for IBM i Modernization Engine for Lifecycle Integration and
common services.
cloudctl case launch \

--case $HOME/offline/${CASE_ARCHIVE} \

--inventory ${CASE_INVENTORY_SETUP} \

--action install-catalog \

--namespace ${NAMESPACE} \

--args "--registry ${LOCAL_DOCKER_REGISTRY} --inputDir $HOME/offline --

recursive" \

--tolerance 1

cloudctl case launch \

--case $HOME/offline/ibm-merlin-cicd-1.0.0.tgz \

--inventory merlinCicdOperatorSetup \

--action install-catalog \

--namespace ${NAMESPACE} \

--args "--registry ${LOCAL_DOCKER_REGISTRY} --inputDir $HOME/offline --

recursive" \

--tolerance 1

cloudctl case launch \

--case $HOME/offline/ibm-merlin-development-environment-1.0.0.tgz \

--inventory merlinDevelopmentEnvironmentOperatorSetup \

--action install-catalog \

--namespace ${NAMESPACE} \

--args "--registry ${LOCAL_DOCKER_REGISTRY} --inputDir $HOME/offline --

recursive" \

--tolerance 1

Verify that the catalog sources for the IBM i Modernization Engine for Lifecycle Integration installer and
common services are created.

oc get pods -n openshift-marketplace

oc get catalogsource -n openshift-marketplace

Install IBM i Modernization Engine for Lifecycle Integration

IBM i Modernization Engine for Lifecycle Integration can be installed by using the cloudctl CLI or by using the
OpenShift Container Platform console.

24 IBM i Modernization Engine for Lifecycle Integration

 Install by using the CLI

Complete these steps to install by using the cloudctl CLI.

Create an environment variable for the storage class for the IBM i Modernization Engine for Lifecycle
Integration installation. For more information, see Data Storage for Merlin.

export STORAGE_CLASS=<storage_class_name>

cloudctl case launch \

--inventory merlinOperator \

--case $HOME/offline/${CASE_ARCHIVE} \

--namespace ${NAMESPACE} \

--action apply-custom-resources \

--args "--licenseAccept true" \

--tolerance 1

Doesn't support to create multiple merlin CRs with one namespace.

Manage browser certificates

Configure certificate for your browser

Modernization Engine for Lifecycle Integration (MERLIN) supports Hyper Text Transfer Protocol over
SecureSocket Layer(HTTPS) to protect the confidential data sent between client and server. Before login the
MERLIN, you need to let the web browser
to trust the MERLIN CA. This document describes how to trust
MERLIN CA for Chrome and Firefox web browser.

How to trust the MERLIN CA for Chrome

When entering the MERLIN web address with chrome first time, Chrome might show a blank page with the
text Loading....

As the Chrome use the system trust store to verify the CA, the ways to adding CA to system store between
Windows and Mac are different, so both Mac and Windows follow the Download MERLIN CA steps to obtain
the Merlin CA, but follow
different steps: Add the CA to trust store with Windows system or Add
the CA to trust store with Mac system to trust CA.

1. Download the MERLIN CA

Click the Not Secure button, and then select the Certificate is not valid item.
Click the Certification Path tab, then click the first CA, and click the View Certificate button.
Click the Details tab in the CA certificate and then click the Copy to File button.
In the Certificate Export Wizard, click the Next button.
Select the DER encoded binary X.509(.CER) and then select Next
Enter the path and name which you want to save the certificate. Then click Next.
Click Finish button
2. Add the CA to trust store with Windows system

If the client is a Windows system, open the folder where the certificate is saved. Double click the
certificate.
In Certificate import Wizard, click the Next button.
Select ‘place all certificate in the following store’ and click browse button.

IBM i Modernization Engine for Lifecycle Integration 25

 Select the Trusted Root Certification Authorities item, and then click ok button. In Certificate
Import Wizard, click Next button.
Click Finish button.
Select Yes in the security warning window
Restart the Chrome browser. Enter the MERLIN address and the Merlin GUI will load
successfully.
3. Add the CA to trust store with Mac system

If client is a Mac system, after saved the certificate, paste it to the Keychain Access which is a
Mac application.
Double click the certificate
Change all items to always trust.
Restart the Chrome browser. Enter the MERLIN address and the Merlin GUI will load
successfully.

How to trust the MERLIN CA for Firefox

The Firefox use its own trust store to verify CA, please follow below steps to obtain MERLIN CA and trust it.

Click Not Secure button and Connection not Secure item.

Click more info item.
Click View Certificate button.
The Certificate will show in a new tab. Select the right side one.
Scoll down the page, and in the Miscellaneous and Download part click PEM to download the
certificate.
Click in the right top and click the settings item.
In the Settings page, select Privacy & Security.
Scoll down this page, select View Certificate in the Certificate part.
In the Certificate Manager, in the Authorities tab, click import button.
Select the download PEM file, click open to go on.
Trust all and click ok button.
Click ok to close the Certificate Manager
Restart Firefox. Enter the MERLIN address and the Merlin GUI will load successfully.

Upgrade IBM i Modernization Engine for Lifecycle

Integration
This document discusses topics related to IBM i Developer Tool.

Versioning
To understand the upgrade and rollback procedures, it is important to understand how components of IBM i
Developer Tool are versioned. There is a distinction between (1) the OLM operator that abstracts the
installation and management of the components
and (2) the operand that is the components themselves. The
operator represents the IBM i Developer Tool installer. The operand is the set of IBM i Developer Tool
components configured by the resource.

The operator and operand are versioned independently: but each version of the operator can install a range of
the operand. The desired version of the operand is set in the spec.version field of the IBM i Developer
Customer Resource resource.

26 IBM i Modernization Engine for Lifecycle Integration

Upgrade
The versions of the operator and operand are decoupled. Upgrading IBM i Developer Tool to the latest version
requires updates to both of operator and operand.

Procedure

The cluster administrator pulls in an update to the OLM catalog of IBM provided
operators, including updates to the catalog for IBM i Developer Tool.

Based on the OLM Subscription, the IBM i Developer Tool operator is upgraded
either automatically or after manual approval.

This will roll out an update to the operator-controller-manager pod, but the
IBM i Developer Customer Resource component will not be changed.

The namespace administrator chooses an available version and updates the

spec.version field on the IBM i Developer Customer Resource custom resource.

The change to the desired version triggers reconciliation of the IBM i Developer
Customer Resource resource and upgrades the IBM i Developer Tool components.

Rollback

The versions of the operator and operand are decoupled. A given version of the operator may support multiple
versions of the operand. If an issue is encountered after an upgrade, the previous stable state can be restored
by changing the IBM i Developer
Customer Resource resource’s spec.version back to the previous value. OLM
does not support reverting the version of the installed operator, but this should not be necessary to restore a
stable state to the IBM i Developer Tool components. Procedure

The namespace administrator sets the spec.version field on the IBM i Developer
Customer Resource custom resource back to its previous value.

The change to the desired version triggers reconciliation of the IBM i Developer
Tool components.

Backup and restore IBM i Modernization Engine For

Lifecycle Integration

Overview
The document introduces the detailed steps for backup and restore IBM i Modernization Engine For Lifecycle
Integration with minio, OADP and a customer plugin ‘cpdbr-velero-plugin’.

Set Minio bucket storage service in OpenShift environment

Before configure the OADP service, a bucket storage must be configured to work as backup location. Note: the
following command need to run to the bastion server.

Download minio and install

wget https://github.com/vmware-tanzu/velero/releases/download/v1.7.1/velero-
v1.7.1-linux-ppc64le.tar.gz

tar zxvf velero-v1.7.1-linux-ppc64le.tar.gz

IBM i Modernization Engine for Lifecycle Integration 27

 cd velero-v1.7.1-linux-ppc64le/examples/minio

oc apply -f 00-minio-deployment.yaml

Initialize PVC for minio

vim minio-config-pvc.yml

apiVersion: v1

kind: PersistentVolumeClaim

metadata:

name: minio-config-pvc

namespace: velero

spec:

accessModes:

- ReadWriteOnce

volumeMode: Filesystem

storageClassName: nfs-storage-provisioner

resources:

requests:

storage: 1Gi

oc apply -f minio-config-pvc.yml

vim minio-storage-pvc.yaml

apiVersion: v1

kind: PersistentVolumeClaim

metadata:

name: minio-storage-pvc

namespace: velero

spec:

accessModes:

- ReadWriteOnce

volumeMode: Filesystem

storageClassName: nfs-storage-provisioner

resources:

requests:

storage: 100Gi

oc apply -f minio-storage-pvc.yaml

oc set volume deployment.apps/minio --add --overwrite --name=config --mount-

path=/config --type=persistentVolumeClaim --claim-name="minio-config-pvc" -n
velero

oc set volume deployment.apps/minio --add --overwrite --name=storage --mount-

path=/storage --type=persistentVolumeClaim --claim-name="minio-storage-pvc" -n
velero

oc set resources deployment minio -n velero --requests=cpu=500m,memory=256Mi --

limits=cpu=1,memory=1Gi

oc get pods -n velero

Expose the minio and get the route

oc expose svc minio -n velero

route.route.openshift.io/minio exposed

oc get route minio -n velero

NAME HOST/PORT PATH SERVICES PORT

TERMINATION WILDCARD

28 IBM i Modernization Engine for Lifecycle Integration

 minio minio-velero.apps.amp-fb35.9.5.36.56.nip.io minio 9000
None

Configure the mc command

Note: Reference to https://docs.min.io/docs/minio-client-quickstart-guide.html

Wget https://dl.min.io/client/mc/release/linux-ppc64le/mc

Chomd +x mc

./mc --help

Use the mc command to create the bucket in minio

./mc alias set minio http:// minio-velero.apps.amp-fb35.9.5.36.56.nip.io minio
minio123

Note: minio and minio123 is the default user and password, which should be find
/velero-v1.7.1-linux-ppc64le/examples/minio/ 00-minio-deployment.yaml

env:

- name: MINIO_ACCESS_KEY

value: "minio"

- name: MINIO_SECRET_KEY

value: "minio123"

./mc mb -p minio/velero

Bucket created successfully `minio/velero`.

./mc ls minio

Install OADP operator

Prepare customer plugin
podman pull docker.io/ibmcom/cpdbr-velero-plugin:4.0.0-beta1-1-ppc64le

podman tag docker.io/ibmcom/cpdbr-velero-plugin:4.0.0-beta1-1-ppc64le the-

registry/cpdbr-velero-plugin:4.0.0-beta1-1-ppc64le

podman push the-registry/cpdbr-velero-plugin:4.0.0-beta1-1-ppc64le

Prepare OADP
Search OADP or Velero in openshift console and install it.

Note, The version of OADP must be higher than 0.5.6 and install it. Reference to:
https://github.com/openshift/oadp-operator/blob/apiv1/docs/install_olm.md#create-the-
dataprotectionapplication-custom-resource

oc annotate namespace oadp-operator openshift.io/node-selector=""

vim credentials-velero

[default]

aws_access_key_id=minio

aws_secret_access_key=minio123

oc create secret generic cloud-credentials --namespace oadp-operator --from-file

cloud=./credentials-velero

IBM i Modernization Engine for Lifecycle Integration 29

 Create data protection instance
In the openshift console, open the OADP operator. Find the DataProtectionApplication, and click create
instance. Edit the yml file like the following script.

apiVersion: oadp.openshift.io/v1alpha1

kind: DataProtectionApplication

metadata:

name: velero-sample

namespace: oadp-operator

spec:

backupLocations:

- velero:

config:

region: minio

s3ForcePathStyle: 'true'

s3Url: 'http://minio-velero.apps.amp-fb35.9.5.36.92.nip.io'

credential:

key: cloud

name: cloud-credentials

default: true

objectStorage:

bucket: velero

prefix: cpdbackup

provider: aws

configuration:

restic:

enable: true

velero:

customPlugins:

- image: >-

Your-registry/cpdbr-velero-plugin:4.0.0-beta1-1-ppc64le

name: cpdbr-velero-plugin

defaultPlugins:

- openshift

- aws

– csi

And then wait a moment to check all pods status, make sure all of them ready.

oc get all -n oadp-operator

NAME READY STATUS

RESTARTS AGE

pod/oadp-velero-sample-1-aws-registry-678ffd4bd9-fqng6 1/1 Running 0

2m1s

pod/openshift-adp-controller-manager-548768c576-pz4g6 1/1 Running 0

25m

pod/restic-6wk8f 1/1 Running 0

2m1s

pod/restic-pcx8s 1/1 Running 0

2m1s

pod/restic-ph256 1/1 Running 0

2m1s

pod/velero-5fd9d9b5dd-gph7f 1/1 Running 0

2m1s

NAME TYPE CLUSTER-IP

EXTERNAL-IP PORT(S) AGE

service/oadp-velero-sample-1-aws-registry-svc ClusterIP
172.30.19.147 <none> 5000/TCP 2m1s

service/openshift-adp-controller-manager-metrics-service ClusterIP
172.30.55.104 <none> 8443/TCP 25m

service/openshift-adp-velero-metrics-svc ClusterIP
172.30.67.84 <none> 8085/TCP 2m1s

30 IBM i Modernization Engine for Lifecycle Integration

 NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE
SELECTOR AGE

daemonset.apps/restic 3 3 3 3 3
<none> 2m1s

NAME READY UP-TO-DATE AVAILABLE

AGE

deployment.apps/oadp-velero-sample-1-aws-registry 1/1 1 1
2m1s

deployment.apps/openshift-adp-controller-manager 1/1 1 1
25m

deployment.apps/velero 1/1 1 1
2m1s

NAME DESIRED CURRENT

READY AGE

replicaset.apps/oadp-velero-sample-1-aws-registry-678ffd4bd9 1 1
1 2m1s

replicaset.apps/openshift-adp-controller-manager-548768c576 1 1
1 25m

replicaset.apps/velero-5fd9d9b5dd 1 1
1 2m1s

NAME HOST/PORT
PATH SERVICES PORT TERMINATION WILDCARD

route.route.openshift.io/oadp-velero-sample-1-aws-registry-route oadp-velero-
sample-1-aws-registry-route-oadp-operator.apps.amp-fb35.9.5.36.56.nip.io
oadp-velero-sample-1-aws-registry-svc <all> None

Configure the cpdbr-cli

Run the following command in bastion server.

wget http://icpfs1.svl.ibm.com/zen/cp4d-builds/4.0.0/dev/utils/cpdbr-
oadp/latest/lib/ppc64le/cpdbr-oadp

chmod +x cpdbr-oadp

./cpdbr-oadp client config set namespace=oadp-operator

For the detailed usage, run ./cpdbr-oadp --help

Backup and Restore

Note: before backup and restore, please make sure the NFS server is set as no_root_squash, or run vim
/etc/exports with /export *(rw,sync,no_root_squash), and then restart NFS server.

Run command to start backup process

./cpdbr-oadp backup create --include-namespaces=nas3 --exclude-
resources='Event,Event.events.k8s.io' --default-volumes-to-restic --snapshot-
volumes=false --cleanup-completed-resources nas3backup --log-level=debug –verbose

Note:

nas3 is the MERLIN operator namespace name. Add additional namespaces after nas, separated by
commas.
nas3backup is the backup instance name, which is replaced with users' namespace.

Success logs as following:

oadp namespace: oadp-operator, processing request...

resolved namespaces [nas3] ...

IBM i Modernization Engine for Lifecycle Integration 31

 W0226 09:17:52.188481 140375 warnings.go:67] batch/v1beta1 CronJob is deprecated
in v1.21+, unavailable in v1.25+; use batch/v1 CronJob

pre-processing rules will be applied for the following resource(s):

(0) nas3/deployment/merlin-operator: op=<mode=quiesce,type=pod-scale>

priority=90

(1) nas3/deployment/vault: op=<mode=quiesce,type=pod-scale>

priority=90

(2) nas3/deployment/ibm-common-service-operator: op=<mode=quiesce,type=pod-

scale>

priority=90

(3) nas3/deployment/keycloak: op=<mode=quiesce,type=pod-scale>

priority=90

(4) nas3/statefulset/engine: op=<mode=quiesce,type=pod-scale>

priority=90

(5) nas3/statefulset/merlin: op=<mode=quiesce,type=pod-scale>

priority=90

(6) nas3/statefulset/postgres: op=<mode=quiesce,type=pod-scale>

priority=90

running 7 async ops in namespaces [nas3]...

waiting for 7 async ops in namespaces [nas3]...

waiting for quiesce to be completed...

waiting for quiesce to be completed...

waiting for quiesce to be completed...

waiting for quiesce to be completed...

waiting for quiesce to be completed...

nas3/deployment/keycloak scaled down successfully

waiting for quiesce to be completed...

nas3/deployment/ibm-common-service-operator scaled down successfully

waiting for quiesce to be completed...

nas3/deployment/vault scaled down successfully

nas3/deployment/merlin-operator scaled down successfully

nas3/statefulset/merlin scaled down successfully

nas3/statefulset/postgres scaled down successfully

nas3/statefulset/engine scaled down successfully

status: succeeded

nas3/deployment/merlin-operator: op=<mode=quiesce,type=pod-scale>,
status=succeeded

nas3/deployment/vault: op=<mode=quiesce,type=pod-scale>, status=succeeded

nas3/deployment/ibm-common-service-operator: op=<mode=quiesce,type=pod-scale>,
status=succeeded

nas3/deployment/keycloak: op=<mode=quiesce,type=pod-scale>, status=succeeded

nas3/statefulset/engine: op=<mode=quiesce,type=pod-scale>, status=succeeded

nas3/statefulset/merlin: op=<mode=quiesce,type=pod-scale>, status=succeeded

nas3/statefulset/postgres: op=<mode=quiesce,type=pod-scale>, status=succeeded

configmap pre-backup hooks took 11.896119058s

configmap pre-backup hooks completed

creating pod cpdbr-vol-mnt in namespace nas3

creating done in namespace nas3

annotation processing in namespace nas3

annotation processing in namespace nas3

annotate pvc "merlin-engine-backend" with cpdbr.cpd.ibm.com/volume-backup-

method=restic

annotate pvc "merlin-gui-file-backend" with cpdbr.cpd.ibm.com/volume-backup-

method=restic

annotate pvc "merlin-postgresql-claim" with cpdbr.cpd.ibm.com/volume-backup-

method=restic

backup request "nas3backup" submitted successfully.

waiting for backup to complete...

..................................................................................
..................................................................................
..................................................................................
...........................................

32 IBM i Modernization Engine for Lifecycle Integration

backup completed with status: Completed.

deleting pod cpdbr-vol-mnt in namespace nas3

deletion done in namespace nas3

W0226 09:23:38.618939 140375 warnings.go:67] batch/v1beta1 CronJob is deprecated

in v1.21+, unavailable in v1.25+; use batch/v1 CronJob

post-processing rules will be applied for the following resource(s):

(0) nas3/statefulset/postgres: op=<mode=unquiesce,type=pod-scale>

priority=90

(1) nas3/statefulset/merlin: op=<mode=unquiesce,type=pod-scale>

priority=90

(2) nas3/statefulset/engine: op=<mode=unquiesce,type=pod-scale>

priority=90

(3) nas3/deployment/vault: op=<mode=unquiesce,type=pod-scale>

priority=90

(4) nas3/deployment/merlin-operator: op=<mode=unquiesce,type=pod-scale>

priority=90

(5) nas3/deployment/keycloak: op=<mode=unquiesce,type=pod-scale>

priority=90

(6) nas3/deployment/ibm-common-service-operator: op=<mode=unquiesce,type=pod-

scale>

priority=90

running 7 async ops in namespaces [nas3]...

scaling up nas3/statefulset/postgres to its original replicas(1)...

scaling up nas3/deployment/merlin-operator to its original replicas(1)...

scaling up nas3/deployment/vault to its original replicas(1)...

scaling up nas3/statefulset/merlin to its original replicas(1)...

scaling up nas3/statefulset/engine to its original replicas(1)...

scaling up nas3/deployment/ibm-common-service-operator to its original

replicas(1)...

scaling up nas3/deployment/keycloak to its original replicas(1)...

status: succeeded

nas3/statefulset/postgres: op=<mode=unquiesce,type=pod-scale>, status=succeeded

nas3/statefulset/merlin: op=<mode=unquiesce,type=pod-scale>, status=succeeded

nas3/statefulset/engine: op=<mode=unquiesce,type=pod-scale>, status=succeeded

nas3/deployment/vault: op=<mode=unquiesce,type=pod-scale>, status=succeeded

nas3/deployment/merlin-operator: op=<mode=unquiesce,type=pod-scale>,
status=succeeded

nas3/deployment/keycloak: op=<mode=unquiesce,type=pod-scale>, status=succeeded

nas3/deployment/ibm-common-service-operator: op=<mode=unquiesce,type=pod-
scale>, status=succeeded

configmap post-backup hooks took 1.650912114s

configmap post-backup hooks completed

annotation processing in namespace nas3

annotation "backup.velero.io/backup-volumes" does not exist in pod "engine-0",

skipping...

annotation "backup.velero.io/backup-volumes" does not exist in pod "merlin-0",

skipping...

annotation "backup.velero.io/backup-volumes" does not exist in pod "merlin-

operator-76bcfb4969-pzpwn", skipping...

annotation "backup.velero.io/backup-volumes" does not exist in pod "postgres-0",

skipping...

annotation "backup.velero.io/backup-volumes" does not exist in pod "vault-

75584d7fc9-tj77f", skipping...

annotation processing in namespace nas3

removing annotation "cpdbr.cpd.ibm.com/volume-backup-method" from pvc "merlin-

engine-backend"

removing annotation "cpdbr.cpd.ibm.com/volume-backup-method" from pvc "merlin-gui-

file-backend"

removing annotation "cpdbr.cpd.ibm.com/volume-backup-method" from pvc "merlin-

postgresql-claim"

backup took 5m48.309030505s

IBM i Modernization Engine for Lifecycle Integration 33

 backup command completed

post-backup hooks are invoked, but applications may take longer to come up.

please use 'oc get po', 'oc get sts', 'oc get deploy' to check workload status.

Delete the Merlin instance, but make sure the namespace still exist.
Use following command to start restore process

./cpdbr-oadp restore create --from-backup=nas3backup nas3t5 --include-cluster-

resources=true --log-level=debug –verbose

Note: nas3t5 is the restore name which can be replaced.

See the log as following:

resolved namespaces [nas3]

restore request "nas3t5" submitted successfully.

waiting for restore to complete...

.....................................................

restore completed with status: Completed.

deleting pod cpdbr-vol-mnt in namespace nas3

deletion done in namespace nas3

W0226 10:48:07.683918 142289 warnings.go:67] batch/v1beta1 CronJob is deprecated

in v1.21+, unavailable in v1.25+; use batch/v1 CronJob

post-processing rules will be applied for the following resource(s):

(0) nas3/statefulset/merlin: op=<mode=unquiesce,type=pod-scale>

priority=90

(1) nas3/statefulset/engine: op=<mode=unquiesce,type=pod-scale>

priority=90

(2) nas3/statefulset/postgres: op=<mode=unquiesce,type=pod-scale>

priority=90

(3) nas3/deployment/ibm-common-service-operator: op=<mode=unquiesce,type=pod-

scale>

priority=90

(4) nas3/deployment/vault: op=<mode=unquiesce,type=pod-scale>

priority=90

(5) nas3/deployment/merlin-operator: op=<mode=unquiesce,type=pod-scale>

priority=90

(6) nas3/deployment/keycloak: op=<mode=unquiesce,type=pod-scale>

priority=90

running 7 async ops in namespaces [nas3]...

scaling up nas3/deployment/ibm-common-service-operator to its original

replicas(1)...

scaling up nas3/statefulset/postgres to its original replicas(1)...

scaling up nas3/deployment/vault to its original replicas(1)...

scaling up nas3/statefulset/engine to its original replicas(1)...

scaling up nas3/statefulset/merlin to its original replicas(1)...

scaling up nas3/deployment/merlin-operator to its original replicas(1)...

scaling up nas3/deployment/keycloak to its original replicas(1)...

status: succeeded

nas3/statefulset/merlin: op=<mode=unquiesce,type=pod-scale>, status=succeeded

nas3/statefulset/engine: op=<mode=unquiesce,type=pod-scale>, status=succeeded

nas3/statefulset/postgres: op=<mode=unquiesce,type=pod-scale>, status=succeeded

nas3/deployment/ibm-common-service-operator: op=<mode=unquiesce,type=pod-
scale>, status=succeeded

nas3/deployment/vault: op=<mode=unquiesce,type=pod-scale>, status=succeeded

nas3/deployment/merlin-operator: op=<mode=unquiesce,type=pod-scale>,
status=succeeded

nas3/deployment/keycloak: op=<mode=unquiesce,type=pod-scale>, status=succeeded

configmap post-restore hooks took 1.748747619s

configmap post-restore hooks completed

restore took 1m35.551002154s

34 IBM i Modernization Engine for Lifecycle Integration

 restore command completed

post-restore hooks are invoked, but applications may take longer to come up.

Wait a moment and check the pods status in the openshift console, all pods will be ready status.

Note: the merlin-operator-XXX maybe not be ready in time, wait a long time and then it will be ready
status.
Note: If the ibm-common-service-operator-XXXX still not ready, delete the pod and operators, then
install a new one “IBM Cloud Pak foundational services” in the namespace.

Data Storage
IBM i Modernization Engine For Lifecycle Integration requires storage, which must be provisioned before IBM i
Modernization Engine For Lifecycle Integration is installed.

Red Hat® OpenShift® Container Platform uses the Kubernetes persistent volume (PV) framework. PVs are
storage resources in the cluster, and persistent volume claims (PVCs) are storage requests that are made on
those PVs by AI Manager. For more information
about persistent storage in OpenShift clusters, see
Understanding persistent storage Opens in a new tab in the Red Hat OpenShift documentation.

Recommended storage providers

The persistent storage that you choose must support the RWO (read-write-once) access mode and support
the block and file storage types. This storage is used for PostgreSQL, the engine and the gui pod.

IBM i Developer and IBM i CI/CD can use the same storage providers as IBM i Modernization Engine for
Lifecycle Integration platform.

Note: For more information about access modes, see OpenShift documentation.

Configure a default storage class

Before install IBM i Modernization Engine For Lifecycle Integration, a default storage class should be
configured by setting storageclass.kubernetes.io/is-default-class: 'true' as following:

kind: StorageClass

apiVersion: storage.k8s.io/v1

metadata:

name: nfs-storage-provisioner

annotations:

storageclass.kubernetes.io/is-default-class: 'true'

provisioner: nfs-storage

parameters:

archiveOnDelete: 'false'

reclaimPolicy: Delete

volumeBindingMode: Immediate

Persistent storage sizing

Persistent storage requirements depend on the size of the stored data sets that your IBM i Developer Tool
deployment processes. The minimum PVC size is 20G for IBM i Developer Tool.

IBM i Modernization Engine for Lifecycle Integration 35

 The access mode is shown for each of the PVs, and is ReadWriteOnce (RWO). For more information about
access modes, see Access modes in the Red Hat OpenShift documentation.

The storage type is shown for each of the PVs, and is either Filesystem or Block. For more information, see
Block volume support in the Red Hat OpenShift documentation.

IBM i Modernization Engine For Lifecycle Integration persists technical data that is related to configuration
and management of the service in any of the follow

IBM i Modernization Engine for Lifecycle Integration persistent volumes

The default names of the three IBM i Modernization Engine for Lifecycle Integration persistent volumes and
their usages are as follows:

PVC name Size Access Mode Description

merlin-engine-backend 2 GB ReadWriteOnce Engine volume for engine logs
merlin-gui-file-backend 1 GB ReadWriteOnce GUI volume for configuration files
merlin-postgresql-claim 5 GB ReadWriteOnce A volume for database

IBM i CI/CD Tool persistent volume

The default name of the IBM i CI/CD Tool persistent volume and its usages are as follows:

PVC name Size Access Mode Description

merlin-cicd-backend 5 GB ReadWriteOnce A volume for cicd logs

IBM i Developer Tool persistent volume

The default name of the IBM i Developer Tool persistent volume and its usages are as follows:

PVC name Size Access Mode Description

postgres-data 1 GB ReadWriteOnce A volume for database

Tracking license consumption of IBM i Modernization

Engine For Lifecycle Integration
IBM i Modernization Engine For Lifecycle Integration contains an integrated service for measuring the license
usage at the cluster level for license evidence purposes.

Overview
The integrated licensing solution collects and stores the license usage information which can be used for
audit purposes and for tracking license consumption in cloud environments. The solution works in the
background and does not require any configuration.
Only one instance of the License Service is deployed per
cluster regardless of the number of Cloud Paks and containerized products that you have installed on the
cluster.

Validating if License Service is deployed on the cluster

36 IBM i Modernization Engine for Lifecycle Integration

 To ensure license reporting continuity for license compliance purposes make sure that License Service is
successfully deployed. It is recommended to periodically verify whether it is active.

To validate whether License Service is deployed and running on the cluster, you can, for example, log in to the
cluster and run the following command:

kubectl get pods --all-namespaces | grep ibm-licensing | grep -v operator

The following response is a confirmation of successful deployment:

1/1 Running

Archiving license usage data before decommissioning the

cluster
Remember to archive the license usage evidence before you decommission the cluster where IBM i
Modernization Engine For Lifecycle Integration was deployed. Retrieve the audit snapshot for the period when
IBM i Modernization Engine For Lifecycle
Integration was on the cluster and store it in case of audit.

For more information about the licensing solution, see License Service documentation.

Merlin Administrator Guide

IBM i Modernization Engine for Lifecycle Integration Platform provides graphic user interface to manage
MERLIN tools, MERLIN users and authorities, user inventory and credentials, life cycle of IBM i virtual
machines, etc.

The platform provides below functions:

Monitor resources for MERLIN tools

Manage the lifecycle of MERLIN Tools
Manage MERLIN users and authorities
Manage connections
Manage IBM i virtual machines
Manage Rest APIs on IBM i

Manage Connections
IBM i Modernization Engine For lifecycle Integration provides manage connections to support manage and
maintain the systems, credentials, and templates for the overall usage within the tools.

Manage Inventory
Manage Templates
Manage Credentials

Manage Inventory
IBM i Modernization Engine for Lifecycle Integration 37
 The inventory works for managing the systems info used for MERLIN. It will save the general system
information including hostname, type, and description and some other information. Now MERLIN supports
four types of hosts, IBM i, Power VC, IBM Cloud,
and Jenkins.
Go to MERLIN GUI, Connections -> Inventory, user will turn to the Inventory page.

All the Inventories which created or got permissions will be shown, it includes Name, Hostname, Type,
Description, Owner, Provision, Created Time, and Updated Time. The Provision item is a tag that specifies the
IBM i server deployed by the Power
VC template.

Add Inventory
Click Add button,
enter the Name, Type and Hostname, after the type selected the required info will be
difference, if one of requirements not meet the +Add button will keep disabled status.

File all necessary fields and click +Add button, then the new inventory record will be imported.

remote CA.
For the security connections, Merlin support Test TLS function, that allow customer to accept the
Such as Power VC Inventory.

38 IBM i Modernization Engine for Lifecycle Integration

 Fill the Hostname and Port, the Test TLS button will be abled to click, and it will catch the Power VC CA, in the
detailed certificate windows, click the Accept button, then this CA be added to Merlin trust store.

Note: Please avoid to use those specific characters .,:;/\"*?<>|=+&%'`@" in Name field. And the
Hostname supports IP, Hostname, and URL.

Delete Inventory
The delete button
is disabled by default, select items in the inventory table, and the selected items will
change to highlight and the delete button change to available status, click the delete button, and
click
yes for the confirmation that will delete all selected items.

Edit Inventory
The Edit button
is disabled by default, select one item in the inventory table, and the selected item will
change to highlight and the Edit button change to available status, click the Edit button, the inventory
info will be shown, all fields are able to be edited except the owner.

Refresh Inventory

Click the refresh button, the MERLIN GUI will get a refresh so that to get the latest inventory info.

Manage Credentials
The Credential works for managing the credential info used for MERLIN. It will save the credential info,
including username, password, ssh key, API token, etc. The detailed credential info will be changed according
to the credential type. Now MERLIN
supports four types of credentials same as the inventory host types.
Go to MERLIN GUI, Connections -> Credentials, user will turn to the Credentials page.

IBM i Modernization Engine for Lifecycle Integration 39

 For
the Admin side, all credentials will be shown, for the user side, all the own Credentials will be shown, it
includes Name, Type, Description, Owner, Created Time, and Updated Time.

Add Credential

Click the Add button, Add the credential name, and select the credential type, the detailed credential
info will be shown. According to the credential type, the credential info is difference.
For credential
of IBM i as an example, user must enter the username and password of
IBM i server, or
the +Add button will keep disabled. Optionally, ssh key information can be specified. If specified, the
ssh key will be used instead of the password to connect
to the IBM i during the IDE developer build
process.

Note: if using ssh key, additional configuration is performed during connection to the IBM i before the
build starts.

Delete Credentials
The delete button is
disabled by default, Select items in the credentials table, and the selected item
will change to highlight and the delete button change to available status, click the delete button and
click yes to confirm that will delete all selected items.

40 IBM i Modernization Engine for Lifecycle Integration

 Edit Credential
The Edit button is disabled by default, select one item in the credential table, the selected item will
change to highlight and the Edit button change to available status, click the Edit button, the credential
info will be shown, all fields can be edited except the owner.

Note: For the security consideration, when editing the credential, the original credential
information will not be shown, and the user should fill all credential information again.

Refresh Credentials

the MERLIN GUI will get a refresh so that to get the latest credentials
Click the refresh button,
information.

Manage Templates
The Templates work for managing the template info used for MERLIN. It will save the template info, including
Name, Inventory, Credential, type, owner, and description. The credential and type info will be changed
according to the Inventory type.
Now MERLIN supports four types of templates same as the inventory host
types.

Go to MERLIN GUI, Connections -> Templates, user will turn to the Templates page.

For the Admin side, all templates will be shown, but the run action only works on own templates, for the user
side, all own templates will be shown, it includes Name, Inventory, Credential, Type, Owner, Created Time,
and Updated Time by default.
Users also could customize the columns by clicking the icon at the right top of
the table.

Add Template

Click the Add button, add the Template name, and select an inventory, the template type is the same
type as inventory, the credential will be filter to the same type. According to the inventory type, the
other
required fields will be difference.
Use Power VC as example, user must enter
the vm info which used in this template, or the +Add button

IBM i Modernization Engine for Lifecycle Integration 41

 will keep disabled.

Fill all necessary fields, the +Add button will be able to click, click the +Add, the new template info will be
imported to Templates table.

Delete Templates
The delete button
is disabled by default, select items in the Templates table, the selected items will
change to highlight and the delete button change to available status, click the delete button, and click
yes to confirm that will delete all selected items.
Edit Template
The Edit button
is disabled by default, select one item in the Templates table, the selected item will
change to highlight and the Edit button change to available status, click the Edit button, the template
info
will be shown, all fields can be edited except the owner.
Run Template

The Run is disabled by default, select one item in the Templates table, the selected item will change to
highlight, and the run button change to available status. According to the different templates type, the
action will be different.
For the Power VC template,
MERLIN supports the Provision actions, that will help the user to deploy a
new IBM VM, the user should make sure all the hardware configurations have been set up on the Power
VC side.

For the IBM i server template, MERLIN supports Enable Ansible environment, Validate the dependent PTFs,
Install Certificate, Enable IBM i developer environment, and Enable ARCAD environment.

42 IBM i Modernization Engine for Lifecycle Integration

 Refresh Templates

Click the refresh button, the MERLIN GUI will get a refresh so that to get the latest Templates info.

Manage MERLIN users and authorities

Users and Groups

Merlin support users and groups. Group is the container of a set of users and groups. All the role and
permissions granted to a group are inherited by all its members. Merlin supports user federation. Users and
groups can be created in Merlin local
repository directly or imported from a LDAP server. Multiple LDAP
servers can be added to Merlin at the same time. When add a LDAP server to Merlin, the users and groups in
the LDAP server are imported into Merlin local user repository. All the
updates to users and groups through
Merlin are kept in Merlin local repository and are not synchronized back to the original LDAP server.

Authorization
Manage Roles
The following roles are supported in Merlin:

Admin – user with the role is the administrator of Merlin and is allowed to manage all aspects of Merlin.
Manager – user with the role is allowed to manage all the resources in Merlin but not allowed to do
user management.
Creator – user with the role is allowed to create projects in Merlin. A user can only be assigned one role
in Merlin. When assign a role to a group, all the members of the group inherits the role automatically.
When revoke a role
from a group, all the members of the group loses the role inherited from the group.

On the left panel of navigation, click Authorization -> Manage Roles to launch the Manage Roles panel. All
the users and groups with specific role is listed on the panel as below

IBM i Modernization Engine for Lifecycle Integration 43

 Assign Role to Users
On the Manage Roles panel, click button Assign to launch the dialog as below.

Select users and groups from All Users/Groups list on the left panel, then click the button to move to
Selected Users/Groups list.

Select role for each of the Selected User/Group on the dropdown box for role.

Click button OK to apply the update.

Edit Role of a User

Click edit icon at the end of each row.

44 IBM i Modernization Engine for Lifecycle Integration

The Role cell is changed to be a dropdown box as below.

Select the role and click the check icon at the end of the row to save the update.

Revoke Role of a User

Select the row of the user on Manage Roles view and then click Remove button to get the role revoked from
the user.

Manage Permissions
In Merlin, only users with Admin role or Manager role are allowed to access all the resources. Owners are
granted all the access to the resources created by themselves. For normal users, need to get permission
before
access the resources. If an authority against a resource is assigned to a group, all the members of the
group have the permission automatically.

Currently, authority is allowed to be granted against projects and inventories. There are two authority
available in Merlin.

View – Allow users to view all the information of the resource

Edit – Allow users to update resources, for example, install/uninstall an application on a project.

On the left navigation panel, click Authorization -> Manage Permissions to launch Manage Permissions
panel. On the panel, the left tab is the resource name. And the right tab is the different view, from user/group
perspective
or from the resource perspective. Below are samples of permissions to Project list from
user/group perspective and from project perspective.

IBM i Modernization Engine for Lifecycle Integration 45

 Grant Permission to Users
Click Add button to launch Grant User Permissions wizard. On the first step, choose the resource type from
the Resource Type dropdown box. Only Project and Inventory options are
supported. Choose the correct
resource type and click Next button to the next step.

Select the users and groups from All Users/Groups list and click the button to add to the Selected
Users/Groups list. Then click Next button to next step.

46 IBM i Modernization Engine for Lifecycle Integration

Select the resources from All Projects or All Inventories list and click the button to add to the Selected
Projects or Selected Inventories List. Then choose the right authority
from dropdown box for each selected
user/group. Finally, click Next button to the next step.

The summary page will list all the permission information just added. If all the information is correct, click
Finish button to make the update.

IBM i Modernization Engine for Lifecycle Integration 47

 Edit Permissions
On By User/Group tab or By Project tab, select a row and click Update button to launch Update User
Permissions dialog. If from By User/Group tab, the dialog lists all the resources
the selected user has
authorities to as below.

48 IBM i Modernization Engine for Lifecycle Integration

If from By Project/By Inventory tab, the dialog lists all the users have the authorities to the resource as below.

On the dialog, specify the right authority from Authority dropdown box. Finally click Save button to apply the
change.

Revoke Permission
On By User/Group tab or By Project tab, select a row and click Remove button. A confirm dialog will be
popped up. If all the information is correct, click OK button to apply the
change.

IBM i Modernization Engine for Lifecycle Integration 49

 If from By User/Group tab, all the permission of the user are revoked. If from By Project or By Inventory tab,
all the users are revoked the authorities to the resource.

Manage Rest APIs on IBM i

Merlin supports to externalize IBM i programs and SQL statement as REST services.

On the left navigation panel, click Rest APIs -> Deploy Rest APIs to launch the Deploy Rest APIs panel. Then
select a template from the dropdown box and click Launch button to launch the Rest deployment wizard.

A new browser tab is opened to launch the REST deploy wizard as below.

To deploy a REST service, an Integrated Web Services Server for i instance need to be created on the IBM i
server first. Integrated Web Services Server for i provides a secure and easy way to configure an environment
for hosting REST services that
are based on IBM i objects such as RPG and COBOL programs and SQL
statements.

Then a REST service could be deployed on the instance to externalize an IBM i programs or SQL statements.
Follow the context help document in the wizard to create Integrated Web Services Server for i instance and
deploy REST services.

Monitor resources for MERLIN tools

Merlin provides a dashboard to monitor the resource consuming of projects. It includes the following metrics:

CPU usage
Memory usage
Receive bandwidth

50 IBM i Modernization Engine for Lifecycle Integration

 Transmit bandwidth
Rate of received packets
Rate of transmitted packets
Rate of received packets dropped
Rate of transmitted packets dropped
File system usage.

On the left navigation panel, click Home -> Dashboard to launch dashboard panel. Then select a project from
Project dropdown box on top of the panel to monitor the resource consuming.

By default, the time range of the charts is 30 minutes. It can be changed from 5 minutes to 2 weeks through
Time range dropdown box.

Below is a sample chart of CPU usage.

IBM i Modernization Engine for Lifecycle Integration 51

Vault control
MERLIN GUI uses Vault server to secure the safety of Users' credential information. When users use a brand
new MERLIN GUI, admin are required to initialize the vault server and save the generated secrets and tokens
in a safe place.

Before
initialization, the vault server status will be Not initialized and users are not able to use Connection in
MERLIN GUI.

Go to the MERLIN GUI, Connection -> Vault, User will turn to Vault Control page.

Initialize Vault

vault button, admin will turn to the initialize page.
Click the initialize

52 IBM i Modernization Engine for Lifecycle Integration

 Admin is required to input the secret share and threshold number, then
the vault server will split the
generated key into a defined number of secrets and a certain threshold of secrets is required to
reconstruct the key, which is then used to unseal and finally enable vault. The vault server will also
generate
a token for interaction with it.
After entering the shares and threshold,
click the Initialize vault button. the credentials and token will
be shown. please copy and save them. And both vault server status and token status will be active
and
you are able to use Connection in MERLIN GUI.
Seal Vault
Admin could
click the Seal Vault button the seal the vault which will make users not be able to use
credentials including add and edit credentials.
Unseal Vault
When MERLIN
is in the Seal status, the Unseal button is available, Admin needs to enter the shares of
the correct secret to Unseal the vault server.

Note: When the vault server status is 'Active' and token status is 'Invalid', the admin is required
to set the token again.

How to set up Email configurations and enable Forgot

Password on Keycloak
This document simply describes how to set up the Email configurations and enable the forgot password
function on Keycloak GUI.
Requirements:

An available SMTP server that allows to relay mails

Administration user

Step 1, Go to the project which installed MERLIN

specific project
Go to the Openshift GUI, Home -> Projects -> click

IBM i Modernization Engine for Lifecycle Integration 53

 Step 2, Get the credential of
keycloak
Workloads -> Secrets -> click merlin-credential-secret in the table

Get ADMIN_USERNAME and ADMIN_PASSWORD

54 IBM i Modernization Engine for Lifecycle Integration

Step 3, Find the route of keycloak
Networking -> Routes -> Click the Location link in the keykloak item. It will open the Keycloak GUI.

Step 4,
Login
Click the Administration Console.

Login with ADMIN_USERNAME and ADMIN_PASSWORD

IBM i Modernization Engine for Lifecycle Integration 55

 Step
5, Set up Email
Realm Settings -> Click Email tab -> enter the necessary info -> Click Save button.

Step 6, Enable Forgot Password

-> enable the Forgot Password -> click Save button.
Realm Settings -> Click Login tab

56 IBM i Modernization Engine for Lifecycle Integration

Step 7, Verify the Forgot Password was enabled

Go to the Merlin login page -> click Forgot Password

Enter the username or email address -> click Submit.

IBM i Modernization Engine for Lifecycle Integration 57

 Note: please make sure this account has set up a valid email address in profile, or this account could not
receive emails.
Received
a Reset Password Email.

Step 8, Reset password

Click the link to reset credentials in the Email -> enter the new password -> click submit, then the password

58 IBM i Modernization Engine for Lifecycle Integration

 will be reset.

User Guide for IBM i Modernization Engine for Lifecycle

Integration
IBM i Modernization Engine for Lifecycle Integration is a set of tools run in OpenShift containers which guide
and assist software developers in the modernization of IBM i applications, allowing them to realize the value
of a hybrid cloud, multi-platform
DevOps implementation.

Manage browser certificates

Configure certificate for your browser

Modernization Engine for Lifecycle Integration (MERLIN) supports Hyper Text Transfer Protocol over
SecureSocket Layer(HTTPS) to protect the confidential data sent between client and server. Before login the
MERLIN, you need to let the web browser
to trust the MERLIN CA. This document describes how to trust
MERLIN CA for Chrome and Firefox web browser.

How to trust the MERLIN CA for Chrome

When entering the MERLIN web address with chrome first time, Chrome might show a blank page with the
text Loading....

As the Chrome use the system trust store to verify the CA, the ways to adding CA to system store between
Windows and Mac are different, so both Mac and Windows follow the Download MERLIN CA steps to obtain
the Merlin CA, but follow
different steps: Add the CA to trust store with Windows system or Add
the CA to trust store with Mac system to trust CA.

IBM i Modernization Engine for Lifecycle Integration 59

 1. Download the MERLIN CA

Click the Not Secure button, and then select the Certificate is not valid item.
Click the Certification Path tab, then click the first CA, and click the View Certificate button.
Click the Details tab in the CA certificate and then click the Copy to File button.
In the Certificate Export Wizard, click the Next button.
Select the DER encoded binary X.509(.CER) and then select Next
Enter the path and name which you want to save the certificate. Then click Next.
Click Finish button
2. Add the CA to trust store with Windows system

If the client is a Windows system, open the folder where the certificate is saved. Double click the
certificate.
In Certificate import Wizard, click the Next button.
Select ‘place all certificate in the following store’ and click browse button.
Select the Trusted Root Certification Authorities item, and then click ok button. In Certificate
Import Wizard, click Next button.
Click Finish button.
Select Yes in the security warning window
Restart the Chrome browser. Enter the MERLIN address and the Merlin GUI will load
successfully.
3. Add the CA to trust store with Mac system

If client is a Mac system, after saved the certificate, paste it to the Keychain Access which is a
Mac application.
Double click the certificate
Change all items to always trust.
Restart the Chrome browser. Enter the MERLIN address and the Merlin GUI will load
successfully.

How to trust the MERLIN CA for Firefox

The Firefox use its own trust store to verify CA, please follow below steps to obtain MERLIN CA and trust it.

Click Not Secure button and Connection not Secure item.

Click more info item.
Click View Certificate button.
The Certificate will show in a new tab. Select the right side one.
Scoll down the page, and in the Miscellaneous and Download part click PEM to download the
certificate.
Click in the right top and click the settings item.
In the Settings page, select Privacy & Security.
Scoll down this page, select View Certificate in the Certificate part.
In the Certificate Manager, in the Authorities tab, click import button.
Select the download PEM file, click open to go on.
Trust all and click ok button.
Click ok to close the Certificate Manager
Restart Firefox. Enter the MERLIN address and the Merlin GUI will load successfully.

Manage Connections

60 IBM i Modernization Engine for Lifecycle Integration

 IBM i Modernization Engine For lifecycle Integration provides manage connections to support manage and
maintain the systems, credentials, and templates for the overall usage within the tools.

Manage Inventory
Manage Templates
Manage Credentials

Manage Inventory
The inventory works for managing the systems info used for MERLIN. It will save the general system
information including hostname, type, and description and some other information. Now MERLIN supports
four types of hosts, IBM i, Power VC, IBM Cloud,
and Jenkins.
Go to MERLIN GUI, Connections -> Inventory, user will turn to
the Inventory page.

All the Inventories which created or got permissions will be shown, it includes Name, Hostname, Type,
Description, Owner, Provision, Created Time, and Updated Time. The Provision item is a tag that specifies the
IBM i server deployed by the Power
VC template.

Add Inventory
Click Add button,
enter the Name, Type and Hostname, after the type selected the required info will be
difference, if one of requirements not meet the +Add button will keep disabled status.

IBM i Modernization Engine for Lifecycle Integration 61

 File all necessary fields and click +Add button, then the new inventory record will be imported.

remote CA.
For the security connections, Merlin support Test TLS function, that allow customer to accept the
Such as Power VC Inventory.

Fill the Hostname and Port, the Test TLS button will be abled to click, and it will catch the Power VC CA, in the
detailed certificate windows, click the Accept button, then this CA be added to Merlin trust store.

Note: Please avoid to use those specific characters .,:;/\"*?<>|=+&%'`@" in Name field. And the
Hostname supports IP, Hostname, and URL.

Delete Inventory
The delete button
is disabled by default, select items in the inventory table, and the selected items will
change to highlight and the delete button change to available status, click the delete button, and
click
yes for the confirmation that will delete all selected items.

Edit Inventory
The Edit button
is disabled by default, select one item in the inventory table, and the selected item will
change to highlight and the Edit button change to available status, click the Edit button, the inventory
info will be shown, all fields are able to be edited except the owner.

Refresh Inventory

Click the refresh button, the MERLIN GUI will get a refresh so that to get the latest inventory info.

62 IBM i Modernization Engine for Lifecycle Integration

Manage Credentials
The Credential works for managing the credential info used for MERLIN. It will save the credential info,
including username, password, ssh key, API token, etc. The detailed credential info will be changed according
to the credential type. Now MERLIN
supports four types of credentials same as the inventory host types.
Go to MERLIN GUI, Connections -> Credentials, user will turn to the Credentials page.

For
the Admin side, all credentials will be shown, for the user side, all the own Credentials will be shown, it
includes Name, Type, Description, Owner, Created Time, and Updated Time.

Add Credential

Click the Add button, Add the credential name, and select the credential type, the detailed credential
info will be shown. According to the credential type, the credential info is difference.
For credential
of IBM i as an example, user must enter the username and password of
IBM i server, or
the +Add button will keep disabled. Optionally, ssh key information can be specified. If specified, the
ssh key will be used instead of the password to connect
to the IBM i during the IDE developer build
process.

Note: if using ssh key, additional configuration is performed during connection to the IBM i before the

IBM i Modernization Engine for Lifecycle Integration 63

 build starts.

Delete Credentials
The delete button is
disabled by default, Select items in the credentials table, and the selected item
will change to highlight and the delete button change to available status, click the delete button and
click yes to confirm that will delete all selected items.
Edit Credential
The Edit button
is disabled by default, select one item in the credential table, the selected item will
change to highlight and the Edit button change to available status, click the Edit button, the credential
info will be shown, all fields can be edited except the owner.

Note: For the security consideration, when editing the credential, the original credential
information will not be shown, and the user should fill all credential information again.

Refresh Credentials
Click the refresh button, the MERLIN GUI will get a refresh so that to get the latest credentials
information.

Manage Templates
The Templates work for managing the template info used for MERLIN. It will save the template info, including
Name, Inventory, Credential, type, owner, and description. The credential and type info will be changed
according to the Inventory type.
Now MERLIN supports four types of templates same as the inventory host
types.

64 IBM i Modernization Engine for Lifecycle Integration

Go to MERLIN GUI, Connections -> Templates, user will turn to the Templates page.

For the Admin side, all templates will be shown, but the run action only works on own templates, for the user
side, all own templates will be shown, it includes Name, Inventory, Credential, Type, Owner, Created Time,
and Updated Time by default.
Users also could customize the columns by clicking the icon at the right top of
the table.

Add Template

Click the Add button, add the Template name, and select an inventory, the template type is the same
type as inventory, the credential will be filter to the same type. According to the inventory type, the
other
required fields will be difference.
Use Power VC as example, user must enter
the vm info which used in this template, or the +Add button
will keep disabled.

Fill all necessary fields, the +Add button will be able to click, click the +Add, the new template info will be
imported to Templates table.

IBM i Modernization Engine for Lifecycle Integration 65

 Delete Templates
The delete button is disabled by default, select items in the Templates table, the selected items will
change to highlight and the delete button change to available status, click the delete button, and click
yes to confirm that will delete all selected items.
Edit Template
The Edit button is disabled by default, select one item in the Templates table, the selected item will
change to highlight and the Edit button change to available status, click the Edit button, the template
info
will be shown, all fields can be edited except the owner.
Run Template
The Run is disabled by default, select one item in the Templates table, the selected item will change to
highlight, and the run button change to available status. According to the different templates type, the
action will be different.
For the Power VC template, MERLIN supports the Provision actions, that will help the user to deploy a
new IBM VM, the user should make sure all the hardware configurations have been set up on the Power
VC side.

For the IBM i server template, MERLIN supports Enable Ansible environment, Validate the dependent PTFs,
Install Certificate, Enable IBM i developer environment, and Enable ARCAD environment.

Refresh Templates

Click the refresh button, the MERLIN GUI will get a refresh so that to get the latest Templates info.

Manage IBM i Servers

66 IBM i Modernization Engine for Lifecycle Integration

MERLIN provides methods to manage IBM i servers, user can run template actions for their IBM i server, also
could manage the IBM i VM life cycle which is deployed by the Power VC template.

Deploy IBM i server with Power VC Template.

There are two methods to use Power VC template
to deploy an IBM i server.
The first method to deploy IBM i server, go to the MERLIN GUI, Connetions -> Templates, users
turn to the templates page, select one Power VC template, Click the run button.

Select
the Provision action and click Run, user will see the Run template window. Before running
this action, please make sure all the hardware configuration has been set up in Power VC side.

In
the Run Template page, it will display the info which you created in the Power VC template,
and select one credential for this new IBM i server, it will create a new user profile with the
username and password in the new IBM i server.

In
the Run CL command field, it allows users to operate simple CL command during the IBM i
deployment. It begins with the system command and the CL command need write into the
following double quotation mark.
The second method to deploy IBM i server, go to the MERLIN GUI Provision->Deploy VM. Select
a Template in the dropdown list, the deployed info will be shown. Select a credential for this new
server.

No matter which methods

to deploy the vm, after clicking the Run button in the Run Template
page, the webpage will auto turn to the Virtual Machines page.

While the server deploying, MERLIN will create the related inventory, templates.
Manage the IBM i server life cycle
Go to the MERLIN GUI, Provision ->
Virtual Machines, select a template at the Select template
dropdown list, all the VMs deployed by this template will be shown.

IBM i Modernization Engine for Lifecycle Integration 67

 It will display the basic info of IBM i server including Name, IP, status, health, resources, and Running
task.
MERLIN
support to manage the IBM i server life cycle, user can operate the start, stop, restart and
delete operations. Select
VM record in the VM tables, which will start, stop, restart, and delete buttons
to be available. Click the button, MERLIN will send the request to Power VC and get the task status to
the Running task column.

Note: delete the IBM i server, the related record will also be deleted.

Running action for the IBM i server

Back to the Templates webpage, select
one IBM i server, click the running button, user could see all
actions that suit running on the IBM i server. Now MERLIN support five actions.

For the Enable Ansible environment action that will help to initiate the yum, python, and Ansible
packages, etc. If the server is not run any task before, this action should run at the first step.
For the Validate the dependent PTFs action that will help to validate if the dependent PTFs have been
installed in the IBM i server.
Minimum HTTP Group PTFs:
IBM i 7.5 SF99952: IBM HTTP Server for i Group level 01
IBM i 7.4 SF99662: IBM HTTP Server for i Group level 20
IBM i 7.3 SF99722: IBM HTTP Server for i Group level 39
Host compilers in 5770WDS:

68 IBM i Modernization Engine for Lifecycle Integration

 IBM i 7.3 PTF SI74590
For the Install the MERLIN Certificate on IBM i action that will help to initialize the trust store
configuration and enable the certificate for the https of RESTAPI services. This will configure TLS on the
ADMIN5 Liberty server on port 2012.
For the Enable IBM i developer environment action that will help to set up the IBM i developer
environment on the specific IBM i server.
For the Enable ARCAD environment actions that will help to set up the IBM i ARCAD environment in a
specific IBM i server.
Select one action in the action window, that item will be highlighted, then click the Run button, and the
related actions
will run. Click Refresh to see the latest log information.

Make sure the IBM i server has already started the SSHD service or the action will fail.

Manage the lifecycle of MERLIN Tools

IBM i Modernization Engine For lifecycle Integration guides and simplifies the use of MERLIN tools which help
implement DevOps & Services-based software. An authorized user can manage the lifecycle of MERLIN tools.
To learn more about the user
role and permissions with MERLIN, see
Manage_MERLIN_users_and_authorities.

* View installed tools

* List MERLIN tools in catalog

* View details of a MERLIN tool

* Install MERLIN tools

* Uninstall a MERLIN tool

IBM i Modernization Engine for Lifecycle Integration 69

 Follow the steps here to manage the lifycle.

Once a user sign-on MERLIN, the installed MERLIN tools which the user has permissions to view are
shown on the homepage.

List MERLIN tools in catalog.

Go to MERLIN GUI, then open Tools->Catalog, the supported MERLIN tools are in the Catalog.

70 IBM i Modernization Engine for Lifecycle Integration

View details of a MERLIN tool

Install MERLIN tools Ensure a proper role or permissions have been granted to user to do the
deployment. To learn more about the user role and permissions with MERLIN, see
Manage_MERLIN_users_and_authorities.

IBM i Modernization Engine for Lifecycle Integration 71

 In catalog, select the tool to be installed

Read the license terms of the MERLIN tool and decide if you accept it.

Create a project where the MERLIN tool is installed into. If the project does exist, the step can be
skiped.

72 IBM i Modernization Engine for Lifecycle Integration

Choose a project where the MERLIN tool is installed into.

Choose an update channel, which is used to track and receive updates for the MERLIN Tool.

Choose a update stratety, which has two strategies, one is Automatic, that means once new versions
are released, the installed MERLIN tool will be upgraded to latest version automatically. The other is
Manual, that means once new versions are
released, the installed MERLIN tool will be upgraded to
latest version automatically. Otherwise, the update must be manually approved before installation can

IBM i Modernization Engine for Lifecycle Integration 73

 begin.

Specify customize application settings.

Review the summary of the MERLIN Tool.

74 IBM i Modernization Engine for Lifecycle Integration

 Access MERLIN Tools after the deployment from the platform or saved URLs.

Uninstall a MERLIN tool Go to MERLIN GUI, then open Tools -> Deployed Tools -> select the tool to be
uinstalled -> Right click on the tool -> Uninstall the Application.

How to Update Passwrord

This document simply describes how to update password.

Open browser, enter the link https://

>/auth/realms/merlin/account

IBM i Modernization Engine for Lifecycle Integration 75

 Sign In with the User credential -> Click Personal Info tab

Click
Account Security -> Singing In -> Click Update button.

Will redirect to the Update password page -> Enter the

New Password and Confirm password -> click Submit

76 IBM i Modernization Engine for Lifecycle Integration

 button. Then the password will be updated.

IBM i Modernization Engine for Lifecycle Integration -

Tools
There are multiple tools available for use that provide additional capabilities.

IBM i Developer Integrated Development Environment

for IBM i Modernization Engine for Lifecycle Integration

IBM i Modernization Engine for Lifecycle Integration 77

 IBM i Developer Integrated Development Environment for IBM i Modernization Engine for Lifecycle
Integration is a development environment that provides an in-browser IDE that you can use to develop IBM i
applications from any machine. It provides
a single-click developer workspace and eliminates local
environment configuration.

IBM i Developer is built on the Red Hat® CodeReady Workspaces project. The core functionality for Red Hat
CodeReady Workspaces is provided by an open source project called Eclipse Che. IBM i Developer uses
Kubernetes and containers to provide your
team with a consistent, secure, and zero-configuration
development environment that interacts with your IBM i platform.

Core capabilities

Developer environment for teams

One-click workspaces for IBM i platform
Enterprise readiness and built-in security
Modern editing experience for IBM i languages (RPG, SQL, and more)
Interaction with IBM i objects and IFS files
Support for project-based developer builds

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for
Lifecycle Integration

Getting Started
Note: For additional getting started information and videos, visit the Merlin Overview support page.

Steps:

Merlin user is created by Merlin adminstrator and the user is given access to the Merlin project with the
IBM i Developer tool
Define Credentials in platform Connections
Define IBM i hostname in Inventory
Note: verify all prerequisites are installed on the IBM i and that configuration has been
completed.
Define IBM i user profile and password in Credentials
Define Template with inventory and credential
Start IBM i Developer
Under Tools>Deployed Tools, launch IBM i Developer to launch the Dashboard. Dashboard is
where application developers create, start, stop, and manage their development workspaces all
from a web browser.
Start workspace
From Create Workspace page, select IBM i Developer tools stack to create a clean workspace
with all the IBM i developer tools.

Note: IBM i Developer is built on top of Red Hat CodeReady Workspaces. For more information on what else
can be done with workspaces, see the Red Hat documentation.

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for
Lifecycle Integration

78 IBM i Modernization Engine for Lifecycle Integration

Overview

Dashboard
The IBM i Developer Dashboard allows the user to create, start, manage, and delete workspaces. Here you
should see the workspaces available.

IBM i Modernization Engine for Lifecycle Integration 79

 The sidebar shows frequently used shortcuts and can be toggled with the top left menu icon

To create a new IBM i Developer Workspace, click on the IBM i Developer tool stack from Create
Workspace

80 IBM i Modernization Engine for Lifecycle Integration

 Other tool stacks are also available.
Custom Workspace option is also available.

To start an existing workspace, go to Workspaces and click on the workspace you want to
open.
You may also start a workspace in Recent Workspaces in the sidebar
Note: You can only have ONE workspace running at a time.

Workspace
Once a Workspace is started, you should see the IBM i Developer Integrated Development Environment (IDE)
displayed on your browser. This is where the user can develop, build, and modernize their applications.

IBM i Modernization Engine for Lifecycle Integration 81

 If this is your first time accessing this workspace, you should see the documentation links from the welcome

82 IBM i Modernization Engine for Lifecycle Integration

page in the editor. Refer to these documents for additional support.

The Workspace contains:

Explorer - to organize the current workspace.

File System:
Files and Folders in your current workspace
IBM i Project Explorer
Work with IBM i projects in your current workspace
IBM i Job Log
Shows the logs from IBM i jobs started in the workspace Note: Right click on the Explorer
heading to toggle views.

IBM i Modernization Engine for Lifecycle Integration 83

84 IBM i Modernization Engine for Lifecycle Integration
Editor area in the center. For information on the editing features, go to the Edit Page.

Tabs on the left for Explorer, Search, Git, etc

IBM i Modernization Engine for Lifecycle Integration 85

 Settings from bottom left
Preferences
IBM i Developer settings can be accessed here
Keyboard shortcuts
Color theme

86 IBM i Modernization Engine for Lifecycle Integration

IBM i Modernization Engine for Lifecycle Integration 87
 Running commands - View > Find Command..., then find the command to run

Terminal View - Terminal > Open Terminal in specific container, then choose the container to open a
terminal with

88 IBM i Modernization Engine for Lifecycle Integration

 Return to dashboard - yellow button to open the workspace list

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for
Lifecycle Integration

Git Integration

IBM i Modernization Engine for Lifecycle Integration 89

 Git is integrated within the Merlin IDE, which means you can run commands like git clone, git pull, git
commit, and so on, to help you with source control management.

In order to run a Git command, go to View > Find Command..., then type in "git" to find the Git command you
wish to run. If you are more familiar with Git on the command line, you may also run the Git commands from
an opened terminal. To open a terminal, do Terminal > Open Terminal in specific container, then select the
terminal you wish to open.

The Source Control: Git View is helpful to see the status of your git branch. here you can see the changes you
have made since the last commit and perform various git actions.

Below is an example to use Git with the Merlin IDE from cloning a project to committing your changes to a
newly created branch.

Steps:

1. Use Git: Clone command to load source from a Git repository

2. Create a new branch for development with Git: Create Branch

3. After making some changes, you will see the list of your changes in the Source Control: Git View. You
may see the diff between the original files and the changed files when you click on a file.

90 IBM i Modernization Engine for Lifecycle Integration

 4. Now to stage the changes with Git: Stage.

5. Use Git: Commit to commit your changes

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for
Lifecycle Integration

IBM i Projects

IBM i Modernization Engine for Lifecycle Integration 91

 IBM i projects are designed to self-describe how they will build themselves as much as possible. These
projects leverage the use of a project level JSON file (iproj.json) to store project metadata information
such as a description,
Git repository, version, license, and several IBM i related attributes (target object
library, library list, initial CL commands, and include directories). Optional directory level JSON files
(.ibmi.json) can be used to override the
target library and CCSID for that directory. For more information on
the project metadata definition of IBM i projects, see Project Metadata.

The IBM i Project Explorer view is what you will use to define IBM i connections for your projects. In doing
this, you will be able to work with your desired libraries, objects, members, and IFS files.

Getting Started
To get started with working on an existing IBM i project that lives in Git, use Git Clone to load the source from a
Git repository. For more information, see Git Integration.

If you are working on a new IBM i project, follow these steps:

1. Navigate to the command palette and run the command Create IBM i Project.
2. Select the workspace in which you want to create the project in.
3. Modify the selected workspace path to include the name of your project.
4. (Optional) Enter a description for your project.
5. Select from the list of connections that were defined in the Merlin Connections.
6. Modify or confirm the suggested build directory you would like to proceed with for the project.

IBM i Connections
To specify an IBM i connection on your project, follow these steps:

1. Open the IBM i Project Explorer view.

Note: By default, the IBM i Project Explorer view should be visible under the Explorer view
container. If not visible, navigate to View > Open View... and select the IBM i Project Explorer
option.
2. Expand your project.
3. Right click on the IBM i and select the Specify IBM i Connection action.
4. Select from the list of connections that were defined in the Merlin Connections.
Note: The Add Templates from Connections in Merlin option can be selected if you wish to be
navigated to define a new Template.
5. Modify or confirm the suggested build directory you would like to proceed with for the project.

Once an IBM i connection is defined on a project, it will be visible in the IBM i description. To then work with
your connection using the following actions upon right clicking the IBM i:

Edit Connection: Edit to another IBM i connection defined in the Merlin Connections.
Restart Connection: Restart the current IBM i connection.
Logout Connection: Logout from the current IBM i connection.

92 IBM i Modernization Engine for Lifecycle Integration

Source
The Source is what will be used to work with source files that exist locally in your workspaces and remotely
on IFS/Git. With source filters and queries, you will be able to work with the desired source files while also
being able
to compare the changes between your local and remote source.

Build Directory
The Source description will render the current build directory for the project which will be used when
performing developer builds. This build directory will be initially set upon specifying an IBM i connection
where the user will
be suggested to proceed with using the default build directory
({userHomeDirectory}/{projectName}). If the user's home directory cannot be retrieved, a temporary
build directory will be suggested instead.

To modify the build directory, the following actions are available upon right click the Source:

Edit Build Directory: Edit to another build directory.

Reset Build Directory: Reset to the default build directory.

IBM i Modernization Engine for Lifecycle Integration 93

 Developer Build
By right clicking the Source, you can access the following related actions to perform developer builds on a
project:

Upload to Build Directory on IBM i: Upload the source to the build directory.
Build Project: Build the source into the target library.

For more information on the behaviour of these actions, see Developer build.

Source Filters
Source filters can be used to filter the source files that are visible under the Source. By right clicking on the
Source and selecting the Filter Source Files action, you can choose from a selection
of filters:

All: All local and remote source files.

Note: Upon defining an IBM i connection on a project, the Source will default to the All filter.
Changed: Source files that are out of synch with the remote build directory.
Remote IFS: Remote source files on IFS.
Local Project: Local project source files.

94 IBM i Modernization Engine for Lifecycle Integration

 Branch Changes: Changes in local source files compared to the latest tagged commit on Git.
Note: This filter uses local tag information and so will not be visible if no tag can be found.
Perform a git pull to retrieve any tags that exist in the remote repository before trying to use
the Branch Changes filter.

For certain source filters, you will be able to observe that the source files have icons that distinguish the state
in which they are in.

Source Queries
To further simplify the set of source files visible under the Source, queries can be added on top of any filter by
right clicking the Source and selecting the Add Source Query action. Upon doing
this, you can create a new
source query or select from any previously added ones. The currently selected source query will be displayed
in the Source description. By right clicking the Source, the following related actions are
also available:

Clear Source Query: Clear the current source query.

Delete Source Query: Delete from a set of previously added source queries.

IBM i

IBM i Modernization Engine for Lifecycle Integration 95

 The IBM i is where you will be leveraging the IBM i connection defined on a project. Once connected, you will
be able to work with your desired libraries, objects, members, and IFS files.

Variables
The project metadata for IBM i projects support the use of variables in the following fields: objlib, curlib,
preUsrlibl, postUsrlibl, setIBMiEnvCmd, buildCommand, compileCommand,
and includePath.
Variables are always prefaced with an &. By levering the use of variables, the same project definition can be
used to target a different build library from one developer to another.

The Variables heading is where you will be able to visualize the set of variables defined in the iproj.json.
Upon right clicking a variable, the Edit Variable action can be used to define a value for
that variable.

Library List
The Library List heading is where you will be able to view your system libraries, user libraries and current
library. The library list is initially set according to your user profile but can be modified based on the fields set
in
the project's iproj.json. When working with libraries and the library list, the following actions can be
used by right clicking on any library:

Clear Library: Delete all objects that you have the authority to delete from the specified library.
Delete Library: Delete the specified library from the system after all objects in the library have been
deleted.
Add to Beginning of Library List: Add the specified library to the beginning of the user portion of the
library list.
Add to End of Library List: Add the specified library to the end of the user portion of the library list.
Set as Current Library: Set the specified library to be the current library.

Note: To create a new library, right click on the IBM i and select Create Library. To also delete any objects
under a library, right click on the object and select Delete Object.

96 IBM i Modernization Engine for Lifecycle Integration

Object Libraries
The Object Libraries heading is where you will be able to view library variables defined in the curlib,
objlib, preUsrlibl, and postUsrlibl of the project's iproj.json

Note: When the objlib is defined (or curlib if the objlib is not defined) strictly with a library name
instead of a variable, it will also be listed here.

IBM i Modernization Engine for Lifecycle Integration 97

 My Queries
The My Queries heading is where you will be able to create QSYS and IFS queries. After selecting the Add
Query action, enter a query of the following format:

Library query: {libraryName}

Object query: {libraryName}/{objectName} {objectType}:{objectAttribute}
Note: If the query is entered as {libraryName}/{objectName}, you will be prompted to
proceed or modify the default object type and object attribute.
Member query: {libraryName}/{objectName}({memberName}.{memberType})
IFS query: {ifsPath}

Note: Queries support the use of variables. Generic names can also be used in the above parameters
excluding the {libraryName} for object queries and member queries.

By right clicking on any created query, you can access the following related actions:

Refresh Query: Refresh the specified query.

Delete Query: Delete the specified query.

98 IBM i Modernization Engine for Lifecycle Integration

Theia and SSH Terminals
To a launch a terminal for a project, the following actions can be used upon right clicking on the IBM i:

Open Terminal in Container: This will open a terminal and navigate to the project in the workspace.
Open SSH Terminal. This will open a terminal, SSH to the IBM i machine, and navigate to the build
directory.

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for
Lifecycle Integration

IBM i Modernization Engine for Lifecycle Integration 99

Editing
The (Integrated Development Environment)IDE is based on Eclipse Che/Theia and it has a similar user
experiences as Visual Studio (VS) Code.

Here are the features for general source code editing.

Keyboard shortcuts
Multiple selections (multi-cursor)
Column (box) selection
Save / Auto Save
Hot Exit
Find and Replace
Search across files
Content assist
Folding
File encoding support

For detailed information on editing features, please check out Visual Studio Code documentation

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for
Lifecycle Integration

Editing RPG
Apart from those common language features mentioned in Edit, ILE RPG source editing also has these
capabilities:

outline view - structured view of source that allow navigation to source, filtering the items
Use View > Outline to open outline view.

100 IBM i Modernization Engine for Lifecycle Integration

Click a
field or a variable in the Outline view will position the editor to its definition and highlight it.

IBM i Modernization Engine for Lifecycle Integration 101

 Outline view supports filtering the items by typing the name of
item inside the outline view.

hover - show information for item under cursor

appear and show the definition of the variable.
Put the mouse over the variable and the hover will

references - show particular code element is referenced throughout the codebase

After right clicking on a specific variable, users can select either Go to References
or Find All
References to show all references.
When
you execute a Go to References
search, the result will be embedded inline. You can navigate
between different references in the peeked editor and make quick edits right there.

The result of executing a Find All References search will show up in the REFERENCES: RESULTS view

102 IBM i Modernization Engine for Lifecycle Integration

on the left.

definition - show source of particular code element

After right clicking on a specific variable, users can
select Go to Definition to go to the definition of the
variable.

formatting - format the whole document or selected region

Formatting options can be found at Preferences.

Users can select Format Document to format the whole document or Format Selection to format the

IBM i Modernization Engine for Lifecycle Integration 103

 selected region after right clicking in the source file.

content assist - code and variable completion

by typing ⌃/CTRL+SPACE.
Content assist can be triggered in editor window

rename - intelligently rename all references to variables

Select Rename Symbol and then type the new desired name
and press Enter. All usages of the symbol
will be renamed, across files.

104 IBM i Modernization Engine for Lifecycle Integration

 source error reporting - errors are shown beside the text in the editor and Problems view
Use View > Problems to open problems view.
The errors display in both editor and problems view. In the editor,
if the cursor hovers over the
problem, it will show the details of the error. In the problems view, clicking a specific problem will
position the editor to the location of the error.

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for
Lifecycle Integration

Editing SQL
SQL source editing capabilities:

formatting
Formatting
options can be found at Preferences.

IBM i Modernization Engine for Lifecycle Integration 105

 Formatting supports both Embedded SQL formatting and Pure SQL formatting. Users can select
Format Document to format the whole document or Format Selection to format the selected region
after right clicking in the source file.

content assist

The content assist provides SQL keyword completion. Content assist can be triggered in editor window

106 IBM i Modernization Engine for Lifecycle Integration

 by typing ⌃/CTRL+SPACE.

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for
Lifecycle Integration

Developer build
IBM i Developer allows the user to run the project-based developer builds. IBM i Developer does not restrict
users from using any specific building technology. For example, users may use Better Object Builder (BOB) or
ARCAD tooling
for the builds. Alternatively, users may even write their scripts and invoke them as long as
those build tools respect the IBM i Projects Standard.

Prepare the Workspace and the Project

Before getting started, please make sure you have set up your IBM i Projects.

Specify an IBM i Connection

Specify the Build Directory
Set the values for any variables defined in the project.

Configure the Build Command and the Compile Command

You may configure to use different build technologies by specifying different build/compile commands. The
build command is for building an entire project. The compile command is for building a single file. There are
two ways you can define those
two commands.

1. The default way of building a project is specified in the Preferences. Those settings apply to all the
projects in the workspace and can be overwritten by a project's iproj.json. To change the
commands, go to File>Settings>Open Preferences (or Ctrl/Cmd + ,)>scroll down to the Build
command or compile command.

IBM i Modernization Engine for Lifecycle Integration 107

 2. For project specific build setup, the build/compile commands can be specified in the project's
iproj.json. See the documentation on how to set
the commands.

Both methods support the substitution of variables.

Variable Description
{filename} resolves to the base file name being edited.
{path} resolves to the full IFS path corresponding to the source in the editor.
{host} resolves to the IBM i hostname.
{usrprf} the user profile that the command will be executed under.
{branch} resolves to the name of the current git branch if this project is managed by git.
Note: For more information about how to use BOB's makei utility, please view the documentation for makei.

Perform a Build/Compile
Select View>Find Command and enter IBM i Developer: Build (or Ctrl/Cmd + Shift + B) to invoke the build
command.

108 IBM i Modernization Engine for Lifecycle Integration

 You can also find a shortcut in the project explorer to directly perform a build for a specific project.

The compile command will compile the currently active file in the workspace by default. To invoke the compile
command, you must first open the source file you want to compile. And then select View>Find Command and
enter IBM i Developer: Compile or IBM i Developer: Build (or Ctrl/Cmd + F7).

You can tell the build/compile command is running from the pop-up output channel.

Getting Feedback
Output from Build/Compile Command
The Output view contains a channel showing all the standard outputs for the running build/compile
commands.

Those outputs can be found under the OUTPUT tab (View->Output, or Ctrl/Cmd + Shift + U). Select IBM i
Build Output in the drop-down on the right.

IBM i Modernization Engine for Lifecycle Integration 109

 You may clear the outputs or turn on and off the auto-scrolling feature using the buttons on the right.

Compiler Feedback
IBM i Developer will populate the problem view (View->Problems, or Ctrl/Cmd + Shift + M) with compiler
feedbacks. Those feedbacks come from the event files under .evfevent directory.By default, the build tools
will create those event
files, and IBM i Develop will then pull them back in the Build/Compile process.

110 IBM i Modernization Engine for Lifecycle Integration

You can click on any line to jump to the source directly.

Job Log Results

IBM i Developer will also read .logs/joblog.json files to populate the IBM i Job Log view (View->Find
View, and enter IBM i Job Log).

The job logs are grouped by commands and you can always find the latest at the top. Click on the command to
show all the job logs related to this command. You can also hover on a job log message to show details.

IBM i Modernization Engine for Lifecycle Integration 111

 You may find the schema for joblog.json under BOB's documentation.

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for
Lifecycle Integration

Settings
Access settings from File > Settings.

Preferences
IBM i Developer
Build Command

Command to invoke when building a project. A project can override the command used by specifying a
build command in the project's iproj.json.
Compile Command
Command to invoke
when building the selected file. A project can override the command used by
specifying a compile command in the project's iproj.json.

Formatting Options RPGLE

Maximum Line Width
The maximum number
of characters for each line.

112 IBM i Modernization Engine for Lifecycle Integration

 Preserve Relative Indent Of Continued Line
Specify if continued lines preserve their relative indentation.
Select Indent
The number of spaces to indent after a select statement.
Start Column
Indentation begins at the column that you set.
Tab Size
The number of spaces to indent.

Formatting Options SQL

Adjust Casing Only

Specify if to only adjust uppercasing or lowercasing and to not change the indentation/line breaks.
Identifiers
Specify the
uppercasing or lowercasing of SQL identifiers.
Keywords And Built-in Functions

Specify the uppercasing or lowercasing of SQL keywords and built-in functions.

Indent
Specify
the indent level for SQL formatting (1-20).
Maximum Line Length
Specify the maximum
number of characters for each line.
New Line On And/Or

break before or after AND or OR keyword, or just leave alone.
Specify if to insert line
New Line On Comma

break before or after a comma, or just leave alone.
Specify if to insert line
Include File

outside the project are resolved when getting the compiler errors after build, it will affect
If include files
the speed of showing the diagnostics in problem view.

Logging
Language Server Logging Category

language server.
Specify logging level for RPG or SQL
Level

logging level.
Specify
Projects

configuration in settings.json.
Edit project
SSH Verbosity Level

for SSH commands is increased.
Specify if the verbosity

Upload Command

Delete Files Not In Source Dir

Specify if remote files that do
not exist locally be deleted when synchronizing local project files to the
remote IBM i IFS directory.

Keyboard shortcuts
Specify keyboard shortcuts to invoke commands.

Color theme
IBM i Modernization Engine for Lifecycle Integration 113
 Select the color theme.

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for
Lifecycle Integration

IBM i Modernization Engine for Lifecycle Integration -

DevOps CI/CD
IBM i CI/CD aims to simplify the experience of DevOps for IBM i application development.
Core capabilities provided:

Out-of-box Jenkins with ARCAD integration. Users can create their own Jenkins environment with
capability to build and deploy IBM i programs.
Graphic interface to simplify key operations of Jenkins. This GUI creates Jenkins pipelines specifically
for IBM i programs development.

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for
Lifecycle Integration

Access IBM i CI/CD

This IBM i CI/CD provides browser-based tooling to set up and manage an automated build, test, and
deployment pipeline for native IBM i applications leveraging Jenkins.

Use Jenkins as the backend automation server for the actual build job.

Define customized profile to manage the source code, build and deploy process.

Integration with ARCAD with Jenkins plugins.

114 IBM i Modernization Engine for Lifecycle Integration

Deploy and Initialize IBM i CI/CD

Deploy IBM i CI/CD from MERLIN platform

Install IBM i CI/CD in the Catalog from MERLIN platform

Follow the Installation Application wizard to complete the installation of IBM i CI/CD.

Launch IBM i CI/CD from MERLIN platform

Under Overview > Quick Launch, click to launch IBM i CI/CD directly.
Under Tools > Deployed Tools, right click and launch IBM i CI/CD in context menu.

Initialize Jenkins in IBM i CI/CD GUI

Jenkins is the automation server behind IBM i CI/CD which runs the actual build and deploy jobs. Both
internal Jenkins and external Jenkins are supported in IBM i CI/CD, internal Jenkins comes with IBM i CI/CD
and external Jenkins can be existing
Jenkins.

Both internal and external Jenkins must be initialized before using in IBM i CI/CD. While the initialization of
external Jenkins only saves the information (Jenkins URL, username, password, and API token) for
authentication with Jenkins REST API
into MERLIN platform, the initialization of internal Jenkins will do the
actual configuration of Jenkins.

Use Jenkins Configuration > Jenkins Server > Initialize Jenkins to open the Initialize Jenkins wizard.
Note: Initialize Jenkins requires admin user.

Initialize internal Jenkins

Select Use internal Jenkins server in step Select Jenkins server type.

Input Jenkins username and password in step Initialize Jenkins using default wizard. The
user will be created in internal Jenkins and used for later authentication with Jenkins.

IBM i Modernization Engine for Lifecycle Integration 115

 Wait for the initialization of internal Jenkins to finish. Current Jenkins information will be
refreshed and the Connectivity will be Available if the initialization finished successfully.

Initialize external Jenkins

Select Use internal Jenkins server in step Select Jenkins server type.

Input external Jenkins information in step Specify Jenkins server information.

Note: Use Generate API token to get the API token after filling in the Jenkins server
URL, username, and password. API token is required when authentication with Jenkins
REST API.
Note: Use Test TLS to verify if the TLS is configured on the external Jenkins server and
import the CA certificate into the trust store if it is not.
Wait for the initialization of external Jenkins to finish. Jenkins information will be refreshed and
the Connectivity will be Available if the initialization process finished successfully.
Note: Another option to set external Jenkins, use Edit selected Jenkins server. Add an available
Jenkins template in MERLIN platform first and select the pre-added Jenkins template. Use Test TLS to
verify if the TLS is configured on the selected Jenkins server and import CA certificate into trust store if

116 IBM i Modernization Engine for Lifecycle Integration

 it is not.

Integrate ARCAD in IBM i CI/CD GUI

Integrate ARCAD will enable the capability to communicate with ARCAD builder server by installing three
ARCAD plugins in Jenkins, including ARCAD-Commons Plugin, ARCAD-Builder Plugin, and ARCAD-Macro
Execution Plugin.

Use Jenkins Configuration > ARCAD Integration > Enable ARCAD Integration to open the Enable ARCAD
Integration dialog.

Note: Enable ARCAD Integration requires an admin user and only supports internal Jenkins. The integration
process will overwrite all the configuration of ARCAD-Builder Plugin and ARCAD-Macro Execution in internal
Jenkins.

Note: Currently IBM i CI/CD only supports the configuration of ARCAD builder server. The configuration of
ARCAD Servers for ARCAD-Macro Execution Plugin is not supported yet while the ARCAD-Skipper CLI will be
put under default
location /merlin/cicd/gui/skipperCLI. If the user wants to utilize the function of
ARCAD-Macro Execution Plugin, use it in Jenkins GUI directly.

Enable ARCAD integration

Input the ARCAD builder URL, and use Test TLS to verify if the TLS is configured on the ARCAD
builder server and import the CA certificate into the trust store if it is not.

Select ARCAD builder server credential in Jenkins credential list, add the credential first under
Jenkins Configuration > Manage Jenkins Credential.

Wait for the ARCAR integration process to finish. And the ARCAD builder URL and selected
credential name will be listed on ARCAD Integration page.

IBM i Modernization Engine for Lifecycle Integration 117

 Use Test Connection to test the connectivity of ARCAD builder server.

Work with IBM i CI/CD profiles

Create IBM i CI/CD profile

IBM i CI/CD profile defines the whole process of source code management, build and deploy actions.
Currently IBM i CI/CD supports both private and public profiles. Private profiles are only visible to the user
themselves while public profiles are
visible to all users.

Use Profile Management > Create New Profile to open the Create New Profile wizard.

Specify General Information

Specify the profile name and the type of profile, private or public.
Upload customized icon for profile if needed, only JPG and PNG supported.

Source Code Management

Define Git repositories by specifying the Git Repository URL and branch information.

Note: If multiple Git repositories are added, fill in the Check out to sub directory to
create sub directory for different repositories.
Note: Specify credential from Jenkins credential list if current Git repository is not public.

118 IBM i Modernization Engine for Lifecycle Integration

Build

Add build servers

Specify build servers by Add Build Server, use customized build server name if needed.
If Specify build server in profile is checked, select an existing server from the server list(
IBM i templates defined
in MERLIN platform ).
If you want to upload the source code defined in step Source Code Management, check
the checkbox Upload source code to build server and fill in the Work directory on the
remote server.
Source code will be uploaded automatically to the defined Work directory
when the profile runs.

Send files to server

Send multiple files to a remote server. Use the relative path of files. Use enter to separate
multiple files. File directory is not supported.

Run CL command

Run CL command in a remote server. Use enter to separate multiple CL commands.

Run an ARCAD-Builder build

Run an ARCAD-Builder build by the ARCAD Jenkins plugins. Enable ARCAD integration
first and make sure the connectivity to ARCAD build server is available.

IBM i Modernization Engine for Lifecycle Integration 119

 Deploy

Add Deploy Server

Specify deploy servers by Add Deploy Server, use customized deploy server name if
needed.

Send files to server

The same as in Build.

Run CL command
The same as in Build.
Distribution on IBM i

Distribution on IBM i support transfer objects from the source library on source IBM i to
the destination library on destination IBM i.
Note: Use Comma to separate multiple objects.
Define multiple deployments for multiple library transfer actions. Make sure the source
library and destination library exist.
Support package certain objects or package the whole library at once.

Transfer files between IBM i

Transfer multiple single files between two IBM i. Use enter to separate multiple files. File
directory is not supported.

120 IBM i Modernization Engine for Lifecycle Integration

 Summary
Summary of the defined Git repositories, build and deploy action in profile.

Run IBM i CI/CD profile

Right-click on the selected profile and click Run Profile to open the Run Profile wizard. Fill in the necessary
information before running the profile.

Every time a profile runs, a new pipeline job will be created in the Jenkins server named as {profile
name}-{username}-{current time}. While Jenkins supports building any job multiple times, IBM i
CI/CD doesn't support that now.

Work with Jenkins

Jenkins is the automation server behind IBM i CI/CD which runs the actual build jobs.

Manage Jenkins credential

IBM i CI/CD supports the management of Jenkins credentials, including add, edit and delete actions.

IBM i Modernization Engine for Lifecycle Integration 121

 Note: All IBM i CI/CD users are under the same Jenkins user, and all added Jenkins credentials are
visible to all users.
Add Jenkins credential
Add Jenkins credential with type Username with password

Add Jenkins credential with type SSH Username with private key

Edit Jenkins Credential

122 IBM i Modernization Engine for Lifecycle Integration

 Edit Jenkins credential with type Username with password

Edit Jenkins credential with type SSH Username with private key

Manage Jenkins jobs

IBM i CI/CD supports the management of Jenkins job, including refresh job list regarding profile name, stop
job build, view build results and delete Jenkins job.

Note: Jenkins job supports build multiple times, but not supported for the profile in IBM i CI/CD now.
In case the user uses Jenkins directly, the latest build is used by IBM i CI/CD when stop build or view
build results.

IBM i Modernization Engine for Lifecycle Integration 123

Manage Jenkins Accessibility
Currently, only admin users are allowed to initialize Jenkins server for both internal and external Jenkins. If
other users want to use the same Jenkins initialized by admin, then the admin user can assign the access to
users by Jenkins Configuration > Manage Jenkins Accessibility.

Manage Jenkins Accessibility

lists users able to access current Jenkins. The template is created when
The Jenkins Accessibility table
adding Jenkins Accessibility with the Jenkins server URL, Jenkins username, password, and API token
generated
for every user.

Assign Jenkins Access to User Assign access of current Jenkins to other users. The process will
automatically create connection resources with the default name jenkins-{cicd namespace}-
username :

Jenkins inventory with the Jenkins URL

Jenkins credential with the Jenkins username, password, and automatically generated API
token for every user
Jenkins template with above Jenkins inventory and credential.

124 IBM i Modernization Engine for Lifecycle Integration

 Note: Jenkins Accessibility table only lists users whose access to Jenkins is assigned through IBM i
CI/CD, since extra data is added when using Assign Jenkins Access to User.

Resources
IBM i Modernization Engine for Lifecycle Integration is built on various platforms and technologies. To get the
most out of those related platforms and technologies, refer to the following resources.

Merlin Overview including videos

IBM i Documentation
IBM Cloud Paks Documentation
Red Hat OpenShift Container Platform Documentation
Red Hat CodeReady Workspaces Documentation
Workspaces Overview
Importing Certificates to browsers
Creating a workspace using a devfile
Configuring Storage Types
Network Problem Troubleshooting

IBM i Modernization Engine for Lifecycle Integration 125