Image descriptor¶

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

Name¶

Key: name
Required: Yes

Image name without the registry part.

Example

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

Version¶

Key: version
Required: Yes

Version of the image.

version: "1.4"

Description¶

Key: description
Required: No

Short summary of the image.

Value of the description key is added to the image as two labels:

description, and
summary.

Note

These labels are not added is these are already defined in the 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¶

Key: from
Required: Yes

Base image of your image.

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

Follow Tag¶

Key: follow_tag
Required: No

Used to denote an image to track the latest version of. This will then be used to replace the floating tag in the from image with the determined static tag. Only supported with redhat configuration option.

follow_tag: "registry.access.redhat.com/ubi8/ubi-minimal:latest"

Args¶

Key: args
Required: No

Every image can include arg instructions. See https://docs.docker.com/engine/reference/builder/#arg for more details. CEKit makes it easy to do so with the args section. An optional default value may be provided.

Note

ARGS will be rendered before any environment variables, labels or execution sections.

args:
    - name: "user1"
      value: "someuser"
    - name: "QUARKUS_EXTENSION"

Environment variables¶

Key: envs
Required: No

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.

It is possible to define a description for an information variable.
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.

The primary difference to the above type is the lack of a value definition. Every configuration environment variable should provide an example usage (example) and short description (description).

Note

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

Note

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

Note

Both forms support adding arbitrary additional keys. These are ignored by CEKit, but might be useful for documentation or other tooling.

envs:
    # Configuration env variables below
    # These will be added to container
    - name: "STI_BUILDER"
        value: "jee"
    - name: "JBOSS_MODULES_SYSTEM_PKGS"
        value: "org.jboss.logmanager,jdk.nashorn.api"

    # Information env variables below
    # These will NOT be defined (there is no value)
    - name: "OPENSHIFT_KUBE_PING_NAMESPACE"
        example: "myproject"
        description: "Clustering project namespace."
    - name: "OPENSHIFT_KUBE_PING_LABELS"
        example: "application=eap-app"
        description: "Clustering labels selector."

    # Both forms may have arbitrary additional metadata keys
    - name: "OPENSHIFT_KUBE_PING_LABELS"
        example: "application=eap-app"
        description: "Clustering labels selector."
        required: True
        execution-time: True

Labels¶

Key: labels
Required: No

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. An optional description may be provided.

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 some files into the image and use them during image build process.

Artifacts section is meant exactly for this. CEKit will try to automatically fetch any artifacts specified in this section.

If for some reason automatic fetching of artifacts is not an option for you, you should define artifacts as plain artifacts and use the cekit-cache command to add the artifact to local cache, making it available for the build process automatically. See Artifact caching chapter.

Artifact features¶

Checksums

Almost all artifacts will be checked for consistency by computing checksum of the fetched file and comparing it with the desired value. Currently supported algorithms are: md5, sha1, sha256 and sha512.

You can define multiple checksums for a single artifact. All specified checksums will be validated.

If no algorithm is provided, artifacts will be fetched every time.

This can be useful when building images with snapshot content. In this case you are not concerned about the consistency but rather focusing on rapid development. We advice that you define checksum when your content becomes stable.

Caching

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

Common artifact keys¶

name

Used to define unique identifier of the artifact.

The name key is very important. It’s role is to provide a unique identifier for the artifact. If it’s not provided, it will be computed from the resource definition, but we strongly suggest to provide the name keys always.

Value of this key does not need to be a filename, because it’s just an identifier used to refer the artifact. Using meaningful and unique identifiers is important in case when you want to use Overrides. It will make it much easier to refer the artifact and thus override it.

target

The output name for fetched resources will match the target attribute. If it is not defined then base name of the name attribute will be used. If it’s not provided either then base name of the path/URL will be used.

Below you can find a few examples.

artifacts:
    - name: jboss-eap-distribution
      path: jboss-eap-6.4.0.zip
      target: jboss-eap.zip

Target file name: jboss-eap.zip.

artifacts:
    - name: jboss-eap-distribution
      path: jboss-eap-6.4.0.zip

Target file name: jboss-eap-distribution.

artifacts:
    - path: jboss-eap-6.4.0.zip

Target file name: jboss-eap-6.4.0.zip.

dest

The dest key defines the destination directory where the particular artifact will be placed within the container image. By default it is set to /tmp/artifacts/.

The dest key specifies the directory path, to control file name, use target key as explained above. In order to get maximum control over the target artifact naming, you should use both dest and target together.

Examples:

artifacts:
    - name: jboss-eap-distribution
        path: jboss-eap-6.4.0.zip
        target: jboss-eap.zip

Target file path is: /tmp/artifacts/jboss-eap.zip.

artifacts:
    - name: jboss-eap-distribution
        path: jboss-eap-6.4.0.zip
        target: jboss-eap.zip
        dest: /opt

Target file path is: /opt/jboss-eap.zip.

Note

The default temporary directory (/tmp/artifacts/) will be cleaned up automatically after the build process is done meaning that artifacts are available only at the build time.

Artifacts using custom dest values are not affected.

Note

See scalar nodes for details on special case handling with overrides and common keys.

description

Describes the artifact. This is an optional key that can be used to add more information about the artifact.

Adding description to artifacts makes it much easier to understand what artifact it is just by looking at the image/module descriptor.

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 so that the build could be resumed.

Artifact types¶

CEKit supports following artifact types:

Plain artifacts
URL artifacts
Path artifacts
Image source artifacts
PNC artifacts

Plain artifacts¶

This is an abstract way of defining artifacts. The only required keys are name and the checksum. This type of artifacts is used to define artifacts that are not available publicly and instead provided by some (internal) systems.

Schema¶

{
    "map": {
        "description": {
            "desc": "Description of the resource",
            "type": "str"
        },
        "dest": {
            "default": "/tmp/artifacts/",
            "desc": "Destination directory inside of the container",
            "type": "str"
        },
        "md5": {
            "desc": "The md5 checksum of the resource",
            "type": "str"
        },
        "name": {
            "desc": "Key used to identify the resource",
            "required": true,
            "type": "str"
        },
        "sha1": {
            "desc": "The sha1 checksum of the resource",
            "type": "str"
        },
        "sha256": {
            "desc": "The sha256 checksum of the resource",
            "type": "str"
        },
        "sha512": {
            "desc": "The sha512 checksum of the resource",
            "type": "str"
        },
        "source-md5": {
            "desc": "The md5 checksum of the source resource",
            "type": "str"
        },
        "source-sha1": {
            "desc": "The sha1 checksum of the source resource",
            "type": "str"
        },
        "source-sha256": {
            "desc": "The sha256 checksum of the source resource",
            "type": "str"
        },
        "source-url": {
            "desc": "The source of the resource",
            "type": "str"
        },
        "target": {
            "desc": "Target file name for the resource",
            "type": "str"
        }
    }
}

Examples¶

artifacts:
    - name: jolokia
      md5: 75e5b5ba0b804cd9def9f20a70af649f
      target: jolokia.tar.gz

artifacts:
    - name: jolokia
      md5: 75e5b5ba0b804cd9def9f20a70af649f
      target: jolokia.tar.gz
      source-url: https://www.foo.com/jolokia-source.jar
      source-md5: 123456789

As you can see, the definition does not define from where the artifact should be fetched. This approach relies on Artifact caching to provide the artifact.

The source-url and source checksum (which may be source-md5, source-sha1 or source-sha256 are optional and denote where the sources may be found.

Note

See Red Hat environment for description how plain artifacts are used in the Red Hat environment.

URL artifacts¶

This is the simplest way of defining artifacts. You need to provide the url key which is the URL from where the artifact should be fetched from.

Schema¶

{
    "map": {
        "description": {
            "desc": "Description of the resource",
            "type": "str"
        },
        "dest": {
            "default": "/tmp/artifacts/",
            "desc": "Destination directory inside of the container",
            "type": "str"
        },
        "md5": {
            "desc": "The md5 checksum of the resource",
            "type": "str"
        },
        "name": {
            "desc": "Key used to identify the resource",
            "type": "str"
        },
        "sha1": {
            "desc": "The sha1 checksum of the resource",
            "type": "str"
        },
        "sha256": {
            "desc": "The sha256 checksum of the resource",
            "type": "str"
        },
        "sha512": {
            "desc": "The sha512 checksum of the resource",
            "type": "str"
        },
        "source-md5": {
            "desc": "The md5 checksum of the source resource",
            "type": "str"
        },
        "source-sha1": {
            "desc": "The sha1 checksum of the source resource",
            "type": "str"
        },
        "source-sha256": {
            "desc": "The sha256 checksum of the source resource",
            "type": "str"
        },
        "source-url": {
            "desc": "The source of the resource",
            "type": "str"
        },
        "target": {
            "desc": "Target file name for the resource",
            "type": "str"
        },
        "url": {
            "desc": "URL where the resource can be found",
            "required": true,
            "type": "str"
        }
    }
}

Tip

You should always specify at least one checksum to make sure the downloaded artifact is correct.

Examples¶

artifacts:
    - name: "jolokia"
      url: "https://github.com/rhuss/jolokia/releases/download/v1.3.6/jolokia-1.3.6-bin.tar.gz"
      # The md5 checksum of the artifact
      md5: "75e5b5ba0b804cd9def9f20a70af649f"

    - name: "jolokia"
      url: "https://github.com/rhuss/jolokia/releases/download/v1.3.6/jolokia-1.3.6-bin.tar.gz"
      # Free text description of the artifact
      description: "Library required to access server data via JMX"
      md5: "75e5b5ba0b804cd9def9f20a70af649f"
      # Final name of the downloaded artifact
      target: "jolokia.tar.gz"
      source-url: https://www.foo.com/jolokia-source.jar
      source-md5: 123456789

As you can see, the definition does not define from where the artifact should be fetched. This approach relies on Artifact caching to provide the artifact.

The source-url and source checksum (which may be source-md5, source-sha1 or source-sha256 are optional and denote where the sources may be found.

Note

See Environment Variables for information on how URL authentication may be configured.

Path artifacts¶

This way of defining artifacts is mostly used in development overrides and enables you to inject artifacts from a local filesystem.

Schema¶

{
    "map": {
        "description": {
            "desc": "Description of the resource",
            "type": "str"
        },
        "dest": {
            "default": "/tmp/artifacts/",
            "desc": "Destination directory inside of the container",
            "type": "str"
        },
        "md5": {
            "desc": "The md5 checksum of the resource",
            "type": "str"
        },
        "name": {
            "desc": "Key used to identify the resource",
            "type": "str"
        },
        "path": {
            "desc": "Relative (suggested) or absolute path to the resource",
            "required": true,
            "type": "str"
        },
        "sha1": {
            "desc": "The sha1 checksum of the resource",
            "type": "str"
        },
        "sha256": {
            "desc": "The sha256 checksum of the resource",
            "type": "str"
        },
        "sha512": {
            "desc": "The sha512 checksum of the resource",
            "type": "str"
        },
        "target": {
            "desc": "Target file name for the resource",
            "type": "str"
        }
    }
}

Tip

You should always specify at least one checksum to make sure the artifact is correct.

Examples¶

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

Image source artifacts¶

Image source artifacts are used in multi-stage builds. With image source artifacts you can define files built in previous stages of the multi-stage builds.

Schema¶

{
    "map": {
        "description": {
            "desc": "Description of the resource",
            "type": "str"
        },
        "dest": {
            "default": "/tmp/artifacts/",
            "desc": "Destination directory inside of the container",
            "type": "str"
        },
        "image": {
            "desc": "Name of the image which holds the resource",
            "required": true,
            "type": "str"
        },
        "name": {
            "desc": "Key used to identify the resource",
            "type": "str"
        },
        "path": {
            "desc": "Path in the image under which the resource can be found",
            "required": true,
            "type": "str"
        },
        "target": {
            "desc": "Target file name for the resource",
            "type": "str"
        }
    }
}

Note

Please note that image source artifacts do not allow for defining checksums due to the nature of this type of artifact.

Examples¶

artifacts:
    - name: application
      # Name of the image (stage) from where we will fetch the artifact
      image: builder
      # Path to the artifact within the image
      path: /path/to/application/inside/the/builder/image.jar

PNC artifacts¶

PNC artifacts are created via the ProjectNCL build system and are intended to be used with OSBS fetch-artifacts-pnc.yaml.

Schema¶

{
    "map": {
        "description": {
            "desc": "Description of the resource",
            "type": "str"
        },
        "dest": {
            "default": "/tmp/artifacts/",
            "desc": "Destination directory inside of the container",
            "type": "str"
        },
        "name": {
            "desc": "Key used to identify the resource",
            "type": "str"
        },
        "pnc_artifact_id": {
            "desc": "The ID of the artifact",
            "required": true,
            "type": "str"
        },
        "pnc_build_id": {
            "desc": "The ID of the build",
            "required": true,
            "type": "str"
        },
        "target": {
            "desc": "Target file name for the resource",
            "type": "str"
        },
        "url": {
            "desc": "Optional URL where the resource can be found",
            "type": "str"
        }
    }
}

Examples¶

artifacts:
    - name: jolokia
      pnc_build_id: 123456
      pnc_artifact_id: 00001
      target: jolokia.tar.gz
      # Optional URL to denote the link to the artifact
      url: https://www.pnc.build.system.com/builds/123456/jolokia-1.3.6-bin.tar.gz

Ports¶

Key: ports
Required: No

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

Volumes¶

Key: volumes
Required: No

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¶

Key: modules
Required: No

The modules section is responsible for defining module repositories and providing the list of modules to be installed in order.

modules:
    repositories:
        # Add local modules located next to the image descriptor
        # These modules are specific to the image we build and are not meant
        # to be shared
        - path: modules

        # Add a shared module repository located on GitHub. This repository
        # can contain several modules.
        - git:
            url: https://github.com/cekit/example-common-module.git
            ref: master

    # Install selected modules (in order)
    install:
        - name: jdk8
        - name: user
        - name: tomcat

Module repositories¶

Key: repositories
Required: No

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¶

Key: install
Required: No

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¶

Key: run
Required: No

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¶

Key: cmd
Required: No

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

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

Entrypoint¶

Key: entrypoint
Required: No

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

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

User¶

Key: user
Required: No

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

run:
    user: "alice"

Working directory¶

Key: workdir
Required: No

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

run:
    workdir: "/home/jboss"

Help¶

Key: help
Required: No

The help.md file functions as a container’s man page - see here for more information. At image build-time CEKit can generate a documentation page about the image. This file is a human-readable conversion of the resulting image descriptor. That is, a descriptor with all overrides and modules combined together, which was used to build the image.

If an image help page is requested to be added to the image (by setting the add key), a help.md is generated and added to the dist-git repository.

By default image help pages are not generated.

The default help template is supplied within CEKit. You can override it for every image via image definition. The optional help sub-section defines a key template, which can be used to define a filename to use for generating image documentation at build time. Note that if the template denotes a file without any substitution markers then effectively the file is copied to the dist-git repository as help.md verbatim.

help:
  add: true
  template: my_help.md

The template is interpreted by the Jinja2 template engine. For a simple example with a image descriptor containing:

schema_version: 1
name: test/image
version: 2
from: centos:7
...

and a help file (which may be named help.jinja, help.md etc) containing:

% {{ name }}

# NAME

Operator - My operator metadata for version {{ version }}

# USAGE

This container image can be used only as part of my operator.

will produce the following rendered Markdown file:

% test/image

# NAME

Operator - My operator metadata for version 2

# USAGE

This container image can be used only as part of my operator.

For a more detailed template example, see the default help.jinja supplied in the CEKit source code.

OSBS¶

Key: osbs
Required: No

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 five keys:

extra_dir
extra_dir_target
repository
koji_target
configuration

osbs:
    extra_dir: osbs-extra
    extra_dir_target: /
    repository:
        name: containers/redhat-openjdk-18
        branch: jb-openjdk-1.8-openshift-rhel-7
    koji_target: rhaos-middleware-rhel-7-containers-candidate
    configuration:
        gating_file: gating.yaml
        container:
            compose:
                pulp_repos: true

OSBS extra directory¶

Key: extra_dir
Required: No

If a directory name specified by extra_dir key will be found next to the image descriptor, this directory and its contents will be copied into the target directory and later to the dist-git directory.

Symbolic links are preserved (not followed).

Copying is done before generation, which means that files from the extra directory can be overridden in the generation phase .

Note

If you do not specify this key in image descriptor, the default value of osbs_extra will be used.

osbs:
    extra_dir: custom-files

OSBS extra copy command¶

Key: extra_dir_target
Required: No

This optional key is used in conjunction with extra_dir above. If this key is specified, then the extra_dir will be placed within the container image at the location denoted by extra_dir_target. If this is not set, no COPY commands will be added.

For example, with the value of / then the contents from dist-git will be copied to the root of the image filesystem

Dist-git source control¶

osbs-extra/
    foobar.yaml
    manifests/
        ...
    metadata/
        ...

CEKit Yaml file¶

osbs:
    extra_dir: osbs-extra
    extra_dir_target: /

Container image file system¶

/
    foobar.yaml
    manifests/
        ...
    metadata/
        ...

With the below example both a different source directory in dist-git and a different target directory within the container image is used.

Dist-git source control¶

custom-files/
    a-directory/
        ...

CEKit Yaml file¶

osbs:
    extra_dir: custom-files
    extra_dir_target: /image-user/tmp

Container image file system¶

/
    image-user/
        tmp/
            a-directory/
                ...

OSBS Repository¶

Key: repository
Required: No

This key serves as a hint which DistGit repository and its branch we use to push generated sources into.

osbs:
    repository:
        name: containers/redhat-openjdk-18
        branch: jb-openjdk-1.8-openshift-rhel-7

OSBS Koji target¶

Key: koji_target
Required: No

To execute a build in OSBS the Koji target parameter needs to be provided. By default it is constructed based on the branch name (see above), like this:

[BRANCH_NAME]-containers-candidate

In most cases this is what is expected, but sometimes you want to change this. An example of such situation is when you use a custom, private branch to execute a scratch build. Target can be overridden by specifying the koji_target key.

osbs:
    koji_target: rhaos-middleware-rhel-7-containers-candidate

OSBS Configuration¶

Key: configuration
Required: No

This key is holding OSBS container.yaml file. See OSBS docs for more information about this file.

CEKit supports two ways of defining content of the container.yaml file:

It can be embedded in container key, or
It can be injected from a file specified in container_file key.

Selecting preferred way of defining this configuration is up to the user. Maintaining external file may be handy in case where it is shared across multiple images in the same repository.

Embedding

In this case whole container.yaml file is embedded in an image descriptor under the container key.

# Embedding
osbs:
    configuration:
        # Configuration is embedded directly in the container key below
        container:
            compose:
                pulp_repos: true

Linking

In this case container.yaml file is read from a file located next to the image descriptor using the container_file key to point to the file.

osbs:
    configuration:
        # Configuration is available in the container.yaml file
        container_file: container.yaml

and container.yaml file content:

compose:
    pulp_repos: true

OSBS Gating Files¶

The gating.yaml file is used within the Container Verification Pipeline (CVP). Both live within the dist-git repository next to the Dockerfile. The configuration within CEKit is very similar to OSBS Configuration

Due to the CVP definition including custom tags embedded definitions are not supported ; instead the gating_file key should be used to specify the file to include.

For example:

osbs:
    configuration:
        gating_file: gating.yaml
        container:
            ...

Packages¶

Key: packages
Required: No

To install, reinstall or remove additional packages you can use the packages section where you specify package names and repositories to be used, as well as the package manager that is used to manage packages in this image. Note that in the generated image removal is performed before installation and reinstall is after installation.

Example package section for RPM-based distro¶

packages:
    repositories:
        - name: extras
            id: rhel7-extras-rpm
    manager: dnf
    manager_flags:
    remove:
        - dummy-package
    install:
        - mongodb24-mongo-java-driver
        - postgresql-jdbc
        - mysql-connector-java
        - maven
        - hostname
    reinstall:
        - tzdata

Example package section for Alpine Linux¶

packages:
    manager: apk
    install:
        - python3

Example package section for APT-based distro¶

packages:
    manager: apt-get
    install:
        - python3-minimal

Packages to install¶

Key: install
Required: No

Packages listed in the install section are marked to be installed in the container image.

packages:
    install:
        - mongodb24-mongo-java-driver
        - postgresql-jdbc

Packages to reinstall¶

Key: reinstall
Required: No

Packages listed in the reinstall section are marked to be reinstalled in the container image.

packages:
    reinstall:
        - tzdata

Packages to remove¶

Key: remove
Required: No

Packages listed in the remove section are marked to be removed from the container image.

packages:
    remove:
        - postgresql-jdbc

Package manager¶

Key: manager
Required: No

It is possible to define package manager used in the image used to install packages as part of the build process.

Currently available options are yum, dnf, microdnf, apt-get and apk.

Note

If you do not specify this key the default value is yum. If your image requires different package manager you need to specify it.

It is only possible to define a single package manager for an image (although multi-stage images may have different package managers). A package manager may be defined in a module or in an image (the latter takes precedence).

The default yum value will work fine on Fedora and RHEL images because OS maintains a symlink to the proper package manager.

Note

For yum, dnf and microdnf the flag --setopt=tsflags=nodocs is automatically added. For microdnf, the flag --setopt=install_weak_deps=0 is also added.

Note

For apt-get the flag --no-install-recommends is also added.

packages:
    manager: dnf
    install:
        - git

Package manager flags¶

This is an optional key. It is only needed to override the default package manager flag values. For example, with a package manager of microdnf. the default flags are --setopt=tsflags=nodocs --setopt=install_weak_deps=0.

packages:
    manager: microdnf
    manager_flags:

This will override the flags meaning that no flags are passed to microdnf.

packages:
    manager: microdnf
    manager_flags: --setopt=tsflags=nodocs

This will also override the flags but only add the single option which is useful for older microdnf versions (pre 3.4.0) which do not support extended setopt commands.

Package repositories¶

Key: repositories
Required: No

Warning

Some package repositories are supported only on specific distributions and package manager combinations. Please refer to documentation below!

CEKit uses all repositories configured inside the image. You can also specify additional repositories using repositories subsection.

Tip

See repository guidelines guide to learn about best practices for repository definitions.

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

Plain repository¶

Note

Available only on RPM-based distributions.

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 repository¶

Note

Available only on RPM-based distributions.

This way 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

Tip

The rpm key can also specify a URL to a RPM file:

packages:
    repositories:
        - name: epel
          rpm: https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

Warning

Images with microdnf do not not support installing from a remote URL. To work around this, the current recommended option is to use a module and use rpm -i to enable the new repo.

URL repository¶

Note

Available only on RPM-based distributions.

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

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

Content sets¶

Note

Available only on RPM-based distributions.

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.

Warning

Content sets can be defined only on the image level!

There are two possibilities how to define Content sets type of repository:

Embedded content sets¶

In this approach content sets are embedded inside image descriptor under the content_sets key.

packages:
    content_sets:
        x86_64:
        - server-rpms
        - server-extras-rpms

Linked content sets¶

In this approach Contet sets file is linked from a separate yaml file next to image descriptor via content_sets_file key.

Image descriptor:

packages:
    content_sets_file: content_sets.yml

content_sets.yml located next to image descriptor:

x86_64:
  - server-rpms
  - server-extras-rpms