kantra

Kantra

Kantra est une CLI qui unifie les capacités d'analyse et de transformation de Konveyor. Il est disponible pour Linux, Mac et Windows.

Table des matières

• Conditions préalables
• Installation
• Configuration (pour Mac et Windows uniquement)
• Usage
  • Analyser une candidature
  • Transformer une application ou des règles XML
  • Tester les règles YAML
• Références
• Code de conduite

Conditions préalables

Podman 4+ est requis pour exécuter Kantra. Par défaut, il est configuré pour utiliser l'exécutable podman disponible sur l'hôte.

Bien que Kantra soit principalement testé avec podman, Docker Engine 24+ ou Docker Desktop 4+ peuvent être utilisés comme alternative. Pour utiliser Docker, définissez la variable d'environnement CONTAINER_TOOL pointant vers le chemin de l'exécutable Docker :

 export CONTAINER_TOOL=/usr/bin/docker

Installation

Pour installer Kantra, téléchargez l'exécutable pour votre plateforme et ajoutez-le au chemin.

Remarque : Pour Mac, vous pourriez recevoir un message d'erreur « Apple n'a pas pu vérifier ». Si vous le faites, vous pouvez exécuter xattr -d com.apple.quarantine kantra pour qu'Apple fasse confiance au binaire kantra .

Téléchargement de la version stable

Accédez à la page de publication et téléchargez le fichier zip contenant un binaire adapté à votre plateforme et à votre architecture. Décompressez l'archive et ajoutez l'exécutable qu'il contient au chemin.

Téléchargement de la version la plus récente/particulière

Le moyen le plus simple d'obtenir le dernier exécutable (ou un exécutable particulier/ancien) est de l'obtenir à partir de l'image du conteneur respectif.

Définissez la variable shell kantra_version sur une version particulière si vous souhaitez récupérer cette version, par exemple kantra_version=v0.4.0 .

Linux

Courir:

 ${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-download

Mac

Lorsque vous n'utilisez pas Docker for Desktop sur votre Mac (voir ci-dessus), vous devez démarrer une machine podman avant d'exécuter des commandes podman (voir Configuration pour Mac)

Une fois la machine démarrée, exécutez :

 ${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-download

Fenêtres

Lorsque vous n'utilisez pas Docker for Desktop sur votre Windows (voir ci-dessus), vous devez démarrer une machine podman avant d'exécuter des commandes podman (voir Configuration pour Windows)

Une fois la machine démarrée, exécutez :

 ${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-download

Assurez-vous d'ajouter l'exécutable au PATH .

Configuration (pour Mac et Windows uniquement)

Sous Mac et Windows, une machine podman doit être démarrée avant d'exécuter des commandes, sauf si vous utilisez Docker (pour Desktop) :

Mac

Avant de démarrer votre machine podman, exécutez :

 ulimit -n unlimited

Initiez votre machine podman :

• Podman 4 :

  Podman 4 nécessite que certains répertoires hôtes soient montés dans la VM :

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

• Podman 5 :

  Podman 5 monte les répertoires $HOME , /private/tmp et /var/folders par défaut, initialisez simplement la machine :

  podman machine init < vm_name >

Si les répertoires d'entrée et/ou de sortie que vous avez l'intention d'utiliser avec kantra se trouvent en dehors de l'arborescence des répertoires $HOME, /private/tmp et /var/folders, vous devez monter ces répertoires en plus de ceux par défaut.

Augmentez les ressources podman (une mémoire minimale de 4G est requise) :

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

Fenêtres

Initialisez la machine :

podman machine init < vm_name > 

Usage

Kantra a trois sous-commandes :

1. analyser : Cette sous-commande permet d'exécuter une analyse du code source sur le code source d'entrée ou un binaire.

2. transform : Cette sous-commande permet soit de convertir des règles XML en YAML, soit d'exécuter des recettes OpenRewrite sur le code source.

3. test : Cette sous-commande permet de tester les règles YAML.

Analyser

La sous-commande analyse permet d'exécuter le code source et l'analyse binaire à l'aide de analyser-lsp

Pour exécuter une analyse sur le code source de l'application, exécutez :

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

--input doit pointer vers un répertoire de code source ou un fichier binaire, --output doit pointer vers un répertoire contenant les résultats de l'analyse.

Tous les drapeaux :

--rules ... --skip-static-report do not generate static report -s, --source stringArray source technology to consider for analysis. Use multiple times for additional sources: --source --source ... -t, --target stringArray target technology to consider for analysis. Use multiple times for additional targets: --target --target ...">

 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  --rules  ...
      --skip-static-report               do not generate static report
  -s, --source stringArray               source technology to consider for analysis. Use multiple times for additional sources: --source  --source  ...
  -t, --target stringArray               target technology to consider for analysis. Use multiple times for additional targets: --target  --target  ...

Analyser plusieurs applications

De par sa conception, Kantra prend en charge l'analyse d'une seule application par exécution de commande Kantra. Cependant, il est possible d'utiliser l'option --bulk pour exécuter plusieurs commandes d'analyse kantra avec différentes applications afin d'obtenir un répertoire de sortie et un rapport statique rempli avec tous les rapports d'analyse des applications.

Exemple:

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 >

Transformer

Transform a deux sous-commandes :

1. openrewrite : Cette sous-commande permet d'exécuter une ou plusieurs recettes OpenRewrite disponibles sur le code source d'entrée.

2. Rules : Cette sous-commande permet de convertir les règles XML Windup au format YAML analyser-lsp.

OuvrirRéécriture

La sous-commande openrewrite permet d'exécuter des recettes OpenRewrite sur le code source.

Pour transformer des applications à l'aide d'OpenRewrite, exécutez :

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

La valeur de l'option --target doit être l'une des recettes OpenRewrite disponibles. Pour lister toutes les recettes disponibles, exécutez :

kantra transform --list-targets

Tous les drapeaux :

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.

Règles

La sous-commande Rules permet de convertir les règles XML Windup en règles YAML analyseur-lsp à l'aide de Windup-shim.

Pour convertir les règles XML Windup au format YAML analyseur-lsp, exécutez :

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

L'indicateur --input doit pointer vers un fichier ou un répertoire contenant des règles XML, --output doit pointer vers un répertoire de sortie pour les règles YAML.

Tous les drapeaux :

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

La sous-commande test permet d'exécuter des tests sur les règles YAML écrites pour analyser-lsp.

L’entrée du lanceur de tests sera un ou plusieurs fichiers de test et/ou répertoires contenant des tests écrits en YAML.

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

Le résultat des tests est imprimé sur la console.

Découvrez différentes manières d'exécuter la commande test dans la documentation du lanceur de tests

Références

• Exemples de scénarios d'utilisation
• Utiliser les options du fournisseur
• Exécuteur de tests pour les règles YAML

Code de conduite

Reportez-vous au code de conduite de Konveyor ici.