Skip to content

armgit / floci

Public Imported from GitHub
0

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

feat(lambda): support custom Docker flags (#3751)

Vũ Thế Huy75d1c2ae6210
diff --git a/docs/configuration/advanced/application-yml.md b/docs/configuration/advanced/application-yml.md
index f4494d2518..22bef0220f 100644
--- a/docs/configuration/advanced/application-yml.md
+++ b/docs/configuration/advanced/application-yml.md
@@ -131,6 +131,7 @@ floci:
lambda:
enabled: true
ephemeral: false # true = remove container after each invocation
+ docker-flags: "" # Extra Docker create flags for Lambda containers
ecr-base-uri: public.ecr.aws # Registry for Lambda runtime images (legacy: floci.ecr-base-uri / FLOCI_ECR_BASE_URI)
honour-architectures: false # true = select the declared Lambda Docker architecture
default-memory-mb: 128
diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md
index de4c5ae62a..e8fcca283c 100644
--- a/docs/configuration/environment-variables.md
+++ b/docs/configuration/environment-variables.md
@@ -220,6 +220,7 @@ See [Initialization Hooks](./initialization-hooks.md) for lifecycle phases and s
| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED` | `false` | Watch Lambda code directories for changes and reload without redeployment |
| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ALLOWED_PATHS` | _(none)_ | Comma-separated host paths that hot-reload is allowed to watch |
| `FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK` | _(none)_ | Docker network for Lambda containers (overrides `FLOCI_SERVICES_DOCKER_NETWORK`) |
+| `FLOCI_SERVICES_LAMBDA_DOCKER_FLAGS` | _(none)_ | Additional Docker flags applied to Lambda containers, such as `--env`, `--volume`, `--publish`, `--add-host`, `--dns`, `--label`, `--network`, `--user`, `--privileged`, and `--platform`. Published ports support `host:container` and `127.0.0.1:host:container` forms |
| `FLOCI_SERVICES_LAMBDA_CONTAINER_NAME_PREFIX` | `floci` | Base name prefix for Lambda-spawned containers and code volumes (must match `[A-Za-z0-9][A-Za-z0-9_.-]*`) |
| `FLOCI_SERVICES_LAMBDA_DOCKER_HOST_OVERRIDE` | _(none)_ | Explicit host/IP Lambda containers use to reach the Runtime API, bypassing auto-detection (e.g. rootless Podman) |
| `FLOCI_SERVICES_LAMBDA_AWS_CONFIG_PATH` | _(none)_ | Host path bind-mounted read-only at `/opt/aws-config` inside Lambda containers for real credential discovery |
diff --git a/docs/services/lambda.md b/docs/services/lambda.md
index c36705bdf6..7b1b61f8a0 100644
--- a/docs/services/lambda.md
+++ b/docs/services/lambda.md
@@ -265,6 +265,7 @@ These AWS Lambda operations have no handler in Floci. Calls will return `404` or
| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED` | `false` | Enable bind-mount hot-reload via `S3Bucket=hot-reload` |
| `FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ALLOWED_PATHS` | *(unset)* | Comma-separated allowlist of host paths that may be bind-mounted |
| `FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK` | *(unset)* | Docker network to attach Lambda containers to (overrides `FLOCI_SERVICES_DOCKER_NETWORK`) |
+| `FLOCI_SERVICES_LAMBDA_DOCKER_FLAGS` | *(unset)* | Additional Docker flags applied to Lambda containers, including `--env`, `--volume`, `--publish`, `--add-host`, `--dns`, `--label`, `--network`, `--user`, `--privileged`, and `--platform`. Published ports support `host:container` and `127.0.0.1:host:container` forms |
| `FLOCI_SERVICES_LAMBDA_EXTRA_HOSTS` | *(unset)* | Comma-separated `hostname:ip` entries added to each Lambda container's `/etc/hosts`; `ip` may be `host-gateway`, mirroring `docker run --add-host` |
| `FLOCI_SERVICES_LAMBDA_DOCKER_HOST_OVERRIDE` | *(unset)* | Explicit host/IP that spawned Lambda containers use to reach Floci's Runtime API, bypassing auto-detection |
| `FLOCI_SERVICES_LAMBDA_CONTAINER_NAME_PREFIX` | `floci` | Base name prefix for spawned Lambda containers and code volumes (e.g. `acme` → `acme-<function>-<id>` containers, `acme-code-<function>-<hash>` volumes). Must be a valid Docker name segment (`[A-Za-z0-9][A-Za-z0-9_.-]*`); invalid values are ignored with a warning |
diff --git a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
index c815f3359a..407855c2ae 100644
--- a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
+++ b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
@@ -2311,6 +2311,9 @@ public interface EmulatorConfig {
/** Docker network to attach Lambda containers to. Empty = default bridge. */
Optional<String> dockerNetwork();
+ /** Additional Docker create flags applied to every Lambda execution container. */
+ Optional<String> dockerFlags();
+
/**
* Base name prefix for the containers and code volumes Lambda spawns, replacing the
* default {@code floci} (e.g. prefix {@code acme} names containers
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 c07dfca29f..facd7da294 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
@@ -567,6 +567,14 @@ public class ContainerBuilder {
return this;
}
+ /** Adds a DNS server to the container configuration. */
+ public Builder withDnsServer(String dnsServer) {
+ if (dnsServer != null && !dnsServer.isBlank()) {
+ dnsServers.add(dnsServer);
+ }
+ return this;
+ }
+
/**
* Builds the immutable ContainerSpec.
*/
diff --git a/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncher.java b/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncher.java
index 13f56f9262..513a06a213 100644
--- a/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncher.java
+++ b/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncher.java
@@ -269,6 +269,9 @@ public class ContainerLauncher implements LambdaRuntimeLauncher {
.withLabels(ContainerStorageHelper.resourceIdentityLabels(
"lambda", fn.getFunctionName(), lambdaAccountId, lambdaRegion));
+ LambdaDockerFlags dockerFlags = configuredDockerFlags();
+ applyDockerFlags(specBuilder, dockerFlags);
+
specBuilder.withEmbeddedDns();
// Inject extra hosts entries into the container if present. Split on the FIRST
@@ -352,7 +355,7 @@ public class ContainerLauncher implements LambdaRuntimeLauncher {
// Create container without starting — provided.* runtimes exec
// /var/runtime/bootstrap on start, so code must be copied first.
- containerId = createContainer(spec, fn);
+ containerId = createContainer(spec, fn, dockerFlags);
LOG.infov("Created container {0} for function {1}", containerId, fn.getFunctionName());
// Docker now holds the real container-to-volume reference, which removeVolume's own in-use
// check protects from here on - release the in-flight marker that stood in for it before
@@ -502,7 +505,10 @@ public class ContainerLauncher implements LambdaRuntimeLauncher {
};
}
- private String createContainer(ContainerSpec spec, LambdaFunction fn) {
+ private String createContainer(ContainerSpec spec, LambdaFunction fn, LambdaDockerFlags dockerFlags) {
+ if (dockerFlags.platform() != null) {
+ return lifecycleManager.create(spec, dockerFlags.platform());
+ }
if (!config.services().lambda().honourArchitectures()) {
return lifecycleManager.create(spec);
}
@@ -514,6 +520,68 @@ public class ContainerLauncher implements LambdaRuntimeLauncher {
return lifecycleManager.create(spec, platform.get());
}
+ private LambdaDockerFlags configuredDockerFlags() {
+ Optional<String> configured = Optional.ofNullable(config.services().lambda().dockerFlags())
+ .orElse(Optional.empty());
+ return configured.filter(value -> !value.isBlank())
+ .map(LambdaDockerFlags::parse)
+ .orElseGet(() -> LambdaDockerFlags.parse(null));
+ }
+
+ private static void applyDockerFlags(ContainerBuilder.Builder builder, LambdaDockerFlags flags) {
+ builder.withEnv(flags.environment());
+ for (String volume : flags.volumes()) {
+ String[] parts = volume.split(":", -1);
+ if (parts.length < 2 || parts.length > 3 || parts[0].isBlank() || parts[1].isBlank()) {
+ throw new IllegalArgumentException("Invalid Lambda Docker volume: " + volume);
+ }
+ if (parts.length == 3 && "ro".equals(parts[2])) {
+ builder.withReadOnlyBind(parts[0], parts[1]);
+ } else if (parts.length == 2 || "rw".equals(parts[2])) {
+ builder.withBind(parts[0], parts[1]);
+ } else {
+ throw new IllegalArgumentException("Invalid Lambda Docker volume mode: " + volume);
+ }
+ }
+ for (String publishedPort : flags.publishedPorts()) {
+ String[] parts = publishedPort.split(":", -1);
+ String hostIp = parts.length == 3 ? parts[0] : null;
+ String hostPort = parts.length == 2 ? parts[0] : parts.length == 3 ? parts[1] : "";
+ String containerPort = parts.length == 2 ? parts[1] : parts.length == 3 ? parts[2] : "";
+ if (hostPort.isBlank() || containerPort.isBlank()) {
+ throw new IllegalArgumentException("Invalid Lambda Docker published port: " + publishedPort);
+ }
+ int parsedHostPort = Integer.parseInt(hostPort);
+ int parsedContainerPort = Integer.parseInt(containerPort);
+ if (hostIp == null) {
+ builder.withPortBinding(parsedContainerPort, parsedHostPort);
+ } else if ("127.0.0.1".equals(hostIp)) {
+ builder.withLoopbackPortBinding(parsedContainerPort, parsedHostPort);
+ } else {
+ throw new IllegalArgumentException("Lambda Docker published ports only support "
+ + "127.0.0.1 as an explicit host address: " + publishedPort);
+ }
+ }
+ for (String extraHost : flags.extraHosts()) {
+ int separator = extraHost.indexOf(':');
+ if (separator <= 0 || separator == extraHost.length() - 1) {
+ throw new IllegalArgumentException("Invalid Lambda Docker extra host: " + extraHost);
+ }
+ builder.withExtraHost(extraHost.substring(0, separator), extraHost.substring(separator + 1));
+ }
+ for (String dnsServer : flags.dnsServers()) {
+ builder.withDnsServer(dnsServer);
+ }
+ builder.withLabels(flags.labels());
+ if (flags.network() != null) {
+ builder.withNetworkMode(flags.network());
+ }
+ if (flags.user() != null) {
+ builder.withUser(flags.user());
+ }
+ builder.withPrivileged(flags.privileged());
+ }
+
public void stop(ContainerHandle handle) {
LOG.infov("Stopping container {0}", handle.getContainerId());
handle.setState(ContainerState.STOPPED);
@@ -887,7 +955,7 @@ public class ContainerLauncher implements LambdaRuntimeLauncher {
acquirePopulatePermit(fn.getFunctionName());
String helperId = null;
try {
- helperId = createContainer(helperSpec, fn);
+ helperId = createContainer(helperSpec, fn, LambdaDockerFlags.parse(null));
lifecycleManager.startCreated(helperId, helperSpec);
copyDirToContainerStrict(lifecycleManager.getDockerClient(), helperId,
Path.of(fn.getCodeLocalPath()), TASK_DIR, fn.getFunctionName());
diff --git a/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/LambdaDockerFlags.java b/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/LambdaDockerFlags.java
new file mode 100644
index 0000000000..932499d8bf
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/LambdaDockerFlags.java
@@ -0,0 +1,111 @@
+package io.github.hectorvent.floci.services.lambda.launcher;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/** Parsed Docker options applied to every Lambda execution container. */
+record LambdaDockerFlags(
+ List<String> environment,
+ List<String> volumes,
+ List<String> publishedPorts,
+ List<String> extraHosts,
+ List<String> dnsServers,
+ Map<String, String> labels,
+ String network,
+ String user,
+ boolean privileged,
+ String platform
+) {
+
+ static LambdaDockerFlags parse(String input) {
+ List<String> tokens = tokenize(input);
+ List<String> environment = new ArrayList<>();
+ List<String> volumes = new ArrayList<>();
+ List<String> publishedPorts = new ArrayList<>();
+ List<String> extraHosts = new ArrayList<>();
+ List<String> dnsServers = new ArrayList<>();
+ Map<String, String> labels = new LinkedHashMap<>();
+ String network = null;
+ String user = null;
+ String platform = null;
+ boolean privileged = false;
+
+ for (int index = 0; index < tokens.size(); index++) {
+ String flag = tokens.get(index);
+ switch (flag) {
+ case "-e", "--env" -> environment.add(value(tokens, ++index, flag));
+ case "-v", "--volume" -> volumes.add(value(tokens, ++index, flag));
+ case "-p", "--publish" -> publishedPorts.add(value(tokens, ++index, flag));
+ case "--add-host" -> extraHosts.add(value(tokens, ++index, flag));
+ case "--dns" -> dnsServers.add(value(tokens, ++index, flag));
+ case "--label" -> addKeyValue(labels, value(tokens, ++index, flag), flag);
+ case "--network" -> network = value(tokens, ++index, flag);
+ case "-u", "--user" -> user = value(tokens, ++index, flag);
+ case "--privileged" -> privileged = true;
+ case "--platform" -> platform = value(tokens, ++index, flag);
+ case "" -> { }
+ default -> throw new IllegalArgumentException("Unsupported Lambda Docker flag: " + flag);
+ }
+ }
+ return new LambdaDockerFlags(List.copyOf(environment), List.copyOf(volumes),
+ List.copyOf(publishedPorts), List.copyOf(extraHosts), List.copyOf(dnsServers),
+ Map.copyOf(labels), network, user, privileged, platform);
+ }
+
+ private static String value(List<String> tokens, int index, String flag) {
+ if (index >= tokens.size() || tokens.get(index).isBlank() || tokens.get(index).startsWith("-")) {
+ throw new IllegalArgumentException("Lambda Docker flag requires a value: " + flag);
+ }
+ return tokens.get(index);
+ }
+
+ private static void addKeyValue(Map<String, String> values, String token, String flag) {
+ int separator = token.indexOf('=');
+ if (separator <= 0) {
+ throw new IllegalArgumentException("Lambda Docker flag requires KEY=VALUE: " + flag);
+ }
+ values.put(token.substring(0, separator), token.substring(separator + 1));
+ }
+
+ static List<String> tokenize(String input) {
+ if (input == null || input.isBlank()) {
+ return List.of();
+ }
+ List<String> tokens = new ArrayList<>();
+ StringBuilder token = new StringBuilder();
+ char quote = 0;
+ boolean escaped = false;
+ for (char character : input.toCharArray()) {
+ if (escaped) {
+ token.append(character);
+ escaped = false;
+ } else if (character == '\\' && quote != '\'') {
+ escaped = true;
+ } else if (quote != 0) {
+ if (character == quote) {
+ quote = 0;
+ } else {
+ token.append(character);
+ }
+ } else if (character == '\'' || character == '"') {
+ quote = character;
+ } else if (Character.isWhitespace(character)) {
+ if (token.length() > 0) {
+ tokens.add(token.toString());
+ token.setLength(0);
+ }
+ } else {
+ token.append(character);
+ }
+ }
+ if (escaped || quote != 0) {
+ throw new IllegalArgumentException("Unterminated quote or escape in Lambda Docker flags");
+ }
+ if (token.length() > 0) {
+ tokens.add(token.toString());
+ }
+ return tokens;
+ }
+}
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 9d8e0d7125..c6e06a84e6 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -301,6 +301,8 @@ floci:
lambda:
enabled: true
ephemeral: false
+ # Extra Docker create flags for Lambda containers, for example: --env KEY=VALUE --volume /host:/container:ro
+ docker-flags: ""
ecr-base-uri: public.ecr.aws # FLOCI_SERVICES_LAMBDA_ECR_BASE_URI — registry for Lambda runtime images (legacy: floci.ecr-base-uri / FLOCI_ECR_BASE_URI)
honour-architectures: false # Select the Lambda architecture for Docker pull and create
default-memory-mb: 128
diff --git a/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncherTest.java b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncherTest.java
index fa87667e00..68fc44a6f6 100644
--- a/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncherTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ContainerLauncherTest.java
@@ -400,6 +400,55 @@ class ContainerLauncherTest {
"small code should be copied directly into /var/task");
}
+ @Test
+ void launchFunction_appliesConfiguredDockerFlagsToRealContainer() throws Exception {
+ when(config.services().lambda().dockerFlags()).thenReturn(Optional.of(
+ "--env NODE_EXTRA_CA_CERTS=/opt/certs/root.pem "
+ + "--volume /tmp/certs:/opt/certs:ro --add-host api.local:host-gateway "
+ + "--dns 1.1.1.1 --label purpose=debug --network lambda-net "
+ + "--user 1000:1000 --privileged --publish 127.0.0.1:5050:5050"));
+ Path codePath = Files.createDirectory(tempDir.resolve("flags-code"));
+
+ LambdaFunction fn = new LambdaFunction();
+ fn.setFunctionName("flags-fn");
+ fn.setRuntime("nodejs20.x");
+ fn.setHandler("index.handler");
+ fn.setCodeLocalPath(codePath.toString());
+
+ launcher.launch(fn);
+
+ ContainerSpec spec = captureRealContainerSpec();
+ assertTrue(spec.env().contains("NODE_EXTRA_CA_CERTS=/opt/certs/root.pem"));
+ assertEquals("lambda-net", spec.networkMode());
+ assertEquals("1000:1000", spec.user());
+ assertTrue(spec.privileged());
+ assertEquals(Map.of(5050, 5050), spec.portBindings());
+ assertEquals(List.of(5050), spec.loopbackPortBindings());
+ assertTrue(spec.extraHosts().contains("api.local:host-gateway"));
+ assertTrue(spec.dnsServers().contains("1.1.1.1"));
+ assertEquals("debug", spec.labels().get("purpose"));
+ assertEquals("/opt/certs", spec.binds().getFirst().getVolume().getPath());
+ assertEquals("/tmp/certs", spec.binds().getFirst().getPath());
+ }
+
+ @Test
+ void launchFunction_rejectsPublishedPortBoundToUnsupportedHostAddress() throws Exception {
+ when(config.services().lambda().dockerFlags()).thenReturn(Optional.of(
+ "--publish 192.0.2.10:5050:5050"));
+ Path codePath = Files.createDirectory(tempDir.resolve("unsupported-publish-address-code"));
+
+ LambdaFunction fn = new LambdaFunction();
+ fn.setFunctionName("unsupported-publish-address-fn");
+ fn.setRuntime("nodejs20.x");
+ fn.setHandler("index.handler");
+ fn.setCodeLocalPath(codePath.toString());
+
+ IllegalArgumentException exception = assertThrows(IllegalArgumentException.class,
+ () -> launcher.launch(fn));
+
+ assertTrue(exception.getMessage().contains("127.0.0.1"));
+ }
+
@Test
void launchFunction_mountsConfiguredFileSystemVolume() throws Exception {
Path codePath = Files.createDirectory(tempDir.resolve("efs-code"));
diff --git a/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/LambdaDockerFlagsTest.java b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/LambdaDockerFlagsTest.java
new file mode 100644
index 0000000000..8ed12087ec
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/LambdaDockerFlagsTest.java
@@ -0,0 +1,59 @@
+package io.github.hectorvent.floci.services.lambda.launcher;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class LambdaDockerFlagsTest {
+
+ @Test
+ void parsesSupportedFlagsAndQuotedValues() {
+ LambdaDockerFlags flags = LambdaDockerFlags.parse(
+ "--env \"NODE_EXTRA_CA_CERTS=/opt/certs/root ca.pem\" "
+ + "--volume /tmp/certs:/opt/certs:ro "
+ + "--publish 127.0.0.1:5050:5050 --add-host api.local:host-gateway "
+ + "--dns 1.1.1.1 --label purpose=debug --network dev-net "
+ + "--user 1000:1000 --privileged --platform linux/amd64");
+
+ assertEquals(List.of("NODE_EXTRA_CA_CERTS=/opt/certs/root ca.pem"), flags.environment());
+ assertEquals(List.of("/tmp/certs:/opt/certs:ro"), flags.volumes());
+ assertEquals(List.of("127.0.0.1:5050:5050"), flags.publishedPorts());
+ assertEquals(List.of("api.local:host-gateway"), flags.extraHosts());
+ assertEquals(List.of("1.1.1.1"), flags.dnsServers());
+ assertEquals(Map.of("purpose", "debug"), flags.labels());
+ assertEquals("dev-net", flags.network());
+ assertEquals("1000:1000", flags.user());
+ assertTrue(flags.privileged());
+ assertEquals("linux/amd64", flags.platform());
+ }
+
+ @Test
+ void supportsShortAliases() {
+ LambdaDockerFlags flags = LambdaDockerFlags.parse(
+ "-e KEY=value -v host:/container -p 8080:80 -u 1000");
+
+ assertEquals(List.of("KEY=value"), flags.environment());
+ assertEquals(List.of("host:/container"), flags.volumes());
+ assertEquals(List.of("8080:80"), flags.publishedPorts());
+ assertEquals("1000", flags.user());
+ }
+
+ @Test
+ void rejectsUnsupportedFlags() {
+ IllegalArgumentException exception = assertThrows(IllegalArgumentException.class,
+ () -> LambdaDockerFlags.parse("--cap-add NET_ADMIN"));
+
+ assertTrue(exception.getMessage().contains("--cap-add"));
+ }
+
+ @Test
+ void rejectsMissingFlagValues() {
+ assertThrows(IllegalArgumentException.class, () -> LambdaDockerFlags.parse("--env"));
+ assertThrows(IllegalArgumentException.class, () -> LambdaDockerFlags.parse("--dns --privileged"));
+ }
+}
diff --git a/src/test/resources/application.yml b/src/test/resources/application.yml
index 0318390f66..303102d083 100644
--- a/src/test/resources/application.yml
+++ b/src/test/resources/application.yml
@@ -141,6 +141,7 @@ floci:
enabled: true
lambda:
enabled: true
+ docker-flags: ""
honour-architectures: false
zip-max-entries: 100000
# aws-config-path: