fabric8io/fabric8-maven-plugin

This minimal but full working example pom.xml shows how a simple spring boot application can be dockerized and prepared for Kubernetes and OpenShift. The full example can be found in directory samples/zero-config.

This setup make some opinionated decisions for you:

These choices can be influenced by configuration options as decribed in Spring Boot Generator.

To start the Docker image build, you simply run

This will create the Docker image against a running Docker daemon (which must be accessible either via Unix Socket or with the URL set in DOCKER_HOST). Alternatively, when connected to an OpenShift cluster (or using the openshift mode explicitly), then a Docker build will be performed on OpenShift which at the end creates an ImageStream.

To deploy the resources to the cluster call

By default a Service and a Deployment object pointing to the created Docker image is created. When running in OpenShift mode, a Service and DeploymentConfig which refers the ImageStream created with fabric8:build will be installed.

Of course you can bind all those fabric8-goals to execution phases as well, so that they are called along with standard lifecycle goals like install. For example, to bind the building of the Kubernetes resource files and the Docker images, add the following goals to the execution of the f-m-p:

If you’d also like to automatically deploy to Kubernetes each time you do a mvn install you can add the deploy goal:

Although the Zero-config mode and its generators can be tweaked with options up to a certain degree, many cases require more flexibility. For such instances, an XML-based plugin configuration can be used, in a way similar to the XML configuration used by docker-maven-plugin.

The plugin configuration can be roughly divided into the following sections:

A working example can be found in the samples/xml-config directory. An extract of the plugin configuration is shown below:

The XML resource configuration is based on plain Kubernetes resource objects. When targeting OpenShift, Kubernetes resource descriptors will be automatically converted to their OpenShift counterparts, e.g. a Kubernetes Deployment will be converted to an OpenShift DeploymentConfig.

The third configuration option is to use an external configuration in form of YAML resource descriptors which are located in the src/main/fabric8 directory. Each resource get its own file, which contains a skeleton of a resource descriptor. The plugin will pick up the resource, enrich it and then combine all to a single kubernetes.yml and openshift.yml file. Within these descriptor files you are can freely use any Kubernetes feature.

Note: In order to support simultaneously both OpenShift and Kubernetes, there is currently no way to specify OpenShift-only features this way, though this might change in future releases.

Let’s have a look at an example from samples/external-resources. This is a plain Spring Boot application, whose images are auto generated like in the Zero-Config case. The resource fragments are in src/main/fabric8.

As you can see, there is no metadata section as would be expected for Kubernetes resources because it will be automatically added by the fabric8-maven-plugin. The object’s Kind, if not given, is automatically derived from the filename. In this case, the fabric8-maven-plugin will create a Deployment because the file is called deployment.yml. Similar mappings between file names and resource type exist for each supported resource kind, the complete list of which (along with associated abbreviations) can be found in the Appendix.

Additionally, if you name your fragment using a name prefix followed by a dash and the mapped file name, the plugin will automatically use that name for your resource. So, for example, if you name your deployment fragment myapp-deployment.yml, the plugin will name your resource myapp. In the absence of such provided name for your resource, a name will be automatically derived from your project’s metadata (in particular, its artifactId as specified in your POM).

No image is also referenced in this example because the plugin also fills in the image details based on the configured image you are building with (either from a generator or from a dedicated image plugin configuration, as seen before).

Enrichment of resource fragments can be fine-tuned by using profile sub-directories. For more details see Profiles.

Now that we have seen some examples for the various ways how this plugin can be used, the following sections will describe the plugin goals and extension points in detail.

Labels and annotations can be easily added to any resource object. This is best explained by an example.

Labels and annotations can be specified in free form as a map. In this map the element name is the name of the label or annotation respectively, whereas the content is the value to set.

The following subelements are possible for <labels> and <annotations> :

Once you’ve configured some docker registry credentials into ~/.m2/setting.xml, as explained in the Authentication section, you can create Kubernetes secrets from a server declaration.

XML configuration

You can create a secret using xml configuration in the pom.xml file. It should contain the following fields:

This is best explained by an example.

Yaml fragment with annotation

You can create a secret using a yaml fragment. You can reference the docker server id with an annotation maven.fabric8.io/dockerServerId. The yaml fragment file should be put under the src/main/fabric8/ folder.

Resource goal also validates the generated resource descriptors using API specification of Kubernetes and OpenShift.

When the fabric8:resource goal is run, an OpenShift Route descriptor (route.yml) will also be generated along the service if an OpenShift cluster is targeted. If you do not want to generate a Route descriptor, you can set the fabric8.openshift.generateRoute property to false.

If you do not want to generate a Route descriptor, you can also specify so in the plugin configuration in your POM as seen below.

If you are using resource fragments, then also you can configure it in your Service resource fragment (e.g. service.yml). You need to add an expose label to the metadata section of your service and set it to false.

In case both the label and the property have been set with conflicting values, precedence will be given to the property value, so if you set the label to true but set the property to false then no Route descriptor will be generated because precedence will be given to the property value.

If the mode is set to kubernetes then a normal Docker build or Dockerless JIB is performed. The connection configuration to access the Docker daemon is described in Access Configuration.

For automatic push to registry, conventions for target image configuration should be followed:-

where ${image.user} should be replaced with registry username.

Currently, Apart from Java 8, base images for Java 11 are supported for Kubernetes build. To enable Java 11 base images, user needs to specift release version 11 in their maven-compiler-plugin configuration in their project pom.

Refer to the spring-boot-with-yaml sample for a demo.

For the openshift mode, OpenShift specific builds will be performed. These are so called Binary Source builds ("binary builds" in short), where the data specified with the build configuration is sent directly to OpenShift as a binary archive.

There are two kind of binary builds supported by this plugin, which can be selected with the buildStrategy configuration option (fabric8.build.strategy property)

Both build strategies update an Image Stream after the image creation.

The Build Config and Image streams can be managed by this plugin. If they do not exist, they will be automatically created by fabric8:build. If they do already exist, they are reused, except when the buildRecreate configuration option (property fabric8.build.recreate) is set to a value as described in Configuration. Also if the provided build strategy is different than the one defined in the existing build configuration, the Build Config is edited to reflect the new type (which in turn removes all build associated with the previous build).

If you want to configure memory/cpu requests and limits related to BuildConfig, you can either provide them as in plugin configuration or as a resource fragment in src/main/fabric8 directory. for XML configuration it needs to be done like this:

This image stream created can then be directly referenced from Deployment Configuration objects created by fabric8:resource. By default, image streams are created with a local lookup policy, so that they can be used also by other resources such as Deployments or StatefulSets. This behavior can be turned off by setting the fabric8.s2i.imageStreamLookupPolicyLocal property to false when building the project.

In order to be able to to create these OpenShift resource objects access to an OpenShift installation is required. The access parameters are described in Access Configuration.

Regardless of which build mode is used, the images are configured in the same way.

The configuration consists of two parts: * a global section which defines the overall behaviour of this plugin * and an <images> section which defines how the images should be build

Many of the options below are relevant for the Kubernetes Workflow or the OpenShift Workflow with Docker builds as they influence how the Docker image is build.

For an S2I binary build, on the other hand, the most relevant section is the Assembly one because the build depends on which buider/base image is used and how it interprets the content of the uploaded docker.tar.

The following sections describe the usual configuration, which is similar to the build configuration used in the docker-maven-plugin.

In addition a more automatic way for creating predefined build configuration can be performed with so called Generators. Generators are very flexible and can be easily created. These are described in an extra section.

Global configuration parameters specify overall behavior common for all images to build. Some of the configuration options are shared with other goals.

You can configure parameters to define how Fabric8 is going to connect to Kubernetes/OpenShift cluster instead of relaying on default parameters.

The configuration how images should be created a defined in a dedicated <images> sections. These are specified for each image within the <images> element of the configuration with one <image> element per image to use.

The <image> element can contain the following sub elements:

The <build> section is mandatory and is explained in below.

There are two different modes how images can be built:

With an inline plugin configuration all information required to build the image is contained in the plugin configuration. By default its the standard XML based configuration for the plugin but can be switched to a property based configuration syntax as described in the section External configuration. The XML configuration syntax is recommended because of its more structured and typed nature.

When using this mode, the Dockerfile is created on the fly with all instructions extracted from the configuration given.

Alternatively an external Dockerfile template or Docker archive can be used. This mode is switched on by using one of these three configuration options within

All paths can be either absolute or relative paths (except when both dockerFileDir and dockerFile are provided in which case dockerFile must not be absolute). A relative path is looked up in ${project.basedir}/src/main/docker by default. You can make it easily an absolute path by using ${project.basedir} in your configuration.

Any additional files located in the dockerFileDir directory will also be added to the build context as well. You can also use an assembly if specified in an assembly configuration. However, you need to add the files on your own in the Dockerfile with an ADD or COPY command. The files of the assembly are stored in a build context relative directory maven/ but can be changed by changing the assembly name with the option <name> in the assembly configuration.

E.g. the files can be added with

so that the assembly files will end up in /my/target/directory within the container.

If this directory contains a .maven-dockerignore (or alternatively, a .maven-dockerexclude file), then it is used for excluding files for the build. Each line in this file is treated as a FileSet exclude pattern as used by the maven-assembly-plugin. It is similar to .dockerignore when using Docker but has a slightly different syntax (hence the different name). Example .maven-dockerexclude or .maven-dockerignore is an example which excludes all compiled Java classes.

If this directory contains a .maven-dockerinclude file, then it is used for including only those files for the build. Each line in this file is also treated as a FileSet exclude pattern as used by the maven-assembly-plugin. Example .maven-dockerinclude shows how to include only jar file that have build to the Docker build context.

Except for the assembly configuration all other configuration options are ignored for now.

When only a single image should be built with a Dockerfile no XML configuration is needed at all. All what need to be done is to place a Dockerfile into the top-level module directory, alongside to pom.xml. You can still configure global aspects in the plugin configuration, but as soon as you add an <image> in the XML configuration, you need to configure also the build explicitly.

The image name is by default set from the Maven coordinates (%g/%a:%l, see Image Name for an explanation of the params which are essentially the Maven GAV) This name can be set with the property docker.name.

If you want to add some <run> configuration to this image for starting it with docker:run then you can add an image configuration but without a <build> section in which case the Dockerfile will be picked up, too. This works only for a single image, though.

fabric8-maven-plugin filters given Dockerfile with Maven properties, much like the maven-resource-plugin does. Filtering is enabled by default and can be switched off with a build config <filter>false</filter>. Properties which we want to replace are specified with the ${..} syntax. Replacement includes Maven project properties such as ${project.artifactId}, properties set in the build, command-line properties, and system properties. Unresolved properties remain untouched.

This partial replacement means that you can easily mix it with Docker build arguments and environment variable reference, but you need to be careful. If you want to be more explicit about the property delimiter to clearly separate Docker properties and Maven properties you can redefine the delimiter. In general, the filter option can be specified the same way as delimiters in the resource plugin. In particular, if this configuration contains a * then the parts left, and right of the asterisks are used as delimiters.

For example, the default <filter>${*}</filter> parse Maven properties in the format that we know. If you specify a single character for <filter> then this delimiter is taken for both, the start and the end. E.g a <filter>@</filter> triggers on parameters in the format @…​@, much like in the maven-invoker-plugin. Use something like this if you want to clearly separate from Docker builds args. This form of property replacement works for Dockerfile only. For replacing other data in other files targeted for the Docker image, please use the maven-resource-plugin or an assembly configuration with filtering to make them available in the docker build context.

The following example uses a Dockerfile in the directory src/main/docker/demo and replaces all properties in the format @property@ within the Dockerfile.

This plugin supports so call dmp-plugins which are used during the build phase. dmp-plugins are enabled by just declaring a dependency in the plugin declaration:

These plugins contain a descriptor META-INF/maven/io.fabric8/dmp-plugin with class names, line-by-line:

During a build with docker:build, those classes are loaded and certain fixed method are called.

The following methods are supported:

If a configured plugin does not provide method of this name and signature, then it will be simply ignored. Also, no interface needs to be implemented to keep the coupling low.

The following official dmp-plugins are known and supported:

Check out samples/run-java for a fully working example.

All build relevant configuration is contained in the <build> section of an image configuration. The following configuration options are supported:

From this configuration this Plugin creates an in-memory Dockerfile, copies over the assembled files and calls the Docker daemon via its remote API.

In order to see the individual build steps you can switch on verbose mode either by setting the property docker.verbose or by using <verbose>true</verbose> in the Global configuration

The <assembly> element within <build> is has an XML struture and defines how build artifacts and other files can enter the Docker image.

In the event you do not need to include any artifacts with the image, you may safely omit this element from the configuration.

When creating a container one or more environment variables can be set via configuration with the env parameter

If you put this configuration into profiles you can easily create various test variants with a single image (e.g. by switching the JDK or whatever).

It is also possible to set the environment variables from the outside of the plugin’s configuration with the parameter envPropertyFile. If given, this property file is used to set the environment variables where the keys and values specify the environment variable. Environment variables specified in this file override any environment variables specified in the configuration.

Labels can be set inline the same way as environment variables:

Using entryPoint and cmd it is possible to specify the entry point or cmd for a container.

The difference is, that an entrypoint is the command that always be executed, with the cmd as argument. If no entryPoint is provided, it defaults to /bin/sh -c so any cmd given is executed with a shell. The arguments given to docker run are always given as arguments to the entrypoint, overriding any given cmd option. On the other hand if no extra arguments are given to docker run the default cmd is used as argument to entrypoint.

An entry point or command can be specified in two alternative formats:

Either shell or params should be specified.

or

This can be formulated also more dense with:

or

As described in section Configuration for external Dockerfiles Docker build arg can be used. In addition to the configuration within the plugin configuration you can also use properties to specify them:

Please note that the system property setting will always override the project property. Also note that for all properties which are not Docker predefined properties, the external Dockerfile must contain an ARGS instruction.

By default the fabric8:debug goal has to edit your Deployment to enable debugging then wait for a pod to start. It might be in development you frequently want to debug things and want to speed things up a bit.

If so you can enable debug mode for each build via the fabric8.debug.enabled property.

e.g. you can pass this property on the command line:

Or you can add something like this to your ~/.m2/settings.xml file so that you enable debug mode for all maven builds on your laptop by using a profile :

Then whenever you type the fabric8:debug goal there is no need for the maven goal to edit the Deployment and wait for a pod to restart; we can immediately start debugging when you type:

The fabric8:debug goal allows to attach a remote debugger to a running container, but the application is free to execute when the debugger is not attached. In some cases, you may want to have complete control on the execution, e.g. to investigate the application behavior at startup. This can be done using the fabric8.debug.suspend flag:

The suspend flag will set the JAVA_DEBUG_SUSPEND environment variable to true and JAVA_DEBUG_SESSION to a random number in your deployment. When the JAVA_DEBUG_SUSPEND environment variable is set, standard docker images will use suspend=y in the JVM startup options for debugging.

The JAVA_DEBUG_SESSION environment variable is always set to a random number (each time you run the debug goal with the suspend flag) in order to tell Kubernetes to restart the pod. The remote application will start only after a remote debugger is attached. You can use the remote debugging feature of your IDE to connect (on localhost, port 5005 by default).

This watcher is enabled by default for all Spring Boot projects. It performs the following actions:

You can try it on any spring boot application via:

Once the goal starts up the spring boot RemoteSpringApplication it will watch for local development changes.

e.g. if you edit the java code of your app and then build it via something like this:

You should see your app reload on the fly in the shell running the fabric8:watch goal!

There is also support for LiveReload as well.

This is a generic watcher that can be used in Kubernetes mode only. Once activated, it listens for changes in the project workspace in order to trigger a redeploy of the application.

The watcher can be activated e.g. by running this command in another shell:

The watcher will detect that the binary artifact has changed and will first rebuild the docker image, then start a redeploy of the Kubernetes pod.

It uses the watch feature of the docker-maven-plugin under the hood.

One of the most generic Generators is the java-exec generator. It is responsible for starting up arbitrary Java application. It knows how to deal with fat-jar applications where the application and all dependencies are included within a single jar and the MANIFEST.MF within the jar references a main class. But also flat classpath applications, where the dependencies are separate jar files and a main class is given.

If no main class is explicitly configured, the plugin first attempts to locate a fat jar. If the Maven build creates a JAR file with a META-INF/MANIFEST.MF containing a Main-Class entry, then this is considered to be the fat jar to use. If there are more than one of such files then the largest one is used.

If a main class is configured (see below) then the image configuration will contain the application jar plus all dependency jars. If no main class is configured as well as no fat jar being detected, then this Generator tries to detect a single main class by searching for public static void main(String args[]) among the application classes. If exactly one class is found this is considered to be the main class. If no or more than one is found the Generator finally does nothing.

It will use the following base image by default, but as explained above and can be changed with the from configuration.

These images always refer to the latest tag. The Red Hat base images are selected, when the plugin itself is a Red Hat supported version (which is detected by the plugins version number).

When a fromMode of istag is used to specify an ImageStreamTag and when no from is given, then as default the ImageStreamTag fis-java-openshift in the namespace openshift is chosen. If you are using a RedHat variation of this plugin (i.e. if the version is ending with -redhat), then a fromMode of istag is the default, otherwise its fromMode = "docker" which use the a plain Docker image reference for the S2I builder image.

Beside the common configuration parameters described in the table common generator options the following additional configuration options are recognized:

The exposed ports are typically later on use by Enrichers to create default Kubernetes or OpenShift services.

You can add additional files to the target image within baseDir by placing files into src/main/fabric8-includes. These will be added with mode 0644, while everything in src/main/fabric8-includes/bin will be added with 0755.

This generator is called spring-boot and gets activated when it finds a spring-boot-maven-plugin in the pom.xml.

This generator is based on the Java Application Generator and inherits all of its configuration values. The generated container port is read from the server.port property application.properties, defaulting to 8080 if it is not found. It also uses the same default images as the java-exec Generator.

Beside the common generator options and the java-exec options the following additional configuration is recognized:

The generator adds Kubernetes liveness and readiness probes pointing to either the management or server port as read from the application.properties. If the management.port (for Spring Boot 1) or management.server.port (for Spring Boot 2) and management.ssl.key-store (for Spring Boot 1) or management.server.ssl.key-store (for Spring Boot 2) properties are set in application.properties otherwise or server.ssl.key-store property is set in application.properties then the probes are automatically set to use https.

The generator works differently when called together with fabric8:watch. In that case it enables support for Spring Boot Developer Tools which allows for hot reloading of the Spring Boot app. In particular, the following steps are performed:

Since during fabric8:watch the application itself within the target/ directory is modified for allowing easy reloading you must ensure that you do a mvn clean before building an artefact which should be put into production. Since the released version are typically generated with a CI system which does a clean build anyway this should be only a theoretical problem.

The WildFly Swarm generator detects a WildFly Swarm build and disables the Prometheus Java agent because of this issue.

Otherwise this generator is identical to the java-exec generator. It supports the common generator options and the java-exec options.

The Thorntail v2 generator detects a Thorntail v2 build and disables the Prometheus Java agent because of this issue.

Otherwise this generator is identical to the java-exec generator. It supports the common generator options and the java-exec options.

The Vert.x generator detects an application using Eclipse Vert.x. It generates the metadata to start the application as a fat jar.

Currently, this generator is enabled if:

Otherwise this generator is identical to the java-exec generator. It supports the common generator options and the java-exec options.

The generator automatically:

You can pass application parameter by setting the JAVA_ARGS env variable. You can pass system properties either using the same variable or using JAVA_OPTIONS. For instance, create src/main/fabric8/deployment.yml with the following content to configure JAVA_ARGS:

This generator named karaf kicks in when the build uses a karaf-maven-plugin. By default the following base images are used:

When a fromMode of istag is used to specify an ImageStreamTag and when no from is given, then as default the ImageStreamTag fis-karaf-openshift:2.0 in the namespace openshift is chosen.

In addition to the common generator options this generator can be configured with the following options:

The webapp generator tries to detect WAR builds and selects a base servlet container image based on the configuration found in the pom.xml:

The base images chosen are:

In addition to the common generator options this generator can be configured with the following options:

The Open Liberty generator runs when the Open Liberty plugin is enabled in the maven build.

The generator is similar to the java-exec generator. It supports the common generator options and the java-exec options.

For Open Liberty, the default value of webPort is 9080.

Default enrichers are used for adding missing resources or adding metadata to given resource objects. The following default enhancers are available out of the box

Fabric8 enrichers are used for providing the connection to other components of the fabric8 Microservices platform. They are useful to add icons to to application or links to documentation sites.