Skip to content

Overview

Dekorate is a collection of Java compile-time generators and decorators for Kubernetes/OpenShift manifests.

It makes generating Kubernetes manifests as easy as adding a dependency to the classpath and customizing as simple as setting an annotation or application property.

Stop wasting time editing xml, json and yml and customize the kubernetes manifests as you configure your java application.

Rebranding Notice

This project was originally called ap4k which stood for Annotation Processors for Kubernetes. As the project now supports decorating of kubernetes manifests without the use of annotations, the name ap4k no longer describes the project in the best possible way. So, the project has been renamed to dekorate.

Experimental features

  • Register hooks for triggering builds and deployment
  • Build hooks

Rationale

There are tons of tools out there for scaffolding / generating kubernetes manifests. Sooner or later these manifests will require customization. Handcrafting is not an appealing option. Using external tools, is often too generic. Using build tool extensions and adding configuration via xml, groovy etc is a step forward, but still not optimal.

Annotation processing has quite a few advantages over external tools or build tool extensions:

  • Configuration is validated by the compiler.
  • Leverages tools like the IDE for writing type safe config (checking, completion etc).
  • Works with all build tools.
  • Can "react" to annotations provided by the framework.

Hello World

This section provides examples on how to get started based on the framework you are using.

NOTE: All examples in README using the version that corresponds to the target branch. On github master that is the latest 2.x release.

Configuration externalization

It is often desired to externalize configuration in configuration files, instead of hard coding things inside annotations.

Dekorate provides the ability to externalize configuration to configuration files (properties or yml). This can be done to either override the configuration values provided by annotations, or to use dekorate without annotations.

For supported frameworks, this is done out of the box, as long as the corresponding framework jar is present. The frameworks supporting this feature are:

  • spring boot
  • thorntail

For these frameworks, the use of annotations is optional, as everything may be configured via configuration files. Each annotation may be expressed using properties or yaml using the following steps.

  • Each annotation property is expressed using a key/value pair.
  • All keys start with the dekorate.<annotation kind>. prefix, where annotation kind is the annotation class name in lowercase, stripped of the Application suffix.
  • The remaining part of key is the annotation property name.
  • For nesting properties the key is also nested following the previous rule.

For all other frameworks or generic java application this can be done with the use of the @Dekorate annotation. The presence of this annotation will trigger the dekorate processes. Dekorate will then look for application.properites or application.yml resources. If present, they will be loaded. If not the default configuration will be used.

Examples:

The following annotation configuration:

@KubernetesApplication(labels=@Label(key="foo", value="bar"))
public class Main {
}

Can be expressed using properties:

dekorate.kubernetes.labels[0].key=foo
dekorate.kubernetes.labels[0].value=bar

or using yaml:

dekorate:
  kubernetes:
    labels:
      - key: foo
        value: bar

In the examples above, dekorate is the prefix that we use to namespace the dekorate configuration. kubernetes defines the annotation kind (its @KubernetesApplication in lower case and stripped of the Application suffix). labels, key and value are the property names and since the Label is nested under @KubernetesApplication so are the properties.

The exact same example for OpenShift (where @OpenshiftApplication is used instead) would be:

@OpenshiftApplication(labels=@Label(key="foo", value="bar"))
public class Main {
}

Can be expressed using properties:

dekorate.openshift.labels[0].key=foo
dekorate.openshift.labels[0].value=bar

or using yaml:

dekorate:
  openshift:
    labels:
      - key: foo
        value: bar
Spring Boot

For spring boot, dekorate will look for configuration under:

  • application.properties
  • application.yml
  • application.yaml

Also, it will look for the same files under the kubernetes profile:

  • application-kubernetes.properties
  • application-kubernetes.yml
  • application-kubernetes.yaml
Vert.x & generic Java

For generic java, if the @Dekorate annotation is present, then dekorate will look for confiugration under:

  • application.properties
  • application.yml

These files can be overridden using the configFiles property on the @Dekorate annotation.

For example:

A generic java application annotated with @Dekorate:


    import io.dekorate.annotation.Dekorate;

    @Dekorate
    public class Main {
        //do stuff
    }

During compilation kubernetes, OpenShift or both resources will be generated (depending on what dekorate jars are present in the classpath). These resources can be customized using properties:

dekorate.openshift.labels[0].key=foo
dekorate.openshift.labels[0].value=bar

or using yaml:

dekorate:
  openshift:
    labels:
      - key: foo
        value: bar

Versions and Branches

The current version of dekorate is <version>2.0.0</version>.

What's changed in 2.x

Most of the changes that happend inside 2.x are internal and are related to the maintainance of the project.

New features

  • Configurable logging threshold
  • Git options
  • Inferring image configuration from application config
  • JaxRS support (without requiring Thorntail)
  • Integration testing framework improvements (detailed diagnostics on error)
  • Updated to kubernetes-client and model v5.1.1

Annotation naming

  • EnableDockerBuild -> DockerBuild
  • EnableS2iBuild -> S2iBuild
  • EnableJibBuild -> JibBuild

Dropped modules

The following features were dropped:

  • service catalog
  • halkyon
  • application crd
  • crd generator (functionality moved to the fabric8 kubernetes-client).
  • dependencies uberjar

Dropped dependencies shadowed uber jar

Earlier version of dekorate used a shadowed uberjar containing all dependencies. As of 2.0.0 the dependencies uberjar is no more. Downstream projects using dekorate as a library will need to switch from io.dekorate.deps.xxx to the original packages.

Component naming

Earlier version of dekorate used names for its core components that we too generic. So, in 2.0.0 the name changed so that they are more descriptive. Naming changes:

  • Generator -> ConfigGenerator
  • Hanlder -> ManifestGenerator

Branches

All dekorate development takes place on the master branch. From that branch current releases are created. Bug fixes for older releases are done through their correspnding branch.

  • master (active development, pull requests should point here)
  • 1.0.x
  • 0.15.x

Pull request guidelines

All pull requests should target the master branch and from there things are backported to where it makes sense.

Frequently asked questions

How do I tell dekorate to use a custom image name?

By default the image name used is ${group}/${name}:${version} as extracted by the project / environment or explicitly configured by the user. If you don't want to tinker those properties then you can:

Using annotations

Add @DockerBuild(image="foo/bar:baz") to the your main or whatever class you use to configure dekorate. If instead of docker you are using jib or s2i you can use @JibBuild(image="foo/bar:baz") or @S2iBuild(image="foo/bar:baz") respectively.

Using annotations

Add the following to your application.properties

dekorate.docker.image=foo/bar:baz

Using annotations

Add the following to your application.yaml

dekorate:
  docker:
    image: foo/bar:baz

Want to get involved?

By all means please do! We love contributions! Docs, Bug fixes, New features ... everything is important!

Make sure you take a look at contributor guidelines. Also, it can be useful to have a look at the dekorate design.