doc: clarify usage & deprecated tags

[PatrickLang]

There has been a lot of confusion since this repo used tags in the past, but that practice has stopped. I see that ContainerD has moved on to vendoring based on commitid, and after discussion is was recommended that Kubernetes do the same. This PR puts that recommendation in the README.

Related discussion:

kubernetes/kubernetes#80116 (comment)

[PatrickLang]

/assign @jterry75

[jterry75]

I would prefer we say something along the lines of: "The tags are associated with a vendoring scheme that is only intended for usage by Docker and the v1 container and process API's. This vendoing scheme is not suitable for ContainerD or Kubernetes which should use commit id's ...".

Feel free to re-word this and prettify it but that is what those numbers are for. Its not for anything other than that and its all we test them for.

[PatrickLang]

Updated - can you review again @jterry75

[dims]

@jterry75 i see a new release 0.8.7 that says This is the v0.8.7 release of containerd-shim-runhcs-v1.exe for containerd So is the statement above still true?

[jterry75]

v0.8.7 is ok for the shim because that is a binary dependency based on a stable API contract (Runtime V2) from containerd. The intent is to make vendor based commits (other than Docker) use commit id's

[jterry75]

@PatrickLang - Can you update this to be a little more generic and reflect the confusion. The goal of our releases is to:

1. Provide a vendor based commit tag for Docker which is code based.
2. Provide a binary release version tag for the stable release of the containerd shim supported in containerd releases.
3. All others are expected to use commit hashes because we are not verifying that when we make changes to a code dependency that we did not break them. We are only verifying this with Docker based vendoring.

[PatrickLang]

@jterry75 - I'm not sure I understand where Kubernetes falls into 1-3 based on the following:

• Docker-EE basic is still in use
• Kubernetes makes extra calls not supported in Docker through HCS for gathering metrics, network stats, and HNS configuration. Those rely on hcsshim

[TBBle]

I guess that would put Kubernetes in the 3rd case, since they're carrying a code dependency on hcsshim directly. It's not affected by Docker's use of hcsshim, and doesn't (for example) imply they must use the same hcsshim version that Docker users.

[jterry75]

Correct

[thaJeztah]

I guess this is fine (and similar to the containerd Go Client API not being stable). Perhaps a heading above this section (to make it stand out better), and updating the description of the (last) tagged release on GitHub to include the same warning would be useful

I'm not sure how go mod handles this, or if it will be persistent in trying to match a tag (as I know it can be picky) perhaps not, given that the latest tag is still < v1.0.0, thus "unstable")

Some questions;

Is the intent to have a stable Go API in future?

I'm not too familiar with the code/api underneath, thus wondering if it's only the Go API I should be concerned about when updating (in moby/moby); a breaking change in the Go API (e.g., a Signature Change or rename of a function) would be easily detected if the code no longer compiles (and can be fixed by adjusting the code that consumes hcsshim), but would there be a risk that the underlying implementation also changed in a breaking way?

/cc @ddebroy @lowenna @vikramhh

[TBBle]

I'm a bit confused by this PR.

It seems that since it was created, a new tagged release was made, which includes the release of the new containerd Runtime V2 shim.

Does that matter? Or should we just ignore it? containerd is still currently vendored to an older commit than the latest tagged release.

[jterry75]

@thaJeztah - No then intent is not to have a stable go API and in fact is the opposite. With the move from Docker to Containerd for runtime the goal is that Containerd depends on our binary shim but does not depend on a stable go API. Our contract and support will be for the shim and its capabilities. Eventually when Docker fully moves to Containerd we can remove the hcsshim code dependency from Docker as well.

[TBBle]

Would that goal require that containerd no longer vendors/imports hcsshim? It's using a few other things than just the shim, and I think it's even using the hcsshim Go API in order to call the shim? I didn't look that closely, I mainly noticed because I think hcsshim is the thing that makes containerd need cgo, pending revendoring to pick up #749.

[jterry75]

@TBBle - The only thing containerd "should" be using from hcsshim is the storage API's for process isolated container mounts and the content store layer processing. It is using only the Runtime V2 ttrpc API to interface with the shim so no code dependency there.

[PatrickLang]

There's now a lot more comments here than in my original PR and I don't have the full background on them. @jterry75 or @jstarks - can you document this as you see fit? I think it will be easier for you to describe as the repo owners.