Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

feat(docker): support explicit GPU device requests (#3789)

Austin Wdfbb0ee7561a
diff --git a/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerBuilder.java b/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerBuilder.java
index 49f8d02c79..c07dfca29f 100644
--- a/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerBuilder.java
+++ b/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerBuilder.java
@@ -4,6 +4,7 @@ import io.github.hectorvent.floci.config.EmulatorConfig;
import io.github.hectorvent.floci.core.common.dns.EmbeddedDnsServer;
import com.github.dockerjava.api.model.AccessMode;
import com.github.dockerjava.api.model.Bind;
+import com.github.dockerjava.api.model.DeviceRequest;
import com.github.dockerjava.api.model.LogConfig;
import com.github.dockerjava.api.model.Mount;
import com.github.dockerjava.api.model.MountType;
@@ -102,6 +103,17 @@ public class ContainerBuilder {
* Fluent builder for constructing ContainerSpec instances.
*/
public static class Builder {
+ /** Docker's capability name for a GPU, as used by {@code docker run --gpus}. */
+ private static final List<List<String>> GPU_CAPABILITY = List.of(List.of("gpu"));
+ /** Count understood by the daemon as "every device it has", i.e. {@code --gpus all}. */
+ private static final int ALL_DEVICES = -1;
+ /**
+ * Device-request driver that selects a Container Device Interface device by name.
+ * Podman resolves this on its Docker-compatible create API (containers/podman#19338);
+ * Docker's own NVIDIA path uses the count/id form instead.
+ */
+ private static final String CDI_DRIVER = "cdi";
+
private final String image;
private final EmulatorConfig config;
private final DockerHostResolver dockerHostResolver;
@@ -128,6 +140,7 @@ public class ContainerBuilder {
private String user;
private final List<String> groupAdd = new ArrayList<>();
private final List<String> dnsServers = new ArrayList<>();
+ private final List<DeviceRequest> deviceRequests = new ArrayList<>();
Builder(String image, EmulatorConfig config, DockerHostResolver dockerHostResolver,
EmbeddedDnsServer embeddedDnsServer,
@@ -419,6 +432,118 @@ public class ContainerBuilder {
return this;
}
+ /**
+ * Requests {@code count} GPUs, the equivalent of {@code docker run --gpus <count>}.
+ * The daemon chooses which devices. Prefer {@link #withGpuDeviceIds(List)} or
+ * {@link #withCdiDevices(List)} when the caller has to pin specific hardware.
+ *
+ * <p>Docker only. Podman accepts this form on its Docker-compatible API and then
+ * starts the container with no device attached (containers/podman#22645), so a
+ * caller that may be talking to Podman should use {@link #withCdiDevices(List)},
+ * whose failure mode is a refused start rather than a silent CPU-only container.
+ *
+ * @param count how many GPUs to request; must be at least one
+ * @throws IllegalArgumentException if {@code count} is below one
+ * @throws IllegalStateException if a device request was already made
+ */
+ public Builder withGpuCount(int count) {
+ if (count < 1) {
+ throw new IllegalArgumentException(
+ "GPU count must be at least 1, or use withAllGpus(); got " + count);
+ }
+ requireNoExistingDeviceRequest();
+ deviceRequests.add(new DeviceRequest()
+ .withCount(count)
+ .withCapabilities(GPU_CAPABILITY));
+ return this;
+ }
+
+ /**
+ * Requests every GPU the daemon exposes, the equivalent of {@code docker run --gpus all}.
+ * Docker only, with the same Podman caveat as {@link #withGpuCount(int)}.
+ *
+ * @throws IllegalStateException if a device request was already made
+ */
+ public Builder withAllGpus() {
+ requireNoExistingDeviceRequest();
+ deviceRequests.add(new DeviceRequest()
+ .withCount(ALL_DEVICES)
+ .withCapabilities(GPU_CAPABILITY));
+ return this;
+ }
+
+ /**
+ * Requests specific GPUs by daemon-assigned id, the equivalent of
+ * {@code docker run --gpus '"device=0,GPU-<uuid>"'}. Ids are indices or vendor UUIDs.
+ *
+ * <p>Indices are not stable across hosts or reboots, so a caller pinning hardware
+ * should prefer a UUID.
+ *
+ * @param deviceIds device ids to request; must be non-empty and individually non-blank
+ * @throws IllegalArgumentException if the list is empty or holds a blank id
+ * @throws IllegalStateException if a device request was already made
+ */
+ public Builder withGpuDeviceIds(List<String> deviceIds) {
+ requireUsableIds(deviceIds, "GPU device id");
+ requireNoExistingDeviceRequest();
+ // Count and ids are alternatives in Docker's API, and sending both is rejected
+ // by the daemon, so this form deliberately leaves the count unset.
+ deviceRequests.add(new DeviceRequest()
+ .withDeviceIds(List.copyOf(deviceIds))
+ .withCapabilities(GPU_CAPABILITY));
+ return this;
+ }
+
+ /**
+ * Requests devices by Container Device Interface name, such as
+ * {@code nvidia.com/gpu=GPU-<uuid>}. CDI is how a Podman daemon exposes accelerators
+ * over its Docker-compatible API, and it is not GPU-specific: the name identifies
+ * whatever device the host's CDI specs describe.
+ *
+ * <p>No capability is attached, because the CDI name already selects the device;
+ * the daemon resolves it against the host's CDI specs and fails the container start
+ * if it cannot.
+ *
+ * @param cdiDeviceNames fully-qualified CDI names, each {@code <vendor>/<class>=<name>}
+ * @throws IllegalArgumentException if the list is empty, or a name is blank or unqualified
+ * @throws IllegalStateException if a device request was already made
+ */
+ public Builder withCdiDevices(List<String> cdiDeviceNames) {
+ requireUsableIds(cdiDeviceNames, "CDI device name");
+ for (String name : cdiDeviceNames) {
+ // Catches the common mistake of passing a device path such as /dev/nvidia0,
+ // which the daemon would otherwise reject with an unresolvable-device error
+ // that does not say what was actually wrong with the value.
+ if (!name.contains("/") || !name.contains("=")) {
+ throw new IllegalArgumentException(
+ "CDI device name must be fully qualified as <vendor>/<class>=<name>; got " + name);
+ }
+ }
+ requireNoExistingDeviceRequest();
+ deviceRequests.add(new DeviceRequest()
+ .withDriver(CDI_DRIVER)
+ .withDeviceIds(List.copyOf(cdiDeviceNames)));
+ return this;
+ }
+
+ private void requireNoExistingDeviceRequest() {
+ if (!deviceRequests.isEmpty()) {
+ throw new IllegalStateException(
+ "A device request is already set; count, device ids and CDI names are alternatives");
+ }
+ }
+
+ private static void requireUsableIds(List<String> ids, String description) {
+ if (ids == null || ids.isEmpty()) {
+ throw new IllegalArgumentException("At least one " + description + " is required");
+ }
+ for (String id : ids) {
+ if (id == null || id.isBlank()) {
+ throw new IllegalArgumentException("A " + description + " must not be blank");
+ }
+ }
+ }
+
/**
* Injects Floci's embedded DNS server into the container so virtual-hosted
* S3 hostnames (my-bucket.localhost.floci.io) resolve to Floci's Docker
@@ -467,7 +592,8 @@ public class ContainerBuilder {
List.copyOf(dnsServers),
workingDir,
user,
- List.copyOf(groupAdd)
+ List.copyOf(groupAdd),
+ List.copyOf(deviceRequests)
);
}
}
diff --git a/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java b/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java
index 79a99b5baf..6339c0f786 100644
--- a/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java
+++ b/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java
@@ -953,6 +953,13 @@ public class ContainerLifecycleManager {
hostConfig.withDns(spec.dnsServers().toArray(new String[0]));
}
+ // Device requests (GPUs). Only set when a caller asked: a daemon configured with an
+ // accelerator runtime as its default must not start handing devices to every
+ // container Floci launches.
+ if (spec.hasDeviceRequests()) {
+ hostConfig.withDeviceRequests(spec.deviceRequests());
+ }
+
return hostConfig;
}
diff --git a/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerSpec.java b/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerSpec.java
index 9c490b0181..15b3ba1bcf 100644
--- a/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerSpec.java
+++ b/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerSpec.java
@@ -1,6 +1,7 @@
package io.github.hectorvent.floci.core.common.docker;
import com.github.dockerjava.api.model.Bind;
+import com.github.dockerjava.api.model.DeviceRequest;
import com.github.dockerjava.api.model.LogConfig;
import com.github.dockerjava.api.model.Mount;
@@ -32,6 +33,7 @@ import java.util.Map;
* @param workingDir Working directory inside the container (overrides image WORKDIR)
* @param user User the container process runs as, formatted "uid[:gid]" (null = image USER)
* @param groupAdd Supplementary group IDs added to the container process
+ * @param deviceRequests Device requests for accelerators such as GPUs (empty = none)
*/
public record ContainerSpec(
String image,
@@ -54,14 +56,15 @@ public record ContainerSpec(
List<String> dnsServers,
String workingDir,
String user,
- List<String> groupAdd
+ List<String> groupAdd,
+ List<DeviceRequest> deviceRequests
) {
/**
* Creates a minimal spec with just the image name.
* All other fields will be null or empty lists.
*/
public ContainerSpec(String image) {
- this(image, null, List.of(), null, null, null, Map.of(), List.of(), List.of(), null, List.of(), List.of(), List.of(), Map.of(), null, false, null, List.of(), null, null, List.of());
+ this(image, null, List.of(), null, null, null, Map.of(), List.of(), List.of(), null, List.of(), List.of(), List.of(), Map.of(), null, false, null, List.of(), null, null, List.of(), List.of());
}
/**
@@ -89,7 +92,37 @@ public record ContainerSpec(
String user,
List<String> groupAdd
) {
- this(image, name, env, cmd, entrypoint, memoryBytes, portBindings, List.of(), exposedPorts, networkMode, mounts, binds, extraHosts, labels, logConfig, privileged, cgroupnsMode, dnsServers, workingDir, user, groupAdd);
+ this(image, name, env, cmd, entrypoint, memoryBytes, portBindings, List.of(), exposedPorts, networkMode, mounts, binds, extraHosts, labels, logConfig, privileged, cgroupnsMode, dnsServers, workingDir, user, groupAdd, List.of());
+ }
+
+ /**
+ * Backward-compatible constructor that defaults {@code deviceRequests} to empty, so a
+ * caller that predates accelerator support keeps building CPU-only containers.
+ */
+ public ContainerSpec(
+ String image,
+ String name,
+ List<String> env,
+ List<String> cmd,
+ List<String> entrypoint,
+ Long memoryBytes,
+ Map<Integer, Integer> portBindings,
+ List<Integer> loopbackPortBindings,
+ List<Integer> exposedPorts,
+ String networkMode,
+ List<Mount> mounts,
+ List<Bind> binds,
+ List<String> extraHosts,
+ Map<String, String> labels,
+ LogConfig logConfig,
+ boolean privileged,
+ String cgroupnsMode,
+ List<String> dnsServers,
+ String workingDir,
+ String user,
+ List<String> groupAdd
+ ) {
+ this(image, name, env, cmd, entrypoint, memoryBytes, portBindings, loopbackPortBindings, exposedPorts, networkMode, mounts, binds, extraHosts, labels, logConfig, privileged, cgroupnsMode, dnsServers, workingDir, user, groupAdd, List.of());
}
/**
@@ -112,4 +145,11 @@ public record ContainerSpec(
public boolean hasLogConfig() {
return logConfig != null;
}
+
+ /**
+ * Returns true if this spec asks the daemon for any device, such as a GPU.
+ */
+ public boolean hasDeviceRequests() {
+ return deviceRequests != null && !deviceRequests.isEmpty();
+ }
}
diff --git a/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerBuilderTest.java b/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerBuilderTest.java
index df19a086ee..4a85f5ffa8 100644
--- a/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerBuilderTest.java
+++ b/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerBuilderTest.java
@@ -1,5 +1,6 @@
package io.github.hectorvent.floci.core.common.docker;
+import com.github.dockerjava.api.model.DeviceRequest;
import io.github.hectorvent.floci.config.EmulatorConfig;
import io.github.hectorvent.floci.core.common.dns.EmbeddedDnsServer;
import org.junit.jupiter.api.Test;
@@ -8,7 +9,9 @@ import java.util.List;
import java.util.Optional;
import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;
@@ -124,6 +127,118 @@ class ContainerBuilderTest {
assertEquals(List.of(), spec.groupAdd());
}
+ @Test
+ void withGpuCountRequestsThatManyGpus() {
+ TestFixture fixture = new TestFixture();
+
+ ContainerSpec spec = fixture.builder.newContainer("alpine")
+ .withGpuCount(2)
+ .build();
+
+ assertEquals(1, spec.deviceRequests().size());
+ DeviceRequest request = spec.deviceRequests().get(0);
+ assertEquals(2, request.getCount());
+ assertEquals(List.of(List.of("gpu")), request.getCapabilities());
+ // Docker rejects a request carrying both a count and explicit ids.
+ assertNull(request.getDeviceIds());
+ assertNull(request.getDriver());
+ }
+
+ @Test
+ void withAllGpusRequestsEveryDevice() {
+ TestFixture fixture = new TestFixture();
+
+ ContainerSpec spec = fixture.builder.newContainer("alpine")
+ .withAllGpus()
+ .build();
+
+ assertEquals(-1, spec.deviceRequests().get(0).getCount());
+ assertEquals(List.of(List.of("gpu")), spec.deviceRequests().get(0).getCapabilities());
+ }
+
+ @Test
+ void withGpuDeviceIdsPinsSpecificDevicesAndLeavesCountUnset() {
+ TestFixture fixture = new TestFixture();
+
+ ContainerSpec spec = fixture.builder.newContainer("alpine")
+ .withGpuDeviceIds(List.of("0", "GPU-1fc572c4-6cd7-0e21-dceb-fa71af82eed5"))
+ .build();
+
+ DeviceRequest request = spec.deviceRequests().get(0);
+ assertEquals(List.of("0", "GPU-1fc572c4-6cd7-0e21-dceb-fa71af82eed5"), request.getDeviceIds());
+ assertEquals(List.of(List.of("gpu")), request.getCapabilities());
+ assertNull(request.getCount());
+ }
+
+ @Test
+ void withCdiDevicesSelectsDevicesByCdiName() {
+ TestFixture fixture = new TestFixture();
+
+ ContainerSpec spec = fixture.builder.newContainer("alpine")
+ .withCdiDevices(List.of("nvidia.com/gpu=GPU-1fc572c4-6cd7-0e21-dceb-fa71af82eed5"))
+ .build();
+
+ DeviceRequest request = spec.deviceRequests().get(0);
+ assertEquals("cdi", request.getDriver());
+ assertEquals(List.of("nvidia.com/gpu=GPU-1fc572c4-6cd7-0e21-dceb-fa71af82eed5"), request.getDeviceIds());
+ // The CDI name already names the device, so no capability is negotiated.
+ assertNull(request.getCapabilities());
+ assertNull(request.getCount());
+ }
+
+ @Test
+ void containersRequestNoDevicesByDefault() {
+ TestFixture fixture = new TestFixture();
+
+ ContainerSpec spec = fixture.builder.newContainer("alpine").build();
+
+ assertEquals(List.of(), spec.deviceRequests());
+ assertFalse(spec.hasDeviceRequests());
+ }
+
+ @Test
+ void gpuCountMustBePositive() {
+ TestFixture fixture = new TestFixture();
+ ContainerBuilder.Builder builder = fixture.builder.newContainer("alpine");
+
+ assertThrows(IllegalArgumentException.class, () -> builder.withGpuCount(0));
+ assertThrows(IllegalArgumentException.class, () -> builder.withGpuCount(-1));
+ }
+
+ @Test
+ void deviceIdsMustBePresentAndNonBlank() {
+ TestFixture fixture = new TestFixture();
+ ContainerBuilder.Builder builder = fixture.builder.newContainer("alpine");
+
+ assertThrows(IllegalArgumentException.class, () -> builder.withGpuDeviceIds(List.of()));
+ assertThrows(IllegalArgumentException.class, () -> builder.withGpuDeviceIds(List.of(" ")));
+ }
+
+ @Test
+ void cdiDeviceNameMustBeFullyQualified() {
+ TestFixture fixture = new TestFixture();
+ ContainerBuilder.Builder builder = fixture.builder.newContainer("alpine");
+
+ // A device path is the mistake this guards: the daemon would otherwise fail the
+ // start with an unresolvable-device error that does not name the real problem.
+ assertThrows(IllegalArgumentException.class, () -> builder.withCdiDevices(List.of("/dev/nvidia0")));
+ assertThrows(IllegalArgumentException.class, () -> builder.withCdiDevices(List.of("nvidia.com/gpu")));
+ }
+
+ @Test
+ void countAndExplicitDevicesAreMutuallyExclusive() {
+ TestFixture fixture = new TestFixture();
+
+ assertThrows(IllegalStateException.class,
+ () -> fixture.builder.newContainer("alpine").withGpuCount(1).withAllGpus());
+ assertThrows(IllegalStateException.class,
+ () -> fixture.builder.newContainer("alpine").withGpuCount(1).withGpuDeviceIds(List.of("0")));
+ assertThrows(IllegalStateException.class,
+ () -> fixture.builder.newContainer("alpine")
+ .withCdiDevices(List.of("nvidia.com/gpu=all"))
+ .withGpuCount(1));
+ }
+
@Test
void imageRegistryBasePrefixesEveryContainerImage() {
TestFixture fixture = new TestFixture();
diff --git a/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerGpuDockerIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerGpuDockerIntegrationTest.java
new file mode 100644
index 0000000000..9a660de6d9
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerGpuDockerIntegrationTest.java
@@ -0,0 +1,169 @@
+package io.github.hectorvent.floci.core.common.docker;
+
+import com.github.dockerjava.api.DockerClient;
+import com.github.dockerjava.api.async.ResultCallback;
+import com.github.dockerjava.api.model.Frame;
+import com.github.dockerjava.core.command.WaitContainerResultCallback;
+import io.quarkus.test.junit.QuarkusTest;
+import jakarta.inject.Inject;
+import org.jboss.logging.Logger;
+import org.junit.jupiter.api.Assumptions;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.UUID;
+import java.util.concurrent.TimeUnit;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Proves a GPU device request survives the round trip to a real daemon and that the
+ * container can see the device. Opt-in, because it needs hardware no CI runner has:
+ * run it with {@code -Dgpu.integration.enabled=true}. Without that flag it skips, so the
+ * request-construction coverage in {@link ContainerBuilderTest} and
+ * {@link ContainerLifecycleManagerDeviceRequestTest} is what runs by default.
+ *
+ * <p>Select a device explicitly with
+ * {@code -Dgpu.integration.cdi-device=nvidia.com/gpu=GPU-<uuid>} against a daemon that
+ * resolves Container Device Interface names, such as Podman. With no device named, the
+ * test asks for every GPU using Docker's count form instead, which is the shape to run
+ * against Docker. Note that Podman accepts the count form and then attaches no device
+ * (containers/podman#22645), so that combination fails here by design.
+ */
+@QuarkusTest
+class ContainerGpuDockerIntegrationTest {
+
+ private static final Logger LOG = Logger.getLogger(ContainerGpuDockerIntegrationTest.class);
+ private static final String ENABLED_PROPERTY = "gpu.integration.enabled";
+ private static final String CDI_DEVICE_PROPERTY = "gpu.integration.cdi-device";
+ private static final String IMAGE_PROPERTY = "gpu.integration.image";
+ private static final String DEFAULT_IMAGE = "docker.io/nvidia/cuda:12.8.1-base-ubuntu24.04";
+
+ @Inject
+ DockerClient dockerClient;
+
+ @Inject
+ ContainerBuilder containerBuilder;
+
+ @Inject
+ ContainerLifecycleManager lifecycleManager;
+
+ @BeforeEach
+ void requireGpuEnabledDaemon() {
+ Assumptions.assumeTrue(Boolean.getBoolean(ENABLED_PROPERTY),
+ "GPU hardware tests are opt-in: run with -D" + ENABLED_PROPERTY + "=true on a host with a GPU");
+ Assumptions.assumeTrue(isDockerAvailable(),
+ "A container daemon must be available for GPU integration tests");
+ }
+
+ @Test
+ void containerWithGpuRequestSeesTheDevice() {
+ String image = System.getProperty(IMAGE_PROPERTY, DEFAULT_IMAGE);
+ String cdiDevice = System.getProperty(CDI_DEVICE_PROPERTY);
+
+ ContainerBuilder.Builder builder = containerBuilder.newContainer(image)
+ .withName("floci-gpu-test-" + UUID.randomUUID())
+ .withCmd(List.of("nvidia-smi", "-L"));
+ if (cdiDevice != null && !cdiDevice.isBlank()) {
+ builder.withCdiDevices(List.of(cdiDevice));
+ } else {
+ builder.withAllGpus();
+ }
+
+ String containerId = null;
+ try {
+ containerId = lifecycleManager.create(builder.build());
+ dockerClient.startContainerCmd(containerId).exec();
+ Integer status = dockerClient.waitContainerCmd(containerId)
+ .exec(new WaitContainerResultCallback())
+ .awaitStatusCode(120, TimeUnit.SECONDS);
+
+ String output = logs(containerId);
+ assertEquals(0, status, "nvidia-smi exited nonzero: " + output);
+ // `nvidia-smi -L` prints one "GPU <n>: <name> (UUID: GPU-...)" line per visible
+ // device, so this is the daemon confirming the request was honoured.
+ assertTrue(output.contains("GPU"), "no GPU listed in the container: " + output);
+ if (cdiDevice != null && !cdiDevice.isBlank()) {
+ String uuid = cdiDevice.substring(cdiDevice.indexOf('=') + 1);
+ assertTrue(output.contains(uuid),
+ "the container saw a device other than the one requested: " + output);
+ }
+ LOG.infov("GPU visible to container: {0}", output.trim());
+ } finally {
+ if (containerId != null) {
+ dockerClient.removeContainerCmd(containerId).withForce(true).exec();
+ }
+ }
+ }
+
+ @Test
+ void containerWithoutGpuRequestSeesNoDevice() {
+ String image = System.getProperty(IMAGE_PROPERTY, DEFAULT_IMAGE);
+
+ ContainerSpec spec = containerBuilder.newContainer(image)
+ .withName("floci-gpu-test-cpu-" + UUID.randomUUID())
+ .withCmd(List.of("nvidia-smi", "-L"))
+ .build();
+
+ String containerId = null;
+ try {
+ containerId = lifecycleManager.create(spec);
+ // Two shapes of "no device", both acceptable: the start itself fails, because
+ // nvidia-smi is injected by the runtime alongside the device and is absent from
+ // the image without one; or the container starts and exits nonzero. What must
+ // not happen is a clean exit, which would mean a container that asked for
+ // nothing still reached a GPU because the daemon defaults to an accelerator
+ // runtime.
+ try {
+ dockerClient.startContainerCmd(containerId).exec();
+ } catch (RuntimeException expected) {
+ LOG.infov("Container without a GPU request could not start, as expected: {0}",
+ expected.getMessage());
+ return;
+ }
+ Integer status = dockerClient.waitContainerCmd(containerId)
+ .exec(new WaitContainerResultCallback())
+ .awaitStatusCode(120, TimeUnit.SECONDS);
+
+ assertTrue(status != null && status != 0,
+ "a container that requested no GPU still reached one: " + logs(containerId));
+ } finally {
+ if (containerId != null) {
+ dockerClient.removeContainerCmd(containerId).withForce(true).exec();
+ }
+ }
+ }
+
+ /** Best effort, as in the sibling Docker tests: a read that fails reports itself in the text. */
+ private String logs(String containerId) {
+ StringBuilder out = new StringBuilder();
+ try {
+ dockerClient.logContainerCmd(containerId).withStdOut(true).withStdErr(true)
+ .exec(new ResultCallback.Adapter<Frame>() {
+ @Override
+ public void onNext(Frame frame) {
+ out.append(new String(frame.getPayload(), StandardCharsets.UTF_8));
+ }
+ }).awaitCompletion(10, TimeUnit.SECONDS);
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ out.append("(interrupted while reading logs)");
+ } catch (Exception e) {
+ out.append("(could not read logs: ").append(e.getMessage()).append(')');
+ }
+ return out.toString();
+ }
+
+ private boolean isDockerAvailable() {
+ try {
+ dockerClient.pingCmd().exec();
+ return true;
+ } catch (Exception e) {
+ LOG.warn("No container daemon available for the GPU integration test", e);
+ return false;
+ }
+ }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManagerDeviceRequestTest.java b/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManagerDeviceRequestTest.java
new file mode 100644
index 0000000000..e18f911475
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManagerDeviceRequestTest.java
@@ -0,0 +1,136 @@
+package io.github.hectorvent.floci.core.common.docker;
+
+import com.github.dockerjava.api.DockerClient;
+import com.github.dockerjava.api.command.CreateContainerCmd;
+import com.github.dockerjava.api.command.CreateContainerResponse;
+import com.github.dockerjava.api.model.DeviceRequest;
+import com.github.dockerjava.api.model.HostConfig;
+import io.github.hectorvent.floci.config.EmulatorConfig;
+import io.github.hectorvent.floci.services.lambda.launcher.ImageCacheService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.RETURNS_SELF;
+import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * Asserts that a spec's device requests reach Docker's HostConfig unchanged, and that a
+ * container which asked for nothing still asks for nothing. The second half is the one
+ * that matters operationally: on a host whose daemon defaults to an accelerator runtime,
+ * silently granting devices to every container Floci launches would be invisible until
+ * something contended for the hardware.
+ */
+@ExtendWith(MockitoExtension.class)
+@DisplayName("ContainerLifecycleManager: device requests")
+class ContainerLifecycleManagerDeviceRequestTest {
+
+ @Mock
+ DockerClient dockerClient;
+
+ @Mock
+ ImageCacheService imageCacheService;
+
+ @Mock
+ ContainerDetector containerDetector;
+
+ @Mock
+ PortAllocator portAllocator;
+
+ @Mock
+ EmulatorConfig config;
+
+ @Mock
+ EmulatorConfig.DockerConfig dockerConfig;
+
+ @Mock
+ EmulatorConfig.TlsConfig tlsConfig;
+
+ @BeforeEach
+ void setUp() {
+ lenient().when(config.docker()).thenReturn(dockerConfig);
+ lenient().when(config.tls()).thenReturn(tlsConfig);
+ lenient().when(dockerConfig.resourceNamespace()).thenReturn(Optional.empty());
+ lenient().when(imageCacheService.ensureImageExists(any()))
+ .thenAnswer(invocation -> invocation.getArgument(0));
+ }
+
+ @Test
+ void gpuCountRequestReachesHostConfig() {
+ CreateContainerCmd createCmd = stubCreateContainer();
+ DeviceRequest request = new DeviceRequest()
+ .withCount(1)
+ .withCapabilities(List.of(List.of("gpu")));
+
+ manager().create(specWithDeviceRequests(List.of(request)));
+
+ assertEquals(List.of(request), capturedHostConfig(createCmd).getDeviceRequests());
+ }
+
+ @Test
+ void cdiDeviceRequestReachesHostConfig() {
+ CreateContainerCmd createCmd = stubCreateContainer();
+ DeviceRequest request = new DeviceRequest()
+ .withDriver("cdi")
+ .withDeviceIds(List.of("nvidia.com/gpu=GPU-1fc572c4-6cd7-0e21-dceb-fa71af82eed5"));
+
+ manager().create(specWithDeviceRequests(List.of(request)));
+
+ List<DeviceRequest> applied = capturedHostConfig(createCmd).getDeviceRequests();
+ assertEquals(1, applied.size());
+ assertEquals("cdi", applied.get(0).getDriver());
+ assertEquals(
+ List.of("nvidia.com/gpu=GPU-1fc572c4-6cd7-0e21-dceb-fa71af82eed5"),
+ applied.get(0).getDeviceIds());
+ }
+
+ @Test
+ void containerThatAskedForNoDeviceGetsNone() {
+ CreateContainerCmd createCmd = stubCreateContainer();
+
+ manager().create(new ContainerSpec("busybox:stable"));
+
+ assertNull(capturedHostConfig(createCmd).getDeviceRequests());
+ }
+
+ private ContainerLifecycleManager manager() {
+ return new ContainerLifecycleManager(
+ dockerClient, imageCacheService, containerDetector, portAllocator, config);
+ }
+
+ private static ContainerSpec specWithDeviceRequests(List<DeviceRequest> deviceRequests) {
+ return new ContainerSpec(
+ "busybox:stable", null, List.of(), null, null, null, Map.of(), List.of(), List.of(), null,
+ List.of(), List.of(), List.of(), Map.of(), null, false, null, List.of(), null,
+ null, List.of(), deviceRequests);
+ }
+
+ private CreateContainerCmd stubCreateContainer() {
+ CreateContainerCmd createCmd = mock(CreateContainerCmd.class, RETURNS_SELF);
+ when(dockerClient.createContainerCmd("busybox:stable")).thenReturn(createCmd);
+ CreateContainerResponse response = mock(CreateContainerResponse.class);
+ when(response.getId()).thenReturn("container-id");
+ when(createCmd.exec()).thenReturn(response);
+ return createCmd;
+ }
+
+ private static HostConfig capturedHostConfig(CreateContainerCmd createCmd) {
+ ArgumentCaptor<HostConfig> hostConfig = ArgumentCaptor.forClass(HostConfig.class);
+ verify(createCmd).withHostConfig(hostConfig.capture());
+ return hostConfig.getValue();
+ }
+}