Criando um executável nativo

Version 22.3 is required. Using the community edition is enough.

On Linux it’s possible to package a native executable that doesn’t depend on any system shared library. There are some system requirements to be fulfilled and additional build arguments to be used along with the native-image invocation, a minimum is -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.

You can override the profile the executable runs with during the test using the quarkus.test.native-image-profile property. Either by adding it to application.properties or by appending it to the command line: ./mvnw verify -Pnative -Dquarkus.test.native-image-profile=test. Your %test. prefixed properties will be used at the test runtime.

You can override the profile the executable is built with and runs with using the quarkus-profile=test property, e.g. ./mvnw clean verify -Pnative -Dquarkus-profile=test. This might come handy if there are test specific resources to be processed, such as importing test data into the database.

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.

It is also possible to re-run the tests against a native executable that has already been built. To do this run ./mvnw test-compile failsafe:integration-test -Pnative. This will discover the existing native image and run the tests against it using 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 quarkus.package.type=native-sources. This will execute the java compilation as if you had started native compilation (-Pnative), 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:

From the output above one can see that, in addition to the produced jar file and the associated lib directory, a text file named native-image.args was created. This file holds all parameters (including the name of the JAR to compile) to pass along to GraalVM’s native-image command. If you have GraalVM installed, you can start the native compilation by executing:

O processo para o Gradle é análogo.

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

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.