Kantra

Kantra is a CLI that unifies analysis and transformation capabilities of Konveyor. It is available for Linux, Mac and Windows.

Table of Contents

• Prerequisites
• Installation
• Setup (For Mac and Windows Only)
• Usage
  • Analyze an application
  • Transform an application or XML rules
  • Test YAML rules
• References
• Code of conduct

Prerequisites

Podman 4+ is required to run kantra. By default, it is configured to use the podman executable available on the host.

Although kantra is primarily tested with podman, Docker Engine 24+ or Docker Desktop 4+ can be used as an alternative. To use docker, set the environment variable PODMAN_BIN pointing to the docker executable's path:

export PODMAN_BIN=/usr/bin/docker

Installation

To install kantra, simply download the executable for your platform and add it to the path.

Downloading stable release

Go to the release page and download the zip file containing a binary for your platform and architecture. Unzip the archive and add the executable in it to the path.

Downloading latest

The easiest way to get the latest exectutable is to get it from the latest container image.

Linux

Run:

podman cp $(podman create --name kantra-download quay.io/konveyor/kantra:latest):/usr/local/bin/kantra . && podman rm kantra-download

Mac

On Mac, you need to start a podman machine prior to running any podman commands (see Setup for Mac)

Once a machine is started, run:

podman cp $(podman create --name kantra-download quay.io/konveyor/kantra:latest):/usr/local/bin/darwin-kantra . && podman rm kantra-download

Windows

On Mac, you need to start a podman machine prior to running any podman commands (see Setup for Windows)

Once a machine is started, run:

podman cp $(podman create --name kantra-download quay.io/konveyor/kantra:latest):/usr/local/bin/windows-kantra . && podman rm kantra-download

Ensure that you add the executable to the PATH.

Setup (For Mac and Windows Only)

On Mac and Windows, a podman machine needs to be started prior to running any commands:

Mac

Prior to starting your podman machine, run:

ulimit -n unlimited

Init your podman machine :

• Podman 4:

  Podman 4 requires some host directories to be mounted within the VM:

  podman machine init <vm_name> -v $HOME:$HOME -v /private/tmp:/private/tmp -v /var/folders/:/var/folders/

• Podman 5:

  Podman 5 mounts $HOME, /private/tmp and /var/folders directories by default, simply init the machine:

  podman machine init <vm_name>

If the input and/or output directories you intend to use with kantra fall outside the tree of $HOME, /private/tmp and /var/folders directories, you should mount those directories in addition to the default.

Increase podman resources (minimum 4G memory is required):

podman machine set <vm_name> --cpus 4 --memory 4096

Windows

Init the machine:

podman machine init <vm_name>

Usage

Kantra has three subcommands:

1. analyze: This subcommand allows running source code analysis on input source code or a binary.

2. transform: This subcommand allows either converting XML rules to YAML or running OpenRewrite recipes on source code.

3. test: This subcommand allows testing YAML rules.

Analyze

analyze subcommand allows running source code and binary analysis using analyzer-lsp

To run analysis on application source code, run:

kantra analyze --input=<path/to/source/code> --output=<path/to/output/dir>

--input must point to a source code directory or a binary file, --output must point to a directory to contain analysis results.

All flags:

Flags:
      --analyze-known-libraries   analyze known open-source libraries
  -h, --help                      help for analyze
  -i, --input string              path to application source code or a binary
      --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
  -m, --mode string               analysis mode. Must be one of 'full' or 'source-only' (default "full")
  -o, --output string             path to the directory for analysis output
      --rules stringArray         filename or directory containing rule files. Use multiple times for additional rules: --rules <rule1> --rules <rule2> ...
      --skip-static-report        do not generate static report
  -s, --source stringArray        source technology to consider for analysis. Use multiple times for additional sources: --source <source1> --source <source2> ...
  -t, --target stringArray        target technology to consider for analysis. Use multiple times for additional targets: --target <target1> --target <target2> ...

Transform

Transform has two subcommands:

1. openrewrite: This subcommand allows running one or more available OpenRewrite recipes on input source code.

2. rules: This subcommand allows converting Windup XML rules into the analyzer-lsp YAML format.

OpenRewrite

openrewrite subcommand allows running OpenRewrite recipes on source code.

To transform applications using OpenRewrite, run:

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

The value of --target option must be one of the available OpenRewrite recipes. To list all available recipes, run:

kantra transform --list-targets

All 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.

Rules

rules subcommand allows converting Windup XML rules to analyzer-lsp YAML rules using windup-shim

To convert Windup XML rules to the analyzer-lsp YAML format, run:

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

--input flag should point to a file or a directory containing XML rules, --output should point to an output directory for YAML rules.

All 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

Test

test subcommand allows running tests on YAML rules written for analyzer-lsp.

The input to test runner will be one or more test files and / or directories containing tests written in YAML.

kantra test /path/to/a/single/tests/file.test.yaml

The output of tests is printed on the console.

See different ways to run the test command in the test runner doc

References

• Example usage scenarios
• Test runner for YAML rules

Code of Conduct

Refer to Konveyor's Code of Conduct here.