Kantra

Cantra

Kantra é uma CLI que unifica os recursos de análise e transformação do Konveyor. Está disponível para Linux, Mac e Windows.

Índice

• Pré-requisitos
• Instalação
• Configuração (somente para Mac e Windows)
• Uso
  • Analisar um aplicativo
  • Transformar um aplicativo ou regras XML
  • Testar regras YAML
• Referências
• Código de Conduta

Pré-requisitos

Podman 4+ é necessário para executar o kantra. Por padrão, ele está configurado para usar o executável podman disponível no host.

Embora o kantra seja testado principalmente com o podman, o Docker Engine 24+ ou o Docker Desktop 4+ podem ser usados ​​como alternativa. Para usar o docker, defina a variável de ambiente CONTAINER_TOOL apontando para o caminho do executável do docker:

 export CONTAINER_TOOL=/usr/bin/docker

Instalação

Para instalar o kantra, baixe o executável para sua plataforma e adicione-o ao caminho.

Observação: no Mac, você pode receber uma mensagem de erro "A Apple não conseguiu verificar". Se fizer isso, você pode executar xattr -d com.apple.quarantine kantra para que a Apple confie no binário kantra .

Baixando a versão estável

Vá para a página de lançamento e baixe o arquivo zip contendo um binário para sua plataforma e arquitetura. Descompacte o arquivo e adicione o executável ao caminho.

Baixando a versão mais recente/específica

A maneira mais fácil de obter o executável mais recente (ou específico/mais antigo) é obtê-lo na respectiva imagem do contêiner.

Defina a variável shell kantra_version para uma versão específica se você quiser obter essa versão, por exemplo, kantra_version=v0.4.0 .

Linux

Correr:

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

Quando não estiver usando o Docker for Desktop em seu Mac (veja acima), você precisará iniciar uma máquina podman antes de executar qualquer comando podman (consulte Configuração para Mac)

Depois que uma máquina for iniciada, execute:

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

Windows

Quando não estiver usando o Docker for Desktop no Windows (veja acima), você precisará iniciar uma máquina podman antes de executar qualquer comando podman (consulte Configuração para Windows)

Depois que uma máquina for iniciada, execute:

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

Certifique-se de adicionar o executável ao PATH .

Configuração (somente para Mac e Windows)

No Mac e no Windows, uma máquina podman precisa ser iniciada antes de executar qualquer comando, a menos que você esteja usando o Docker (para Desktop):

Mac

Antes de iniciar sua máquina podman, execute:

 ulimit -n unlimited

Inicie sua máquina podman:

• Podman 4 :

  O Podman 4 requer que alguns diretórios de host sejam montados na VM:

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

• Podman 5 :

  O Podman 5 monta os diretórios $HOME , /private/tmp e /var/folders por padrão, basta iniciar a máquina:

  podman machine init < vm_name >

Se os diretórios de entrada e/ou saída que você pretende usar com o kantra estiverem fora da árvore dos diretórios $HOME, /private/tmp e /var/folders, você deverá montar esses diretórios além do padrão.

Aumente os recursos do podman (é necessária memória mínima de 4G):

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

Windows

Inicie a máquina:

podman machine init < vm_name > 

Uso

Kantra tem três subcomandos:

1. analisar : Este subcomando permite executar a análise do código-fonte no código-fonte de entrada ou em um binário.

2. transform : Este subcomando permite converter regras XML em YAML ou executar receitas OpenRewrite no código-fonte.

3. test : este subcomando permite testar regras YAML.

Analisar

O subcomando analyze permite executar código-fonte e análise binária usando analyzer-lsp

Para executar a análise no código-fonte do aplicativo, execute:

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

--input deve apontar para um diretório de código-fonte ou arquivo binário, --output deve apontar para um diretório para conter os resultados da análise.

Todas as bandeiras:

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

Analise vários aplicativos

Por design, o kantra oferece suporte à análise de aplicativo único por execução de comando do kantra. No entanto, é possível usar a opção --bulk para executar vários comandos de análise do kantra com diferentes aplicativos para obter um diretório de saída e um relatório estático preenchido com todos os relatórios de análise de aplicativos.

Exemplo:

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 >

Transformar

Transform tem dois subcomandos:

1. openrewrite : Este subcomando permite executar uma ou mais receitas OpenRewrite disponíveis no código-fonte de entrada.

2. regras : este subcomando permite converter regras Windup XML no formato YAML analyzer-lsp.

AbrirReescrever

O subcomando openrewrite permite executar receitas OpenRewrite no código-fonte.

Para transformar aplicativos usando OpenRewrite, execute:

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

O valor da opção --target deve ser uma das receitas OpenRewrite disponíveis. Para listar todas as receitas disponíveis, execute:

kantra transform --list-targets

Todas as bandeiras:

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.

Regras

O subcomando regras permite converter regras Windup XML em regras YAML do analisador-lsp usando windup-shim

Para converter regras Windup XML para o formato YAML analyzer-lsp, execute:

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

O sinalizador --input deve apontar para um arquivo ou diretório contendo regras XML, --output deve apontar para um diretório de saída para regras YAML.

Todas as bandeiras:

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

Teste

O subcomando test permite executar testes em regras YAML escritas para analyzer-lsp.

A entrada para o executor de teste será um ou mais arquivos de teste e/ou diretórios contendo testes escritos em YAML.

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

A saída dos testes é impressa no console.

Veja diferentes maneiras de executar o comando de teste no documento do executor de testes

Referências

• Exemplos de cenários de uso
• Usando opções de provedor
• Executor de testes para regras YAML

Código de Conduta

Consulte o Código de Conduta do Konveyor aqui.