Browse code

api: info: deprecate "Commit.Expected" fields

The `Commit` type was introduced in 2790ac68b32b399c872de88388bdccc359ed7a88,
to assist triaging issues that were reported with an incorrect version of
runc or containerd. At the time, both `runc` and `containerd` were not yet
stable, and had to be built from a specific commit to guarantee compatibility.

We encountered various situations where unexpected (and incompatible) versions
of those binaries were packaged, resulting in hard to trace bug-reports.
For those situations, a "expected" version was set at compile time, to
indicate if the version installed was different from the expected version;

docker info
...
runc version: a592beb5bc4c4092b1b1bac971afed27687340c5 (expected: 69663f0bd4b60df09991c08812a60108003fa340)

Both `runc` and `containerd` are stable now, and docker 19.03 and up set the
expected version to the actual version since c65f0bd13c85d29087419fa555281311091825e7
and 23.0 did the same for the `init` binary b585c64e2b01f924fc358fe059871baa469bb460,
to prevent the CLI from reporting "unexpected version".

In short; the `Expected` fields no longer serves a real purpose.

In future, we can even consider deprecating the `ContainerdCommit`, `RuncCommit`
and `InitCommit` fields on the `/info` response (as we also include this
information as part of the components returned in `/version`), but those
can still be useful currently for situations where a user only provides
`docker info` output.

This patch starts with deprecating the `Expected` field.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Sebastiaan van Stijn authored on 2024/09/11 17:37:40
Showing 6 changed files
... ...
@@ -100,6 +100,12 @@ func (s *systemRouter) getInfo(ctx context.Context, w http.ResponseWriter, r *ht
100 100
 			// Containerd field introduced in API v1.46.
101 101
 			info.Containerd = nil
102 102
 		}
103
+
104
+		// TODO(thaJeztah): Expected commits are deprecated, and should no longer be set in API 1.49.
105
+		info.ContainerdCommit.Expected = info.ContainerdCommit.ID //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
106
+		info.RuncCommit.Expected = info.RuncCommit.ID             //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
107
+		info.InitCommit.Expected = info.InitCommit.ID             //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
108
+
103 109
 		if versions.GreaterThanOrEqualTo(version, "1.42") {
104 110
 			info.KernelMemory = false
105 111
 		}
... ...
@@ -6170,6 +6170,8 @@ definitions:
6170 6170
       Expected:
6171 6171
         description: |
6172 6172
           Commit ID of external tool expected by dockerd as set at build time.
6173
+
6174
+          **Deprecated**: This field is deprecated and will be omitted in a API v1.49.
6173 6175
         type: "string"
6174 6176
         example: "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
6175 6177
 
... ...
@@ -137,8 +137,13 @@ type PluginsInfo struct {
137 137
 // Commit holds the Git-commit (SHA1) that a binary was built from, as reported
138 138
 // in the version-string of external tools, such as containerd, or runC.
139 139
 type Commit struct {
140
-	ID       string // ID is the actual commit ID of external tool.
141
-	Expected string // Expected is the commit ID of external tool expected by dockerd as set at build time.
140
+	// ID is the actual commit ID or version of external tool.
141
+	ID string
142
+
143
+	// Expected is the commit ID of external tool expected by dockerd as set at build time.
144
+	//
145
+	// Deprecated: this field is no longer used in API v1.49, but kept for backward-compatibility with older API versions.
146
+	Expected string
142 147
 }
143 148
 
144 149
 // NetworkAddressPool is a temp struct used by [Info] struct.
... ...
@@ -196,7 +196,6 @@ func populateRuncCommit(v *system.Commit, cfg *configStore) error {
196 196
 		return err
197 197
 	}
198 198
 	v.ID = commit
199
-	v.Expected = commit
200 199
 	return nil
201 200
 }
202 201
 
... ...
@@ -223,7 +222,6 @@ func (daemon *Daemon) populateInitCommit(ctx context.Context, v *system.Info, cf
223 223
 		return nil
224 224
 	}
225 225
 	v.InitCommit.ID = commit
226
-	v.InitCommit.Expected = v.InitCommit.ID
227 226
 	return nil
228 227
 }
229 228
 
... ...
@@ -437,7 +435,6 @@ func (daemon *Daemon) populateContainerdCommit(ctx context.Context, v *system.Co
437 437
 		return nil
438 438
 	}
439 439
 	v.ID = rv.Revision
440
-	v.Expected = rv.Revision
441 440
 	return nil
442 441
 }
443 442
 
... ...
@@ -24,6 +24,9 @@ keywords: "API, Docker, rcli, REST, documentation"
24 24
   `platform` parameter (JSON encoded OCI Platform type) that allows to specify
25 25
   a platform to load/save. Not passing this parameter will result in
26 26
   loading/saving the full multi-platform image.
27
+* Deprecated: The `ContainerdCommit.Expected`, `RuncCommit.Expected`, and
28
+  `InitCommit.Expected` fields in the `GET /info` endpoint are deprecated
29
+  and will be omitted in API v1.49.
27 30
 
28 31
 ## v1.47 API changes
29 32
 
... ...
@@ -17,11 +17,11 @@ func TestInfoBinaryCommits(t *testing.T) {
17 17
 	assert.NilError(t, err)
18 18
 
19 19
 	assert.Check(t, "N/A" != info.ContainerdCommit.ID)
20
-	assert.Check(t, is.Equal(info.ContainerdCommit.Expected, info.ContainerdCommit.ID))
20
+	assert.Check(t, is.Equal(info.ContainerdCommit.Expected, info.ContainerdCommit.ID)) //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
21 21
 
22 22
 	assert.Check(t, "N/A" != info.InitCommit.ID)
23
-	assert.Check(t, is.Equal(info.InitCommit.Expected, info.InitCommit.ID))
23
+	assert.Check(t, is.Equal(info.InitCommit.Expected, info.InitCommit.ID)) //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
24 24
 
25 25
 	assert.Check(t, "N/A" != info.RuncCommit.ID)
26
-	assert.Check(t, is.Equal(info.RuncCommit.Expected, info.RuncCommit.ID))
26
+	assert.Check(t, is.Equal(info.RuncCommit.Expected, info.RuncCommit.ID)) //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.49.
27 27
 }