source.variant vs image.variant confusion

[nbuwe]

There seems to be some confusion w.r.t. source.variant and image.variant and I think I've ended up getting it wrong while working on PR-#904, but I think that's b/c I looked at the wrong selection of examples. The notes below are a bit all over the place - apologies if the narration falls apart, but I hope they demonstrate the problem.

source.md documents source.variant as:

The variant field is only used in a few distributions and defaults to default.

image.md documents image.variant as:

The variant field can be anything and is used in the Incus metadata as well as for filtering.

However note, that shared/definition.go sets the image's variant to "default":

distrobuilder/shared/definition.go

Lines 330 to 333 in 2d568eb

	// Set default variant
	if d.Image.Variant == "" {
	d.Image.Variant = "default"
	}

And different sources look at different "variant"s. E.g. Ubuntu checks the one from the image:

distrobuilder/sources/ubuntu-http.go

Lines 39 to 42 in 2d568eb

	switch strings.ToLower(s.definition.Image.Variant) {
	case "default":
	baseURL = fmt.Sprintf("%s/releases/%s/release/", s.definition.Source.URL,
	s.definition.Image.Release)

while apertis-http.go seems to use both source:

distrobuilder/sources/apertis-http.go

Lines 50 to 51 in 2d568eb

	baseURL = fmt.Sprintf("%s/%s/%s",
	s.definition.Source.URL, s.definition.Source.Variant, release)

and (a few lines down) image:

distrobuilder/sources/apertis-http.go

Lines 59 to 62 in 2d568eb

	baseURL = fmt.Sprintf("%s/%s/%s/%s/",
	baseURL, exactRelease, s.definition.Image.ArchitectureMapped, s.definition.Image.Variant)
	fname := fmt.Sprintf("ospack_%s-%s-%s_%s.tar.gz",
	release, s.definition.Image.ArchitectureMapped, s.definition.Image.Variant, exactRelease)

I looked at the Ubuntu example, so I used image in my Alpaquita PR, but aside from the above all other sources use source.variant (which defaults to an empty string, despite what docs claim - see above) e.g.:

distrobuilder/sources/debootstrap.go

Lines 26 to 28 in 2d568eb

	if s.definition.Source.Variant != "" {
	args = append(args, "--variant", s.definition.Source.Variant)
	}

At least all the filtering code consistently use image.variant for variants filters. apertis seems to be confused, and only ubuntu faces potential issues when the same variant (image.variant) value is used both for source selection and for filtering and there's a risk of breaking existing configs that currently happen to work.

[stgraber]

Yeah, would make sense to clean this up and line it up with the documentation.

Effectively using source.variant anywhere where a different source tarball or environment must be used and keeping the image.variant solely for image metadata and as the filter for the other config sections (for example, when applying a file or action section only for a desktop variant image).