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.mdindex f4494d2518..22bef0220f 100644--- a/docs/configuration/advanced/application-yml.md+++ b/docs/configuration/advanced/application-yml.md@@ -131,6 +131,7 @@ floci:lambda:enabled: trueephemeral: false # true = remove container after each invocation+ docker-flags: "" # Extra Docker create flags for Lambda containersecr-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 architecturedefault-memory-mb: 128diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.mdindex 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.mdindex 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.javaindex 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 containersdiff --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.javaindex 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.javaindex 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.javanew file mode 100644index 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.ymlindex 9d8e0d7125..c6e06a84e6 100644--- a/src/main/resources/application.yml+++ b/src/main/resources/application.yml@@ -301,6 +301,8 @@ floci:lambda:enabled: trueephemeral: 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 createdefault-memory-mb: 128diff --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.javaindex 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"));+ }+@Testvoid 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.javanew file mode 100644index 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.ymlindex 0318390f66..303102d083 100644--- a/src/test/resources/application.yml+++ b/src/test/resources/application.yml@@ -141,6 +141,7 @@ floci:enabled: truelambda:enabled: true+ docker-flags: ""honour-architectures: falsezip-max-entries: 100000# aws-config-path: