Fabric8 Documentation

Fabric8 Maven Plugin version 2.x

NOTE We highly recommend you use 3.x or later. We can help you migrate to the new version via the fabric8:migrate goal.

If you wish to stay on the 2.x version then here's the documentation:

Goals

• fabric8:migrate helps migrate your project from 2.x fabric8-maven-plugin to using the new shiny 3.x or newer version

For building and pushing docker images

• docker:build builds the docker image for your maven project
• docker:push pushes the locally built docker image to the global or a local docker registry

For generating and applying Kubernetes JSON

• fabric8:json generates kubernetes json for your maven project
• fabric8:apply applies the kubernetes json into a namespace in a kubernetes cluster
• fabric8:rolling works like fabric8:apply but performs a rolling update on any replication controllers which already exist
• fabric8:recreate works like fabric8:apply but forces all resources which exist to be recreated

Goals for working with Kubernetes

• fabric8:devops uses the fabric8-devops-connector to connect various DevOps services like git hosting, chat, issue tracking and CI / CD builds in jenkins for a project reusing the optional project specific fabric8.yml configuration file
• fabric8:create-env generates environment variable scripts for Kubernetes services so you can simulate running programs as if they were inside kubernetes
• fabric8:create-routes generates any missing OpenShift Routes for the current services
• fabric8:delete-pods deletes pods for the current projects docker image so that they get recreated by the replication controllers to use the latest image
• fabric8:clean cleans up the namespace

Goals for working with Helm Chart repositories

• fabric8:helm generates a Helm Chart for your application
• fabric8:helm-push goal commits and pushes changes to the Helm chart repository to the remote git repository

Adding the plugin to your project

To enable this maven plugin and to automatically generate/copy and release the App JSON file as part of your build add this to your pom.xml:

  <plugin>
    <groupId>io.fabric8</groupId>
    <artifactId>fabric8-maven-plugin</artifactId>
    <version>${fabric.version}</version>
    <executions>
      <execution>
        <id>json</id>
        <goals>
          <goal>json</goal>
        </goals>
      </execution>
    </executions>
  </plugin>

To automatically generate an App Zip for your project then add this:

  <plugin>
    <groupId>io.fabric8</groupId>
    <artifactId>fabric8-maven-plugin</artifactId>
    <version>${project.version}</version>
    <executions>
      <execution>
        <id>zip</id>
        <phase>package</phase>
        <goals>
          <goal>zip</goal>
        </goals>
      </execution>
    </executions>
  </plugin>

Generating CDI environment variables

If you use CDI for your dependency injection and use the @ConfigProperty annotation from deltaspike to inject environment variables or default values into your Java code then you can automatically generate a json schema file for each jar you create by just adding a provided scope dependency on the fabric8-apt module.

e.g. add this to your pom.xml

<dependency>
  <groupId>io.fabric8</groupId>
  <artifactId>fabric8-apt</artifactId>
  <scope>provided</scope>
</dependency>

This will then generate inside your jar a file called io/fabric8/environment/schema.json which will be a JSON Schema document describing all the environment variables, their types, default values and their description (if you added some javadoc for them).

Including the environment variables in the generated JSON

By default any discovered environment variable JSON Schema files will be included in the generated JSON so that your app JSON has all the available known environment variables from a CDI perspective; which makes it easy to change the app without too much detailed knowledge of the source code and helps reduce typeos since all the environment variable names are defaulted.

If you wish to disable this behaviour then set the maven property fabric8.includeAllEnvironmentVariables to false.

Viewing all the environment variable injection points

If you have transitive dependencies which include the generated io/fabric8/environment/schema.json file in their jars you can view the overall list of environment variable injection points for a project via:

mvn fabric8:describe-env

This will then list all the environment variables, their default value, type and description.

Deploying into the Library

Before deploying you need to make sure your docker image is available to Kubernetes. See above for how to do this. Any docker registry that is accessible to Kubernetes is supported.

To deploy your App Zip into the wiki in the web console use the following goal:

mvn fabric8:deploy

This goal uses the default fabric8 console URL of http://dockerhost:8484/hawtio/ unless you specify the FABRIC8_CONSOLE environment variable to point at something else.

e.g. to try this against a locally running hawtio try:

export FABRIC8_CONSOLE=http://localhost:8282/hawtio/

This goal will then POST the App Zip into the wiki so you should be able to view the newly posted App at http://dockerhost:8484/hawtio/wiki/branch/master/view

Example

To see these plugins in action check out how to run and example quickstart