fix(providers): inject shim version at build time

Glossary & Concept Primer

Vocabulary an unfamiliar reviewer needs before the rest of the dashboard makes sense.

provider shim

A small standalone controller under providers/<name>/ that renders a ModelDeployment into an upstream provider's resource (KAITO, Dynamo, KubeRay, llm-d, vLLM). Each ships as its own container image.

InferenceProviderConfig.status.version

A status field on the cluster-scoped CRD that reports which version of a provider shim is running. Read by kubectl, the Web UI, and the Headlamp plugin. The bug: this value was a hard-coded const that never tracked the actual release.

ProviderVersion

The Go symbol whose value populates status.version. Was a const (e.g. "kaito-provider:v0.1.0"); now a var derived as ProviderConfigName + "-provider:" + shimVersion.

shimVersion

New unexported package var, initialized to "dev". The actual -ldflags -X injection target. Unexported visibility doesn't matter to the linker — -X resolves the symbol regardless.

-ldflags "-X importpath.name=value"

Go linker flag that overwrites a string variable's value at link time. Critical constraint: it silently no-ops on a non-constant initializer (which is why shimVersion, not the composite ProviderVersion, is the target).

SHIM_VERSION

The build-arg / Make variable carrying the version into the build. Release workflows set it to ${{ inputs.version }}; local/CI builds default it to a git stamp.

go list -m

Prints the current module path from go.mod. Used so the -X target ($(MODULE).shimVersion) is computed, never hand-typed — eliminating path-drift bugs.

git stamp / dev-<sha>

The default SHIM_VERSION for non-release builds: dev-$(git rev-parse --short HEAD), with -dirty appended when the working tree has uncommitted/untracked content.

versions.env

Repo-root file holding pinned upstream runtime versions (e.g. DYNAMO_VERSION, VLLM_VERSION). Distinct from the shim version — the PR deliberately does not add the shim version here (the release tag is its source of truth).

Where the version comes from: before vs. after

The same value — what status.version reports — but sourced differently. Toggle to compare.

Injection chain: which build path sets the version

Three entry points feed the same -X target. The Go literal is the last-resort fallback only.

Only the first two paths set a real tag. The third (go run/go test) intentionally leaves "dev", which is why the tests use a prefix check, not an equality check.

Dockerfile guard: fail loud, never ship :dev

What happens to a docker build depending on whether SHIM_VERSION was passed.

config.go schema diff (representative: dynamo)

The same shape applies to all five providers. Old on the left, new on the right.

const (
  ProviderConfigName = "dynamo"
  // ProviderVersion is the version…
  ProviderVersion = "dynamo-provider:v0.2.0"
  ProviderDocumentation = "…"
)

const (
  ProviderConfigName = "dynamo"
  ProviderDocumentation = "…"
)
// injected via -ldflags -X …shimVersion
var shimVersion = "dev"
var ProviderVersion =
  ProviderConfigName + "-provider:" + shimVersion

ProviderConfigName stays a const; only the version moves to a var so the linker can rewrite it.

Before / After capabilities

The dimensions a reviewer cares about, side by side.

Annotated Diff

5 of the most consequential hunks shown. The remaining ~20 hunks are the same four-part pattern (config.go / Makefile / Dockerfile / config_test.go) repeated across the other four providers, plus the four one-line release-workflow build-arg additions. Omitted hunks listed at the end.

const (
  ProviderConfigName = "dynamo"
- // ProviderVersion is the version of the AIRunway Dynamo provider controller.
- ProviderVersion = "dynamo-provider:v0.2.0"
  ProviderDocumentation = "https://…/dynamo.md"
)
+ // shimVersion is injected at build time via -ldflags -X …shimVersion
+ var shimVersion = "dev"
+ var ProviderVersion = ProviderConfigName + "-provider:" + shimVersion

+ MODULE := $(shell go list -m)
+ GIT_SHA      := $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown)
+ GIT_DIRTY    := $(shell test -n "$$(git status --porcelain 2>/dev/null)" && echo '-dirty')
+ SHIM_VERSION ?= dev-$(GIT_SHA)$(GIT_DIRTY)
- LDFLAGS := -X github.com/kaito-project/airunway/providers/dynamo.DynamoVersion=$(DYNAMO_VERSION)
+ LDFLAGS := -X $(MODULE).DynamoVersion=$(DYNAMO_VERSION)
+ LDFLAGS += -X $(MODULE).shimVersion=$(SHIM_VERSION)

+ ARG SHIM_VERSION
  …
- RUN cd providers/kaito && CGO_ENABLED=0 … go build -a -o provider cmd/main.go
+ RUN test -n "${SHIM_VERSION}" || (echo "ERROR: SHIM_VERSION build arg is required…" >&2; exit 1)
+ RUN cd providers/kaito && MODULE=$(go list -m) && \
+   CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} \
+   go build -a -ldflags="-X ${MODULE}.shimVersion=${SHIM_VERSION}" -o provider cmd/main.go

- if ProviderVersion != "dynamo-provider:v0.2.0" {
-   t.Errorf("expected provider version 'dynamo-provider:v0.2.0', got %s", ProviderVersion)
+ if !strings.HasPrefix(ProviderVersion, "dynamo-provider:") {
+   t.Errorf("expected provider version to start with 'dynamo-provider:', got %s", ProviderVersion)

+ - name: Assert shimVersion injection + git-stamp default
+   run: |
+     mod=$(cd "providers/$p" && go list -m)
+     go version -m "providers/$p/bin/provider" \
+       | grep -Eq -- "-X ${mod}.shimVersion=dev-[0-9a-f]+(-dirty)?" || exit 1
+     make -C "providers/$p" build SHIM_VERSION=v9.9.9-citest
+     go version -m "providers/$p/bin/provider" \
+       | grep -F -- "-X ${mod}.shimVersion=v9.9.9-citest" || exit 1

Omitted hunks (same patterns)

• providers/{kaito,kuberay,llmd,vllm}/config.go — same const→var conversion as dynamo.
• providers/{kuberay,llmd,vllm}/Makefile — same MODULE + git-stamp + LDFLAGS pattern (llmd/vllm retrofit existing LLMDSchedulerImage/VLLMVersion flags onto $(MODULE)).
• providers/{dynamo,kuberay,llmd,vllm}/Dockerfile — same ARG + test -n guard + computed MODULE.
• providers/{kaito,kuberay,llmd,vllm}/config_test.go — prefix assertion (llmd/vllm add a new TestProviderConstants).
• .github/workflows/release-{dynamo,kaito,kuberay,llmd}-provider.yml — one-line SHIM_VERSION=${{ inputs.version }} build-arg.
• .github/workflows/release-vllm-provider.yml — new file, a full workflow mirroring the dynamo one.

Risk Assessment

Severity: CRIT WARN INFO OK

Assumptions & Unknowns

Everything I'm guessing, couldn't verify, or would need to confirm with the author. All hedging lives here.

• Go var-init ordering. I assume ProviderVersion = ProviderConfigName + "-provider:" + shimVersion resolves correctly because Go initializes package-level vars in dependency order regardless of source position. This is guaranteed by the spec — confidence high — but I did not run the binary to confirm the injected value reaches status.version end-to-end.
• CI matrix coverage. The test.yml step uses ${{ matrix.provider }}; I assume the matrix enumerates all five providers. I did not read the full provider-go-checks matrix definition to confirm vllm is included.
• External referencers of ProviderVersion. I did not grep the controller/backend for code that imports and compares ProviderVersion as a const. The const→var change is compile-compatible for normal use, but a const-only context (e.g. array size, switch case) would break.
• The go list -m in Dockerfile RUN. I assume go list -m resolves correctly inside the build container's working directory for each provider. Plausible given the cd providers/<name>, but unverified against an actual image build.
• vLLM workflow parity. I assume the new release-vllm-provider.yml faithfully mirrors the dynamo workflow's semantics. I read it in the diff and it looks complete, but it has never run in CI (workflow_dispatch only), so there's no execution evidence.
• Did not verify the panel's findings here. This dashboard is my structural read of the diff. The five-model review panel ran independently; their findings are collated in FINAL-REPORT.md, not folded into this dashboard.