Docs: Mark the registry DeleteObjects checksum issue fixed in 19.2

Andrew Dunnrequested to merge
docs/registry-deletes-checksum-disabled-19-2 into master

What does this MR do?

The 19.0 upgrade note says no gitlab.rb setting helps when S3-compatible storage rejects the registry's checksum header on DeleteObjects calls. That stopped being true in GitLab 19.2.0. With checksum_disabled set to true, the registry now sends a Content-MD5 header and no checksum header on those calls.

This MR limits the warning to GitLab 19.0 and 19.1 and states the 19.2.0 behavior. The existing registry['storage'] example needs no change. Affected versions stays 19.0.0 because the item is the intentional driver change, and the body documents the 19.2.0 fix for one sub-case.

flowchart TD
    accTitle: DeleteObjects header by GitLab version
    accDescr: With checksum_disabled set to true, registry v4.40.0 and v4.40.1 send a CRC32 checksum header on DeleteObjects calls and v4.40.2 and later send a Content-MD5 header instead.
    A[Registry deletes blobs, checksum_disabled true] ==> B[DeleteObjects request to the S3 backend]
    B ==> C{GitLab version}
    C ==>|19.0 and 19.1, registry v4.40.0 and v4.40.1| D[x-amz-checksum-crc32 header]
    C ==>|19.2.0 and later, registry v4.40.2 and later| E[Content-MD5 header, no checksum header]
    D ==> F[A backend that rejects the header fails the delete]

Where the claims come from

  • The fix is container registry merge request 2880, listed in the registry v4.40.2-gitlab changelog. The code is in the S3 v2 driver, which removes the SDK checksum middleware and adds Content-MD5 for DeleteObjects (lines 237-344).
  • GitLab 19.0 bundles registry v4.40.0-gitlab and then v4.40.1-gitlab from 19.0.2, 19.1 bundles v4.40.1-gitlab, and 19.2 bundles v4.40.2-gitlab. Neither earlier version has the middleware change. The Linux package pins the version in config/software/registry.rb (line 22 on the 19-1-stable and 19-2-stable branches). The 19.0.0+ee.0 and 19.0.1+ee.0 tags pin v4.40.0-gitlab, every tag from 19.0.2+ee.0 to 19.0.9+ee.0 and from 19.1.0+ee.0 to 19.1.8+ee.0 pins v4.40.1-gitlab, and 19.2.0+ee.0 pins v4.40.2-gitlab. The container images for the Helm chart pin the same versions in ci_files/variables.yml at v19.0.9, v19.1.8 and v19.2.0.
  • The registry['storage'] hash in gitlab.rb is written unchanged into the storage: line of the registry config.yml (template line 8). checksum_disabled is read from that hash in the parameter parser.

What the registry sends

On a self-managed GitLab 19.2.0 Linux package with MinIO as the S3 backend, registry garbage collection deleted untagged blobs through DeleteObjects. The request headers were recorded on the way to MinIO. A proxy in front of MinIO acted as a strict backend. It returns 400 InvalidRequest to any x-amz-checksum-* header on DeleteObjects and 400 MissingContentMD5 when Content-MD5 is missing. No real strict backend was tested.

  • v4.40.2-gitlab (19.2.0) with checksum_disabled set to true sends Content-MD5 only. The proxy accepts the delete.
  • v4.40.2-gitlab (19.2.0) with checksum_disabled not set sends x-amz-checksum-crc64nvme. The proxy returns 400.
  • v4.40.1-gitlab, built from its tag, with checksum_disabled set to true sends x-amz-checksum-crc32. The proxy returns 400.

The last case is the 19.0 and 19.1 behavior the note already describes. The two 19.2.0 results come from the packaged registry.

Related issues

Related to container-registry#2309 (closed)

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.

An AI coding assistant wrote this change and this description. It checked each claim against the sources this MR cites. It ran the project's Vale and markdownlint-cli2 configurations on the changed page, with no findings on the changed lines. It also reproduced the described DeleteObjects behavior on a test VM against MinIO behind a proxy that rejects checksum headers. The VM ran the 19.2.0 registry from the Linux package and v4.40.1-gitlab built from its tag.

Merge request reports