CLI Guide

The Migration Toolkit for Applications (MTA) supports the following migrations:

MTA provides a comprehensive set of rules to assess the suitability of your applications for containerization and deployment on Red Hat OpenShift Container Platform (RHOCP). You can run an MTA analysis to assess your applications' suitability for migration to multiple target platforms.

For more information about use cases and migration paths, see the MTA for developers web page.

You can install the CLI using podman pull.

You can install the CLI for use with Docker on Windows. This is the required approach when migrating applications built with .NET framework 4.5 or later on Windows to cross-platform .NET 8.0.

However, when running any container image based on Red Hat Enterprise Linux 9 (RHEL9) or Universal Base Image 9 (UBI9), the following error can be returned when starting the container:

Fatal glibc error: CPU does not support x86-64-v2

This error is caused because Red Hat Enterprise Linux 9 or Universal Base Image 9 container images must be run on a CPU architecture that supports x86-64-v2.

For more details, see (Running Red Hat Enterprise Linux 9 (RHEL) or Universal Base Image (UBI) 9 container images fail with "Fatal glibc error: CPU does not support x86-64-v2").

CLI runs the container runtime correctly. However, different container runtime configurations are not supported.

Although unsupported, you can run CLI with Docker instead of Podman, which would resolve this issue.

To achieve this, you replace the PODMAN_BIN path with the path to Docker.

For example, if you experience this issue, instead of issuing:

PODMAN_BIN=/usr/local/bin/docker mta-cli analyze

You replace PODMAN_BIN with the path to Docker:

<Docker Root Dir>=/usr/local/bin/docker mta-cli analyze

While this is not supported, it would allow you to explore CLI while you work to upgrade your hardware or move to hardware that supports x86_64-v2.

You can run the Migration Toolkit for Applications (MTA) CLI against an application.

$ <MTA_HOME>/mta-cli analyze \
    --input <path_to_jee-example-app-1.0.0.ear> \
    --output <path_to_report_output> --source eap5 --target eap7 \

$ <MTA_HOME>/mta-cli analyze --mode source-only --input <path_to_customer-management>
--output <path_to_report_output> --target eap8

$ <MTA_HOME>/mta-cli analyze --input <path_to_jee-example-app-1.0.0.ear> \
    --output <path_to_report_output> \
    --target eap7

You can now run the Migration Toolkit for Applications (MTA) CLI against multiple applications and generate a combined report. This can save you time and give you a better idea of how to prepare a set of applications for migration.

This feature is currently a Developer Preview feature.

Analyze supports running source code and binary analysis by using the analyzer-lsp tool. analyzer-lsp evaluates the rules for the providers and determines rule matches.

mta-cli analyze --input=<path_to_source_code> --output=<path_to_output_directory>

All flags:

Analyze application source code

Usage:
  mta-cli analyze [flags]

Flags:

      --analyze-known-libraries           Analyze known open-source libraries.
      --context-lines (int)               Number of lines of source code to
                                          include in the output for each
                                          incident (default: `100`).
  -d, --dependency-folders (stringArray)  Directory for dependencies.
      --enable-default-rulesets           Run default rulesets with analysis
                                          (default: `true`).
  -h, --help                              Help for analyze.
      --http-proxy (string)               HTTP proxy string URL.
      --https-proxy (string)              HTTPS proxy string URL.
      --incident-selector (string)        An expression to select incidents
                                          based on custom variables.
                                          Example:
                                          !package=io.demo.config-utils
  -i, --input (string)                    Path to application source code or
                                          a binary.
      --jaeger-endpoint (string)          Jaeger endpoint to collect traces.
      --json-output                       Create analysis and dependency
                                          output as JSON.
      --list-sources                      List rules for available
                                          migration sources.
      --list-targets                      List rules for available
                                          migration targets.
  -l, --label-selector (string)           Run rules based on specified label
                                          selector expression.
      --maven-settings (string)           Path to the custom maven
                                          settings file to use.
      --overwrite                         Overwrite output directory.
      --skip-static-report                Do not generate the static report.
  -m, --mode (string)                     Analysis mode, must be one of
                                          `full` or `source-only`
                                          (default: `full`).
      --no-proxy (string)                 Proxy-excluded URLs
                                          (relevant only with proxy).
  -o, --output (string)                   Path to the directory for analysis
                                          output.
      --overwrite                         Overwrite output directory.
      --rules (stringArray)               Filename or directory containing
                                          rule files.
      --skip-static-report                Do not generate the static report.
  -s, --source (string)                   Source technology to consider
                                          for analysis.
                                          To specify multiple sources,
                                          repeat the parameter:
                                          `--source <source_1>
                                          --source <source_2>` etc.
  -t, --target (string)                   Target technology to consider
                                          for analysis.
                                          To specify multiple targets,
                                          repeat the parameter:
                                          `--target <target_1>
                                          --target <target_2>` etc.


Global Flags:
      --log-level uint32                  Log level (default: 4).
      --no-cleanup                        Do not cleanup temporary resources.

You can use transformation to perform the following actions:

Transform application source code or mta XML rules

Usage:
  mta-cli transform [flags]
  mta-cli transform [command]

Available Commands:
  openrewrite Transform application source code using OpenRewrite recipes
  rules       Convert XML rules to YAML

Flags:
  -h, --help   help for transform

Global Flags:
      --log-level uint32   log level (default 4)
      --no-cleanup         do not clean up temporary resources

Use "mta-cli transform [command] --help" for more information about a command.

Transform application source code using OpenRewrite recipes

Usage:
  mta-cli transform openrewrite [flags]

Flags:
  -g, --goal string     target goal (default "dryRun")
  -h, --help            help for openrewrite
  -i, --input string    path to application source code directory
  -l, --list-targets    list all available OpenRewrite recipes
  -s, --maven-settings string   path to a custom maven settings file to use
  -t, --target string   target openrewrite recipe to use. Run --list-targets to get a list of packaged recipes.

Global Flags:
      --log-level uint32   log level (default 4)
      --no-cleanup         do not clean up temporary resources

mta-cli transform openrewrite --input=<path/to/source/code> --target=<exactly_one_target_from_the_list>

Convert XML rules to YAML

Usage:
  mta-cli transform rules [flags]

Flags:
  -h, --help                help for rules
  -i, --input stringArray   path to XML rule file(s) or directory
  -o, --output string       path to output directory

Global Flags:
      --log-level int   log level (default 5)

mta-cli transform rules --input=<path/to/xmlrules> --output=<path/to/output/dir>

When analyzing a multi-language application with Migration Toolkit for Applications (MTA) CLI, you can explicitly set a supported language provider according to your application language to run the analysis for.

When analyzing a multi-language application with Migration Toolkit for Applications (MTA) CLI, you can run the analysis for an unsupported language provider. To do so, you must override an existing supported language provider with your own unsupported language provider by using the --override-provider-settings option.

Access this report from the report landing page by clicking on the application name in the Application List.

The dashboard gives an overview of the entire application migration effort. It summarizes:

Figure 3.3. Dashboard

The top navigation bar lists the various reports that contain additional details about the migration of this application. Note that only those reports that are applicable to the current application will be available.

Access this report from the dashboard by clicking the Issues link.

This report includes details about every issue that was raised by the selected migration paths. The following information is provided for each issue encountered:

Figure 3.4. Issues report

Each reported issue may be expanded, by clicking on the title, to obtain additional details. The following information is provided.

Figure 3.5. Expanded issue

Issues are sorted into four categories by default. Information on these categories is available at ask Category.

Previously, a violation generated by a rule with zero effort was listed as an issue in the static report. This is now listed as an insight instead. Issues are generated by general rules, whereas string tags are generated by tagging rules. String tags indicate the presence of a technology but do not show the code location. With the introduction of Insights, you can see the technology used in the application along with its usage in the code.

For example, a rule searching for deprecated API usage in the code that does not impact the current migration but can be tracked and fixed when needed in the future.

Unlike issues, insights do not need to be fixed for a successful migration. They are generated by any rule that doesn’t have a positive effort value and category assigned. They might have a message and tag.

You can view Insights under the Insights tab in the static report.

- customVariables: []
  description: Embedded library - Apache Wicket
  labels:
  - konveyor.io/include=always
  links: []
  ruleID: mvc-01000
  tag:
  - Apache Wicket
  - Embedded library - Apache Wicket
  when:
    builtin.file:
      pattern: .*wicket.*\.jar

- category: potential
  customVariables: []
  description: RESTful Web Services @Context annotation has been deprecated
  effort: 0
  message: Future versions of this API will no longer support `@Context` and related
    types such as `ContextResolver`.
  ruleID: jakarta-ws-rs-00001
  when:
    java.referenced:
      location: ANNOTATION
      pattern: jakarta.ws.rs.core.Context

Access this report from the dashboard by clicking the Application Details link.

The report lists the story points, the Java incidents by package, and a count of the occurrences of the technologies found in the application. Next is a display of application messages generated during the migration process. Finally, there is a breakdown of this information for each archive analyzed during the process.

Figure 3.6. Application Details report

Expand the jee-example-app-1.0.0.ear/jee-example-services.jar to review the story points, Java incidents by package, and a count of the occurrences of the technologies found in this archive. This summary begins with a total of the story points assigned to its migration, followed by a table detailing the changes required for each file in the archive. The report contains the following columns.

Note that if an archive is duplicated several times in an application, it will be listed just once in the report and will be tagged with [Included multiple times].

Figure 3.7. Duplicate archive in an application

The story points for archives that are duplicated within an application will be counted only once in the total story point count for that application.

Access this report from the dashboard by clicking the Technologies link.

The report lists the occurrences of technologies, grouped by function, in the analyzed application. It is an overview of the technologies found in the application, and is designed to assist users in quickly understanding each application’s purpose.

The image below shows the technologies used in the jee-example-app.

Figure 3.8. Technologies in an application

The Source report displays the migration issues in the context of the source file in which they were discovered.

Figure 3.9. Source report