Image descriptor¶
Image descriptor contains all information Cekit needs to build and test a container image.
Contents
Name¶
This key is required.
Image name without the registry part.
name: "jboss-eap-7/eap70-openshift"
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."
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:
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.
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 url
s,
path
s 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
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.
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
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"