SupportConsoleDevelopersStart a trialContact

Chapter 3. Installing the Migration Toolkit for Applications user interface

You can install the Migration Toolkit for Applications (MTA) user interface on all Red Hat OpenShift cloud services and Red Hat OpenShift self-managed editions.

Important

To be able to create MTA instances, you must first install the MTA Operator.

The MTA Operator is a structural layer that manages resources deployed on OpenShift, such as database, front end, and back end, to automatically create an MTA instance.

3.1. Persistent volume requirements

To successfully deploy, the MTA Operator requires 2 RWO persistent volumes (PVs) used by different components. If the rwx_supported configuration option is set to true, the MTA Operator requires an additional 2 RWX PVs that are used by Maven and the hub file storage. The PVs are described in the following table:

Table 3.1. Required persistent volumes
NameDefault sizeAccess modeDescription

hub database

10 GiB

RWO

Hub database

hub bucket

100 GiB

RWX

Hub file storage; required if the rwx_supported configuration option is set to true

keycloak postgresql

1 GiB

RWO

Keycloak back end database

cache

100 GiB

RWX

Maven m2 cache; required if the rwx_supported configuration option is set to true

3.2. Installing the Migration Toolkit for Applications Operator and the user interface

You can install the Migration Toolkit for Applications (MTA) and the user interface on Red Hat OpenShift versions 4.13-4.15.

Prerequisites

  • 4 vCPUs, 8 GiB RAM, and 40 GiB persistent storage.
  • Any cloud services or self-hosted edition of Red Hat OpenShift on versions 4.13-4.15.
  • You must be logged in as a user with cluster-admin permissions.

For more information, see OpenShift Operator Life Cycles.

Procedure

  1. In the Red Hat OpenShift web console, click Operators OperatorHub.
  2. Use the Filter by keyword field to search for MTA.
  3. Click the Migration Toolkit for Applications Operator and then click Install.
  4. On the Install Operator page, click Install.
  5. Click Operators Installed Operators to verify that the MTA Operator appears in the openshift-mta project with the status Succeeded.
  6. Click the MTA Operator.

  7. Under Provided APIs, locate Tackle, and click Create Instance.

    The Create Tackle window opens in Form view.

  8. Review the custom resource (CR) settings. The default choices should be acceptable, but make sure to check the system requirements for storage, memory, and cores.

  9. To work directly with the YAML file, click YAML view and review the CR settings that are listed in the spec section of the YAML file.

    The most commonly used CR settings are listed in this table:

    Table 3.2. Tackle CR settings
    NameDefaultDescription

    cache_data_volume_size

    100 GiB

    Size requested for the cache volume; ignored when rwx_supported=false

    cache_storage_class

    Default storage class

    Storage class used for the cache volume; ignored when rwx_supported=false

    feature_auth_required

    True

    Flag to indicate whether keycloak authorization is required (single user/“noauth”)

    feature_isolate_namespace

    True

    Flag to indicate whether namespace isolation using network policies is enabled

    hub_database_volume_size

    10 GiB

    Size requested for the Hub database volume

    hub_bucket_volume_size

    100 GiB

    Size requested for the Hub bucket volume

    hub_bucket_storage_class

    Default storage class

    Storage class used for the bucket volume

    keycloak_database_data_volume_size

    1 GiB

    Size requested for the Keycloak database volume

    pathfinder_database_data_volume_size

    1 GiB

    Size requested for the Pathfinder database volume

    maven_data_volume_size

    100 GiB

    Size requested for the Maven m2 cache volume; deprecated in MTA 6.0.1

    rwx_storage_class

    NA

    Storage class requested for the Tackle RWX volumes; deprecated in MTA 6.0.1

    rwx_supported

    True

    Flag to indicate whether the cluster storage supports RWX mode

    rwo_storage_class

    NA

    Storage class requested for the Tackle RW0 volumes

    rhsso_external_access

    False

    Flag to indicate whether a dedicated route is created to access the MTA managed RHSSO instance

    analyzer_container_limits_cpu

    1

    Maximum number of CPUs the pod is allowed to use

    analyzer_container_limits_memory

    4GiB

    Maximum amount of memory the pod is allowed to use. You can increase this limit if the pod displays OOMKilled errors.

    analyzer_container_requests_cpu

    1

    Minimum number of CPUs the pod needs to run

    analyzer_container_requests_memory

    4GiB

    Minimum amount of memory the pod needs to run

    Example YAML file

    kind: Tackle
apiVersion: tackle.konveyor.io/v1alpha1
metadata:
  name: mta
  namespace: openshift-mta
spec:
  hub_bucket_volume_size: "25Gi"
  maven_data_volume_size: "25Gi"
  rwx_supported: "false"

  10. Edit the CR settings if needed, and then click Create.
  11. In Administration view, click Workloads Pods to verify that the MTA pods are running.
  12. Access the user interface from your browser by using the route exposed by the mta-ui application within OpenShift.

  13. Use the following credentials to log in:

    • User name: admin
    • Password: Passw0rd!
  14. When prompted, create a new password.

3.2.1. Eviction threshold

Each node has a certain amount of memory allocated to it. Some of that memory is reserved for system services. The rest of the memory is intended for running pods. If the pods use more than their allocated amount of memory, an out-of-memory event is triggered and the node is terminated with a OOMKilled error.

To prevent out-of-memory events and protect nodes, use the --eviction-hard setting. This setting specifies the threshold of memory availability below which the node evicts pods. The value of the setting can be absolute or a percentage.

Example of node memory allocation settings

  • Node capacity: 32 GiB
  • --system-reserved setting: 3 GiB
  • --eviction-hard setting: 100 MiB

The amount of memory available for running pods on this node is 28.9 GiB. This amount is calculated by subtracting the system-reserved and eviction-hard values from the overall capacity of the node. If the memory usage exceeds this amount, the node starts evicting pods.

3.3. Red Hat Single Sign-On

The MTA uses Red Hat Single Sign-On (RHSSO) instance for user authentication and authorization.

The MTA operator manages the RHSSO instance and configures a dedicated realm with necessary roles and permissions.

MTA-managed RHSSO instance allows you to perform advanced RHSSO configurations, such as adding a provider for User Federation or integrating identity providers. To access the RHSSO Admin Console, enter the URL https://<_route_>/auth/admin in your browser by replacing <route> with the MTA web console address.

Example:

The admin credentials for RHSSO are stored in a secret file named credential-mta-rhsso in the namespace where MTA is installed.

To retrieve your admin credentials, run the following command: 

oc get secret credential-mta-rhsso -o yaml

To create a dedicated route for the RHSSO instance, set the rhsso_external_access parameter to true in the Tackle custom resource (CR) for MTA.

Additional resources

3.3.1. Roles, Personas, Users, and Permissions

MTA makes use of three roles, each of which corresponds to a persona:

Table 3.3. Roles and personas
RolePersona

tackle-admin

Administrator

tackle-architect

Architect

tackle-migrator

Migrator

The roles are already defined in your RHSSO instance. You do not need to create them.

If you are an MTA administrator, you can create users in your RHSSO and assign each user one or more roles, one role per persona.

3.3.1.1. Roles, personas, and access to user interface views

Although a user can have more than one role, each role corresponds to a specific persona:

  • Administrator: An administrator has all the permissions that architects and migrators have, along with the ability to create some application-wide configuration parameters that other users can consume but cannot change or view. Examples: Git credentials, Maven settings.xml files.
  • Architect: A technical lead for the migration project who can run assessments and can create and modify applications and information related to them. An architect cannot modify or delete sensitive information, but can consume it. Example: Associate an existing credential to the repository of a specific application.
  • Migrator: A user who can analyze applications, but not create, modify, or delete them.

As described in User interface views, MTA has two views, Administration and Migration.

Only administrators can access Administration view. Architects and migrators have no access to Administration view, they cannot even see it.

Administrators can perform all actions supported by Migration view. Architects and migrators can see all elements of Migration view, but their ability to perform actions in Migration view depends on the permissions granted to their role.

The ability of administrators, architects, and migrators to access the Administration and Migration views of the MTA user interface is summarized in the table below:

Table 3.4. Roles vs. access to MTA views
MenuArchitectMigratorAdmin

Administration

No

No

Yes

Migration

Yes

Yes

Yes

3.3.1.2. Roles and permissions

The following table contains the roles and permissions (scopes) that MTA seeds the managed RHSSO instance with:

tackle-admin

Resource Name

Verbs

 

addons

delete
get
post
put

 

adoptionplans

post
get
post
put

 

applications

delete
get
post
put

 

applications.facts

delete
get
post
put

 

applications.tags

delete
get
post
put

 

applications.bucket

delete
get
post
put

 

assessments

delete
get
patch
post
put

 

businessservices

delete
get
post
put

 

dependencies

delete
get
post
put

 

identities

delete
get
post
put

 

imports

delete
get
post
put

 

jobfunctions

delete
get
post
put

 

proxies

delete
get
post
put

 

reviews

delete
get
post
put

 

settings

delete
get
post
put

 

stakeholdergroups

delete
get
post
put

 

stakeholders

delete
get
post
put

 

tags

delete
get
post
put

 

tagtypes

delete
get
post
put

 

tasks

delete
get
post
put

 

tasks.bucket

delete
get
post
put

 

tickets

delete
get
post
put

 

trackers

delete
get
post
put

 

cache

delete
get

 

files

delete
get
post
put

 

rulebundles

delete
get
post
put

tackle-architect

Resource Name

Verbs

 

addons

delete
get
post
put

 

applications.bucket

delete
get
post
put

 

adoptionplans

post

 

applications

delete
get
post
put

 

applications.facts

delete
get
post
put

 

applications.tags

delete
get
post
put

 

assessments

delete
get
patch
post
put

 

businessservices

delete
get
post
put

 

dependencies

delete
get
post
put

 

identities

get

 

imports

delete
get
post
put

 

jobfunctions

delete
get
post
put

 

proxies

get

 

reviews

delete
get
post
put

 

settings

get

 

stakeholdergroups

delete
get
post
put

 

stakeholders

delete
get
post
put

 

tags

delete
get
post
put

 

tagtypes

delete
get
post
put

 

tasks

delete
get
post
put

 

tasks.bucket

delete
get
post
put

 

trackers

get

 

tickets

delete
get
post
put

 

cache

get

 

files

delete
get
post
put

 

rulebundles

delete
get
post
put

tackle-migrator

Resource Name

Verbs

 

addons

get

 

adoptionplans

post

 

applications

get

 

applications.facts

get

 

applications.tags

get

 

applications.bucket

get

 

assessments

get
post

 

businessservices

get

 

dependencies

delete
get
post
put

 

identities

get

 

imports

get

 

jobfunctions

get

 

proxies

get

 

reviews

get
post
put

 

settings

get

 

stakeholdergroups

get

 

stakeholders

get

 

tags

get

 

tagtypes

get

 

tasks

delete
get
post
put

 

tasks.bucket

delete
get
post
put

 

tackers

get

 

tickets

get

 

cache

get

 

files

get

 

rulebundles

get

3.4. Installing and configuring the Migration Toolkit for Applications Operator in a Red Hat OpenShift Local environment

Red Hat OpenShift Local provides a quick and easy way to set up a local OpenShift cluster on your desktop or laptop. This local cluster allows you to test your applications and configuration parameters before sending them to production.

3.4.1. Operating system requirements

Red Hat OpenShift Local requires the following minimum version of a supported operating system:

3.4.1.1. Red Hat OpenShift Local requirements on Microsoft Windows

On Microsoft Windows, Red Hat OpenShift Local requires the Windows 10 Fall Creators Update (version 1709) or later. Red Hat OpenShift Local does not run on earlier versions of Microsoft Windows. Microsoft Windows 10 Home Edition is not supported.

3.4.1.2. Red Hat OpenShift Local requirements on macOS

On macOS, Red Hat OpenShift Local requires macOS 11 Big Sur or later. Red Hat OpenShift Local does not run on earlier versions of macOS.

3.4.1.3. Red Hat OpenShift Local requirements on Linux

On Linux, Red Hat OpenShift Local is supported only on the latest two Red Hat Enterprise Linux 8 and 9 minor releases and on the latest two stable Fedora releases.

When using Red Hat Enterprise Linux, the machine running Red Hat OpenShift Local must be registered with the Red Hat Customer Portal.

Ubuntu 18.04 LTS or later and Debian 10 or later are not supported and might require manual setup of the host machine.

3.4.1.3.1. Required software packages for Linux

Red Hat OpenShift Local requires the libvirt and NetworkManager packages to run on Linux:

  • On Fedora and Red Hat Enterprise Linux run: 

    sudo dnf install NetworkManager

  • On Debian/Ubuntu run: 

    sudo apt install qemu-kvm libvirt-daemon libvirt-daemon-system network-manager

3.4.2. Installing the Migration Toolkit for Applications Operator in a Red Hat OpenShift Local environment

To install Red Hat OpenShift Local:

  1. Download the latest release of Red Hat OpenShift Local for your platform.

    1. Download OpenShift Local.
    2. Download pull secret.

  2. Assuming you saved the archive in the ~/Downloads directory, follow these steps: 

    cd ~/Downloads
    tar xvf crc-linux-amd64.tar.xz

  3. Copy the crc executable to it: 

    cp ~/Downloads/crc-linux-<version-number>-amd64/crc ~/bin/crc

  4. Add the ~/bin/crc directory to your $PATH variable: 

    export PATH=$PATH:$HOME/bin/crc
    echo 'export PATH=$PATH:$HOME/bin/crc' >> ~/.bashrc

  5. To disable telemetry, run the following command: 

    crc config set consent-telemetry no
Note

For macOS, download the relevant crc-macos-installer.pkg.

  1. Navigate to Downloads using Finder.
  2. Double-click on crc-macos-installer.pkg.

3.4.3. Setting up Red Hat OpenShift Local

The crc setup command performs operations to set up the environment of your host machine for the Red Hat OpenShift Local instance.

The crc setup command creates the ~/.crc directory.

  1. Set up your host machine for Red Hat OpenShift Local: 

    crc setup

3.4.4. Starting the Red Hat OpenShift Local instance

Red Hat OpenShift Local presets represent a managed container runtime, and the lower bounds of system resources required by the instance to run it.

Note
  • On Linux or macOS, ensure that your user account has permission to use the sudo command.
  • On Microsoft Windows, ensure that your user account can elevate to Administrator privileges.

The crc start command starts the Red Hat OpenShift Local instance and configured container runtime. It offers the following flags:

FlagsTypeDescriptionDefault value

-b, --bundle

string

Bundle path/URI - absolute or local path, HTTP, HTTPS or docker URI, for example, 'https://foo.com/crc_libvirt_4.15.14_amd64.crcbundle', 'docker://quay.io/myorg/crc_libvirt_4.15.14_amd64.crcbundle:2.37.1'

default '/home/<user>/.crc/cache/ crc_libvirt_4.15.14_amd64.crcbundle'

-c, –cpus

int

Number of CPU cores to assign to the instance

4

–disable-update-check

 

Do not check for update

 

-d, –disk-size

uint

Total size in GiB of the disk used by the instance

31

-h, –help

 

Help for start

 

-m, –memory

int

MiB of memory to assign to the instance

10752

-n, –nameserver

string

IPv4 address of name server to use for the instance

 

-o, –output

string

Output format in JSON

 

-p, –pull-secret-file

string

File path of image pull secret (download from https://console.redhat.com/openshift/create/local)

 

It also offers the following global flags:

FlagsTypeDescriptionDefault value

–log-level

string

log level for example:

* debug

* info

* warn

* error

info

The default configuration creates a virtual machine (VM) with 4 virtual CPUs, a disk size of 31 GiB, and 10 GiB of RAM. However, this default configuration is not sufficent to stably run MTA.

To increase the number of virtual CPUs to 6, the disk-size to 200 GiB, and the memory to 20 GiB, run crc config as follows:

+ 

crc config set cpus 6

+ 

crc config set disk-size 200

+ 

$ crc config set memory 20480

To check the configuration, run:

+ 

crc config view

Example Output

+ 

- consent-telemetry    : yes
- cpus                 : 6
- disk-size            : 200
- memory               : 16384
Note

Changes to the inputted configuration property are only applied when the CRC instance is started.

If you already have a running CRC instance, for this configuration change to take effect, stop the CRC instance with crc stop and restart it with crc start.

3.4.5. Checking the status of Red Hat OpenShift Local instance

To check the status of your Red Hat OpenShift Local instance, run:

+ 

crc status

Example Output

+ 

CRC VM:          Running
OpenShift:       Starting (v4.15.14)
RAM Usage:       9.25GB of 20.97GB
Disk Usage:      31.88GB of 212.8GB (Inside the CRC VM)
Cache Usage:     26.83GB
Cache Directory: /home/<user>/.crc/cache

3.4.6. Configuration of the Migration Toolkit for Applications Operator in a Red Hat OpenShift Local environment

The following table shows the recommended minimum configurations of Red Hat OpenShift Local tested:

Memory (GiB)CPUDisk sze (GiB)

20

5

110

20

5

35, with the MTA Operator configurations cache_data_volume_size and hub_bucket_volume_size set to 5GiB.

3.5. Adding minimum requirements for Java analyzer and discovery

There is a minimum requirement for the Java analyzer, and also the discovery task, which by default is set to 2 GiB.

While this minimum requirement can be lowered to 1.5 GiB, it is not recommended.

You can also increase this minimum requirement to more than 2 GiB. 

kind: Tackle
apiVersion: tackle.konveyor.io/v1alpha1
metadata:
  name: tackle
  namespace: openshift-mta
spec:
  feature_auth_required: 'true'
  provider_java_container_limits_memory: 2Gi
  provider_java_container_requests_memory: 2Gi
Note

To guarantee scheduling has the correct space, provider_java_container_limits_memory and provider_java_container_requests_memory should be assigned the same amount of space.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.