Question: Tags vs Release version

[fenz]

I'm trying to understand how to use the tagging in the proper way.
As far as I got, an image tag for a container is in the name (in Singularity.pokemon should be pokemon) and the "release version" can be considered as a snapshot/SHA since you can update a tag (pokemon) and still want to have the possibility to use the previous "SHA".
I have to understand how to use this since I'm still a bit confused but I got even more confused when I looked at a shpc recipe: https://github.com/singularityhub/singularity-hpc/blob/main/registry/singularityhub/singularity-deploy/container.yaml
There it seems "tags" and "release versions" are used interchangeably ("salad" vs "0.0.12"):

latest:
  0.0.12: singularityhub/singularity-deploy
tags:
  0.0.12: singularityhub/singularity-deploy
  salad: 0.0.1

I know all of this is just a "template" which can be customized but I was wondering if you can try to clarify the difference between "tags" and "release versions" and how you suggest to use them.

[vsoch]

For Singularity deploy, a tag is a Singularity file extension that is then present in the container name (e.g Singularity.salad). And the digest is the GitHub release. Sorry for the confusion - the file you linked has a bug introduced by the auto update script! @alecbcs we will need to take a look! You can look at previous versions of the file to see the correct way to do it.

[fenz]

So I somehow got it right. Mentioning the GitHub release as "digest" makes it more clear in my opinion.
Now I was looking for a way to point to the "latest" digest of a certain tag but it seems not possible. That's anyway a different discussion. Thanks for the clarification.

[vsoch]

I think you're right - would you like to submit a PR to update the description in the README?

For latest, that's a hard question - it would have to be the tag associated with Singularity.latest. I completely made this up and it's still in more of a "proof of concept" stage, so if you have ideas for how we could do this, I will gladly update shpc to support it.

[alecbcs]

Oh interesting! This definitely comes down to a misunderstanding I had about singularity-deploy when writing Binoc's SHPC parser. I'd figured that tags would comes from the the git tags/releases rather than the file names. Since you can also make a git tag a moving target (although I wouldn't recommend it under most circumstances) have we thought about someone creating releases called latest and develop under GitHub and periodically moving the release pointers? For example they would re-release latest pointing at v0.0.1 and then later v0.0.2. Or does this not follow the Spec of Singularity deploy and thus we shouldn't worry about it?

@vsoch that was fast getting autamus/binoc#7 submitted!

[vsoch]

@alecbcs I do think we would want to have a clean strategy to deploy consistent (tags?) for latest and develop (or other) - are you thinking that we should refactor for a release to be a tag (e.g., 0.0.1, latest, or develop) and then within that tag, perhaps there would just be a known set of associated files? How would we represent the digest? Or would there be no digest, just the tag?

I'd like to improve how this is currently designed, so let's chat about how we can do that.

[alecbcs]

@vsoch hypothetically if we went the way of releases as tags that might be beneficial to encourage people to make good use of tags as versions rather than these moving targets we've had a hard time dealing with.

I think this might also be more in line with what we're doing when updating docker containers to versioned releases in shpc. Right now in shpc we're versioning containers tags like this,

docker: ghcr.io/autamus/abyss
url: https://github.com/orgs/autamus/packages/container/package/abyss
maintainer: '@vsoch'
description: ABySS is a de novo, parallel, paired-end sequence assembler that is designed
  for short reads.
latest:
  2.3.1: sha256:92b2975865998a0560f66d2120d224822e8e1ab350b606a0e308e1fbbbaecd9d
tags:
  2.3.0: sha256:92b2975865998a0560f66d2120d224822e8e1ab350b606a0e308e1fbbbaecd9d
  2.3.1: sha256:92b2975865998a0560f66d2120d224822e8e1ab350b606a0e308e1fbbbaecd9d
  latest: sha256:92b2975865998a0560f66d2120d224822e8e1ab350b606a0e308e1fbbbaecd9d

Which I believe is closer to using the versions as tags rather than digests? Basing the tags off of releases might also help make the container.yaml filters in shpc specs more applicable to singularity deploy by ignoring any releases that contain something like -rc1, -dev, etc....

As for what to do with the digests they could be the name of the file in the release pack?

This might complicate other parts of shpc or singularity deploy or might be that it isn't as intuitive for users. You've been in the singularity world much longer than I have so these are just some thoughts from my package management experience with Autamus.

[vsoch]

Nope i think this is spot on, and more intuitive than what we currently have. I don't think I have enough time today to do all the changes to singularity-deploy, shpc, and then binoc, but I can do this next weekend. Let's keep this issue open to work on it, and I'll ping here when I've made some progress!

[vsoch]

And @fenz thank you for opening this issue - I'll have it fixed up hopefully next weekend so using singularity-deploy is easier and more intuitive. Stay tuned!

[fenz]

Thanks for updating this. Indeed since "GitHub release" are also "GitHub tags" it starts to be confusing to look at them in a different way (compared to tag in container images). Moreover, I would rather prefer to have a list of releases for an image and not adding a file in the repo for each new release. This would also allow to manage the build in a different way since I think at the moment all the recipes are build when you do a release, no matter if you changed or not a certain recipe file.
Are you also thinking about keeping the different versions in different branches? So you could also be considering the "main" as just the "Bleeding edge" and all the "stable" releases are in a branch following a specific naming convention like "release/" (or anything customizable with a workflow parameter). I'm not a great git expert so I'm not saying that's the best approach but I feel that's something worth to investigate.

[vsoch]

One issue I'm thinking about is that, given that we use GitHub releases as tags, that means you can only associate one image with a release tag. It's probably akin to an issue we haven't addressed yet with architecture - there can be multiple digests for the same tag on Docker Hub or elsewhere for different architectures, and we currently just provide one. So if it's the case that one release == one container, and the release tag (e.g., 0.0.1) is associated with an exact (single) file that we could derive by way of parsing the release artifacts, I think this could work. But if we require multiple files per release tag, OR if the bot binoc cannot discover the name of the tag, then we have an issue. For shpc pull, the name of the binary in the release also needs to be predictable, so I am not sure doing something like a hash is an option.

Kind of struggling to figure out how to implement this - I made my current choices to use a tag as a Singularity. prefix and a digest as the GitHub release because of this exact need to support multiple tags (file extensions) per release cycle (GitHub tag).

[fenz]

Sorry for late reply. I'm not expert of building images for different architectures but would this not require a change/option add to the build command executed in the workflow?
Building for different architecture or even different base OS image (ex. ubuntu vs. centos) can possibly be done creating different recipes and generate different files in a specific release, but still I would threat release like a tag for the image.
Maybe you can add a "suffix" based on the name of the recipe:
github/myapp release 0.0.1

• Singularity.centos -> myapp:0.0.1-centos.sif
• Singularity.x86 -> myapp:0.0.1-x86.sif

In this case each release I will generate different "digests" for different recipes but the app tag/version will be still based on the release.
This could be also managed at branch level, so merge a PR to a "release/0.0.1" branch will generate the release "0.0.1" (but VERSION file can work as well).
I could be wrong but I feel this more aligned with a standard "release" concept where you can generate .tar/.zip/x86/arm/etc but all those file are part of a release X of a specific app.
In your example, the app "singularityhub-singularity-deploy", version "0.0.12", architecture/baseOS "pokemon" will be:

https://github.com/singularityhub/singularity-deploy/releases/download/0.0.12/singularityhub-singularity-deploy.pokemon.sif

I guess there's still the issue with defining a digest, I'm not sure if the "suffix" is enough as "digest". In this case you need also to define a "default/amd64" digest (in case of Singularity recipe with no suffix).

[vsoch]

@fenz if the tag in the above is 0.0.12 (the GitHub release) how would the image name be predicted / discovered?

[vsoch]

@alecbcs what about... if we can get the commit for a release (e.g., https://stackoverflow.com/questions/56724610/how-to-get-a-commit-sha-from-a-release-or-tag-on-github-api-v3/56753582) then we could possibly look at files: https://docs.github.com/en/rest/reference/repos#get-a-commit and then look for Singularity.<*> recipes. Of course if a release has more than one commit we would need to go back until the previous release (and stop before we parse it). That's how Singularity Hub used to derive changed recipes for a repo!

Of course that assumes that we only want to release changed recipes, which might not be the case. I guess the simple and silly approach (which is reasonable for a GitHub workflow) would be to clone the repository in a temporary directory and look for the Singularity. files. Is that too much?

The issue is that the shpc "pull" client needs to also have a way to predict the URI of a container. I suppose if the name and tag (e.g., singularity-deploy-pokemon.sif) is in the name, they would just need to ask for it directly. And then maybe binoc can do the magic to discover new recipes? Let me know what you think!

[fenz]

@vsoch I'm not getting the "predictability" question. I think I'm missing some bit here regarding the whole process/need for both the workflow and shpc.
So forgive me if I say something stupid but I thought if you look for a version X of an application Y you find it at:
REPO_URL/releases/download/X/Y.default.sif
and this correspond to the image: Y:X-default (in a tag syntax).
By the way, as said I'm probably not getting the issue so I'll let you discuss and find a smart solution ;)

[vsoch]

@fenz I can do a better job of describing the issue! So binoc is the bot that looks for updates, and when we update from Docker Hub we can easily discover both tags and digests from the API calls. For GitHub release artifacts, we can of course easily discover new releases (e.g., 0.0.12) but it's not clear to me how we then discover the recipes. If we can get the artifact names from the release, it could be a simple matter of just parsing those into strings that we call digests. But then we run into another issue - if a GitHub release 0.0.12 has three different associated sif binaries, which one is correct to call the digest? That's why I originally reversed it - find the tags first, and then use the GitHub release as the digest. E.g.,:

salad: 0.0.12
pokemon: 0.0.12

Because we might have the same Sif filenames (e.g., salad) over different GitHub releases (0.0.12) and we can represent multiple files, but we couldn't do that if 0.0.12 is the tag. We could only choose one. E.g., a sif for salad, pokemon, and latest can't ALL be associated with the 0.0.12 tag.