fake-k8s-device

fake-k8s-device is a minimal Kubernetes device plugin for registering configurable fake devices with kubelet. Each configured resource becomes its own device plugin endpoint, and the number of allocatable resources is the number of fake device IDs listed for that resource.

What it does

• Registers one device plugin per configured resource name.
• Reports all configured devices as healthy through ListAndWatch.
• Returns selected fake device IDs to containers via environment variables.
• Optionally writes an allocation annotation on each container response.

Configuration

See examples/config.yaml:

pluginDirectory: /var/lib/kubelet/device-plugins
socketPrefix: fake-k8s-device
resources:
  - name: devices.example.com/fake-gpu
    devices:
      - fake-gpu-0
      - fake-gpu-1

Important constraints:

• resources[].name must be a qualified extended resource name such as example.com/fake-gpu.
• A resource can use either devices or deviceNamePrefix with count.
• The resolved device count determines allocatable capacity. Three fake device IDs means allocatable count 3.
• Each resource name and device ID must be unique within its resource block.

Run

go run ./cmd/fake-k8s-device -config examples/config.yaml

Print the embedded build version:

go run ./cmd/fake-k8s-device -version

Local builds use the most recent Git tag as a base and append commit state when the checkout is not an exact release tag. With no tags present, the base defaults to v0.0.0, so a local build looks like v0.0.0-dev+<commit> or v0.0.0-dev+<commit>.dirty.

The kubelet device plugin socket directory usually needs the process to run on a node with access to /var/lib/kubelet/device-plugins.

Release automation

This repo includes GitHub Actions for CI, release tagging, and image publishing:

• .github/workflows/ci.yml builds the binary and container image on pushes to main and on pull requests.
• .github/workflows/tag-release.yml creates the next vMAJOR.MINOR.PATCH tag from the latest existing tag. If no tags exist, it starts from v0.0.0.
• .github/workflows/publish-image.yml publishes dboslee/fake-k8s-device for linux/amd64 and linux/arm64 when a v* tag is pushed.

The publish workflow expects these repository secrets:

• DOCKERHUB_USERNAME
• DOCKERHUB_TOKEN

Current scope

This is intentionally small. It implements registration, ListAndWatch, and Allocate, but does not yet support:

• dynamic config reloads
• health transitions
• checkpoint recovery
• re-registration after kubelet restart