Criando um Executável Nativo

A criação de um executável nativo requer o uso de uma distribuição do GraalVM. Há três distribuições: Oracle GraalVM Community Edition (CE), Oracle GraalVM Enterprise Edition (EE) e Mandrel. As diferenças entre as distribuições Oracle e Mandrel são as seguintes:

GraalVM for JDK 21 é necessário.

No Linux, é possível empacotar um executável nativo que não dependa de nenhuma biblioteca compartilhada do sistema. Há alguns requisitos de sistema a serem atendidos e argumentos de construção adicionais a serem usados junto com a invocação native-image ; o mínimo é -Dquarkus.native.additional-build-args="--static","--libc=musl" .

A compilação de binários totalmente estáticos é feita através de um link estático com o musl em vez de glibc e não deve ser usada em produção sem testes rigorosos.

Por padrão, os testes de integração build e run são feitos usando o profile prod.

Você pode substituir o perfil com o qual o executável roda durante o teste usando a propriedade quarkus.test.native-image-profile . Adicione-a a application.properties ou acrescente-a à linha de comando: ./mvnw verify -Dnative -Dquarkus.test.native-image-profile=test . Suas propriedades prefixadas com %test. serão usadas no tempo de execução do teste.

Você pode substituir o perfil com o qual o executável é construído e rodado usando a propriedade quarkus.profile=test , por exemplo, ./mvnw clean verify -Dnative -Dquarkus.profile=test . Isso pode ser útil se houver recursos específicos de teste a serem processados, como a importação de dados de teste para o banco de dados.

Com o exemplo mencionado acima em seu application.properties , o banco de dados gerenciado do Hibernate ORM será preenchido com dados de teste durante a execução do teste no modo JVM e durante a execução do teste no modo nativo. O executável de produção conterá apenas o recurso version.txt , sem dados de teste supérfluos.

Ao executar testes dessa forma, as únicas coisas que realmente são executadas nativamente são os endpoints da aplicação, que só podem ser testados por meio de chamadas HTTP. Seu código de teste não é realmente executado nativamente, portanto, se você estiver testando um código que não chama seus endpoints HTTP, provavelmente não é uma boa ideia executá-los como parte dos testes nativos.

Se você compartilhar sua classe de teste entre a JVM e as execuções nativas, como aconselhamos acima, poderá marcar determinados testes com a anotação @DisabledOnIntegrationTest para ignorá-los ao testar uma imagem nativa.

Também é possível executar novamente os testes em um executável nativo que já tenha sido criado. Para fazer isso, execute ./mvnw test-compile failsafe:integration-test -Dnative . Isso descobrirá a imagem nativa existente e executará os testes com base nela usando o failsafe.

Se o processo não conseguir encontrar a imagem nativa por algum motivo ou se você quiser testar uma imagem nativa que não esteja mais no diretório de destino, poderá especificar o executável com a propriedade de sistema -Dnative.image.path= .

A maneira mais fácil de criar uma container-image a partir da sua aplicação Quarkus é utilizar uma das extensões de imagem de contêiner.

Se uma dessas extensões estiverem presente, então a criação de uma imagem de contêiner para o executável nativo é executar um único comando:

Consulte o Guia do container-image para obter mais informações.

É possível executar a aplicação em um contêiner usando o JAR produzido pelo Quarkus Maven Plugin. No entanto, nesta seção, vamos nos concentrar na criação de uma imagem de contêiner usando o executável nativo produzido.

When using a local GraalVM installation, the native executable targets your local operating system (Linux, macOS, Windows etc). However, as a container may not use the same executable format as the one produced by your operating system, we will instruct the Maven build to produce an executable by leveraging a container runtime (as described in this section):

O executável produzido será um executável Linux de 64 bits, portanto, dependendo do seu sistema operacional, ele pode não ser mais executável. No entanto, isso não é um problema, pois vamos copiá-lo para um contêiner. A geração do projeto forneceu um Dockerfile.native-micro no diretório src/main/docker com o seguinte conteúdo:

Depois, se não tiver deletado o executável nativo criado, pode construir a imagem docker com:

E, finalmente, execute-o com:

A geração do projeto também forneceu um Dockerfile.native na pasta src/main/docker com o seguinte conteúdo:

A imagem mínima da UBI é maior do que a micro mencionada acima. Ela contém mais utilitários, como o gerenciador de pacotes microdnf .

A seção anterior mostrou como criar um executável nativo usando o Maven ou o Gradle, mas isso exige que o executável nativo tenha sido criado primeiro. Além disso, esse executável nativo deve ser um executável Linux de 64 bits.

Talvez você queira criar o executável nativo diretamente em um contêiner sem ter um contêiner final que contenha as ferramentas de criação. Essa abordagem é possível com uma compilação do Docker em vários estágios:

Esta construção em vários estágios pode ser realizada da seguinte forma:

Exemplo de Dockerfile para fazer o build com o Maven:

Salve esse arquivo em src/main/docker/Dockerfile.multistage, uma vez que não está incluído no startup rápido.

Exemplo de Dockerfile para build com o Gradle:

Se estiver utilizando o Gradle no seu projeto, pode utilizar este exemplo de Dockerfile. Salve-o em src/main/docker/Dockerfile.multistage.

E, finalmente, execute-o com:

Se estiver procurando por imagens de contêineres pequenas, a abordagem sem distribuição reduz o tamanho da camada base. A ideia por trás do sem distribuição é o uso de uma imagem base única e mínima que contenha todos os requisitos e, às vezes, até a própria aplicação.

O Quarkus fornece uma imagem base sem distribuição que você pode usar no seu Dockerfile . Você só precisa copiar sua aplicação e pronto:

O Quarkus fornece a imagem quay.io/quarkus/quarkus-distroless-image:2.0 . Ela contém os pacotes necessários para rodar um executável nativo e tem apenas 9 Mb. Basta adicionar sua aplicação sobre essa imagem e você obterá uma imagem de contêiner minúscula.

As imagens sem distribuição não devem ser utilizadas em produção sem um teste rigoroso.

O build de binários totalmente linkados estaticamente permite a utilização de uma imagem de rascunho contendo apenas o executável nativo resultante.

Exemplo de Dockerfile de vários estágios para criar uma imagem a partir de scratch:

As imagens Scratch não devem ser utilizadas em produção sem um teste rigoroso.

O Quarkus pode compactar o executável nativo produzido usando UPX. Mais detalhes na documentação de Compressão UPX .

In certain circumstances, you may want to build the native image in a separate step. For example, in a CI/CD pipeline, you may want to have one step to generate the source that will be used for the native image generation and another step to use these sources to actually build the native executable. For this use case, you can set the additional flag quarkus.native.sources-only=true. This will execute the java compilation as if you had started native compilation (-Dnative), but stops before triggering the actual call to GraalVM’s native-image.

Após finalizar a compilação, você encontrará o artefato compilado em target/native-sources:

Na saída acima, é possível ver que, além do arquivo jar produzido e do diretório lib associado, foi criado um arquivo de texto chamado native-image.args . Esse arquivo contém todos os parâmetros (inclusive o nome do JAR a ser compilado) a serem transmitidos ao comando native-image do GraalVM. Um arquivo de texto chamado graalvm.version também foi criado e contém a versão do GraalVM que deve ser usada. Se o GraalVM estiver instalado e corresponder a essa versão, você poderá iniciar a compilação nativa executando:

O processo para o Gradle é análogo.

Também é possível executar o processo de compilação num contêiner:

-Dquarkus.native.container-build=true produzirá um arquivo de texto adicional chamado native-builder.image com o nome da imagem docker a ser utilizada para construir a imagem nativa.

Uma visão geral de alto nível do que seriam as várias etapas de um pipeline CI/CD é a seguinte:

O ambiente que executa o passo 1 apenas necessita do Java e Maven (ou Gradle) instalados, enquanto o ambiente que executa o passo 3 apenas necessita de uma instalação GraalVM (incluindo a funcionalidade native-image ).

Dependendo do resultado final desejado do pipeline CI/CD, o binário gerado pode então ser utilizado para criar uma imagem de contêiner.