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.

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