Chapter 3. Installing the Migration Toolkit for Applications user interface
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 Name Default size Access mode Description hub database 10Gi RWO Hub database hub bucket 100Gi RWX Hub file storage; required if the rwx_supported configuration option is set to true keycloak postgresql 1Gi RWO Keycloak back end database cache 100Gi 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.17, 4.16, 4.15. Prerequisites 4 vCPUs, 8 GB RAM, and 40 GB persistent storage. Any cloud services or self-hosted edition of Red Hat OpenShift on versions 4.17, 4.16, 4.15. You must be logged in as a user with cluster-admin permissions. For more information, see OpenShift Operator Life Cycles . Procedure In the Red Hat OpenShift web console, click Operators OperatorHub . Use the Filter by keyword field to search for MTA . Click the Migration Toolkit for Applications Operator and then click Install . On the Install Operator page, click Install . Click Operators Installed Operators to verify that the MTA Operator appears in the openshift-mta project with the status Succeeded . Click the MTA Operator. Under Provided APIs , locate Tackle , and click Create Instance . The Create Tackle window opens in Form view. 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. 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 Name Default Description cache_data_volume_size 100Gi 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 10Gi Size requested for the Hub database volume hub_bucket_volume_size 100Gi 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 1Gi Size requested for the Keycloak database volume keycloak_sso_req_passwd_update true If the flag is set to true , users are required to update their password after their first login. pathfinder_database_data_volume_size 1Gi Size requested for the Pathfinder database volume maven_data_volume_size 100Gi 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 4Gi 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 4Gi Minimum amount of memory the pod needs to run ui_container_limits_cpu 500m Maximum number of CPUs the UI pod resource is allowed to use ui_container_limits_memory 800Mi Maximum amount of memory the UI pod resource is allowed to use. You can increase this limit if the pod displays OOMKilled errors. ui_container_requests_cpu 100m Minimum number of CPUs the UI pod resource needs to run ui_container_requests_memory 350Mi Minimum amount of memory the UI pod resource needs to run provider_java_container_limits_cpu 1 Maximum number of CPUs the Java provider resource is allowed to use provider_java_container_limits_memory 2Gi Maximum amount of memory the Java provider resource is allowed to use. You can increase this limit if the pod displays OOMKilled errors. provider_java_container_requests_cpu 1 Minimum number of CPUs the Java provider resource needs to run provider_java_container_requests_memory 2Gi Minimum amount of memory the Java provider resource 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" Edit the CR settings if needed, and then click Create . In Administration view, click Workloads Pods to verify that the MTA pods are running. Access the user interface from your browser by using the route exposed by the mta-ui application within OpenShift. Use the following credentials to log in: User name : admin Password : Passw0rd! 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: 32Gi --system-reserved setting: 3Gi --eviction-hard setting: 100Mi The amount of memory available for running pods on this node is 28.9 GB. 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: MTA web console: https://mta-openshiftmta.example.com/ RHSSO Admin console: https://mta-openshiftmta.example.com/auth/admin 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: 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. No multi-user access restrictions on resources There are no multi-user access restrictions on resources. For example, an analyzer task created by a user can be canceled by any other user. Additional resources Configuring LDAP and Active Directory in RHSSO Red Hat Single Sign-On features and concepts 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 Role Persona 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 Menu Architect Migrator Admin 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: Download the latest release of Red Hat OpenShift Local for your platform. Download OpenShift Local . Download pull secret . Assuming you saved the archive in the ~/Downloads directory , follow these steps: cd ~/Downloads tar xvf crc-linux-amd64.tar.xz Copy the crc executable to it: cp ~/Downloads/crc-linux-<version-number>-amd64/crc ~/bin/crc Add the ~/bin/crc directory to your USDPATH variable: export PATH=USDPATH:USDHOME/bin/crc echo 'export PATH=USDPATH:USDHOME/bin/crc' >> ~/.bashrc To disable telemetry, run the following command: crc config set consent-telemetry no Note For macOS, download the relevant crc-macos-installer.pkg . Navigate to Downloads using Finder . 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 . 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: Flags Type Description Default 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 GB of the disk used by the instance 31 -h, -help Help for start -m, -memory int Mi 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: Flags Type Description Default 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 GB, and 10 GB 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 GB, and the memory to 20 GB, run crc config as follows: crc config set cpus 6 crc config set disk-size 200 USD 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 (Gi) CPU Disk sze (Gi) 20Gi 5 110Gi 20Gi 5 35Gi , with the MTA Operator configurations cache_data_volume_size and hub_bucket_volume_size set to 5Gi . 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 GB. While this minimum requirement can be lowered to 1.5 GB, it is not recommended. You can also increase this minimum requirement to more than 2 GB. 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.
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" get secret credential-mta-rhsso -o yaml sudo dnf install NetworkManager sudo apt install qemu-kvm libvirt-daemon libvirt-daemon-system network-manager cd ~/Downloads tar xvf crc-linux-amd64.tar.xz cp ~/Downloads/crc-linux-<version-number>-amd64/crc ~/bin/crc export PATH=USDPATH:USDHOME/bin/crc echo 'export PATH=USDPATH:USDHOME/bin/crc' >> ~/.bashrc crc config set consent-telemetry no crc setup crc config set cpus 6 crc config set disk-size 200 crc config set memory 20480 crc config view - consent-telemetry : yes - cpus : 6 - disk-size : 200 - memory : 16384 crc status 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 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