Skip to content

armgit / floci

Public Imported from GitHub
0

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

feat(docker): attach link-local addresses to a container's network endpoint (#4063)

Priamo Germosen30c89986bd80
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 7b8eca2c3e..d8e44278b6 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
@@ -145,6 +145,7 @@ public class ContainerBuilder {
private String user;
private final List<String> groupAdd = new ArrayList<>();
private final List<String> dnsServers = new ArrayList<>();
+ private final List<String> linkLocalIps = new ArrayList<>();
private final List<DeviceRequest> deviceRequests = new ArrayList<>();
Builder(String image, EmulatorConfig config, DockerHostResolver dockerHostResolver,
@@ -300,6 +301,19 @@ public class ContainerBuilder {
return this;
}
+ /**
+ * Adds a link-local IPv4 address to the container's endpoint on the configured Docker
+ * network, which must be user-defined. Only that one network is supported. The spec is
+ * rejected at {@link #build()} when the address or the network is not valid for this.
+ * Docker does not check that an address is unique on the network, so callers allocate them.
+ */
+ public Builder withLinkLocalIp(String ip) {
+ if (ip != null && !ip.isBlank() && !linkLocalIps.contains(ip.trim())) {
+ linkLocalIps.add(ip.trim());
+ }
+ return this;
+ }
+
/**
* Sets the Docker network from a service-specific Optional, falling back to
* the global services.dockerNetwork() if not present.
@@ -642,7 +656,8 @@ public class ContainerBuilder {
List.copyOf(deviceRequests),
nanoCpus,
cpuShares,
- readonlyRootfs
+ readonlyRootfs,
+ List.copyOf(linkLocalIps)
);
}
}
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 aab38c073e..2285080b31 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
@@ -3,6 +3,7 @@ package io.github.hectorvent.floci.core.common.docker;
import io.github.hectorvent.floci.config.ContainerCaBundle;
import io.github.hectorvent.floci.config.EmulatorConfig;
import io.github.hectorvent.floci.services.lambda.launcher.ImageCacheService;
+import com.fasterxml.jackson.annotation.JsonProperty;
import com.github.dockerjava.api.DockerClient;
import com.github.dockerjava.api.command.CreateContainerCmd;
import com.github.dockerjava.api.command.CreateContainerResponse;
@@ -21,6 +22,7 @@ import com.github.dockerjava.api.model.Mount;
import com.github.dockerjava.api.model.MountType;
import com.github.dockerjava.api.model.Ports;
import com.github.dockerjava.core.command.WaitContainerResultCallback;
+import io.quarkus.runtime.annotations.RegisterForReflection;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import org.apache.commons.compress.archivers.tar.TarArchiveEntry;
@@ -134,6 +136,20 @@ public class ContainerLifecycleManager {
}
private String create(ContainerSpec spec, String resolvedImage, String platform) {
+ String containerId = createWithCaBundle(spec, resolvedImage, platform);
+ if (spec.hasNetworkConfiguration()) {
+ try {
+ attachNetworkBeforeStart(containerId, spec);
+ } catch (RuntimeException e) {
+ removeIfExists(containerId);
+ throw new IllegalStateException(
+ "Failed to attach pre-start network configuration for container " + containerId, e);
+ }
+ }
+ return containerId;
+ }
+
+ private String createWithCaBundle(ContainerSpec spec, String resolvedImage, String platform) {
LOG.debugv("Creating container from spec: image={0}, name={1}", spec.image(), spec.name());
// Built once: a dynamic port binding allocates its host port here.
@@ -194,6 +210,44 @@ public class ContainerLifecycleManager {
return containerId;
}
+ /**
+ * Applies endpoint IPAM while the container is still in CREATED state. docker-java does not
+ * expose Docker's {@code NetworkingConfig} on create, but it does expose the equivalent
+ * network-connect endpoint, so the container is reconnected before it starts.
+ */
+ private void attachNetworkBeforeStart(String containerId, ContainerSpec spec) {
+ if (!spec.hasPortBindings()) {
+ dockerClient.disconnectFromNetworkCmd()
+ .withContainerId(containerId)
+ .withNetworkId(spec.networkMode())
+ .exec();
+ }
+ ContainerNetwork endpoint = new ContainerNetwork().withIpamConfig(new LinkLocalIpam(spec.linkLocalIps()));
+ dockerClient.connectToNetworkCmd()
+ .withContainerId(containerId)
+ .withNetworkId(spec.networkMode())
+ .withContainerNetwork(endpoint)
+ .exec();
+ }
+
+ /**
+ * Docker Engine accepts LinkLocalIPs, but docker-java omits the model property. Registered for
+ * reflection because Jackson finds the added getter reflectively in a native image.
+ */
+ @RegisterForReflection
+ private static final class LinkLocalIpam extends ContainerNetwork.Ipam {
+ private final List<String> linkLocalIps;
+
+ private LinkLocalIpam(List<String> linkLocalIps) {
+ this.linkLocalIps = List.copyOf(linkLocalIps);
+ }
+
+ @JsonProperty("LinkLocalIPs")
+ public List<String> getLinkLocalIps() {
+ return linkLocalIps;
+ }
+ }
+
/**
* Copies the CA bundle into the created, not yet started, container so runtimes that read
* {@code SSL_CERT_FILE} and friends at init find it. A copy rather than a bind mount because
@@ -237,7 +291,8 @@ public class ContainerLifecycleManager {
startContainer(containerId);
LOG.infov("Started container {0}", containerId);
- if (spec.networkMode() != null && !spec.networkMode().isBlank() && spec.hasPortBindings()) {
+ if (spec.networkMode() != null && !spec.networkMode().isBlank()
+ && spec.hasPortBindings() && !spec.hasNetworkConfiguration()) {
try {
dockerClient.connectToNetworkCmd()
.withContainerId(containerId)
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 05a9ae0ded..9b5e455c53 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
@@ -8,6 +8,9 @@ import com.github.dockerjava.api.model.VolumesFrom;
import java.util.List;
import java.util.Map;
+import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
/**
* Immutable specification for a Docker container to be created.
@@ -39,6 +42,7 @@ import java.util.Map;
* @param nanoCpus Hard CPU quota in billionths of a CPU (null = no quota)
* @param cpuShares Relative CPU weight against other containers (null = daemon default)
* @param readonlyRootfs Whether the container's own filesystem is mounted read only
+ * @param linkLocalIps Link-local IPv4 addresses assigned to the container's endpoint on the configured network
*/
public record ContainerSpec(
String image,
@@ -66,8 +70,19 @@ public record ContainerSpec(
List<DeviceRequest> deviceRequests,
Long nanoCpus,
Integer cpuShares,
- boolean readonlyRootfs
+ boolean readonlyRootfs,
+ List<String> linkLocalIps
) {
+ private static final Pattern LINK_LOCAL_IPV4 = Pattern.compile("^169\\.254\\.(\\d{1,3})\\.(\\d{1,3})$");
+ private static final Set<String> NETWORKS_WITHOUT_ENDPOINT_IPAM = Set.of("bridge", "default", "host", "none");
+
+ public ContainerSpec {
+ if (linkLocalIps != null && !linkLocalIps.isEmpty()) {
+ requireUserDefinedNetwork(networkMode);
+ linkLocalIps.forEach(ContainerSpec::requireLinkLocalIpv4);
+ }
+ }
+
/**
* Creates a minimal spec with just the image name.
* All other fields will be null or empty lists.
@@ -75,7 +90,7 @@ public record ContainerSpec(
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(), List.of(), Map.of(), null, false, null, List.of(),
- null, null, List.of(), List.of(), null, null, false);
+ null, null, List.of(), List.of(), null, null, false, List.of());
}
/**
@@ -106,7 +121,7 @@ public record ContainerSpec(
) {
this(image, name, env, cmd, entrypoint, memoryBytes, portBindings, List.of(), exposedPorts,
networkMode, mounts, binds, List.of(), extraHosts, labels, logConfig, privileged,
- cgroupnsMode, dnsServers, workingDir, user, groupAdd, List.of(), null, null, false);
+ cgroupnsMode, dnsServers, workingDir, user, groupAdd, List.of(), null, null, false, List.of());
}
/**
@@ -140,7 +155,7 @@ public record ContainerSpec(
this(image, name, env, cmd, entrypoint, memoryBytes, portBindings, loopbackPortBindings,
exposedPorts, networkMode, mounts, binds, List.of(), extraHosts, labels, logConfig,
privileged, cgroupnsMode, dnsServers, workingDir, user, groupAdd, List.of(),
- null, null, false);
+ null, null, false, List.of());
}
/**
@@ -174,7 +189,7 @@ public record ContainerSpec(
this(image, name, env, cmd, entrypoint, memoryBytes, portBindings, loopbackPortBindings,
exposedPorts, networkMode, mounts, binds, List.of(), extraHosts, labels, logConfig,
privileged, cgroupnsMode, dnsServers, workingDir, user, groupAdd, deviceRequests,
- null, null, false);
+ null, null, false, List.of());
}
/**
@@ -204,4 +219,35 @@ public record ContainerSpec(
public boolean hasDeviceRequests() {
return deviceRequests != null && !deviceRequests.isEmpty();
}
+
+ private static void requireUserDefinedNetwork(String networkMode) {
+ if (networkMode == null || networkMode.isBlank()
+ || NETWORKS_WITHOUT_ENDPOINT_IPAM.contains(networkMode) || networkMode.startsWith("container:")) {
+ throw new IllegalArgumentException(
+ "Link-local addresses need a user-defined Docker network, but the network is '"
+ + networkMode + "'");
+ }
+ }
+
+ private static void requireLinkLocalIpv4(String ip) {
+ Matcher matcher = ip == null ? null : LINK_LOCAL_IPV4.matcher(ip);
+ if (matcher == null || !matcher.matches()
+ || Integer.parseInt(matcher.group(1)) > 255 || Integer.parseInt(matcher.group(2)) > 255) {
+ throw new IllegalArgumentException("'" + ip + "' is not an IPv4 address in 169.254.0.0/16");
+ }
+ }
+
+ /**
+ * Returns true when the container asks for link-local addresses on its network endpoint.
+ */
+ public boolean hasLinkLocalIps() {
+ return linkLocalIps != null && !linkLocalIps.isEmpty();
+ }
+
+ /**
+ * Returns true when the configured network must be attached with endpoint settings before start.
+ */
+ public boolean hasNetworkConfiguration() {
+ return networkMode != null && !networkMode.isBlank() && hasLinkLocalIps();
+ }
}
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 4a85f5ffa8..eb1c5e4e38 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
@@ -127,6 +127,57 @@ class ContainerBuilderTest {
assertEquals(List.of(), spec.groupAdd());
}
+ @Test
+ void withLinkLocalIpRoundTripsIntoSpecIgnoringBlanksAndDuplicates() {
+ TestFixture fixture = new TestFixture();
+
+ ContainerSpec spec = fixture.builder.newContainer("alpine")
+ .withDockerNetwork(Optional.of("test-network"))
+ .withLinkLocalIp("169.254.170.3")
+ .withLinkLocalIp(" 169.254.170.3 ")
+ .withLinkLocalIp(" ")
+ .build();
+
+ assertEquals(List.of("169.254.170.3"), spec.linkLocalIps());
+ }
+
+ @Test
+ void linkLocalIpWithoutUserDefinedNetworkIsRejected() {
+ TestFixture fixture = new TestFixture();
+
+ assertThrows(IllegalArgumentException.class,
+ () -> fixture.builder.newContainer("alpine").withLinkLocalIp("169.254.170.3").build());
+ for (String network : List.of("bridge", "host", "none", "container:router")) {
+ assertThrows(IllegalArgumentException.class,
+ () -> fixture.builder.newContainer("alpine")
+ .withDockerNetwork(Optional.of(network))
+ .withLinkLocalIp("169.254.170.3")
+ .build(),
+ network);
+ }
+ }
+
+ @Test
+ void nonLinkLocalAddressIsRejected() {
+ TestFixture fixture = new TestFixture();
+
+ for (String ip : List.of("10.0.0.5", "169.254.300.1", "169.254.1", "not-an-ip")) {
+ assertThrows(IllegalArgumentException.class,
+ () -> fixture.builder.newContainer("alpine")
+ .withDockerNetwork(Optional.of("test-network"))
+ .withLinkLocalIp(ip)
+ .build(),
+ ip);
+ }
+ }
+
+ @Test
+ void linkLocalIpsDefaultToNone() {
+ TestFixture fixture = new TestFixture();
+
+ assertEquals(List.of(), fixture.builder.newContainer("alpine").build().linkLocalIps());
+ }
+
@Test
void withGpuCountRequestsThatManyGpus() {
TestFixture fixture = new TestFixture();
diff --git a/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManagerNetworkTest.java b/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManagerNetworkTest.java
new file mode 100644
index 0000000000..ec5cb4c4d3
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManagerNetworkTest.java
@@ -0,0 +1,139 @@
+package io.github.hectorvent.floci.core.common.docker;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.github.dockerjava.api.DockerClient;
+import com.github.dockerjava.api.command.ConnectToNetworkCmd;
+import com.github.dockerjava.api.command.CreateContainerCmd;
+import com.github.dockerjava.api.command.CreateContainerResponse;
+import com.github.dockerjava.api.command.DisconnectFromNetworkCmd;
+import com.github.dockerjava.api.command.RemoveContainerCmd;
+import com.github.dockerjava.api.model.ContainerNetwork;
+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.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.InOrder;
+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.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.RETURNS_SELF;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.inOrder;
+import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class ContainerLifecycleManagerNetworkTest {
+
+ private static final String LINK_LOCAL_IP = "169.254.170.31";
+
+ @Mock
+ DockerClient dockerClient;
+
+ @Mock
+ ImageCacheService imageCacheService;
+
+ @Mock
+ ContainerDetector containerDetector;
+
+ @Mock
+ PortAllocator portAllocator;
+
+ @Mock
+ EmulatorConfig config;
+
+ @Mock
+ EmulatorConfig.DockerConfig dockerConfig;
+
+ @Mock
+ EmulatorConfig.TlsConfig tlsConfig;
+
+ private CreateContainerCmd createCmd;
+ private DisconnectFromNetworkCmd disconnectCmd;
+ private ConnectToNetworkCmd connectCmd;
+
+ @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));
+
+ createCmd = mock(CreateContainerCmd.class, RETURNS_SELF);
+ CreateContainerResponse response = mock(CreateContainerResponse.class);
+ disconnectCmd = mock(DisconnectFromNetworkCmd.class, RETURNS_SELF);
+ connectCmd = mock(ConnectToNetworkCmd.class, RETURNS_SELF);
+ lenient().when(dockerClient.createContainerCmd("busybox:stable")).thenReturn(createCmd);
+ lenient().when(createCmd.exec()).thenReturn(response);
+ lenient().when(response.getId()).thenReturn("container-id");
+ lenient().when(dockerClient.disconnectFromNetworkCmd()).thenReturn(disconnectCmd);
+ lenient().when(dockerClient.connectToNetworkCmd()).thenReturn(connectCmd);
+ }
+
+ @Test
+ void createReconnectsLinkLocalEndpointBeforeReturningContainer() throws Exception {
+ manager().create(specWithLinkLocalIp(Map.of()));
+
+ InOrder order = inOrder(createCmd, disconnectCmd, connectCmd);
+ order.verify(createCmd).exec();
+ order.verify(disconnectCmd).exec();
+ order.verify(connectCmd).exec();
+ ArgumentCaptor<ContainerNetwork> endpoint = ArgumentCaptor.forClass(ContainerNetwork.class);
+ verify(connectCmd).withContainerNetwork(endpoint.capture());
+ String serialized = new ObjectMapper().writeValueAsString(endpoint.getValue());
+ assertTrue(serialized.contains("\"LinkLocalIPs\":[\"" + LINK_LOCAL_IP + "\"]"), serialized);
+ }
+
+ @Test
+ void createKeepsPublishedPortsByConnectingWithoutDisconnecting() {
+ manager().create(specWithLinkLocalIp(Map.of(8080, 18080)));
+
+ verify(disconnectCmd, never()).exec();
+ verify(connectCmd).exec();
+ }
+
+ @Test
+ void createRemovesContainerWhenNetworkAttachFails() {
+ RemoveContainerCmd removeCmd = mock(RemoveContainerCmd.class, RETURNS_SELF);
+ lenient().when(dockerClient.removeContainerCmd("container-id")).thenReturn(removeCmd);
+ doThrow(new IllegalStateException("network gone")).when(connectCmd).exec();
+
+ assertThrows(IllegalStateException.class, () -> manager().create(specWithLinkLocalIp(Map.of())));
+
+ verify(dockerClient).removeContainerCmd("container-id");
+ }
+
+ @Test
+ void createLeavesNetworkAloneWithoutLinkLocalIps() {
+ manager().create(new ContainerSpec("busybox:stable"));
+
+ verify(disconnectCmd, never()).exec();
+ verify(connectCmd, never()).exec();
+ }
+
+ private ContainerLifecycleManager manager() {
+ return new ContainerLifecycleManager(dockerClient, imageCacheService, containerDetector,
+ portAllocator, config);
+ }
+
+ private static ContainerSpec specWithLinkLocalIp(Map<Integer, Integer> portBindings) {
+ return new ContainerSpec(
+ "busybox:stable", null, List.of(), null, null, null, portBindings, List.of(),
+ List.of(), "test-network", List.of(), List.of(), List.of(), List.of(), Map.of(), null,
+ false, null, List.of(), null, null, List.of(), List.of(), null, null, false,
+ List.of(LINK_LOCAL_IP));
+ }
+}