Dekorate: Gerando manifests Kubernetes e OpenShift para projetos Java

O Dekorate, anteriormente conhecido como ap4k que significa annotation processors for Kubernetes, é projetado para tornar simples a geração de manifests para Kubernetes e OpenShift em projetos baseados em Java. O projeto foi renomeado já que o mesmo suporta a geração de manifests sem o uso de anotações, logo o nome ap4k não faz mais sentido para o projeto.

O Dekorate é uma coleção de geradores e decorators em tempo de compilação Java para manifests Kubernetes e OpenShift. Os desenvolvedores não precisam mais editar nenhum XML, JSON ou YAML para customizar os manifests.

Com o Dekorate os desenvolvedores podem gerar ou customizar manifests usando processamento de anotações, arquivos de propriedades de configuração (application.properties), ou ambos. O Dekorate suporta o Kubernetes, OpenShift, Knative, Tekton, Prometheus, Jaeger, Service Catalog, e Halkyon CRD. Além disso, o Dekorate integra com frameworks como o Spring Boot, Quarkus, Thorntail, e também fornece uma ferramenta para projetos Java genéricos que permite que qualquer projeto que use maven, gradle, sbt, e bazel gere os manifests.

Vamos explorar como o Dekorate se integra à uma aplicação Quarkus.

O Quarkus já possui uma extensão Kubernetes que internamente usa o Dekorate para gerar e customizar manifests para o Kubernetes, OpenShift e Knative. Essa extensão permite implantar uma aplicação Quarkus em um cluster Kubernetes aplicando os manifests gerados, ou mesmo criar uma imagem de container e enviar a mesma para um registry antes de implantar a aplicação.

Para adicionar a extensão, basta executar no terminal:

mvn quarkus:add-extension -Dextensions="io.quarkus:quarkus-kubernetes"

Após o término da compilação, os manifests gerados estarão disponíveis em: target/kubernetes/.

O arquivo kubernetes.json será parecido com:

{"apiVersion" : "v1","kind" : "ServiceAccount","metadata" : {"annotations" : {"app.quarkus.io/vcs-url" : "<>","app.quarkus.io/build-timestamp" : "2020-06-04 - 05:13:57 +0000","app.quarkus.io/commit-id" : "<>"},"labels" : {"app.kubernetes.io/name" : "decorate","app.kubernetes.io/version" : "1.0.0-SNAPSHOT"},"name" : "decorate"}}

Até o momento, essa extensão manipula coisas como portas e health checks, sem que seja necessário nenhuma configuração do usuário.

Para uma aplicação Spring Boot, existem dois starters disponíveis, io.dekorate:kubernetes-spring-starter:1.0.0 para o Kubernetes, e io.dekorate:openshift-spring-starter:1.0.0 para o OpenShift.

No Spring Boot, é possível ignorar as anotações fazendo uso de recursos já existentes no framework. Para customizar os manifests gerados, é possível adicionar propriedades do Dekorate no application.yml/application.properties, ou ainda usar anotações junto com o application.yml/application.properties. Por padrão, as configurações definidas nos arquivos de propriedades tem prioridade sobre as configurações definidas via annotation.

Abaixo temos a ordem de prioridade das configurações do Dekorate:

1. Annotations;

2. application.properties;

3. application.yaml;

4. application.yml;

5. application-kubernetes.properties;

6. application-kubernetes.yaml;

7. application-kubernetes.yml.

Para uma aplicação Thorntail, existem dois starters disponíveis, io.dekorate:kubernetes-thorntail-starter:jar:1.0.0 para o Kubernetes, e io.dekorate:openshift-thorntail-starter:jar:1.0.0 para o OpenShift.

A partir desses starters, é possível usar as anotações do Dekorate, tais como @KubernetesApplication, @OpenShiftApplication, etc.

Para gerar os manifests do Kubernetes para uma aplicação Java genérica, basta adicionar a dependência io.dekorate:kubernetes-annotations:jar:1.0.0 para o Kubernetes, e io.dekorate:openshit-annotations:jar:1.0.0 para o OpenShift.

Então adicionar a anotação @Dekorate, ou @KubernetesApplication, em uma das classes Java.

import io.dekorate.kubernetes.annotation.KubernetesApplication;
 
@KubernetesApplication
public class Main {public static void main(String[] args) {}}

Após a execução de mvn clean package os manifests estarão disponíveis sob target/classes/META-INF/dekorate.

O kubernetes.yml será parecido com:

apiVersion: "apps/v1"
kind: "Deployment"
metadata:
  name: "kubernetes-example"
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: "my-gradle-app"
      app.kubernetes.io/version: "1.0-SNAPSHOT"
  template:
    metadata:
      labels:
        app.kubernetes.io/name: "my-gradle-app"
        app.kubernetes.io/version: "1.0-SNAPSHOT"
    spec:
      containers:- env:- name: "KUBERNETES_NAMESPACE"
          valueFrom:
            fieldRef:
              fieldPath: "metadata.namespace"
        image: "default/my-gradle-app:1.0-SNAPSHOT"
        imagePullPolicy: "IfNotPresent"
        name: "my-gradle-app"

Para gerar os manifests do OpenShift para uma aplicação genérica Java, basta usar a anotação @Dekorate, ou @OpenshiftApplication, que funciona exatamente como a @KubernetesApplication, porém irá gerar o openshift.yml/openshift.json.

O Dekorate traz algumas funcionalidades adicionais além da geração de manifests. Essas funcionalidades incluem coisas como fazer o build, implantar, e testar.

O Dekorate permite que os usuários conectem ferramentas externas (por exemplo, docker ou oc) para acionar construções de imagem de container após o final da compilação, uma vez que o Dekorate não gera arquivos do Docker nem fornece suporte interno para executar construções do docker ou s2i.

Até o momento, como funcionalidade experimental temos o seguinte:

• docker build hook (requer o binário do docker, habilitado com -Ddekorate.build=true);

• docker push hook (requer o binário do docker, habilitado com -Ddekorate.push=true);

• OpenShift s2i build hook (requer o binário do oc, acionado com -Ddekorate.deploy=true).

O Dekorate também traz extensões JUnit 5 para o Kubernetes e Openshift, que permite que os desenvolvedores executem testes de ponta a ponta. Até esse momento as funcionalidades suportadas são condições de ambiente, builds de container, aplicar os manifest gerados em um ambiente específico, e injetar testes com a aplicação/pod cliente.

Maiores detalhes, tais como todas as opções de configuração e exemplos de código (Spring Boot, Thorntail, Vertx, Istio), podem ser encontradas no repositório do GitHub.