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 like jar files, installers, etc. In most cases you will want to add files into the image and use them during 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. Currently supported algorithms are: md5, sha1 and sha256. If no algorithm is provided, artifact will be fetched every time.
All artifacts are automatically cached during an image build. To learn more about cache please take a look at Artifact Caching
The output name for downloaded resources will match the target
attribute, which defaults to
the base name of the file/URL.
Note
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.
Plain¶
This is the easiest way of defining an artifact. You are just specifying its name and md5 checksum. This approach relies on Artifact Caching to provide the artifact in cache. This section should be used to show that a particular artifact is needed for the image but its not publicly available.
artifacts:
- name: jolokia-1.3.6-bin.tar.gz
md5: 75e5b5ba0b804cd9def9f20a70af649f
target: jolokia.jar
Note
See Red Hat Environment for a description how Plain Artifacts are affected by Red Hat switch.
URL¶
This way of defining repository ask Cekit to download and artifact from a specified URL.
artifacts:
- 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
Path¶
This way of defining artifact is mostly used in development overrides and enables you to inject an artifact from a local filesystem.
artifacts:
- name: jolokia-1.3.6-bin.tar.gz
path: local-artifacts/jolokia-1.3.6-bin.tar.gz
md5: 75e5b5ba0b804cd9def9f20a70af649f
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
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
- URL
- ContentSets
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"
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
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
Content sets¶
Content sets are tightly integrated to OSBS style of defining repositories in content_sets.yml
file.
If this kind of repository is present in the image descriptor it overrides all other repositories types.
For local Docker based build these repositories are ignored similarly to Plain repository types and
we expect repository definitions to be available inside image. See
upstream docs for more details about
content sets.
Note
Behavior of Content sets repositories is changed when running in Red Hat Environment.
There are two possibilities how to define Content sets type of repository:
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"
OSBS¶
This section represents object we use to hint OSBS builder with a configuration which needs to be tweaked for successful and reproducible builds.
It contains two main keys:
repository
configuration
Repository¶
This key serves as a hint which DistGit repository and its branch we use to push generated sources into.
Example:
osbs:
repository:
name: containers/redhat-openjdk-18
branch: jb-openjdk-1.8-openshift-rhel-7
Configuration¶
This key is holding OSBS container.yaml
file ( :ref:`docs<https://osbs.readthedocs.io/en/latest/users.html?highlight=container.yaml#image-configuration>`_ )
container.yaml
file can be embedded in container
key or inject from a file specified in container_file
key.