Overrides¶
During an image life cycle there can be a need to do a slightly tweaked builds – using different base images, injecting newer libraries etc. We want to support such scenarios without a need of duplicating whole image sources.
To achieve this CEKit supports overrides mechanism for its descriptors. You can override anything from the descriptor. The overrides are based on overrides descriptor – a YAML object containing overrides for the image descriptor.
To use an override descriptor you need to pass --overrides-file
argument to
CEKit. This may be a path based object or a URL scheme (HTTP/HTTPS/file). You can also pass JSON/YAML
object representing changes directly via --overrides
command line argument.
- Example
Use
overrides.yaml
file located in current working directory$ cekit build --overrides-file overrides.yaml podman
- Example
Use
overrides.yaml
file located on a remote server$ cekit build --overrides-file https://example.com/overrides.yaml podman
- Example
Override a label via command line
$ cekit build --overrides '{"labels": [{"name": "foo", "value": "overridden"}]}' podman
Note
It is possible to specify YAML as well as JSON on the CLI e.g.
$ cekit -v build --overrides 'labels:
- name: foo
value: overridden' --dry-run podman
Overrides chaining¶
You can even specify multiple overrides. Overrides are resolved that last specified is the most important one. This means that values from last override specified overrides all values from former ones.
- Example
If you run following command, label
foo
will be set tobaz
.$ cekit build --overrides "{'labels': [{'name': 'foo', 'value': 'bar'}]} --overrides "{'labels': [{'name': 'foo', 'value': 'baz'}]}" podman
How overrides works¶
CEKit is using YAML format for its descriptors. Overrides in CEKit works on YAML node level.
Scalar nodes¶
Scalar nodes are easy to override, if CEKit finds any scalar node in an overrides descriptor it updates its value in image descriptor with the overridden one.
- Example
Overriding scalar node
# Image descriptor schema_version: 1 name: "dummy/example" version: "0.1" from: "busybox:latest"
# Override descriptor schema_version: 1 from: "fedora:latest"
# Resulting image descriptor schema_version: 1 name: "dummy/example" version: "0.1" from: "fedora:latest"
Sequence nodes¶
Sequence nodes are a little bit tricky, if they’re representing plain arrays, we cannot easily override any value so CEKit is just replacing the whole sequence.
- Example
Overriding plain array node.
# Image descriptor schema_version: 1 name: "dummy/example" version: "0.1" from: "busybox:latest" run: cmd: - "echo" - "foo"
# Override descriptor schema_version: 1 run: cmd: - "bar"
# Resulting image descriptor schema_version: 1 name: "dummy/example" version: "0.1" from: "busybox:latest" run: cmd: - "bar"
Mapping nodes¶
Mappings are merged via name
key. If CEKit is overriding a mapping or array of mappings
it tries to find a name
key in mapping and use and identification of mapping.
If two name
keys matches, all keys of the mapping are updated.
- Example
Updating mapping node.
# Image descriptor schema_version: 1 name: "dummy/example" version: "0.1" from: "busybox:latest" envs: - name: "FOO" value: "BAR"
# Override descriptor schema_version: 1 envs: - name: "FOO" value: "new value"
# Resulting image descriptor schema_version: 1 name: "dummy/example" version: "0.1" from: "busybox:latest" envs: - name: "FOO" value: "new value"
Removing keys¶
Overriding can result into need of removing a key from a descriptor. You can achieve this by overriding a key with a YAML null value.
You can use either the null
word or the tilde character: ~
to remove particular
key.
- Example
Remove value from a defined variable.
If you have a variable defined in a following way:
envs: - name: foo value: bar
you can remove
value
key via following override:envs: - name: foo value: ~
It will result into following variable definition:
envs: - name: foo
Warning
In some cases it will not be possible to remove the element and an error saying that
schema cannot be validated will be shown. If you run it again with verbose output enabled
(--verbose
) you will see required.novalue
messages.
Improvement to this behavior is tracked here: https://github.com/cekit/cekit/issues/460
Artifact Overrides¶
While artifact overrides function in general as per scalar nodes there is some
special case handling for merging for the common keys of target
and dest
and description
.
If the original definition contains a non-default destination e.g. /destination
and the override does not specify
a destination then the original value will be maintained rather than overwriting it with the default value of
/tmp/artifacts
.
If the original contains a target or description definition and the override does not specify a target/description then the original value will be maintained.
Examples¶
Maintain destination with plain override with new target
Original (URL artifact)¶name: 'bar.jar' dest: '/tmp/destination/' url: 'https://foo/original-bar.jar' target: 'original-bar.jar'
Overrides (Plain artifact)¶name: 'bar.jar' md5: 234234234234 target: 'bar2222.jar'
Result¶name: 'bar.jar' dest: '/tmp/destination/' md5: 234234234234 target: 'bar2222.jar'
Maintain destination and target with plain override: