Support arm64 workspaces by pinning multi-platform image digests

What does this MR do and why?

Stage ④ of #550128: lets workspaces run on linux/arm64 nodes.

GitLab pins two images for workspaces: the tools injector image (WORKSPACE_TOOLS_IMAGE) and the default devfile image. Both were pinned by the digest of their linux/amd64 manifest rather than the image index, on purpose. The VS Code fork only shipped x86-64 binaries, and pinning the amd64 manifest kept arm64 machines (for example Rancher Desktop on Apple Silicon) on the emulated amd64 variant of both images. See the comment this MR removes from ee/lib/remote_development/files.rb.

That limitation is gone:

This MR pins both images by their image index digest, so the container runtime pulls the variant that matches the node:

Image Before (linux/amd64 manifest digest) After (index digest: linux/amd64 + linux/arm64)
WORKSPACE_TOOLS_IMAGE 20250903132715-workspaces-tools@sha256:0f92a034… 20261013232549-workspaces-tools@sha256:ec12f2a7…
Default devfile image 20250414234733-…@sha256:3b3fb137… 20261022020504-…@sha256:973f8fd2…

Both pins move together on purpose. The tools injector copies the VS Code server into the workspace volume, and the main container runs it. The server's node is dynamically linked against glibc, so it only starts when the main container image has the same architecture as the injected tools. Flipping only the tools image would inject an arm64 editor into the amd64-only default image on arm64 nodes.

Also in this MR:

  • The comments in workspace_operations_constants.rb and files.rb now explain this coupling instead of the old workaround.
  • The spec fixtures that copy the default devfile image are updated (settings_initializer_spec compares default_devfile.yaml with example.default_devfile.yaml.erb verbatim).
  • Docs: workspaces run on linux/amd64 or linux/arm64 clusters, and the workspace container image must support the architecture of the node.
  • The background migration copies (lib/gitlab/background_migration/remote_development/**/bm_*) are deliberately unchanged: they are frozen snapshots for the migration and were not bumped with earlier image updates either.

Impact on existing amd64 workspaces

None expected. Compared with the images pinned today, the new amd64 variants contain the same VS Code commit (d78a74bcdfad14d5d3b1b782f87255d802b57511), the same GitLab Workflow extension (6.17.0) and the same agentw commit (3dc2510e0396716a77dcabfb70a115c9d07e66e4). The default image has the same tool versions, which its tag encodes; it was only rebuilt.

One behavior change on arm64 nodes that emulate amd64, such as Rancher Desktop on Apple Silicon: a custom devfile image that exists only for amd64 no longer works there, because the injected editor is now arm64. Before this MR, both images ran emulated as amd64. The default devfile now runs natively on those machines. Self-managed instances and GDK can set GITLAB_REMOTE_DEVELOPMENT_TOOLS_INJECTOR_IMAGE to the amd64 manifest digest if they need the old behavior.

End-to-end test

Run on AKS (Kubernetes v1.37.0) with the exact image references from this branch, extracted from the committed files. Each test pod has WORKSPACE_TOOLS_IMAGE as an init container that copies the tools into /projects/.gl-tools (as the tools injector does), and the default devfile image as the main container. Both pods run under the restricted Pod Security Standard as uid 5001. One pod ran on an arm64 node (Standard_E4pds_v5), the other on an amd64 node (Standard_D4ads_v5):

Check in the main container linux/arm64 linux/amd64
19 tools run: go, gopls, node, yarn, ruby, gem, bundle, python, pip, php, composer, java, mvn, rustc, cargo, conan, gcc, docker, git ✅ ✅
Every native binary matches the node's ELF architecture (go version reports linux/arm64 / linux/amd64, Ruby reports aarch64-linux / x86_64-linux) ✅ ✅
Injected agentw, VS Code node and ripgrep have the node's architecture ✅ ✅
VS Code native modules (node-pty, @vscode/spdlog, @parcel/watcher, kerberos) load inside the default image ✅ ✅
gitlab-webide-server started with the flags from internal_poststart_command_start_vscode.sh: GET /version returns d78a74bc…, GET / returns 200 ✅ (2 s) ✅ (2 s)

Overall: 40 of 40 checks passed on arm64, 41 of 41 on amd64. amd64 has one extra ELF check, because Conan there is a self-contained binary, while arm64 installs it from PyPI.

References

Screenshots or screen recordings

Not applicable: no UI change. The end-to-end results above cover the before and after.

How to set up and validate locally

  1. Confirm that both images are multi-platform. Each command lists linux/amd64 and linux/arm64:

    docker buildx imagetools inspect registry.gitlab.com/gitlab-org/gitlab-build-images:20261013232549-workspaces-tools@sha256:ec12f2a705dac25bc0aa6dcf80b01a5de35ece297a258e5677dc023c82ee7ef6
    docker buildx imagetools inspect registry.gitlab.com/gitlab-org/gitlab-build-images/workspaces/ubuntu-24.04:20261022020504-golang-1.23-node-23.9-yarn-1.22-ruby-3.4.2-rust-1.85-php-8.4.5-java-21.0.6-python-3.13-docker-27.5.1@sha256:973f8fd236fe9f5c47fa44a75b7daaeb767e6490fc140b572ce4c2e44235a334
  2. On an arm64 machine with GDK workspaces set up (for example Rancher Desktop on Apple Silicon), create a workspace with the GitLab default devfile.

  3. Confirm that the workspace container runs natively (kubectl exec -n <namespace> <pod> -c development-environment -- uname -m returns aarch64) and that VS Code opens.

  4. On an amd64 cluster, create a workspace the same way and confirm it starts as before.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

/cc @zhaochen_li @vtak

🤖 Generated with Claude Code

Merge request reports

Loading
Loading