1. Introduction

This is a preview feature to get early feedback. Only the set of documented features are available to users.

The kubernetes-gradle-plugin brings your Gradle Java applications on to Kubernetes. This plugin focuses on two tasks:

  • Building Container images.

  • Creating Kubernetes resource descriptors.

2. Common Scenarios

When working with kubernetes-gradle-plugin, you’ll probably be facing similar situations and following the same patterns other users do. These are some of the most common scenarios and configuration modes:

2.1. Zero Configuration

It’s very common, especially when dealing with the inner development loop, that you don’t need to provide any configuration for your Gradle project. You can get started simply by adding the plugin to your build.gradle file:

Example for setting up the kubernetes-gradle-plugin in build.gradle
plugins {
  id 'org.eclipse.jkube.kubernetes' version '1.5.1'
}

In this case, kubernetes-gradle-plugin analyzes your project and configures the container image and the cluster configuration manifests using a set of opinionated defaults.

2.2. Using Groovy Configuration

If the zero configuration mode doesn’t fit your use case, and you want more flexibility, you can also use kubernetes-gradle-plugin Groovy configuration to configure plugin as per your needs. kubernetes-gradle-plugin provides a rich set of configuration in form of Groovy DSL which can be used to tune plugin’s output as per your specific requirements.

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

  • Global configuration options are responsible for tuning the behavior of plugin tasks.

  • images defines which container images are used and configured.

  • resources defines the resource descriptors for deploying on Kubernetes cluster.

  • enricher configures various aspects of creating and enhancing resource descriptors.

A working example can be found in quickstarts/gradle/groovy-dsl-config directory.

2.2.1. Configuring Images

This section provides an overview of images element with which you can configure different aspects of container images generated by kubernetes-gradle-plugin. Here is an example of providing Groovy DSL configuration for a simple image:

Example for providing image using Groovy DSL configuration
kubernetes {
    images {
        image {
            name = "jkube/${project.name}:${project.version}" (1)
            alias = "camel-service" (2)
            build {
                from = "quay.io/jkube/jkube-java-binary-s2i:0.0.9" (3)
                assembly { (4)
                    targetDir = "/deployments" (5)
                    layers = [{ (6)
                        fileSets = [{ (7)
                            directory = file("${project.rootDir}/build/dependencies")
                       }]
                    }]
                }
                env { (8)
                    JAVA_LIB_DIR = "/deployments/dependencies/*"
                    JAVA_MAIN_CLASS = "org.apache.camel.cdi.Main"
                }
                labels { (9)
                    labelWithValue = "foo"
                    version = "${project.version}"
                    artifactId = "${project.name}"
                }
                ports = ["8787"] (10)
            }
        }
    }
}
1 Name with which we want our image to be built; See name field in Image Configuration for details.
2 Shortcut name for image; See alias field in Image Configuration for details.
3 Base image on which this image would be built upon; See from field in Image Build Configuration for more details.
4 Assembly Configuration for copying files/directories into image. See Assembly Configuration for more details.
5 Target directory inside image for copying a directory into image
6 Assembly layer; See Assembly Inline/Layer Configuration for details.
7 FileSet Assembly Configuraton for copying directories. See fileSets field in Assembly Layer Configuration for details.
8 Environment variables added to image. See Environment and Labels for details.
9 Labels added to image. See Environment and Labels for details.
10 Ports to be exposed. See port field in Image Build Configuration for details.

You can read more about supported fields in image configuration element in Image Configuration section.

Copying Files/Directories into Image

If you want to copy some files/directories into your image. You can make use of kubernetes-gradle-plugin Assembly Configuration. You would need to provide assembly element in image > build.

Here is an example of copying a single jar file into image. This configuration would copy a jar file located in build/libs/ to /deployments folder inside the image:

Example for copying a file to image using Groovy DSL configuration:
kubernetes {
    images {
        image {
            name = "${project.group}/${project.name}:${project.version}"
            build {
                from = "quay.io/jkube/jkube-java-binary-s2i:0.0.9"
                assembly {
                    targetDir = "/deployments"
                    layers = [{
                        id = "custom-assembly-for-copying-file"
                        files = [{
                            source = file("build/libs/${project.name}-${project.version}-all.jar")
                            outputDirectory = "."
                        }]
                    }]
                }
            }
        }
    }
}

In order to copy directories, you would be using fileSets configuration element instead of files. Here is an example of copying directories. This example would copy build/dependencies directory to /deployments directory inside image.

Example for copying a directory to image using Groovy DSL configuration:
kubernetes {
    images {
        image {
            name = "${project.group}/${project.name}:${project.version}"
            build {
                from = "quay.io/jkube/jkube-java-binary-s2i:0.0.9"
                assembly {
                    targetDir = "/deployments"
                    layers = [{
                        id = "custom-assembly-for-copying-directory"
                        fileSets = [{
                            directory = file("${project.rootDir}/build/dependencies")
                       }]
                    }]
                }
            }
        }
    }
}

2.2.2. Kubernetes Labels and Annotations

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

Example for label and annotations
kubernetes {
  resources {
    labels { (1)
      all { (2)
        extraLabel = "quickstart-groovy-dsl-configuration"
      }
      service { (3)
        database = 'mysql'
        persistent = 'true'
      }
      replicaSet { (4)
        // ...
      }
      pod { (5)
        // ...
      }
      deployment { (6)
        // ...
      }
    }
    annotations { (7)
       // ...
    }
 }
}
1 labels section with resources contains labels which should be applied to objects of various kinds
2 Within all labels which should be applied to every object can be specified
3 service labels are used to label services
4 replicaSet labels are for replica set and replication controller
5 pod holds labels for pod specifications in replication controller, replica sets and deployments
6 deployment is for labels on deployments (kubernetes) and deployment configs (openshift)
7 The subelements are also available for specifying annotations.

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. See Labels and Annotations Configuration for more details.

2.2.3. Kubernetes Controller Generation

In JKube terminology, a Controller resource is a Kubernetes resource which manages Pods created for your application. These can be one of the following resources:

By default Deployment is generated in Kubernetes mode. You can easily configure different aspects of generated Controller resource using Groovy DSL configuration. Here is an example:

Example of Controller Resource Configuration
kubernetes {
  resources {
    labels {
      all {
        extraLabel = "quickstart-groovy-dsl-configuration"
      }
    }
    env { (1)
      organization = "Eclipse Foundation"
      projectName = "jkube"
    }
    controllerName = "${project.name}-controller" (2)
    containerPrivileged = true (3)
    imagePullPolicy = "Always" (4)
    replicas = "2" (5)
    liveness { (6)
      getUrl = "http://:8080/q/health"
      tcpPort = "8080"
      initialDelaySeconds = "3"
      timeoutSeconds = "3"
    }
    volumes = [{ (7)
      name = "scratch"
      type = "emptyDir"
      medium = "Memory"
      mounts = ["/var/scratch"]
    }]
  }
}
1 Environment variables added to all of your application Pods
2 Name of Controller(metadata.name set in generated Deployment, Job, ReplicaSet etc)
3 Setting Security Context of all application Pods.
4 Configure how images would be updated. Can be one of IfNotPresent, Always or Never. Read Kubernetes Images docs for more details.
5 Number of replicas of pods we want to have in our application
6 Define an HTTP liveness request, see Kubernetes Liveness/Readiness probes for more details.
7 Mounting an EmptyDir Volume to your application pods

See Kubernetes Controller Configuration for more details.

2.2.4. Ingress Generation

Once you’ve enabled jkube.createExternalUrls property, you should be able to generate an opinionated ingress during k8sResource task. You can also configure it as per your needs using Groovy DSL configuration or by providing your own resource fragments.

Here is an example of configuring Ingress using Groovy DSL configuration:

Enable Ingress Generation by enabling createExternalUrl property
jkube.createExternalUrls = true

Services which are exposed by Ingress should also contain expose = true label. If not, you can configure plugin to expose them like this: .Example for exposing Service for Ingress

kubernetes {
    enricher {
        config {
            "jkube-service" {
                expose = "true"
            }
        }
    }
}
Example for Ingress Configuration
kubernetes {
  resources {
    ingress {
      ingressTlsConfigs = [{ (1)
        hosts = ["foo.bar.com"]
        secretName = "testsecret-tls"
      }]
      ingressRules = [{
        host = "foo.bar.com" (2)
        paths = [{
          pathType = "Prefix" (3)
          path = "/foo" (4)
          serviceName = "service1" (5)
          servicePort = "8080" (6)
        }]
      }]
    }
  }
}
1 Ingress TLS Configuration to specify Secret that contains TLS private key and certificate
2 Host names, can be precise matches or a wildcard. See Kubernetes Ingress Hostname documentation for more details
3 Ingress Path Type, Can be one of ImplementationSpecific, Exact or Prefix
4 Ingress path corresponding to provided service.name
5 Service Name corresponding to path
6 Service Port corresponding to path

For more information, please see Ingress Configuration.

You can create Ingress using yaml fragment also. You would need to place a fragment of yaml in src/main/jkube directory like this:

Ingress fragment Example
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tls-example-ingress
spec:
  tls:
  - hosts:
    - https-example.foo.com
    secretName: testsecret-tls
  rules:
  - host: https-example.foo.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: service1
            port:
              number: 80

2.2.5. ServiceAccount Generation

You can configure resources configuration to generate a ServiceAccount or configure an already existing ServiceAccount into your generated Deployment.

Here is an example of Groovy DSL configuration to generate a ServiceAccount:

Example for Creating ServiceAccount via Groovy DSL
kubernetes {
  resources {
    serviceAccounts = [{
      name = "my-serviceaccount" (1)
      deploymentRef = "my-deployment-name" (2)
    }]
  }
}
1 Name of ServiceAccount to be created
2 Deployment which will be using this ServiceAccount

If you don’t want to generate ServiceAccount but just use an existing ServiceAccount in your Deployment. You can configure it via serviceAccount field in resource configuration. Here is an example:

Example for Configuring already existing ServiceAccount into generated Deployment
kubernetes {
  resources {
    serviceAccount = "my-existing-serviceaccount"
  }
}

Service Account Resource fragment:

If you don’t want to use Groovy DSL configuration, you can provide a resource fragment for ServiceAccount resource. Here is how it would look like:

ServiceAccount resource fragment
apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-robot

2.3. Using Dockerfile

You can build a container image and deploy to Kubernetes with kubernetes-gradle-plugin by just providing a Dockerfile. kubernetes-gradle-plugin builds a container image based on your Dockerfile and generates opinionated Kubernetes manifests by inspecting it.

2.3.1. Placing Dockerfile in project root directory

You can place the Dockerfile in the project root directory along with build.gradle. kubernetes-gradle-plugin detects it and automatically builds an image based on this Dockerfile. There is no need to provide any sort of configuration apart from Dockerfile and project root directory as docker context directory. The Image is created with an opinionated name from group, artifact and version. The name can be overridden by using the jkube.image.name property. Read Simple Dockerfile section for more details.

2.3.2. Placing Dockerfile in some other directory

You can choose to place your Dockerfile at some other location. By default, the plugin assumes it to be src/main/docker, but you’ll need to configure docker context directory in plugin configuration. When not specified, context directory is assumed to be Dockerfile’s parent directory. You can take a look at Docker File Provided Quickstarts for more details.

2.3.3. Controlling what gets copied to image

When using Dockerfile mode, every file and directory present in the Docker build context directory gets copied to the created Docker image. In case you want to ignore some files, or you want to include only a specific set of files, the kubernetes-gradle-plugin provides the following options to achieve this:

2.3.4. Using Property placeholders in Dockerfiles

You can reference properties in your Dockerfiles using standard maven property placeholders ${*}. For example, if you have a property in your gradle.properties like this:

gradle.properties
fromImage = fabric8/s2i-java
Dockerfile
FROM ${fromImage}:latest-java11

You can override placeholders using the filter field in image build configuration, see Build Filtering for more details.

2.4. Kubernetes Resource Fragments

You can also use an external configuration in form of YAML resource descriptors which are located in the src/main/jkube directory. Each resource gets 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.

Let’s have a look at an example from quickstarts/gradle/external-resources. This is a plain Spring Boot application, whose images are auto generated like in case of no configuration. The resource fragments are in src/main/jkube.

Example fragment "deployment.yml"
spec:
  replicas: 1
  template:
    spec:
      volumes:
        - name: config
          gitRepo:
            repository: 'https://github.com/jstrachan/sample-springboot-config.git'
            revision: 667ee4db6bc842b127825351e5c9bae5a4fb2147
            directory: .
      containers:
        - volumeMounts:
            - name: config
              mountPath: /app/config
          env:
            - name: KUBERNETES_NAMESPACE
              valueFrom:
                fieldRef:
                  apiVersion: v1
                  fieldPath: metadata.namespace
      serviceAccount: ribbon

As you can see, there is no metadata section as would be expected for Kubernetes resources because it will be automatically added by the kubernetes-gradle-plugin. The object’s Kind, if not given, is automatically derived from the filename. In this case, the kubernetes-gradle-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 Kind Filename Mapping.

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 project name as specified in your build.gradle).

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.

3. Tasks Overview

This plugin supports a rich set for providing a smooth Java developer experience. These tasks can be categorized in multiple groups:

  • Build and Deployment tasks are all about creating and managing Kubernetes build artifacts like Docker images or S2I builds.

  • Development tasks target help not only in developing resource descriptors to the development cluster but also to manage the lifecycle of the development cluster as well.

Table 1. Build & Deployment Tasks
Task Description

k8sBuild

Build images

k8sPush

Pushes the built images to the container image registry

k8sResource

Generate resource manifests for your application

k8sApply

Applies the generated resources to the connected cluster

k8sHelm

Generate Helm charts for your application

Table 2. Development Tasks
Task Description

k8sDebug

Debug your Java app running on the cluster

k8sLog

Show the logs of your Java app running on the cluster

k8sUndeploy

Deletes the kubernetes resources that you deployed via the k8sApply task

3.1. Build And Deployment Tasks

3.1.1. k8sBuild

This task is for building container images for your application.

Kubernetes Build

A normal Docker build is performed by default.For Kubernetes builds the kubernetes-gradle-plugin uses the Docker remote API so the URL of your Docker Daemon must be specified.The URL can be specified by the dockerHost or machine configuration, or by the DOCKER_HOST environment variable.

The Docker remote API supports communication via SSL and authentication with certificates.The path to the certificates can be specified by the certPath or machine configuration, or by the DOCKER_CERT_PATH environment variable.

If you don’t have access to docker daemon, you can change build strategy using buildStrategy option in Groovy configuration like this:

Example of overriding default build strategy
kubernetes {
    buildStrategy = 'jib'
}

These are the different options supported by buildStrategy:

Table 3. JKube Build Strategies

buildStrategy

Description

docker

Docker build with a binary source

jib

Deamonless container image creation using JIB build

kubernetes-gradle-plugin by default tries to build up an opinionated Image Configuration by inspecting build.gradle. You can also provide your own Dockerfile or provide Custom ImageConfiguration via Groovy DSL configuration.

3.1.2. k8sPush

This task uploads images to the registry which have a build configuration section. The images to push can be restricted with the global option filter (see Build Goal Configuration for details). The registry to push is by default docker.io but can be specified as part of the images’s name the Docker way. E.g. docker.test.org:5000/data:1.5 will push the image data with tag 1.5 to the registry docker.test.org at port 5000. Registry credentials (i.e. username and password) can be specified in multiple ways as described in section Authentication.

3.1.3. k8sResource

This task generates Kubernetes resources based on your project. It can either be opinionated defaults or based on the configuration provided in Groovy DSL configuration or resource fragments in src/main/jkube. Generated resources are in build/classes/java/main/META-INF/jkube/kubernetes directory. You can find all Groovy DSL configuration options for k8sResource in Kubernetes Resource configuration section.

Resource task also validates the generated resource descriptors using API specification of Kubernetes. You can see configuration options regarding Kubernetes resource validation in Global Configuration section.

3.1.4. k8sApply

This task applies the resources created with k8sResource to a connected Kubernetes cluster.

gradle k8sApply

3.1.5. k8sHelm

This task is for creating Helm charts for your Gradle project so that you can install, update or delete your app in Kubernetes using Helm.

For creating a Helm chart you simply call k8sHelm task on the command line:

gradle k8sResource k8sHelm

The k8sResource goal is required to create the resource descriptors which are included in the Helm chart. If you have already built the resource then you can omit this task.

The configuration is defined in a helm section within the plugin’s configuration:

Example Helm configuration
kubernetes {
  helm {
    chart = 'Jenkins'
    keywords = ['ci', 'cd', 'server']
    dependencies = [{
      name = 'ingress-nginx'
      version = '1.26.0'
      repository = 'https://kubernetes.github.io/ingress-nginx'
    }]
  }
}

This configuration section knows the following sub-elements in order to configure your Helm chart.

Table 4. Helm configuration
Element Description Property

chart

The Chart name.

Defaults to project name.

jkube.helm.chart

version

The Chart SemVer version.

Defaults to project version

jkube.helm.version

description

The Chart single-sentence description.

Defaults to project description.

jkube.helm.description

home

The Chart URL for this project’s home page.

jkube.helm.home

sources

The Chart list of URLs to source code for this project.

maintainers

The Chart list of maintainers (name+email).

icon

The Chart URL to an SVG or PNG image to be used as an icon, default is extracted from the kubernetes manifest (kubernetes.yml) jkube.io/iconUrl annotation if not provided.

jkube.helm.icon

keywords

Comma separated list of keywords to add to the chart.

engine

The template engine to use.

additionalFiles

The list of additional files to be included in the Chart archive. Any file named README or LICENSE will always be included by default.

type / types

Platform for which to generate the chart. By default this is kubernetes, but can be also openshift for using OpenShift specific resources in the chart. You can also add both values as a comma separated list.

Please note that there is no OpenShift support yet for charts, so this is experimental.

jkube.helm.type

sourceDir

Where to find the resource descriptors generated with k8sResource. By default this is ${basedir}/build/classes/java/main/classes/META-INF/jkube, which is also the output directory used by k8sResource.

jkube.helm.sourceDir

outputDir

Where to create the Helm chart, which is ${basedir}/build/jkube/helm by default for Kubernetes and ${basedir}/build/jkube/helmshift for OpenShift.

jkube.helm.outputDir

tarballOutputDir

Where to create the the Helm chart archive, which is ${basedir}/build if not provided.

jkube.helm.tarballOutputDir

chartExtension

The Helm chart file extension (tgz, tar.bz, tar.bzip2, tar.bz2), default value is tar.gz if not provided.

jkube.helm.chartExtension

dependencies

The list of dependencies for this chart

In a next step you can install this via the helm command line tool as follows:

helm install nameForChartInRepository build/jkube/helm/${chartName}/Kubernetes

or

helm install build/jkube/helm/${chartName}/Kubernetes --generate-name

In addition, this task will also create a tar-archive below ${basedir}/build which contains the chart with its template. This tar is added as an artifact with classifier helm to the build (helmshift for the OpenShift mode).

3.2. Development Tasks

3.2.1. k8sDebug

This task enables debugging in your Java app and then port forwards from localhost to the latest running pod of your app so that you can easily debug your app from your Java IDE.

gradle k8sDebug

Then follow the on screen instructions.

The default debug port is 5005.If you wish to change the local port to use for debugging then pass in the jkube.debug.port parameter:

gradle k8sDebug -Djkube.debug.port=8000

Then in your IDE you start a Remote debug execution using this remote port using localhost and you should be able to set breakpoints and step through your code.

This lets you debug your apps while they are running inside a Kubernetes cluster - for example if you wish to debug a REST endpoint while another pod is invoking it.

Debug is enabled via the JAVA_ENABLE_DEBUG environment variable being set to true.This environment variable is used for all the standard Java docker images used by Spring Boot, flat classpath and executable JAR projects and Wildfly Swarm.If you use your own custom docker base image you may wish to also respect this environment variable too to enable debugging.

Speeding up debugging

By default the k8sDebug task 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 jkube.debug.enabled property.

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

gradle k8sResource k8sApply -Djkube.debug.enabled=true

Then whenever you type the k8sDebug task there is no need for the gradle task to edit the Deployment and wait for a pod to restart; we can immediately start debugging when you type:

gradle k8sDebug
Debugging with suspension

The k8sDebug task 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 jkube.debug.suspend flag:

gradle k8sDebug -Djkube.debug.suspend

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 task 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).

The jkube.debug.suspend flag will disable readiness probes in the Kubernetes deployment in order to start port-forwarding during the early phases of application startup

3.2.2. k8sLog

This task tails the log of the app that you deployed via the k8sApply task

gradle k8sLog

You can then terminate the output by hitting Ctrl+C

If you wish to get the log of the app and then terminate immediately then try:

gradle k8sLog -Djkube.log.follow=false

This lets you pipe the output into grep or some other tool

gradle k8sLog -Djkube.log.follow=false | grep Exception

If your app is running in multiple pods you can configure the pod name to log via the jkube.log.pod property, otherwise it defaults to the latest pod:

gradle k8sLog -Djkube.log.pod=foo

If your pod has multiple containers you can configure the container name to log via the jkube.log.container property, otherwise it defaults to the first container:

gradle k8sLog -Djkube.log.container=foo

3.2.3. k8sUndeploy

This task is for deleting the kubernetes resources that you deployed via the k8sApply or k8sDeploy tasks.

It iterates through all the resources generated by the k8sResource task and deletes them from your current Kubernetes cluster.

gradle k8sUndeploy

4. Gradle Groovy DSL Configuration

4.1. Global Configuration

Table 5. Global configuration
Element Description Property

apiVersion

Use this variable if you are using an older version of docker not compatible with the current default use to communicate with the server.

jkube.docker.apiVersion

authConfig

Authentication information when pulling from or pushing to Docker registry. There is a dedicated section Authentication for how to do security.

access

Group of configuration parameters to connect to Kubernetes/OpenShift cluster.

autoPull

Decide how to pull missing base images or images to start:

  • on : Automatic download any missing images (default)

  • off : Automatic pulling is switched off

  • always : Pull images always even when they already exist locally

  • once : For multi-module builds images are only checked once and pulled for the whole build.

jkube.docker.autoPull

buildRecreate

If the effective build mode is openshift then this option decides how the OpenShift resource objects associated with the build should be treated when they already exist:

  • buildConfig or bc : Only the BuildConfig is recreated

  • imageStream or is : Only the ImageStream is recreated

  • all : Both, BuildConfig and ImageStream are recreated

  • none : Neither BuildConfig nor ImageStream is recreated

The default is none. If you provide the property without value then all is assumed, so everything gets recreated.

jkube.build.recreate

buildSourceDirectory

Default directory that contains the assembly descriptor(s) used by the plugin. The default value is src/main/docker. This option is only relevant for the k8sBuild task.

jkube.build.source.dir

buildStrategy

Defines what build strategy to choose while building container image. Possible values are docker and jib out of which docker is default.

jkube.build.strategy

certPath

Path to SSL certificate when SSL is used for communicating with the Docker daemon. These certificates are normally stored in ~/.docker/. With this configuration the path can be set explicitly. If not set, the fallback is first taken from the environment variable DOCKER_CERT_PATH and then as last resort ~/.docker/. The keys in this are expected with it standard names ca.pem, cert.pem and key.pem. Please refer to the Docker documentation for more information about SSL security with Docker.

jkube.docker.certPath

createNewResources

Create new Kubernetes resources.

Defaults to true

jkube.deploy.create

debugSuspend

Disables readiness probes in Kubernetes Deployment in order to start port forwarding during early phases of application startup.

Defaults to false.

jkube.debug.suspend

deletePodsOnReplicationControllerUpdate

Delete all the pods if we update a Replication Controller.

Defaults to true.

jkube.deploy.deletePods

dockerHost

The URL of the Docker Daemon. If this configuration option is not given, then the optional <machine> configuration section is consulted. The scheme of the URL can be either given directly as http or https depending on whether plain HTTP communication is enabled or SSL should be used. Alternatively the scheme could be tcp in which case the protocol is determined via the IANA assigned port: 2375 for http and 2376 for https. Finally, Unix sockets are supported by using the scheme unix together with the filesystem path to the unix socket.

The discovery sequence used by the docker-maven-plugin to determine the URL is:

  1. Value of dockerHost (jkube.docker.host)

  2. The Docker host associated with the docker-machine named in <machine>, i.e. the DOCKER_HOST from docker-machine env.

  3. The value of the environment variable DOCKER_HOST.

  4. unix:///var/run/docker.sock if it is a readable socket.

jkube.docker.host

filter

In order to temporarily restrict the operation of plugin tasks this configuration option can be used. Typically this will be set via the system property jkube.image.filter when Gradle is called. The value can be a single image name (either its alias or full name) or it can be a comma separated list with multiple image names. Any name which doesn’t refer an image in the configuration will be ignored.

jkube.image.filter

failOnNoKubernetesJson

Fail if there is no kubernetes json present.

Defaults to false.

jkube.deploy.failOnNoKubernetesJson

failOnValidationError

If value is set to true then any validation error will block the plugin execution. A warning will be printed otherwise.

Default is false.

jkube.failOnValidationError

ignoreServices

Ignore Service resources while applying resources. This is particularly useful when in recreate mode to let you easily recreate all the ReplicationControllers and Pods but leave any service definitions alone to avoid changing the portalIP addresses and breaking existing pods using the service.

Defaults to false.

jkube.deploy.ignoreServices

imagePullPolicy

Specify whether images should be pull when looking for base images while building or images for starting. This property can take the following values (case insensitive):

  • IfNotPresent: Automatic download any missing images (default)

  • Never : Automatic pulling is switched off always

  • Always : Pull images always even when they already exist locally.

By default a progress meter is printed out on the console, which is omitted when using Maven in batch mode (option -B). A very simplified progress meter is provided when using no color output (i.e. with -Djkube.useColor=false).

jkube.docker.imagePullPolicy

interpolateTemplateParameters

Interpolate parameter values from *template.yml fragments in the generated resource list (kubernetes.yml).

This is useful when using JKube in combination with Helm.

Placeholders for variables defined in template files can be used in the different resource fragments. Helm generated charts will contain these placeholders/parameters.

For resource task, these placeholders are replaced in the aggregated resource list YAML file (not in the individual generated resources) if this option is enabled.

Defaults to true.

jkube.interpolateTemplateParameters

jsonLogDir

The folder we should store any temporary json files or results

Defaults to ${project.rootDir}/build/jkube/applyJson.

jkube.deploy.jsonLogDir

kubernetesManifest

The generated kubernetes YAML file.

Defaults to ${basedir}/build/META-INF/jkube/kubernetes.yml.

jkube.kubernetesManifest

kubernetesTemplate

File or directory containing the Kubernetes YAML files to be included as Chart templates.

Defaults to ${basedir}/build/classes/java/main/META-INF/jkube/kubernetes

jkube.kubernetesTemplate

localDebugPort

Default port available for debugging your application inside Kubernetes.

Defaults to 5005.

jkube.debug.port

logFollow

Get follow logs for your application inside Kubernetes.

Defaults to true.

jkube.log.follow

logContainerName

Get logs of some specific container inside your application Deployment.

Defaults to null.

jkube.log.container

logPodName

Get logs of some specific pod inside your application Deployment.

Defaults to null.

jkube.log.pod

machine

Docker machine configuration.

maxConnections

Number of parallel connections are allowed to be opened to the Docker Host. For parsing log output, a connection needs to be kept open (as well for the wait features), so don’t put that number to low. Default is 100 which should be suitable for most of the cases.

jkube.docker.maxConnections

mergeWithDekorate

When resource generation is delegated to Dekorate, should JKube resources be merged with Dekorate generated ones.

Defaults to false.

jkube.mergeWithDekorate

outputDirectory

Default output directory to be used by this plugin. The default value is build/docker and is only used for the task k8sBuild.

jkube.build.target.dir

offline

Whether to try detecting Kubernetes Cluster or stay offline.

Defaults to false.

jkube.offline

profile

Profile to which contains enricher and generators configuration. See Profiles for details.

jkube.profile

pushRegistry

The registry to use when pushing the image. See Registry Handling for more details.

jkube.docker.push.registry

recreate

Update resources by deleting them first and then creating them again.

Defaults to false.

jkube.recreate

registry

Specify globally a registry to use for pulling and pushing images. See Registry handling for details.

jkube.docker.registry

pushRetries

How often should a push be retried before giving up. This useful for flaky registries which tend to return 500 error codes from time to time.

Defaults to 0.

jkube.docker.push.retries

resourceEnvironment

Environment name where resources are placed. For example, if you set this property to dev and resourceDir is the default one, plugin will look at src/main/jkube/dev.

Defaults to null.

jkube.environment

resourceSourceDirectory

Folder where to find project specific files.

Defaults to ${project.rootDir}/src/main/jkube.

jkube.resourceDir

resourceTargetDirectory

The generated Kubernetes manifests target directory.

Defaults to ${basedir}/build/classes/java/main/META-INF/jkube.

jkube.targetDir

rollingUpgrades

Use Rolling Upgrades to apply changes.

jkube.rolling

servicesOnly

Only process services so that those can be recursively created/updated first before creating/updating any pods and Replication Controllers.

Defaults to false.

jkube.deploy.servicesOnly

serviceUrlWaitTimeSeconds

Seconds to wait for a URL to be generated for a service

Defaults to 5.

jkube.serviceUrl.waitSeconds

skip

With this parameter the execution of this plugin can be skipped completely.

jkube.skip

skipApply

If set no resource maniefst would be applied to connected Kubernetes cluster.

Defaults to false.

jkube.skip.apply

skipBuild

If set not images will be build (which implies also skip.tag) with k8sBuild.

jkube.skip.build

skipTag

If set to true this plugin won’t add any tags to images that have been built with k8sBuild.

jkube.skip.tag

skipMachine

Skip using docker machine in any case

jkube.docker.skip.machine

skipPush

If set to true the plugin won’t push any images that have been built.

Defaults to false.

jkube.skip.push

skipResourceValidation

If value is set to true then resource validation is skipped. This may be useful if resource validation is failing for some reason but you still want to continue the deployment.

Default is false.

jkube.skipResourceValidation

skipTag

If set to true this plugin won’t push any tags

Defaults to false.

jkube.skip.tag

useProjectClassPath

Should we use the project’s compile time classpath to scan for additional enrichers/generators.

Defaults to false.

jkube.useProjectClassPath

verbose

Boolean attribute for switching on verbose output like the build steps when doing a Docker build. Default is false.

jkube.docker.verbose

workDirectory

The JKube working directory. Defaults to ${project.build.directory}/jkube.

jkube.workDir

4.2. Image Configuration

The configuration how images should be created are 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:

Table 6. Image Configuration
Element Description

name

Each image configuration has a mandatory, unique docker repository name. This can include registry and tag parts, but also placeholder parameters. See below for a detailed explanation.

alias

Shortcut name for an image which can be used for identifying the image within this configuration. This is used when linking images together or for specifying it with the global image configuration element.

registry

Registry to use for this image. If the name already contains a registry this takes precedence. See Registry handling for more details.

build

Element which contains all the configuration aspects when doing a k8sBuild. This element can be omitted if the image is only pulled from a registry e.g. as support for integration tests like database images.

The build section is mandatory and is explained in below.

When specifying the image name in the configuration with the name field you can use several placeholders which are replaced during runtime by this plugin. In addition you can use regular Gradle properties which are resolved by Gradle itself.

Table 7. Image Names
Placeholder Description

%g

The last part of the Gradle group name, sanitized so that it can be used as username on GitHub. Only the part after the last dot is used. E.g. for a group id org.eclipse.jkube this placeholder would insert jkube

%a

A sanitized version of the artefact id so that it can be used as part of an Docker image name. I.e. it is converted to all lower case (as required by Docker)

%v

The project version.

%l

If the project version ends with -SNAPSHOT then this placeholder is latest, otherwise its the full version (same as %v)

%t

If the project version ends with -SNAPSHOT this placeholder resolves to snapshot-<timestamp> where timestamp has the date format yyMMdd-HHmmss-SSSS (eg snapshot-). This feature is especially useful during development in oder to avoid conflicts when images are to be updated which are still in use. You need to take care yourself of cleaning up old images afterwards, though.

4.3. Build Configuration

Here are different modes how images can be built:

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

External Dockerfile or Docker archive

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

  • contextDir specifies docker build context if an external dockerfile is located outside of Docker build context. If not specified, Dockerfile’s parent directory is used as build context.

  • dockerFile specifies a specific Dockerfile path. The Docker build context directory is set to contextDir if given. If not the directory by default is the directory in which the Dockerfile is stored.

  • dockerArchive specifies a previously saved image archive to load directly. If a dockerArchive is provided, no dockerFile must be given.

All paths can be either absolute or relative paths. A relative path is looked up in $projectDir/src/main/docker by default. You can make it easily an absolute path by using $projectDir in your 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 .Example

COPY maven/ /my/target/directory

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

If this directory contains a .jkube-dockerignore (or alternatively, a .jkube-dockerexclude file), then it is used for excluding files for the build. If the file doesn’t exist, or it’s empty, then there are no exclusions.

Each line in this file is treated as an entry in the excludes assembly fileSet configuration . Files can be referenced by using their relative path name. Wildcards are also supported, patterns will be matched using FileSystem#getPathMatcher glob syntax.

It is similar to .dockerignore when using Docker but has a slightly different syntax (hence the different name).

Example .jkube-dockerexclude or .jkube-dockerignore is an example which excludes all compiled Java classes.

Example 1. Example .jkube-dockerexclude or .jkube-dockerignore
build/classes/**  (1)
1 Exclude all compiled classes

If this directory contains a .jkube-dockerinclude file, then it is used for including only those files for the build. If the file doesn’t exist or it’s empty, then everything is included.

Each line in this file is treated as an entry in the includes assembly fileSet configuration . Files can be referenced by using their relative path name. Wildcards are also supported, patterns will be matched using FileSystem#getPathMatcher glob syntax.

Example .jkube-dockerinclude shows how to include only jar file that have build to the Docker build context.

Example 2. Example .jkube-dockerinclude
build/libs/*.jar (1)
1 Only add jar file to you Docker build context.

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

Simple Dockerfile build

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

The image name is by default set from the Gradle coordinates (%g/%a:%l, see Image Name for an explanation of the params which are essentially the Gradle’s group, project name and project version) This name can be set with the property jkube.image.name in gradle.properties.

Filtering

kubernetes-gradle-plugin filters given Dockerfile with Gradle properties, much like the maven-resource-plugin does. Filtering is enabled by default and can be switched off with a build config filter='false'. Properties which we want to replace are specified with the ${..} syntax. Replacement includes 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 Gradle 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='${*}' parse Gradle 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='@' triggers on parameters in the format @…​@. 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 assembly configuration with filtering to make them available in the docker build context.

Example

The following example replaces all properties in the format @property@ within the Dockerfile.

kubernetes {
    images {
        image {
            name = 'user/demo'
            build {
                filter = '@'
            }
        }
    }
}

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

Table 8. Build configuration (image)
Element Description

assembly

Specifies the assembly configuration as described in Build Assembly

args

Map specifying the value of Docker build args which should be used when building the image with an external Dockerfile which uses build arguments. The key-value syntax is the same as when defining Gradle properties (or labels or env). This argument is ignored when no external Dockerfile is used. Build args can also be specified as properties as described in Build Args

buildOptions

Map specifying the build options to provide to the docker daemon when building the image. These options map to the ones listed as query parameters in the Docker Remote API and are restricted to simple options (e.g.: memory, shmsize). If you use the respective configuration options for build options natively supported by the build configuration (i.e. noCache, cleanup=remove for buildoption forcerm=1 and args for build args) then these will override any corresponding options given here. The key-value syntax is the same as when defining environment variables or labels as described in Setting Environment Variables and Labels.

cleanup

Cleanup dangling (untagged) images after each build (including any containers created from them). Default is try which tries to remove the old image, but doesn’t fail the build if this is not possible because e.g. the image is still used by a running container. Use remove if you want to fail the build and none if no cleanup is requested.

contextDir

Path to a directory used for the build’s context. You can specify the Dockerfile to use with dockerFile, which by default is the Dockerfile found in the contextDir. The Dockerfile can be also located outside of the contextDir, if provided with an absolute file path. See External Dockerfile for details.

cmd

A command to execute by default (i.e. if no command is provided when a container for this image is started). See Startup Arguments for details.

compression

The compression mode how the build archive is transmitted to the docker daemon (k8sBuild) and how docker build archives are attached to this build as sources. The value can be none (default), gzip or bzip2.

dockerFile

Path to a Dockerfile which also triggers Dockerfile mode. See External Dockerfile for details.

dockerArchive

Path to a saved image archive which is then imported. See Docker archive for details.

entryPoint

An entrypoint allows you to configure a container that will run as an executable. See Startup Arguments for details.

env

The environments as described in Setting Environment Variables and Labels.

filter

Enable and set the delimiters for property replacements. By default properties in the format ${..} are replaced with Gradle properties. You can switch off property replacement by setting this property to false. When using a single char like @ then this is used as a delimiter (e.g @…​@). See Filtering for more details.

from

The base image which should be used for this image. If not given this default to busybox:latest and is suitable for a pure data image.

fromExt

Extended definition for a base image. This field holds a map of defined in key = "value" format. The known keys are:

  • name : Name of the base image

A provided from takes precedence over the name given here. This tag is useful for extensions of this plugin.

imagePullPolicy

Specific pull policy for the base image. This overwrites any global pull policy. See the global configuration option imagePullPolicy for the possible values and the default.

labels

Labels as described in Setting Environment Variables and Labels.

maintainer

The author (MAINTAINER) field for the generated image

noCache

Don’t use Docker’s build cache. This can be overwritten by setting a system property docker.noCache when running Gradle.

cacheFrom

A list of image elements specifying image names to use as cache sources.

optimise

if set to true then it will compress all the runCmds into a single RUN directive so that only one image layer is created.

ports

The exposed ports which is a list of port elements, one for each port to expose. Whitespace is trimmed from each element and empty elements are ignored. The format can be either pure numerical ("8080") or with the protocol attached ("8080/tcp").

shell

Shell to be used for the runCmds. It contains arg elements which are defining the executable and its params.

runCmds

Commands to be run during the build process. It contains run elements which are passed to the shell. Whitespace is trimmed from each element and empty elements are ignored. The run commands are inserted right after the assembly and after workdir into the Dockerfile.

skip

if set to true disables building of the image. This config option is best used together with a gradle property

skipTag

If set to true this plugin won’t add any tags to images.

tags

List of additional tag elements with which an image is to be tagged after the build. Whitespace is trimmed from each element and empty elements are ignored.

user

User to which the Dockerfile should switch to the end (corresponds to the USER Dockerfile directive).

volumes

List of volume elements to create a container volume. Whitespace is trimmed from each element and empty elements are ignored.

workdir

Directory to change to when starting the container.

4.4. Assembly

The assembly element within build element defines how build artifacts and other files can be added to the Docker image.

Table 9. Assembly Configuration (image : build )
Element Description

name

Assembly name, which is maven by default. This name is used for the archives and directories created during the build. This directory holds the files specified by the assembly. If an external Dockerfile is used then this name is also the relative directory which contains the assembly files.

targetDir

Directory under which the files and artifacts contained in the assembly will be copied within the container. The default value for this is ${assembly.name}, so /maven if name is not set to a different value.

inline

Deprecated: Use layers instead Inlined assembly descriptor as described in Assembly - Inline below.

layers

Each of the layers that the assembly will contain as described in Assembly - Layer below.

exportTargetDir

Specification whether the targetDir should be exported as a volume. This value is true by default except in the case the targetDir is set to the container root (/). It is also false by default when a base image is used with from since exporting makes no sense in this case and will waste disk space unnecessarily.

excludeFinalOutputArtifact

By default, the project’s final artifact will be included in the assembly, set this flag to true in case the artifact should be excluded from the assembly.

mode

Mode how the how the assembled files should be collected:

  • dir : Files are simply copied (default),

  • tar : Transfer via tar archive

  • tgz : Transfer via compressed tar archive

  • zip : Transfer via ZIP archive

The archive formats have the advantage that file permission can be preserved better (since the copying is independent from the underlying files systems)

permissions

Permission of the files to add:

  • ignore to use the permission as found on files regardless on any assembly configuration

  • keep to respect the assembly provided permissions

  • exec for setting the executable bit on all files (required for Windows when using an assembly mode dir)

  • auto to let the plugin select exec on Windows and keep on others.

keep is the default value.

tarLongFileMode

Sets the TarArchiver behaviour on file paths with more than 100 characters length. Valid values are: "warn"(default), "fail", "truncate", "gnu", "posix", "posix_warn" or "omit"

user

User and/or group under which the files should be added. The user must already exist in the base image.

It has the general format user[:group[:run-user]]. The user and group can be given either as numeric user- and group-id or as names. The group id is optional.

If a third part is given, then the build changes to user root before changing the ownerships, changes the ownerships and then change to user run-user which is then used for the final command to execute. This feature might be needed, if the base image already changed the user (e.g. to 'jboss') so that a chown from root to this user would fail.

For example, the image jboss/wildfly use a "jboss" user under which all commands are executed. Adding files in Docker always happens under the UID root. These files can only be changed to "jboss" is the chown command is executed as root. For the following commands to be run again as "jboss" (like the final standalone.sh), the plugin switches back to user jboss (this is this "run-user") after changing the file ownership. For this example a specification of jboss:jboss:jboss would be required.

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

4.4.1. Assembly - Inline/Layer

Inlined assembly description with a format very similar to Maven Assembly Plugin.

Partial configuration example of an inline/layer element
assembly {
    targetDir = "/deployments"
    layers = [{
        fileSets = [{
            directory = file("${project.rootDir}/build/dependencies")
            outputDirectory = "static"
       }]
    }]
}

The layers element within the assembly element can have one or more layer elements with a Groovy DSL structure that supports the following configuration options:

Table 10. Assembly - Inline/Layer (image : build : assembly )
Element Description

id

Unique ID for the layer.

files

List of files for the layer.

Each file has the following fields:

  • source: Absolute or relative path from the project’s directory of the file to be included in the assembly.

  • outputDirectory: Output directory relative to the root of the root directory of the assembly.

  • destName: Destination filename in the outputDirectory.

  • fileMode: Similar to a UNIX permission, sets the file mode of the file included.

fileSets

List of filesets for the layer.

Each fileset has the following fields:

  • directory: Absolute or relative location from the project’s directory.

  • outputDirectory: Output directory relative to the root of the root directory of the assembly fileSet.

  • includes: A set of files and directories to include.

    • If none is present, then everything is included.

    • Files can be referenced by using their complete path name.

    • Wildcards are also supported, patterns will be matched using FileSystem#getPathMatcher glob syntax.

  • excludes: A set of files and directory to exclude.

    • If none is present, then there are no exclusions.

    • Wildcards are also supported, patterns will be matched using FileSystem#getPathMatcher glob syntax.

  • fileMode: Similar to a UNIX permission, sets the file mode of the files included.

  • directoryMode: Similar to a UNIX permission, sets the directory mode of the directories included.

baseDirectory

Base directory from which to resolve the Assembly’s layer files and filesets.

4.5. Environment and Labels

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

Example
env {
    JAVA_HOME = "/opt/jdk8"
    CATALINA_OPTS = "-Djava.security.egd=file:/dev/./urandom"
}

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:

Example
labels {
     labelWithValue = "foo"
     version = "${project.version}"
     artifactId = "${project.name}"
}

4.6. Startup Arguments

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.

See this stackoverflow question for a detailed explanation.

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

Table 11. Entrypoint and Command Configuration
Mode Description

shell

Shell form in which the whole line is given to shell -c for interpretation.

exec

List of arguments (with inner <args>) arguments which will be given to the exec call directly without any shell interpretation.

Either shell or params should be specified.

Example
entryPoint {
    // Shell Form
    shell = 'java -jar maven/hello-world-1.5.1.jar'
}

or

Example
entryPoint {
    // exec form
    exec = ['java','-jar','maven/hello-world-1.5.1.jar']
}
INFO

Startup arguments are not used in S2I builds

4.7. Build Args

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:

  • Set a system property when running Gradle, eg.: -Ddocker.buildArg.http_proxy=http://proxy:8001. This is especially useful when using predefined Docker arguments for setting proxies transparently.

  • Set a project property within the build.gradle, eg.:

Example
docker.buildArg.myBuildArg = myValue

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.

4.8. Kubernetes Resources Configuration

This section includes Groovy DSL configuration options you can use to tweak generated Kubernetes manifests.

4.8.1. Labels/Annotations

Table 12. Label and annotation configuration
Element Description

all

All entries specified in the all sections are applied to all resource objects created.

deployment

Labels and annotations applied to Deployment (for Kubernetes).

pod

Labels and annotations applied pod specification as used in ReplicationController, ReplicaSets, Deployments and DeploymentConfigs objects.

replicaSet

Labels and annotations applied to ReplicaSet and ReplicationController objects.

service

Labels and annotations applied to Service objects.

ingress

Labels and annotations applied to Ingress objects.

serviceAccount

Labels and annotations applied to ServiceAccount objects.

4.8.2. Controllers

A Controller resource is a Kubernetes resource which manages Pods created for your application. It can be one of these options:

Here are the fields available in resources Groovy DSL configuration that would work with k8sResource:

Table 13. resources fields for configuring generated controllers
Element Description

env

Environment variables which will be added to containers in Pod template spec.

volumes

Configuration element for adding volume mounts to containers in Pod template spec

controllerName

Name of the controller resource(i.e. Deployment, ReplicaSet, StatefulSet etc) generated

liveness

Configuration element for adding a liveness probe

readiness

Configuration element for adding readiness probe

containerPrivileged

Run container in privileged mode. Sets privileged: true in generated Controller’s PodTemplateSpec

imagePullPolicy

How images should be pulled (maps to ImagePullPolicy).

replicas

Number of replicas to create

serviceAccount

ServiceAccount name which will be used by pods created by controller resources(e.g. Deployment, ReplicaSet etc)

Probe Groovy DSL Configuration

Probe configuration is used for configuring liveness and readiness probes for containers. Both liveness and readiness probes the following options:

Table 14. Groovy DSL Probe configuration
Element Description

initialDelaySeconds

Initial delay in seconds before the probe is started.

timeoutSeconds

Timeout in seconds how long the probe might take.

exec

Command to execute for probing.

getUrl

Probe URL for HTTP Probe. Configures HTTP probe fields like host, scheme, path etc by parsing URL. For example, a getUrl = "http://:8080/health" would result in probe generated with fields set like this:

host: ""

path: /health

port: 8080

scheme: HTTP

Host name with empty value defaults to Pod IP. You probably want to set "Host" in httpHeaders instead.

tcpPort

TCP port to probe.

failureThreshold

When a probe fails, Kubernetes will try failureThreshold times before giving up

successThreshold

Minimum consecutive successes for the probe to be considered successful after having failed.

httpHeaders

Custom headers to set in the request.

periodSeconds

How often in seconds to perform the probe. Defaults to 10 seconds. Minimum value is 1.

Volume Groovy DSL Configuration

volumes field contains a list of volume configurations. Different configurations are supported in order to support different Volumes in Kubernetes.

Here are the options supported by a single volume :

Table 15. Groovy DSL volume configuration
Element Description

type

type of Volume

name

name of volume to be mounted

mounts

List of mount paths of this volume.

path

Path for volume

medium

medium ,applicable for Volume type emptyDir

repository

repository ,applicable for Volume type gitRepo

revision

revision ,applicable for Volume type gitRepo

secretName

Secret name ,applicable for Volume type secret

server

Server name, applicable for Volume type nfsPath

readOnly

Whether it’s read only or not

pdName

pdName, applicable for Volume type gcePdName

fsType

File system type for Volume

partition

partition, applicable for Volume type gcePdName

endpoints

endpoints, applicable for Volume type glusterFsPath

claimRef

Claim Reference, applicable for Volume type persistentVolumeClaim

volumeId

volume id

diskName

disk name, applicable for Volume type azureDisk

diskUri

disk uri, applicable for Volume type azureDisk

kind

kind, applicable for Volume type azureDisk

cachingMode

caching mode, applicable for Volume type azureDisk

hostPathType

Host Path type

shareName

Share name, applicable for Volume type azureFile

user

User name

secretFile

Secret File, applicable for Volume type cephfs

secretRef

Secret reference, applicable for Volume type cephfs

lun

LUN(Logical Unit Number)

targetWwns

target WWNs, applicable for Volume type fc

datasetName

data set name, applicable for Volume type flocker

portals

list of portals, applicable for Volume type iscsi

targetPortal

target portal, applicable for Volume type iscsi

registry

registry, applicable for Volume type quobyte

volume

volume, applicable for Volume type quobyte

group

group, applicable for Volume type quobyte

iqn

IQN, applicable for Volume type iscsi

monitors

list of monitors, applicable for Volume type rbd

pool

pool, applicable for Volume type rbd

keyring

keyring, applicable for Volume type rbd

image

image, applicable for Volume type rbd

gateway

gateway, applicable for Volume type scaleIO

system

system, applicable for Volume type scaleIO

protectionDomain

protection domain, applicable for Volume type scaleIO

storagePool

storage pool, applicable for Volume type scaleIO

volumeName

volume name, applicable for Volume type scaleIO and storageOS

configMapName

ConfigMap name, applicable for Volume type configMap

configMapItems

List of ConfigMap items, applicable for Volume type configMap

items

List of items, applicable for Volume type downwardAPI

4.8.3. Ingress

Here are the supported options while providing ingress in Groovy configuration

Table 16. ingress configuration
Element Description

ingressRules

IngressRule configuration

ingressTlsConfigs

Ingress TLS configuration

IngressRule Groovy Configuration

Here are the supported options while providing ingressRules in Groovy configuration

Table 17. ingressRule configuration
Element Description

host

Host name

paths

IngressRule path configuration

IngressRule Path Groovy Configuration

Here are the supported options while providing paths in Groovy DSL configuration

Table 18. IngressRule path Groovy DSL configuration
Element Description

pathType

type of Path

path

path

serviceName

Service name

servicePort

Service port

resource

Resource reference in Ingress backend

IngressRule Path Resource Groovy Configuration

Here are the supported options while providing resource in IngressRule’s path Groovy configuration

Table 19. IngressRule Path resource Groovy configuration
Element Description

name

Resource name

kind

Resource kind

apiGroup

Resource’s apiGroup

IngressRule Path Resource Groovy Configuration

Here are the supported options while providing ingressTlsConfigs in IngressRule’s path Groovy configuration

Table 20. IngressTls ingressTlsConfig Groovy configuration
Element Description

secretName

Secret name

hosts

a list of string host objects

5. Registry handling

Docker uses registries to store images. The registry is typically specified as part of the name. I.e. if the first part (everything before the first /) contains a dot (.) or colon (:) this part is interpreted as an address (with an optionally port) of a remote registry. This registry (or the default docker.io if no registry is given) is used during push and pull operations. This plugin follows the same semantics, so if an image name is specified with a registry part, this registry is contacted. Authentication is explained in the next section.

There are some situations however where you want to have more flexibility for specifying a remote registry. This might be because you do not want to hard code a registry into build.gradle but provide it from the outside with an environment variable or a system property.

This plugin supports various ways of specifying a registry:

  • If the image name contains a registry part, this registry is used unconditionally and can not be overwritten from the outside.

  • If an image name doesn’t contain a registry, then by default the default Docker registry docker.io is used for push and pull operations. But this can be overwritten through various means:

    • If the image configuration contains a registry subelement this registry is used.

    • Otherwise, a global configuration element registry is evaluated which can be also provided as system property via -Djkube.docker.registry.

    • Finally an environment variable DOCKER_REGISTRY is looked up for detecting a registry.

This registry is used for pulling (i.e. for autopull the base image when doing a k8sBuild) and pushing with k8sPush. However, when these two tasks are combined on the command line like in mvn -Djkube.docker.registry=myregistry:5000 package k8sBuild k8sPush the same registry is used for both operation. For a more fine grained control, separate registries for pull and push can be specified.

  • In the plugin’s configuration with the parameters pullRegistry and pushRegistry, respectively.

  • With the system properties jkube.docker.pull.registry and jkube.docker.push.registry, respectively.

Example
kubernetes {
    registry = "docker.jolokia.org:443"
    images {
        image1 {
            // Without an explicit registry
            name = "jolokia/jolokia-java"
            // Hence use this registry
            registry = "docker.ro14nd.de"
        }
        image2 {
            name ="postgresql"
            // No registry in the name, hence use this globally
            // configured docker.jolokia.org:443 as registry
        }
        image3 {
            // Explicitly specified always wins
            name = "docker.example.com:5000/another/server"
        }
    }
}

There is some special behaviour when using an externally provided registry like described above:

  • When pulling, the image pulled will be also tagged with a repository name without registry. The reasoning behind this is that this image then can be referenced also by the configuration when the registry is not specified anymore explicitly.

  • When pushing a local image, temporarily a tag including the registry is added and removed after the push. This is required because Docker can only push registry-named images.

6. Registry Authentication

When pulling (via the autoPull mode of k8sBuild) or pushing image, it might be necessary to authenticate against a Docker registry.

There are five different locations searched for credentials. In order, these are:

  • Providing system properties jkube.docker.username and jkube.docker.password from the outside.

  • Using a authConfig section in the plugin configuration with username and password elements.

  • Using OpenShift configuration in ~/.config/kube

  • Login into a registry with docker login (credentials in a credential helper or in ~/.docker/config.json)

Using the username and password directly in the build.gradle is not recommended since this is widely visible. This is the easiest and transparent way, though. Using an authConfig is straight forward:

kubernetes {
    images {
        image {
            name = "consol/tomcat-7.0"
        }
    }
    authConfig {
        username = "jolokia"
        password = "s!cr!t"
    }
}

The system property provided credentials are a good compromise when using CI servers like Jenkins. You simply provide the credentials from the outside:

Example
gradle -Djkube.docker.username=jolokia -Djkube.docker.password=s!cr!t k8sPush

The most secure way is to rely on docker’s credential store or credential helper and read confidential information from an external credentials store, such as the native keychain of the operating system. Follow the instruction on the docker login documentation.

As a final fallback, this plugin consults $DOCKER_CONFIG/config.json if DOCKER_CONFIG is set, or ~/.docker/config.json if not, and reads credentials stored directly within this file. This unsafe behavior happened when connecting to a registry with the command docker login from the command line with older versions of docker (pre 1.13.0) or when docker is not configured to use a credential store.

6.1. Pull vs. Push Authentication

The credentials lookup described above is valid for both push and pull operations. In order to narrow things down, credentials can be provided for pull or push operations alone:

In an authConfig section a sub-section pull and/or push can be added. In the example below the credentials provider are only used for image push operations:

Example
kubernetes {
    images {
        image {
            name = "consol/tomcat-7.0"
        }
    }
    authConfig {
        push {
            username = "jolokia"
            password = "secret"
        }
    }
}

When the credentials are given on the command line as system properties, then the properties jkube.docker.pull.username / jkube.docker.pull.password and jkube.docker.push.username / jkube.docker.push.password are used for pull and push operations, respectively (when given). Either way, the standard lookup algorithm as described in the previous section is used as fallback.

7. Kind/Filename Mapping

7.1. Default Kind/Filename Mapping

Kind Filename Type

BuildConfig

bc, buildconfig

ClusterRole

cr, crole, clusterrole

ConfigMap

cm, configmap

ClusterRoleBinding

crb, clusterrb, clusterrolebinding

CronJob

cj, cronjob

CustomResourceDefinition

crd, customerresourcedefinition

DaemonSet

ds, daemonset

Deployment

deployment

DeploymentConfig

dc, deploymentconfig

ImageStream

is, imagestream

ImageStreamTag

istag, imagestreamtag

Ingress

ingress

Job

job

LimitRange

lr, limitrange

Namespace

ns, namespace

NetworkPolicy

np, networkpolicy

OAuthClient

oauthclient

PolicyBinding

pb, policybinding

PersistentVolume

pv, persistentvolume

PersistentVolumeClaim

pvc, persistentvolumeclaim

Project

project

ProjectRequest

pr, projectrequest

ReplicaSet

rs, replicaset

ReplicationController

rc, replicationcontroller

ResourceQuota

rq, resourcequota

Role

role

RoleBinding

rb, rolebinding

RoleBindingRestriction

rbr, rolebindingrestriction

Route

route

Secret

secret

Service

svc, service

ServiceAccount

sa, serviceaccount

StatefulSet

statefulset

Template

template

Pod

pd, pod

7.2. Custom Kind/Filename Mapping

You can add your custom Kind/Filename mappings. To do it you have two approaches:

  • Setting an environment variable or system property called jkube.mapping pointing out to a .properties files with pairs <kind>⇒filename1>, <filename2> By default if no environment variable nor system property is set, scan for a file located at classpath /META-INF/jkube.kind-filename-type-mapping-default.properties.

  • By embedding in task configuration the mapping:

kubernetes {
    mappings {
        mapping {
            kind = "Var"
            filenameTypes = "foo, bar"
        }
    }
}