fabric8:json

The maven fabric8:json goal generates the kubernetes.json file for your App from your Maven project and adds it as an artifact to your build so that it gets versioned and released along with your artifacts.

For a summary of the options see the Maven Property Reference

Generation options

You have various options for how to create the kubernetes.json

• hand craft yourself and put it into src/main/resources so that you can use Maven's default resource filtering to replace any project properties (e.g. the group ID, artifact ID, version number)
• let the fabric8:json goal generate it for you using its default rules and maven properties (see below)
• use the annotation processors and typesafe builders to create the metadata yourself; or enrich the default created metadata
• you can enrich the generated JSON with additional metadata JSON file (using the fabric8.extra.json property which defaults to the file target/classes/kubernetes-extra.json)

If you have a maven project which is a typical microservice style application with a single replication controller and service then we recommend just using the defaults that get generated; otherwise try the annotation processors and typesafe builders to create, edit or enrich the generated metadata (e.g. to add extra services).

Example usage

In a maven project type:

mvn fabric8:json
open target/classes/kubernetes.json

You'll then see the generated kubernetes JSON file.

Creating OpenShift Templates

OpenShift templates are an extension to Kubernetes JSON to allow parameters to be specified which are then specified by a user or generated as the template gets processed and applied.

To generate an OpenShift Template for your Maven project you just need to define one or more parameters for your project using the maven properties fabric8.parameter.FOO.description and fabric8.parameter.FOO.value. Refer to the Maven Property Reference for more details.

Specifying environment variables

You can use maven properties to specify environment variables to pass into the generated PodSpec in the ReplicationController as follows...

<project>
...
  <properties>
    <fabric8.env.FOO>bar</fabric8.env.FOO>
    ...
  </properties>
...
</project>

The above will then be the equivalent in docker terms of running...

docker run -d -e FOO=bar ${DOCKER_IMAGE}

Templates and parameters

When using OpenShift templates you want to parameterize things so users can more easily configure things. This means using expressions like ${FOO} inside environment variable names or values.

One issue with this is that maven properties tend to expand expressions of the form ${FOO} if there is a maven property or environment variable of that name. There is currently no way to escape those expressions inside maven property elements in the pom.xml <properties/> element.

So to make it easier to configure environment variables while bypassing maven's property expansion, you can use a file specified via fabric8.envProperties property which defaults to the file src/main/fabric8/env.properties.

i.e. if you create a file called src/main/fabric8/env.properties in your project that looks like this

FOO = bar
ANOTHER = some ${CHEESE}

In the above example there will be 2 environment variables defined, FOO and ANOTHER with ANOTHER using a template parameter expression for CHEESE

Note that you can mix and match both approaches. The nice thing about maven properties is they can be inherited from parent projects. The nice thing about the env.properties file approach is you have more fine grained control over property expansion and dealing better with OpenShift template parameter expressions.

Combining JSON files

The fabric8:json goal generates a kubernetes.json for each maven project which is enabled. Often maven projects are multi-module which means you'll have lots of fine grained generated kubernetes.json files. This is useful; but you often want to combine files together to make courser grained JSON files that are easier for users to consume.

Another advantage of combining the JSON files together is that the fabric8:json goal automatically moves Service objects first; so that if you have cyclical apps which depend on each other, the combined JSON will force the services to be created up front before any Pods to avoid breaking links. (Services must be defined first so that their environment variables become available if using those for service discovery).

By default a List of items is created; unless the pom.xml defines any OpenShift template parameters (see Creating OpenShift Templates for more detail) or any of the dependent JSON files are Template. The fabric8:json goal automatically combines OpenShift Templates together; unifying the list of template parameters to create a single combined Template.

You can generate a separate JSON file with the dependencies of the current project, use fabric8.combineJson.target property for that. If you want to create a Template of the current project and its dependencies, you can set fabric8.extra.json property to ${fabric8.combineJson.target}, and don’t forget to change the name of the Template (because "Combining JSON files" feature uses the names of templates for filtering duplicate), for example: <fabric8.combineJson.project>${project.artifactId}Combine</fabric8.combineJson.project>

Examples

The fabric8 project defines a number of different application modules for all the various parts of fabric8.

If you enable the fabric8.combineDependencies property then the fabric8:json goal will scan the maven dependencies for any dependency of <classifier>kubernetes</classifier> and <type>json</type> and combine them into the resulting JSON.

See this example to see how we can configure this in a pom.xml.

Maven Properties

You can use maven properties to customize the generation of the JSON:

You define the maven properties in the pom.xml file using the <properties> tag such as:

    <properties>
      <fabric8.label.container>java</fabric8.label.container>
      <fabric8.label.group>myapp</fabric8.label.group>
      <fabric8.iconRef>camel</fabric8.iconRef>
    </properties>

If you wish to override or add a property from the command line, you can do this by using Java JVM system properties. A property from the command line will override any existing option configured in the pom.xml file. For example to add a 3rd label and change the icon, you can do:

mvn fabric8:json -Dfabric8.label.foo=bar -Dfabric8.iconRef=java

There are many options as listed in the following table: