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:
- The VS Code fork builds natively for linux/arm64 (gitlab-web-ide-vscode-fork!136 (merged), first release
1.94.0-1.0.0-dev-20260915124137). workspaces-toolsis published for linux/amd64 and linux/arm64 (gitlab-build-images!1168 (merged)).- The default image is published for both again (gitlab-build-images!1195 (merged), with the qemu fix in gitlab-build-images!1197 (merged)).
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.rbandfiles.rbnow explain this coupling instead of the old workaround. - The spec fixtures that copy the default devfile image are updated (
settings_initializer_speccomparesdefault_devfile.yamlwithexample.default_devfile.yaml.erbverbatim). - Docs: workspaces run on
linux/amd64orlinux/arm64clusters, 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 |
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
- #550128
- gitlab-web-ide-vscode-fork#53
- gitlab-web-ide-vscode-fork!136 (merged)
- gitlab-build-images!1111 (merged)
- gitlab-build-images!1168 (merged)
- gitlab-build-images!1195 (merged)
- gitlab-build-images!1197 (merged)
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
-
Confirm that both images are multi-platform. Each command lists
linux/amd64andlinux/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 -
On an arm64 machine with GDK workspaces set up (for example Rancher Desktop on Apple Silicon), create a workspace with the GitLab default devfile.
-
Confirm that the workspace container runs natively (
kubectl exec -n <namespace> <pod> -c development-environment -- uname -mreturnsaarch64) and that VS Code opens. -
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