Module descriptor

Module descriptor contains all information Cekit needs to introduce a feature to an image. Modules are used as libraries or shared building blocks across images.

It is very important to make a module self-containg which means that executing scripts defined in the module’s definition file should always end up in a state where you could define the module as being installed.

Modules can be stacked – some modules will be run before, some after you module. Please keep that in mind that at the time when you are developing a module – you don’t know how and when it’ll be executed.


This key is required.

Module name.

name: "python_flask_module"


This key is required.

Version of the image.

version: "1.4"


Short summary of the image.

Value of the description key is added to the image as two labels: description and summary unless such labels are already defined in the image descriptor’s Labels section.

description: "Red Hat JBoss Enterprise Application 7.0 - An application platform for hosting your apps that provides an innovative modular, cloud-ready architecture, powerful management and automation, and world class developer productivity."


This key is required.

Base image of your image.

from: "jboss-eap-7-tech-preview/eap70:1.2"

Environment variables

Similar to labels – we can specify environment variables that should be present in the container after running the image. We provide envs section for this.

Environment variables can be divided into two types:

  1. Information environment variables – these are set and available in the image. This type of environment variables provide information to the image consumer. In most cases such environment variables should not be modified.

  2. Configuration environment variables – this type of variables are used to define environment variables used to configure services inside running container.

    These environment variables are not set during image build time but can be set at run time.

    Every configuration enviromnent variable should provide an example usage (example) and short description (description).

Please note that you could have an environment variable with both: a value and example set. This suggest that this environment variable could be redefined.


Configuration environment variables (without value) are not generated to the build source. These can be used instead as a source for generating documentation.

    - name: "STI_BUILDER"
      value: "jee"
      value: "org.jboss.logmanager,jdk.nashorn.api"
      example: "myproject"
      description: "Clustering project namespace."
      example: "application=eap-app"
      description: "Clustering labels selector."



Learn more about standard labels in container images.

Every image can include labels. Cekit makes it easy to do so with the labels section.

    - name: "io.k8s.description"
      value: "Platform for building and running JavaEE applications on JBoss EAP 7.0"
    - name: "io.k8s.display-name"
      value: "JBoss EAP 7.0"


It’s common for images to require external artifacts. In most cases you will want to add files into the image and use them at the image build process.

Artifacts section is meant exactly for this. Cekit will automatically fetch any artifacts specified in this section and check their consistency by computing checksum of the downloaded file and comparing it with the desired value. The output name for downloaded resources will match the name attribute, which defaults to the base name of the file/URL. Artifact locations may be specified as urls, paths or git references.


If you are using relative path to define an artifact, path is considered relative to an image descriptor which introduced that artifact.

Example: If an artifact is defined inside /foo/bar/image.yaml with a path: baz/ the artifact will be resolved as /foo/bar/baz/

      # File will be downloaded and verified.
    - name: jolokia-1.3.6-bin.tar.gz
      md5: 75e5b5ba0b804cd9def9f20a70af649f

      # File exists on local machine relative to this file. Checksum will be verified.
      # The "name" attribute defaults to: "hawkular-javaagent-1.0.0.CR4-redhat-1-shaded.jar"
    - path: local-artifacts/hawkular-javaagent-1.0.0.CR4-redhat-1-shaded.jar
      md5: e133776c76a474ed46ac88c856eabe34

      # git project will be cloned
      # "name" attribute defaults to "project"
    - git:
          ref: master


Currently supported algorithms are: md5, sha1 and sha256. If no algorithm is provided, artifact will be fetched every time.

For artifacts that are not publicly available Cekit provides a way to add a description detailing a location from which the artifact can be obtained.

    - path:
      md5: 9a5d37631919a111ddf42ceda1a9f0b5
      description: "Red Hat JBoss EAP 6.4.0 distribution available on Customer Portal:"

If Cekit is not able to download an artifact and this artifact has a description defined – the build will fail but a message with the description will be printed together with information on where to place the manually downloaded artifact.


All artifacts are automatically cached during an image build. To learn more about cache please take a look at Artifact Caching


To install additional RPM packages you can use the packages section where you specify package names and repositories to be used.

        - mongodb24-mongo-java-driver
        - postgresql-jdbc
        - mysql-connector-java
        - maven
        - hostname

Packages are defined in the install subsection.


Cekit uses all repositories configured inside the image. You can also specify additional repositories using repositories subsection. Cekit currently supports following multiple ways of defining additional repositories:

  • Plain
  • RPM
  • ODCS
  • URL


See Repository mangement to learn about best practices for repository definitions.


This is the default option. With this approach you specify repository id and Cekit will not perform any action and expect the repository definition exists inside the image. This is useful as a hint which repository must be present for particular image to be buildable. The definition can be overridden by your preferred way of injecting repositories inside the image.

        - name: extras
          id: rhel7-extras-rpm
          description: "Repository containing extras RHEL7 extras packages"


Behavior of plain repositories is changed when running in Red Hat Environment.


This ways is using repository configuration files and related keys packaged as an RPM.

Example: To enable CentOS SCL inside the image you should define repository in a following way:

        - name: scl
          rpm: centos-release-scl


This way is instructs ODCS to generate on demand pulp repositories. To use ODCS define repository section in following way:

        - name: Extras
              repository: rhel-7-extras-rpm


Only on demand pulp ODCS repositories are supported now.


This approach enables you to download a yum repository file and corresponding GPG key. To do it, define repositories section in a way of:

        - name: foo
            repository: https://web.example/foo.repo
            gpg: https://web.exmaple/foo.gpg


This section is used to mark which ports should be exposed in the container. If we want to highlight a port used in the container, but not necessary expose it – we should set the expose flag to false (true by default).

You can provide additional documentation as to the usage of the port with the keys protocol, to specify which IP protocol is used over the port number (e.g TCP, UDP…) and service to describe what network service is running on top of the port (e.g. “http”, “https”). You can provide a human-readable long form description of the port with the description key.

    - value: 8443
      service: https
    - value: 8778
      expose: false
      protocol: tcp
      description: internal port for frob communication.


Specifies the user (can be username or uid) that should be used to launch the entrypoint process.

    user: "alice"


In case you want to define volumes for your image, just use the volumes section!

    - name: "volume.eap"
      path: "/opt/eap/standalone"


The name key is optional. If not specified the value of path key will be used.


Module repositories

Module repositories specify location of modules that are to be incorporated into the image. These repositories may be git repositories or directories on the local file system (path). Cekit will scan the repositories for module.xml files, which are used to encapsulate image details that may be incorporated into multiple images.

      # Modules pulled from Java image project on GitHub
    - git:
          ref: 1.0

      # Modules pulled locally from "custom-modules" directory, collocated with image descriptor
    - path: custom-modules

Module installation

The install section is used to define what modules should be installed in the image in what order. Name used to specify the module is the name field from the module descriptor.

      - name:
      - name: xpaas.amq.install

You can even request specific module version via version key as follows:

      - name:
        version: 1.2-dev
      - name: xpaas.amq.install


Sets the current working directory of the entrypoint process in the container.

    workdir: "/home/jboss"


The run section encapsulates instructions related to launching main process in the container including: cmd, entrypoint, user and workdir. All subsections are described later in this paragraph.

Below you can find full example that uses every possible option.

        - "argument1"
        - "argument2"
        - "/opt/eap/bin/"
    user: "alice"
    workdir: "/home/jboss"


Command that should be executed by the container at run time.

        - "some cmd"
        - "argument"


Entrypoint that should be executed by the container at run time.

        - "/opt/eap/bin/"


Execute section defines what needs to be done to install this module in the image. Every execution listed in this section will be run at image build time in the order as defined.

      # The file will be executed first as root user
    - script:
      # Then the file will be executed as jboss user
    - script:
      user: jboss


When no user is defined, root user will be used to execute the script.