Floating tag support doc #1295

mthalman · 2024-12-11T16:47:14Z

Contributes to #1279

This provides a policy that is discussed in #1279. I want to get consensus on the policy first and then will make tag updates in a later PR.

MichaelSimons · 2024-12-11T21:48:08Z

lifecycle.md

@@ -48,9 +48,24 @@ Note: this content should be moved to another location as it is not lifecycle re

 Build and test images are referenced in repo infra files, across a variety of `main` and `release/*` branches. Updating these references is a multi-step detail-oriented task. It is a pain, but necessary.

-We use version specific references in infra to ensure that our CI builds are reliable. One can imagine using floating OS tags (such as `debian-oldest` and `debian-latest`), however such an approach would be guaranteed to break our build. We know that since we often see build and test breaks that need addressing in PRs where we update build and test images.
+Several types of tag styles are provided:


Would these tags be created regardless if they are being used or would they be created on demand? I question if they are going to be used for every distro/image variant.

I also lean towards on-demand. In fact, I'm not sure we want all distros being tested with floating tags.

Several types

Several or two?

MichaelSimons · 2024-12-11T21:55:05Z

lifecycle.md

+There is a vetting process before a `latest` floating tag gets moved to a newer distro version:
+
+1. Version-specific tags for the new distro version are provided.
+1. The [dotnet/runtime](https://github.com/dotnet/runtime) repo is updated to reference the new version-specific tags.


Aren't there going to be cases where images aren't referenced by the runtime?

I don't like this vetting process in a way. If vetting is required you shouldn't be using the version specific tags. I tend to learn towards the .NET Docker Alpine floating tag policy. The new distro is made available one month, the next month the floating tag is updated. This is a more scalable model.

That works as a policy. If we found an issue in runtime, we'd pause roll-out in dotnet-docker. We'd do the same with this system. It does mean that we'll have to be intentional w/ensuring we get coverage in runtime pretty quickly.

As long as the new system is pause-able, it doesn't need vetting.

richlander · 2024-12-13T19:45:41Z

lifecycle.md

 * version-specific: The tag name includes the distro's version. Example: `alpine-3.21-helix-amd64`
-* floating: The tag name has no version. Instead it is routinely updated to reference a new version as the distro's lifecycle progresses. There are two sub-types of floating tags:
+* floating (optional): The tag name has no version. Instead it is routinely updated to reference a new version as the distro's lifecycle progresses. There are two sub-types of floating tags:
  * latest: References the latest validated version of the distro. Example: `alpine-latest-helix-amd64`


I'm concerned about this tags being unbounded. At some point in a product release, it is time to turn up the dial on stability and to not move OS versions forward. In a year, we may want to stop updating .NET tags for that reasons. Similarly, "oldest" for .NET 8 and .NET 10 do not match, now. I've already moved .NET 10 to use Alpine 3.21 in dotnet/runtime as "oldest".

I'm a big fan of the model we used for our build images. They are version-specific. I think we should use the same model for build and test images. That approach would be significantly simplifying for teams. Just one model to understand.

https://github.com/dotnet/runtime/blob/main/docs/workflow/using-docker.md#the-official-runtime-docker-images

I'm also not convinced that we need oldest and latest. I think we should just offer one image variant to teams, just like we do for build images. If they need more versions, they can go with DIY.

In dotnet/runtime, the CoreCLR build targets the trailing edge of OS versions we support. Libraries biases to newest.

I think the best model is to:

Continue to use runtime to hold the baton on "oldest"

Use libraries to validate that "newest" is OK.

Push other repos (that use the floating tag) to newest after that, with a single tag (that doesn't say "newest").

Today, these tags are (effectively) exclusively referenced in our own infra. As we move to VMR/UB, there may be more users of these images. We need to be cognizant of that and ensure we don't break them when they attempt to build and test old .NET versions.

I'm a big fan of the model we used for our build images. They are version-specific. I think we should use the same model for build and test images.

That gets outside the scope of what is being addressed here. That's going to move us into producing new images, not just tagging changes. I would encourage you to create a separate issue for this.

I think the best model is to:

Continue to use runtime to hold the baton on "oldest"

Use libraries to validate that "newest" is OK.

Push other repos (that use the floating tag) to newest after that, with a single tag (that doesn't say "newest").

Let me check with you that I'm interpreting this correctly. This means we would have a floating tag that represents the latest version. If repos want an older version, they should use a version-specific tag. And libraries would still use a version-specific tag, targeting the latest, that we can use for vetting.

I don't see why we need new images. I'm only talking about tagging.

Let's make this concrete. We should model this for .NET 8 and 10 for Alpine. As I said, I'd like to retain the ability to stop taking Alpine changes for .NET 8 late in the .NET 8 lifecycle (last 6 months).

I don't see why we need new images. I'm only talking about tagging.

I thought you were referring to using net8.0 and net9.0 tagging like we do for the build images.

Yes. For our build images, it's completely different content. For this, I'm suggesting just different tags, all handled in manifest.json.

Imagine just before .NET 9 EOL:

alpine-net9.0 -- same as alpine-3.23-helix-amd64, referenced in release/9.0 branches

alpine-net10.0 -- same as alpine-3.24-helix-amd64, referenced in release/10.0 branches

The .NET 9 image is eventually pinned to Alpine 3.23 while the .NET 10 image keeps on marching forward. The reason is that .NET 9 is in maintenance and we value high stability and low cost at that point.

We don't need any special tools for this. We could do this now.

Some thoughts on users of these tags:

Should only update tags (from Alpine 3.23 to 3.24, for example) in the middle weeks of the month. If Patch Tuesday is the B week, then we should update change these tags on a C or D week, ideally also on a Tuesday. We don't want to disrupt servicing activities.

If a change breaks one or a few teams, it is their responsibility to fix their code. That's part of the terms of use of these tags. If a change breaks most users, then the tag change should be reverted.

The tags should only be updated after they test cleanly in runtime, otherwise, we're in YOLO mode.

Not appropriate for repos that have -staging branches, like https://github.com/dotnet/runtime/tree/release/8.0-staging. That pattern places a high premium on a commit encoding/representing all aspects of code and config. Floating tags are antithetical to that approach.

If Patch Tuesday is the B week, then we should update change these tags on a C or D week, ideally also on a Tuesday. We don't want to disrupt servicing activities.

Timing is a good point. Wouldn't we want to make these prior to code complete?

Yes. Perhaps that's just the C week. I don't know what that timing is so really just bringing up the topic. I am certain the B week is a bad choice. There is always the chance that we'll regret something we shipped and need to make a quick update in the B week.

Made updates in cae40fc. This gets rid of oldest tags, defines the C week policy, and .NET version scoping.

richlander · 2025-01-16T21:35:24Z

lifecycle.md

+
+#### Stability Period
+
+Floating tags are scoped to a specific .NET version.


Maybe add some text that says "after EOL, the version-specific tag is no longer maintained".

richlander · 2025-01-16T21:35:49Z

LGTM. One remaining small comment. Thanks for doing this!

MichaelSimons · 2025-01-17T15:49:58Z

lifecycle.md

+
+#### Moving the Floating Tag
+
+There is a workflow that is following before a floating tag gets moved to a newer distro version:


Suggested change

There is a workflow that is following before a floating tag gets moved to a newer distro version:

There is a workflow that is followed before a floating tag gets moved to a newer distro version:

MichaelSimons · 2025-01-17T15:52:44Z

lifecycle.md

+
+There is a workflow that is following before a floating tag gets moved to a newer distro version:
+1. First, version-specific tags for the new distro version are provided.
+1. After a one month evaluation period, the floating tag is ready to reference the new version, assuming there are no issues found.


Would it be worthwhile to update the in-development version ahead of servicing versions of .NET? e.g. updating the .NET 10 alpine image before updating the .NET 9.0 + 8.0 images. This could help provide stability in the servicing versions.

That is an interesting idea. That likely makes sense.

Is it reasonable to transition the update over 2 months then? I'd prefer to only take actions on C weeks. So first update the 10.0 tag then wait a month to update the 9.0/8.0 tags. Sound ok?

Can you write up a proposed timeline? I'm not following why we need two months but I might be missing something.

It was based on Michael's suggestion:

updating the .NET 10 alpine image before updating the .NET 9.0 + 8.0 images.

If not 2 months, then what is the timeframe between updating .NET 10 and the others?

Here is what I interpreted by the suggestion, for a timeline:

July: Alpine 3.22 ships

August:

.NET 10 Preview -- Switches to Alpine 3.22 as only option (for both version-specific and floating tags)

.NET 8/9 -- Both 3.21 and 3.22 are available as version-specific options; floating stays on 3.21

September:

.NET 8/9 -- Both 3.21 and 3.22 are available as version-specific options; floating stays is updated to 3.22

Perhaps @MichaelSimons meant something different.

I was originally thinking a shorter timeline (2 week in main). I don't see a particular driving reason for that. The two month rollout it amenable to me.

@richlander - Where does the runtime evaluation period fit into your timeline? Are you suggesting that floating tags for .NET 10 Preview get updated prior to a 1 month evaluation period in runtime? Or does that evaluation period start in July?

Good question. I forgot about that. Let's assume that July (in this example) is "runtime signoff".

MichaelSimons · 2025-01-17T15:58:24Z

lifecycle.md

+Floating tags have no distro version indicated in the name and are scoped to a .NET version (e.g. `alpine-net9.0-helix-amd64`).
+It is routinely updated to reference a new version as the distro's and .NET's lifecycles progress.
+
+Floating tags are provided on an as-needed basis.


Should this state what the process is if needed? Self-service? Who is responsible for onboarding the OS versions and moving the floating tag accordingly?

I think we want to have an issue filed if a floating tag is desired so that we can ensure it's appropriate.

Moving the floating tag should be done centrally and not delegated, I think, since there needs to be a close schedule followed. So that would be done by us, the maintainers.

lifecycle.md

richlander

LGTM -- Let's try this plan and adapt if needed.

Floating tag support

3009db4

mthalman requested a review from a team as a code owner December 11, 2024 16:47

dotnet-issue-labeler bot added area-infrastructure untriaged labels Dec 11, 2024

mthalman requested a review from richlander December 11, 2024 16:47

break up lines to satisfy linter

3562aea

MichaelSimons reviewed Dec 11, 2024

View reviewed changes

Updates from feedback

e434503

mthalman requested a review from MichaelSimons December 13, 2024 19:26

richlander reviewed Dec 13, 2024

View reviewed changes

review updates

cae40fc

mthalman requested a review from richlander January 16, 2025 18:44

richlander reviewed Jan 16, 2025

View reviewed changes

richlander approved these changes Jan 16, 2025

View reviewed changes

MichaelSimons reviewed Jan 17, 2025

View reviewed changes

mthalman commented Jan 21, 2025

View reviewed changes

lifecycle.md Show resolved Hide resolved

more updates from feedback

83297b6

mthalman requested review from MichaelSimons and richlander January 21, 2025 18:04

Appease the markdown linter

8cfd1b4

richlander approved these changes Jan 21, 2025

View reviewed changes

mthalman changed the title ~~Floating tag support~~ Floating tag support doc Jan 21, 2025

MichaelSimons approved these changes Jan 21, 2025

View reviewed changes

mthalman merged commit 1e77b9a into dotnet:main Jan 22, 2025
5 checks passed

mthalman deleted the issue1279 branch January 22, 2025 13:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Floating tag support doc #1295

Floating tag support doc #1295

mthalman commented Dec 11, 2024 •

edited

Loading

MichaelSimons Dec 11, 2024

richlander Dec 12, 2024

richlander Dec 12, 2024 •

edited

Loading

MichaelSimons Dec 11, 2024

richlander Dec 12, 2024 •

edited

Loading

richlander Dec 13, 2024

mthalman Dec 13, 2024

richlander Dec 13, 2024

richlander Dec 13, 2024

mthalman Dec 13, 2024

richlander Dec 13, 2024 •

edited

Loading

richlander Dec 16, 2024 •

edited

Loading

MichaelSimons Dec 16, 2024

richlander Dec 16, 2024 •

edited

Loading

mthalman Jan 16, 2025

richlander Jan 16, 2025

richlander commented Jan 16, 2025

MichaelSimons Jan 17, 2025

MichaelSimons Jan 17, 2025

richlander Jan 17, 2025

mthalman Jan 17, 2025

richlander Jan 17, 2025

mthalman Jan 17, 2025

richlander Jan 17, 2025

MichaelSimons Jan 21, 2025

mthalman Jan 21, 2025

richlander Jan 21, 2025

MichaelSimons Jan 17, 2025

mthalman Jan 21, 2025

richlander left a comment


		#### Stability Period

		Floating tags are scoped to a specific .NET version.


		#### Moving the Floating Tag

		There is a workflow that is following before a floating tag gets moved to a newer distro version:

	There is a workflow that is following before a floating tag gets moved to a newer distro version:
	There is a workflow that is followed before a floating tag gets moved to a newer distro version:

Floating tag support doc #1295

Floating tag support doc #1295

Conversation

mthalman commented Dec 11, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richlander Dec 12, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richlander Dec 12, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richlander Dec 13, 2024 • edited Loading

Choose a reason for hiding this comment

richlander Dec 16, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richlander Dec 16, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richlander commented Jan 16, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richlander left a comment

Choose a reason for hiding this comment

mthalman commented Dec 11, 2024 •

edited

Loading

richlander Dec 12, 2024 •

edited

Loading

richlander Dec 12, 2024 •

edited

Loading

richlander Dec 13, 2024 •

edited

Loading

richlander Dec 16, 2024 •

edited

Loading

richlander Dec 16, 2024 •

edited

Loading