kantra
v0.5.3
Kantra is a CLI that unifies analysis and transformation capabilities of Konveyor. It is available for Linux, Mac and Windows.
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
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 CONTAINER_TOOL pointing to the docker executable's path:
export CONTAINER_TOOL=/usr/bin/docker
To install kantra, download the executable for your platform and add it to the path.
Note: For Mac you might get a "Apple could not verify" error message. If you do you can run xattr -d com.apple.quarantine kantra to have Apple trust the kantra binary.
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.
The easiest way to get the latest (or a particular/older) executable is to get it from the respective container image.
Set the shell variable kantra_version to a particular version if you want to grab that version,
e.g., kantra_version=v0.4.0.
Run:
${CONTAINER_TOOL:-podman} cp $(${CONTAINER_TOOL:-podman} create --name kantra-download quay.io/konveyor/kantra:${kantra_version:-latest}):/usr/local/bin/kantra . && ${CONTAINER_TOOL:-podman} rm kantra-downloadWhen you are not using Docker for Desktop on your Mac (see above), you need to start a podman machine prior to running any podman commands (see Setup for Mac)
Once a machine is started, run:
${CONTAINER_TOOL:-podman} cp $(${CONTAINER_TOOL:-podman} create --name kantra-download quay.io/konveyor/kantra:${kantra_version:-latest}):/usr/local/bin/darwin-kantra . && ${CONTAINER_TOOL:-podman} rm kantra-downloadWhen you are not using Docker for Desktop on your Windows (see above), you need to start a podman machine prior to running any podman commands (see Setup for Windows)
Once a machine is started, run:
${CONTAINER_TOOL:-podman} cp $(${CONTAINER_TOOL:-podman} create --name kantra-download quay.io/konveyor/kantra:${kantra_version:-latest}):/usr/local/bin/windows-kantra . && ${CONTAINER_TOOL:-podman} rm kantra-downloadEnsure that you add the executable to the
PATH.
On Mac and Windows, a podman machine needs to be started prior to running any commands, unless you are using Docker (for Desktop):
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
Init the machine:
podman machine init <vm_name>
Kantra has three subcommands:
analyze: This subcommand allows running source code analysis on input source code or a binary.
transform: This subcommand allows either converting XML rules to YAML or running OpenRewrite recipes on source code.
test: This subcommand allows testing YAML rules.
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 --bulk running multiple analyze commands in bulk will result to combined static report --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. ex: (!package=io.konveyor.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 -l, --label-selector string run rules based on specified label selector expression --list-sources list rules for available migration sources --list-targets list rules for available migration targets --maven-settings string path to a custom maven settings file to use -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. 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> ...
By design, kantra supports single application analysis per kantra command execution. However, it is possible use --bulk option for executing multiple kantra analyze commands with different applications to get an output directory and static-report populated with all applications analysis reports.
Example:
kantra analyze --bulk --input=<path/to/source/A> --output=<path/to/output/ABC>kantra analyze --bulk --input=<path/to/source/B> --output=<path/to/output/ABC>kantra analyze --bulk --input=<path/to/source/C> --output=<path/to/output/ABC>
Transform has two subcommands:
openrewrite: This subcommand allows running one or more available OpenRewrite recipes on input source code.
rules: This subcommand allows converting Windup XML rules into the analyzer-lsp YAML format.
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 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 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
Example usage scenarios
Using provider options
Test runner for YAML rules
Refer to Konveyor's Code of Conduct here.
