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
andsha512
.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 thename
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 thename
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, usetarget
key as explained above. In order to get maximum control over the target artifact naming, you should use bothdest
andtarget
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.
{
"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"
}
}
}
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.
{
"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.
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.
Path artifacts#
This way of defining artifacts is mostly used in development overrides and enables you to inject artifacts from a local filesystem.
{
"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.
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.
{
"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.
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
.
{
"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"
}
}
}
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