Contrib/local builds

[jdarling-centroid]

Proposed Changes

This PR makes local Docker test image builds reproducible and versioned, and adds a single-command workflow for building both current and historical RKE2 refs.

Key changes:

• Added make build-local-test-image and new build script:
  • scripts/build-local-test-image
• Added support for building older versions from a tag/branch/commit via RKE2_REF without changing the current checkout.
• Default image tagging is now versioned (no latest/local defaults):
  • rancher/rke2-test:<resolved-version>-<goos>-<arch>
  • rancher/rke2-test:<resolved-version>
• Added compatibility handling so older refs that still expect legacy airgap artifact naming can build on non-amd64 hosts.
• Dockerfile local build fixes:
  • fixed line continuation parse issue in the gh install layer
  • switched legacy ENV key value to ENV key=value
  • test-stage airgap artifact path updated to architecture-aware output.
• Added local build documentation in BUILDING.md with current/historical build examples and expected behavior.

Yes, this change includes documentation updates.

Types of Changes

• Bugfix
• Developer experience improvement / build workflow enhancement
• Documentation update

Verification

Local validation performed with:

• RKE2_REF=v1.34.4+rke2r1 make build-local-test-image

Expected/observed result:

• build completes successfully
• produced tags:
  • rancher/rke2-test:v1.34.4-rke2r1-linux-arm64
  • rancher/rke2-test:v1.34.4-rke2r1

Additional manual verification paths:

• make build-local-test-image (current checkout)
• RKE2_REF=<commit-sha> make build-local-test-image
• optional override: IMAGE_TAG=<custom> make build-local-test-image

Testing

No new unit tests were added (build workflow/script and Dockerfile pathing changes).
Validation was done by running the full Dockerized build flow end-to-end for a historical tagged ref, including artifact generation and final --target test image build.

Linked Issues

None currently.
(If preferred, I can open/link a tracking issue for “local test image build from historical refs + versioned tagging”.)

User-Facing Change

Added a supported one-command local Docker test-image build workflow (make build-local-test-image) with versioned image tags and RKE2_REF support for building tagged/older refs.

Further Comments

The implementation intentionally avoids mutating the caller’s checkout when RKE2_REF is used by building from an isolated local clone.
It also preserves compatibility for older refs with legacy artifact naming expectations to reduce friction when validating historical releases from modern host architectures.

[jdarling-centroid]

Here is a sample Docker Compose file that can be used to spin up a 3 node cluster on a Mac:

services:
  rke2-server-1:
    image: rancher/rke2-test:v1.34.4-rke2r1
    container_name: rke2-server-1
    hostname: rke2-server-1
    privileged: true
    security_opt:
      - seccomp=unconfined
    cgroup: host
    command: ["server", "--kubelet-arg=seccomp-default=false"]
    healthcheck:
      test: ["CMD-SHELL", "ps aux | grep -q '[k]ube-apiserver'"]
      interval: 5s
      timeout: 5s
      retries: 60
      start_period: 30s
    environment:
      RKE2_TOKEN: devtoken
      RKE2_DEBUG: "true"
    ports:
      - "6443:6443"
      - "9345:9345"
    volumes:
      - ./containerd-config.toml.tmpl:/var/lib/rancher/rke2/agent/etc/containerd/config.toml.tmpl:ro
      - rke2-1-kubelet:/var/lib/kubelet
      - rke2-1-cni:/var/lib/cni
      - rke2-1-log:/var/log

  rke2-server-2:
    image: rancher/rke2-test:v1.34.4-rke2r1
    container_name: rke2-server-2
    hostname: rke2-server-2
    privileged: true
    security_opt:
      - seccomp=unconfined
    cgroup: host
    environment:
      RKE2_TOKEN: devtoken
      RKE2_DEBUG: "true"
    command: ["server", "--server", "https://rke2-server-1:9345", "--kubelet-arg=seccomp-default=false"]
    depends_on:
      rke2-server-1:
        condition: service_healthy
    volumes:
      - ./containerd-config.toml.tmpl:/var/lib/rancher/rke2/agent/etc/containerd/config.toml.tmpl:ro
      - rke2-2-kubelet:/var/lib/kubelet
      - rke2-2-cni:/var/lib/cni
      - rke2-2-log:/var/log

  rke2-server-3:
    image: rancher/rke2-test:v1.34.4-rke2r1
    container_name: rke2-server-3
    hostname: rke2-server-3
    privileged: true
    security_opt:
      - seccomp=unconfined
    cgroup: host
    environment:
      RKE2_TOKEN: devtoken
      RKE2_DEBUG: "true"
    command: ["server", "--server", "https://rke2-server-1:9345", "--kubelet-arg=seccomp-default=false"]
    depends_on:
      rke2-server-1:
        condition: service_healthy
    volumes:
      - ./containerd-config.toml.tmpl:/var/lib/rancher/rke2/agent/etc/containerd/config.toml.tmpl:ro
      - rke2-3-kubelet:/var/lib/kubelet
      - rke2-3-cni:/var/lib/cni
      - rke2-3-log:/var/log

volumes:
  rke2-1-kubelet:
  rke2-1-cni:
  rke2-1-log:
  rke2-2-kubelet:
  rke2-2-cni:
  rke2-2-log:
  rke2-3-kubelet:
  rke2-3-cni:
  rke2-3-log:

[dereknola]

This seems to just a duplication and mixture of the old dev-shell and the scripts/build-image-test (which is not exposed as it own make target, but is done as part of make build). I don't understand what benefit this brings over just using the existing build system, other than the ability to REF different version of RKE2.

Currently I can already run make build and then use the resulting rancher/rke2-test:v1.35.1-dev.9d4725b7 as a way to run rke2 server

docker run --privileged -v /lib/modules:/lib/modules -v /sys/fs/cgroup:/sys/fs/cgroup rancher/rke2-test:v1.35.1-dev.9d4725b7 server  --snapshotter=native

[jdarling-centroid]

It pretty much is just a wrapper around the existing functionality, and a small sample file on how it can be used locally. I found myself needing to test some code and processes and the existing answers on the issues was similar to "We don't support that, yet there is a Dockerfile"

There were a couple minor tweaks to the makefile, and Dockerfile changes for passing in version and whitespace to =.

Seemed the only barrier to entry was a clean wrapper and a simple example. Thought I'd submit my changes in case it would help others.