Test & Doc: buildah-config --port syntax

[taqtiqa-mark]

Description
The current tests don't have any tests for port configuration.

This Redhat documentation suggests the syntax for adding a port includes the type decoration/tcp

# buildah config --port 80/tcp working-container

The current documentation is ambiguous.
It is also not documented how to add multiple ports some with different types, e.g. tcp or udp.

[rhatdan]

@TomSweeneyRedHat Could you look into this.
@taqtiqa-mark thanks for the feedback.

[taqtiqa-mark]

To give some detail bout the use case.
Composing an OCI using a library of scripts - to be open sourced once I can get a working Jupyter container. Now available here

source ./scripts/apline/3.7/h2o/buildah-config.sh
source ./scripts/apline/3.7/consul/buildah-config.sh
source ./scripts/apline/3.7/nomad/buildah-config.sh

So in fact all config items can be expected to be set multiple times.

What is the defined behavior for each config item, i.e. which are overwritten, which are appended.

Hope that makes sense?

[rhatdan]

So you are going to call the buildah config multiple times? I think we would have to experiment.
I could flip it on you and ask which ones would you expect to me appended versus replaced.

Options that are a slice should be able to be called multiple times and append while options that are a string/bool will be replaced. We probably should document this in the buildah config help and the man pages.

Slices:
Annotations
Env
Label
Port
Volume

All others will be replaced.

[taqtiqa-mark]

[Update 2:] Added behavior the OCI spec v1.0.1 would suggest. Subject to interpretation is indicated with (?).
[Update 1:] Use cases will develop over here and example repo's it points to. Hope this helps stimulate buildah uptake/adoption.

Thanks for considering this use case.

I think the most important behavior is that buildah should warn and continue when any config item exists and is being reset (overwritten or appended).
Exiting/abending could be optional if it is required. Or vice versa, as long as the 'Inform and continue' behavior is available.
Container configuration errors can/should be caught by someones unit and/or integration tests.

I think there is a world of pain ahead if buildah starts promising/trying to catch config errors/inconsistencies. GIGO is likely the best that can be promised/achieved.

As to which item is replaced and which is appended. I'll take whatever you decide ;)

which ones would you expect to me appended versus replaced

I assume the default behavior is "Inform/log and continue",
It seems there are three possible behaviors, append (slices), concatenate (strings), replace (slices, boolean and strings).

In the CLI I'd reduce these to replace and append.

The first column indicates behavior the OCI spec v1.0.1 suggests should be supported.
Looking at the current configuration items, maybe the simplest, least disruptive, and intuitive is something like:

OCI v1.0.1	Current (Proposed) Item	Current (?) Default Behavior	Proposed Extended Item	Proposed Extended Behavior
NA	annotation	Replace	NA	NA
Replace	arch	Replace	NA	NA
NA	author	Replace	NA	NA
Append	(authors)	Replace	authors-append	Concatenate (comma delimited)
Append	cmd[1]	Replace	cmd-append	Concatenate (space delimited)
See issue #595	created-by	Replace	created-by-append	Concatenate (comma delimited)
Replace	(description)	Replace	NA	NA
Replace	(documentation)	Replace	NA	NA
Append	entrypoint	Replace	entrypoint-append	Concatenate (space delimited)
Append	env	Replace	env-append	Append
NA	label	Replace	NA	NA
Append	(licenses)	Replace	licenses-append	SPDX License Expression
Replace	os	Replace	NA	NA
Append	port	Replace	port-append	Append
Replace	(ref-name)	Replace	NA	NA
Replace	(revision)	Replace	NA	NA
Replace	(source)	Replace	NA	NA
Replace	(title)	Replace	NA	NA
Replace	(url)	Replace	NA	NA
Replace	user	Replace	NA	NA
Replace	(vendor)	Replace	NA	NA
Replace	(version)	Replace	NA	NA
Append	volume	Replace	volume-append	Append (comma delimiter?)
Replace	workingdir	Replace	NA	NA

[1] This is tricky, I can envision use cases where you do want to build up the parameters that are passed to the entry point - concatenate. Other use cases where the parameter handed to the entrypoint should be the last seen (replace).

[2] Must follow the annotation rules

My 2c.

Hope that helps.

[rhatdan]

Just getting back to this, buildah config --env a=b
appends if a does not exist, and replaces a's value with b if it did exist.

[rhatdan]

@taqtiqa-mark Is this still something we should look at?

[rhatdan]

Lack of response closing.