|
1 | 1 | # Providers |
2 | 2 |
|
3 | 3 | > **Note:** These provider implementations are included in-tree temporarily for testing and development purposes. The intention is for all providers to live out-of-tree as independent operators. |
| 4 | +
|
| 5 | +## Reported version contract (`shimVersion` / `SHIM_VERSION`) |
| 6 | + |
| 7 | +Every shim reports its own version through `InferenceProviderConfig.status.version`, |
| 8 | +which `kubectl`, the Web UI, and the Headlamp plugin display. That value is |
| 9 | +**injected at build time** — it is deliberately *not* a hand-maintained constant |
| 10 | +(a constant is never bumped at release and silently goes stale, which is the bug |
| 11 | +this pattern exists to prevent). |
| 12 | + |
| 13 | +If you add a new shim, replicate the contract exactly: |
| 14 | + |
| 15 | +1. **`config.go`** — declare the injection target as an **unexported `var` with a |
| 16 | + plain string literal**, then compose the public version from it: |
| 17 | + |
| 18 | + ```go |
| 19 | + // shimVersion is injected at build time via -ldflags -X; "dev" is the |
| 20 | + // fallback for bare `go build`/`go run`/`go test` that bypass the Makefile. |
| 21 | + var shimVersion = "dev" |
| 22 | + |
| 23 | + // ProviderVersion is written to InferenceProviderConfig.status.version. |
| 24 | + var ProviderVersion = ProviderConfigName + "-provider:" + shimVersion |
| 25 | + ``` |
| 26 | + |
| 27 | + - Inject **`shimVersion`**, never `ProviderVersion`: `-X` can only patch a var |
| 28 | + whose initializer is a single string constant. `ProviderVersion` has a |
| 29 | + composite initializer, so `-X` on it silently no-ops. Keep `shimVersion` |
| 30 | + unexported — `-X` resolves a linker symbol regardless of Go visibility. |
| 31 | + - Both must be `var`, not `const` (`-X` cannot touch a `const`, and a `const` |
| 32 | + cannot reference a `var`). |
| 33 | + |
| 34 | +2. **`Makefile`** — resolve the module path with `go list -m` (never hand-type it) |
| 35 | + and feed both a release tag and a git-stamp default through one `-X`: |
| 36 | + |
| 37 | + ```makefile |
| 38 | + MODULE := $(shell go list -m) |
| 39 | + GIT_SHA := $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown) |
| 40 | + GIT_DIRTY := $(shell test -n "$$(git status --porcelain 2>/dev/null)" && echo '-dirty') |
| 41 | + SHIM_VERSION ?= dev-$(GIT_SHA)$(GIT_DIRTY) |
| 42 | + LDFLAGS += -X $(MODULE).shimVersion=$(SHIM_VERSION) |
| 43 | + ``` |
| 44 | + |
| 45 | + Pass `--build-arg SHIM_VERSION=$(SHIM_VERSION)` to `docker-build`. |
| 46 | + |
| 47 | +3. **`Dockerfile`** — declare `ARG SHIM_VERSION` **with no default** and fail loud |
| 48 | + if it is missing, so a bare `docker build` cannot ship `:dev` under a real |
| 49 | + release tag. Resolve the module path the same way: |
| 50 | + |
| 51 | + ```dockerfile |
| 52 | + ARG SHIM_VERSION |
| 53 | + RUN test -n "${SHIM_VERSION}" || (echo "ERROR: SHIM_VERSION build arg is required; pass --build-arg SHIM_VERSION=..." >&2; exit 1) |
| 54 | + RUN cd providers/<name> && MODULE=$(go list -m) && \ |
| 55 | + go build -ldflags="-X ${MODULE}.shimVersion=${SHIM_VERSION}" -o provider cmd/main.go |
| 56 | + ``` |
| 57 | + |
| 58 | +4. **Release workflow** — pass `SHIM_VERSION=${{ inputs.version }}` (the same value |
| 59 | + that tags the image) in the `build-args:` block, so `status.version` equals the |
| 60 | + image tag by construction. |
| 61 | + |
| 62 | +5. **Tests** — assert the *shape* (`strings.HasPrefix(ProviderVersion, "<name>-provider:")`), |
| 63 | + not an exact literal, and include a `TestShimVersionInjection` that asserts the |
| 64 | + **runtime** value under injection (gated on `EXPECT_PROVIDER_VERSION` so plain |
| 65 | + `go test` skips). The CI matrix in `.github/workflows/test.yml` runs it built |
| 66 | + with `-ldflags` so a silent `-X` no-op fails the build. |
0 commit comments