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:

Parameter Description
docker.image Used by the docker-maven-plugin to define the output docker image name.
fabric8.json.target The generated kubernetes JSON file. Defaults to using the file target/classes/kubernetes.json
fabric8.pureKubernetes Should we exclude OpenShift templates and any extensions like OAuthConfigs in the generated or combined JSON? This defaults to false
fabric8.combineDependencies If enabled then the maven dependencies will be scanned for any dependency of <classifier>kubernetes</classifier> and <type>json</type> which are then combined into the resulting generated JSON file. See Combining JSON files
fabric8.combineJson.target The generated kubernetes JSON file dependencies on the classpath. See Combining JSON files. Defaults to using the property fabric8.json.target
fabric8.combineJson.project The project label used in the generated Kubernetes JSON dependencies template. See Combining JSON files. This defaults to ${project.artifactId}
fabric8.container.name The docker container name of the application in the generated JSON. This defaults to ${project.artifactId}-container
fabric8.containerPrivileged Whether the generated container should be run in priviledged mode (defaults to false)
fabric8.envProperties The properties file used to specify environment variables which allows ${FOO_BAR} expressions to be used without any Maven property expansion. Defaults to using the file src/main/fabric8/env.properties
fabric8.env.FOO = BAR Defines the environment variable FOO and value BAR.
fabric8.extra.json Allows an extra JSON file to be merged into the generated kubernetes json file. Defaults to using the file target/classes/kubernetes-extra.json.
fabric8.extended.environment.metadata Whether to try to fetch extended environment metadata during the json, or apply goals. The following ENV variables is supported: BUILD_URI, GIT_URL, GIT_COMMIT, GIT_BRANCH If any of these ENV variable is empty then if this option is enabled, then the value is attempted to be fetched from an online connection to the Kubernetes master. If the connection fails then the goal will report this as a failure gently and continue. This option can be turned off, to avoid any live connection to the Kubernetes master.
fabric8.generateJson If set to false then the generation of the JSON is disabled.
fabric8.iconRef Provides the resource name of the icon to use; found using the current classpath (including the ones shipped inside the maven plugin). For example icons/myicon.svg to find the icon in the src/main/resources/icons directorty. You can refer to a common set of icons by setting this option to a value of: activemq, camel, java, jetty, karaf, mule, spring-boot, tomcat, tomee, weld, wildfly
fabric8.iconUrl The URL to use to link to the icon in the generated Template.
fabric8.iconUrlPrefix The URL prefix added to the relative path of the icon file
fabric8.iconBranch The SCM branch used when creating a URL to the icon file. The default value is master.
fabric8.imagePullPolicy Specifies the image pull policy; one of Always, Never or IfNotPresent, . Defaults to Always if the project version ends with SNAPSHOT otherwise it is left blank. On newer OpenShift / Kubernetes versions a blank value implies IfNotPresent
fabric8.imagePullPolicySnapshot Specifies the image pull policy used by default for SNAPSHOT maven versions.
fabric8.includeAllEnvironmentVariables Should the environment variable JSON Schema files, generate by the **fabric-apt** API plugin be discovered and included in the generated kuberentes JSON file. Defaults to true.
fabric8.includeNamespaceEnvVar Whether we should include the namespace in the containers' env vars. Defaults to true
fabric8.label.FOO = BAR Defines the kubernetes label FOO and value BAR.
fabric8.livenessProbe.exec Creates a exec action liveness probe with this command.
fabric8.livenessProbe.httpGet.path Creates a HTTP GET action liveness probe on with this path.
fabric8.livenessProbe.httpGet.port Creates a HTTP GET action liveness probe on this port.
fabric8.livenessProbe.httpGet.host Creates a HTTP GET action liveness probe on this host.
fabric8.livenessProbe.port Creates a TCP socket action liveness probe on specified port.
fabric8.metrics.scrape Enable/disable the export of metrics to Prometheus. See more details at OpenShift template parameter FOO.
fabric8.parameter.FOO.value Defines the value of the OpenShift template parameter FOO.
fabric8.port.container.FOO = 1234 Declares that the pod's container has a port named FOO with a container port 1234.
fabric8.port.host.FOO = 4567 Declares that the pod's container has a port port named FOO which is mapped to host port 4567.
fabric8.provider The provider name to include in resource labels (defaults to fabric8).
fabric8.readinessProbe.exec Creates a exec action readiness probe with this command.
fabric8.readinessProbe.httpGet.path Creates a HTTP GET action readiness probe on with this path.
fabric8.readinessProbe.httpGet.port Creates a HTTP GET action readiness probe on this port.
fabric8.readinessProbe.httpGet.host Creates a HTTP GET action readiness probe on this host.
fabric8.readinessProbe.port Creates a TCP socket action readiness probe on specified port.
fabric8.replicas The number of pods to create for the Replication Controller if the plugin is generating the App JSON file.
fabric8.replicationController.name The name of the replication controller used in the generated JSON. This defaults to ${project.artifactId}-controller
fabric8.serviceAccount The name of the service account to use in this pod (defaults to none)
fabric8.service.name The name of the Service to generate. Defaults to ${project.artifactId} (the artifact Id of the project)
fabric8.service.headless Whether or not we should generate headless services (services with no ports exposed, no cluster IPs, and are not managed my the Kube Proxy)
fabric8.service.port The port of the Service to generate (if a kubernetes service is required).
fabric8.service.type The type of the service. Set to "LoadBalancer" if you wish an external load balancer to be created.
fabric8.service.containerPort The container port of the Service to generate (if a kubernetes service is required).
fabric8.service.protocol The protocol of the service. (If not specified then kubernetes will default it to TCP).
fabric8.service.port.<portName> The service port to generate (if a kubernetes service is required with multiple ports).
fabric8.service.containerPort.<portName> The container port to target to generate (if a kubernetes service is required with multiple ports).
fabric8.service.nodePort.<portName> The node port of this service to generate (if a kubernetes service is required with multiple ports).
fabric8.service.protocol.<portName> The protocol of this service port to generate (if a kubernetes service is required with multiple ports).
fabric8.service.<name>.port The port of the Service to generate for service <name>.
fabric8.service.<name>.type The type of the service. Set to "LoadBalancer" if you wish an external load balancer to be created.
fabric8.service.<name>.containerPort The container port of the Service to generate (if a kubernetes service is required).
fabric8.service.protocol The protocol of the service. (If not specified then kubernetes will default it to TCP).
fabric8.service.<name>.port.<portName> The service port to generate (if a kubernetes service is required with multiple ports).
fabric8.service.<name>.containerPort.<portName> The container port to target to generate (if a kubernetes service is required with multiple ports).
fabric8.service.<name>.nodePort.<portName> The node port of this service to generate (if a kubernetes service is required with multiple ports).
fabric8.service.<name>.protocol.<portName> The protocol of this service port to generate (if a kubernetes service is required with multiple ports).
fabric8.volume.FOO.emptyDir = somemedium Defines the emtpy volume with name FOO and medium somemedium.
fabric8.volume.FOO.hostPath = /some/path Defines the host dir volume with name FOO.
fabric8.volume.FOO.mountPath = /some/path Defines the volume mount with name FOO.
fabric8.volume.FOO.readOnly Specifies whether or not a volume is read only.
fabric8.volume.FOO.secret = BAR Defines the secret name to be BAR for the FOO volume.