Image descriptor

Image descriptor contains all information Cekit needs to build and test a container image.

Name

This key is required.

Image name without the registry part.

name: "jboss-eap-7/eap70-openshift"

Version

This key is required.

Version of the image.

version: "1.4"

Description

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."

From

This key is required.

Base image of your image.

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

help

The optional help sub-section defines a single key template, which can be used to define a filename to use for generating image documentation at build time. By default, a template supplied within Cekit is used.

At image build-time, the template is interpreted by the Jinja2 template engine. For a concrete example, see the default help.jinja supplied in the Cekit source code.

help:
  template: myhelp.jinja

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.

Note

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

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

Labels

Note

Learn more about standard labels in container images.

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

labels:
    - 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"

Artifacts

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.

Note

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/1.zip the artifact will be resolved as /foo/bar/baz/1.zip

artifacts:
      # File will be downloaded and verified.
    - name: jolokia-1.3.6-bin.tar.gz
      url: https://github.com/rhuss/jolokia/releases/download/v1.3.6/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:
          url: https://github.com/organization/project
          ref: master

Note

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.

artifacts:
    - path: jboss-eap-6.4.0.zip
      md5: 9a5d37631919a111ddf42ceda1a9f0b5
      description: "Red Hat JBoss EAP 6.4.0 distribution available on Customer Portal: https://access.redhat.com/jbossnetwork/restricted/softwareDetail.html?softwareId=37393&product=appplatform&version=6.4&downloadType=distributions"

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.

Note

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

Packages

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

packages:
    install:
        - mongodb24-mongo-java-driver
        - postgresql-jdbc
        - mysql-connector-java
        - maven
        - hostname

Packages are defined in the install subsection.

Repositories

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

Note

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

Plain

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.

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

Note

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

RPM

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:

packages:
    repositories:
        - name: scl
          rpm: centos-release-scl

ODCS

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

packages:
    repositories:
        - name: Extras
          odcs:
              repository: rhel-7-extras-rpm

Note

Only on demand pulp ODCS repositories are supported now.

URL

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

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

Ports

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.

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

User

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

run:
    user: "alice"

Volumes

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

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

Note

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

Modules

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:
  repositories:
      # Modules pulled from Java image project on GitHub
    - git:
          url: https://github.com/jboss-container-images/redhat-openjdk-18-openshift-image
          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.

modules:
  install:
      - name: xpaas.java
      - name: xpaas.amq.install

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

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

Workdir

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

run:
    workdir: "/home/jboss"

Run

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.

run:
    cmd:
        - "argument1"
        - "argument2"
    entrypoint:
        - "/opt/eap/bin/wrapper.sh"
    user: "alice"
    workdir: "/home/jboss"

Cmd

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

run:
    cmd:
        - "some cmd"
        - "argument"

Entrypoint

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

run:
    entrypoint:
        - "/opt/eap/bin/wrapper.sh"