Light, fluffy, and always free - The AWS Local Emulator alternative
feat(lambda): mount host AWS config for real credential discovery (#703)
Taewoo Ryuaee46fe2da84
diff --git a/docs/services/lambda.md b/docs/services/lambda.mdindex 32fdb4f6a2..0751863fe2 100644--- a/docs/services/lambda.md+++ b/docs/services/lambda.md@@ -287,6 +287,51 @@ FLOCI_DNS_EXTRA_SUFFIXES=localhost.localstack.cloudFLOCI_DNS_EXTRA_SUFFIXES=localhost.localstack.cloud,localhost.example.internal```+### Real AWS Credentials++By default, Floci injects placeholder credentials (`test`/`test`/`test`) into Lambda containers. This is sufficient when all SDK calls target Floci's emulated services.++For hybrid local/cloud testing — where some services are emulated and others hit real AWS — you can mount your host `~/.aws` directory into Lambda containers:++```yaml+services:+ floci:+ image: floci/floci:latest+ environment:+ FLOCI_SERVICES_LAMBDA_AWS_CONFIG_PATH: /Users/me/.aws+ volumes:+ - /var/run/docker.sock:/var/run/docker.sock+```++When `aws-config-path` is set:++- The host path is bind-mounted **read-only** into each Lambda container at `/opt/aws-config`+- `AWS_SHARED_CREDENTIALS_FILE` and `AWS_CONFIG_FILE` env vars are set so the SDK discovers credentials regardless of the container's HOME directory+- No `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` env vars are injected++When unset (default), Floci reads credentials from its own environment and falls back to `test`/`test`/`test`.++!!! tip "Routing specific services to real AWS"+ To keep some services on Floci while others hit real AWS, clear the global endpoint and set service-specific overrides in your function's `--environment`:++ ```+ AWS_ENDPOINT_URL= # clear Floci's global endpoint+ AWS_ENDPOINT_URL_SES=http://localhost.floci.io:4566 # SES stays on Floci+ AWS_ENDPOINT_URL_CLOUDWATCHLOGS=http://localhost.floci.io:4566 # CloudWatch stays on Floci+ ```++ The AWS SDK supports `AWS_ENDPOINT_URL_<SERVICE>` natively. Services without an override will use real AWS endpoints.++!!! note "Credential passthrough without mounting"+ If you don't need the full `~/.aws` directory (e.g., you only have static credentials), you can pass them to Floci's environment directly. When `aws-config-path` is unset, Floci forwards its own `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` env vars into Lambda containers:++ ```yaml+ environment:+ AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}+ AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}+ AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}+ ```+### Private registry authenticationContainer image functions (`"PackageType": "Image"`) that pull from private registries need Docker credentials. See [Docker Configuration → Private Registry Authentication](../configuration/docker.md#private-registry-authentication) for the full guide.diff --git a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.javaindex 559b30602f..7852a17add 100644--- a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java+++ b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java@@ -659,6 +659,19 @@ public interface EmulatorConfig {@WithDefault("100")int unreservedConcurrencyMin();+ /**+ * Host path to bind-mount (read-only) into Lambda containers at /opt/aws-config.+ * When set, no AWS credential env vars are injected; instead+ * AWS_SHARED_CREDENTIALS_FILE and AWS_CONFIG_FILE are set to point at+ * the mounted files, ensuring SDK discovery works regardless of container HOME.+ * When absent, Floci injects credentials from its own environment+ * (AWS_ACCESS_KEY_ID, etc.) or falls back to test/test/test.+ * Blank values are treated as absent.+ *+ * Env var: FLOCI_SERVICES_LAMBDA_AWS_CONFIG_PATH+ */+ Optional<String> awsConfigPath();+HotReload hotReload();interface HotReload {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.javaindex b6a0bcc754..6a87930bff 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@@ -2,6 +2,7 @@ package io.github.hectorvent.floci.core.common.docker;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.LogConfig;import com.github.dockerjava.api.model.Mount;@@ -216,6 +217,11 @@ public class ContainerBuilder {return this;}+ public Builder withReadOnlyBind(String hostPath, String containerPath) {+ this.binds.add(new Bind(hostPath, new Volume(containerPath), AccessMode.ro));+ return this;+ }+/*** Adds a named volume mount.*/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 bfc4e78b25..e19b5d5ee7 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@@ -29,6 +29,7 @@ import java.time.LocalDate;import java.time.format.DateTimeFormatter;import java.util.ArrayList;import java.util.List;+import java.util.Optional;/*** Starts and stops Docker containers for Lambda function execution.@@ -169,9 +170,22 @@ public class ContainerLauncher {}env.add("AWS_DEFAULT_REGION=" + lambdaRegion);env.add("AWS_REGION=" + lambdaRegion);- env.add("AWS_ACCESS_KEY_ID=test");- env.add("AWS_SECRET_ACCESS_KEY=test");- env.add("AWS_SESSION_TOKEN=test");+ Optional<String> awsConfigPath = config.services().lambda().awsConfigPath()+ .filter(s -> !s.isBlank());+ if (awsConfigPath.isPresent()) {+ // ~/.aws will be mounted — don't inject credentials, let SDK discover them.+ // Set explicit file paths so discovery works regardless of container HOME.+ env.add("AWS_SHARED_CREDENTIALS_FILE=/opt/aws-config/credentials");+ env.add("AWS_CONFIG_FILE=/opt/aws-config/config");+ } else {+ // Use Floci's own env vars, fallback to test/test/test+ String ak = System.getenv("AWS_ACCESS_KEY_ID");+ String sk = System.getenv("AWS_SECRET_ACCESS_KEY");+ String st = System.getenv("AWS_SESSION_TOKEN");+ env.add("AWS_ACCESS_KEY_ID=" + (ak != null ? ak : "test"));+ env.add("AWS_SECRET_ACCESS_KEY=" + (sk != null ? sk : "test"));+ env.add("AWS_SESSION_TOKEN=" + (st != null ? st : "test"));+ }env.add("FLOCI_HOSTNAME=" + flociHostname);env.add("FLOCI_ENDPOINT=" + flociEndpoint);env.add("AWS_ENDPOINT_URL=" + flociEndpoint);@@ -208,6 +222,15 @@ public class ContainerLauncher {specBuilder.withCmd(fn.getHandler());}+ // Mount host AWS config into Lambda container (read-only) for SDK credential discovery+ awsConfigPath.ifPresent(hostPath -> {+ if (!Files.isDirectory(Path.of(hostPath))) {+ LOG.warnv("awsConfigPath '{0}' does not exist or is not a directory; "+ + "Lambda containers may fail to discover credentials", hostPath);+ }+ specBuilder.withReadOnlyBind(hostPath, "/opt/aws-config");+ });+ContainerSpec spec = specBuilder.build();// Create container without starting — provided.* runtimes execdiff --git a/src/main/resources/application.yml b/src/main/resources/application.ymlindex 808b21f330..552b5db3ae 100644--- a/src/main/resources/application.yml+++ b/src/main/resources/application.yml@@ -122,6 +122,7 @@ floci:container-idle-timeout-seconds: 300region-concurrency-limit: 1000unreserved-concurrency-min: 100+ # aws-config-path: # Host path to bind-mount (read-only) at /opt/aws-config for real credential discoveryhot-reload:enabled: falseapigateway: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.javaindex c6eb7726e9..b1c63effc6 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@@ -64,6 +64,7 @@ class ContainerLauncherTest {when(config.services()).thenReturn(services);when(services.lambda()).thenReturn(lambda);when(lambda.dockerNetwork()).thenReturn(Optional.empty());+ lenient().when(lambda.awsConfigPath()).thenReturn(Optional.empty());when(config.docker()).thenReturn(docker);when(docker.logMaxSize()).thenReturn("10m");when(docker.logMaxFile()).thenReturn("3");@@ -173,12 +174,45 @@ class ContainerLauncherTest {verify(lifecycleManager).create(specCaptor.capture());List<String> env = specCaptor.getValue().env();- assertTrue(env.contains("AWS_ACCESS_KEY_ID=test"),- "default AWS_ACCESS_KEY_ID should be injected");- assertTrue(env.contains("AWS_SECRET_ACCESS_KEY=test"),- "default AWS_SECRET_ACCESS_KEY should be injected");- assertTrue(env.contains("AWS_SESSION_TOKEN=test"),- "default AWS_SESSION_TOKEN should be injected");+ assertTrue(env.stream().anyMatch(e -> e.startsWith("AWS_ACCESS_KEY_ID=")),+ "AWS_ACCESS_KEY_ID should be injected when awsConfigPath is absent");+ assertTrue(env.stream().anyMatch(e -> e.startsWith("AWS_SECRET_ACCESS_KEY=")),+ "AWS_SECRET_ACCESS_KEY should be injected when awsConfigPath is absent");+ assertTrue(env.stream().anyMatch(e -> e.startsWith("AWS_SESSION_TOKEN=")),+ "AWS_SESSION_TOKEN should be injected when awsConfigPath is absent");+ }++ @Test+ void launchFunction_fallsBackToTestCredentialsWhenEnvUnset() throws Exception {+ // When System.getenv returns null for AWS vars, credentials should be test/test/test.+ // Since we can't control System.getenv in unit tests, we verify the values are either+ // from the environment or the "test" fallback — both are valid.+ Path codePath = Files.createDirectory(tempDir.resolve("creds-fallback"));++ LambdaFunction fn = new LambdaFunction();+ fn.setFunctionName("fallback-fn");+ fn.setRuntime("nodejs20.x");+ fn.setHandler("index.handler");+ fn.setCodeLocalPath(codePath.toString());++ launcher.launch(fn);++ ArgumentCaptor<ContainerSpec> specCaptor = ArgumentCaptor.forClass(ContainerSpec.class);+ verify(lifecycleManager).create(specCaptor.capture());++ List<String> env = specCaptor.getValue().env();+ String accessKey = env.stream().filter(e -> e.startsWith("AWS_ACCESS_KEY_ID=")).findFirst().orElse("");+ String secretKey = env.stream().filter(e -> e.startsWith("AWS_SECRET_ACCESS_KEY=")).findFirst().orElse("");+ String sessionToken = env.stream().filter(e -> e.startsWith("AWS_SESSION_TOKEN=")).findFirst().orElse("");++ // Value should be either the host env var or "test" fallback+ String expectedAk = System.getenv("AWS_ACCESS_KEY_ID") != null ? System.getenv("AWS_ACCESS_KEY_ID") : "test";+ String expectedSk = System.getenv("AWS_SECRET_ACCESS_KEY") != null ? System.getenv("AWS_SECRET_ACCESS_KEY") : "test";+ String expectedSt = System.getenv("AWS_SESSION_TOKEN") != null ? System.getenv("AWS_SESSION_TOKEN") : "test";++ assertEquals("AWS_ACCESS_KEY_ID=" + expectedAk, accessKey);+ assertEquals("AWS_SECRET_ACCESS_KEY=" + expectedSk, secretKey);+ assertEquals("AWS_SESSION_TOKEN=" + expectedSt, sessionToken);}@Test@@ -246,14 +280,23 @@ class ContainerLauncherTest {List<String> env = specCaptor.getValue().env();// Docker honours the last occurrence of a duplicate Env entry, so user// overrides must appear after the Floci defaults.- int defaultKeyIdx = env.indexOf("AWS_ACCESS_KEY_ID=test");- int userKeyIdx = env.indexOf("AWS_ACCESS_KEY_ID=user-key");+ int defaultKeyIdx = -1;+ int userKeyIdx = -1;+ int defaultSecretIdx = -1;+ int userSecretIdx = -1;+ for (int i = 0; i < env.size(); i++) {+ if (env.get(i).startsWith("AWS_ACCESS_KEY_ID=") && userKeyIdx < 0 && !env.get(i).equals("AWS_ACCESS_KEY_ID=user-key")) {+ defaultKeyIdx = i;+ }+ if (env.get(i).equals("AWS_ACCESS_KEY_ID=user-key")) userKeyIdx = i;+ if (env.get(i).startsWith("AWS_SECRET_ACCESS_KEY=") && userSecretIdx < 0 && !env.get(i).equals("AWS_SECRET_ACCESS_KEY=user-secret")) {+ defaultSecretIdx = i;+ }+ if (env.get(i).equals("AWS_SECRET_ACCESS_KEY=user-secret")) userSecretIdx = i;+ }assertTrue(defaultKeyIdx >= 0, "default AWS_ACCESS_KEY_ID still present");assertTrue(userKeyIdx > defaultKeyIdx,"user AWS_ACCESS_KEY_ID must appear after the default");-- int defaultSecretIdx = env.indexOf("AWS_SECRET_ACCESS_KEY=test");- int userSecretIdx = env.indexOf("AWS_SECRET_ACCESS_KEY=user-secret");assertTrue(defaultSecretIdx >= 0, "default AWS_SECRET_ACCESS_KEY still present");assertTrue(userSecretIdx > defaultSecretIdx,"user AWS_SECRET_ACCESS_KEY must appear after the default");@@ -293,4 +336,67 @@ class ContainerLauncherTest {verify(lifecycleManager, never()).createAndStart(any());}++ @Test+ void launchFunction_awsConfigPath_bindsAndSkipsCredentials() throws Exception {+ EmulatorConfig.LambdaServiceConfig lambda = config.services().lambda();+ when(lambda.awsConfigPath()).thenReturn(Optional.of("/home/user/.aws"));++ Path codePath = Files.createDirectory(tempDir.resolve("creds-mount"));++ LambdaFunction fn = new LambdaFunction();+ fn.setFunctionName("mount-fn");+ fn.setRuntime("nodejs20.x");+ fn.setHandler("index.handler");+ fn.setCodeLocalPath(codePath.toString());++ launcher.launch(fn);++ ArgumentCaptor<ContainerSpec> specCaptor = ArgumentCaptor.forClass(ContainerSpec.class);+ verify(lifecycleManager).create(specCaptor.capture());++ ContainerSpec spec = specCaptor.getValue();++ // Should bind-mount to /opt/aws-config (read-only)+ assertTrue(spec.binds().stream()+ .anyMatch(b -> b.getPath().equals("/home/user/.aws")+ && b.getVolume().getPath().equals("/opt/aws-config")+ && b.getAccessMode() == com.github.dockerjava.api.model.AccessMode.ro),+ "awsConfigPath should be bind-mounted read-only to /opt/aws-config");++ // Should set explicit file paths for SDK discovery+ List<String> env = spec.env();+ assertTrue(env.contains("AWS_SHARED_CREDENTIALS_FILE=/opt/aws-config/credentials"),+ "AWS_SHARED_CREDENTIALS_FILE should point to mounted path");+ assertTrue(env.contains("AWS_CONFIG_FILE=/opt/aws-config/config"),+ "AWS_CONFIG_FILE should point to mounted path");++ // Should NOT inject credential env vars+ assertTrue(env.stream().noneMatch(e -> e.startsWith("AWS_ACCESS_KEY_ID=")),+ "AWS_ACCESS_KEY_ID should not be injected when awsConfigPath is set");+ assertTrue(env.stream().noneMatch(e -> e.startsWith("AWS_SECRET_ACCESS_KEY=")),+ "AWS_SECRET_ACCESS_KEY should not be injected when awsConfigPath is set");+ assertTrue(env.stream().noneMatch(e -> e.startsWith("AWS_SESSION_TOKEN=")),+ "AWS_SESSION_TOKEN should not be injected when awsConfigPath is set");+ }++ @Test+ void launchFunction_noAwsConfigPath_noBindMount() throws Exception {+ Path codePath = Files.createDirectory(tempDir.resolve("no-aws-config"));++ LambdaFunction fn = new LambdaFunction();+ fn.setFunctionName("no-mount-fn");+ fn.setRuntime("nodejs20.x");+ fn.setHandler("index.handler");+ fn.setCodeLocalPath(codePath.toString());++ launcher.launch(fn);++ ArgumentCaptor<ContainerSpec> specCaptor = ArgumentCaptor.forClass(ContainerSpec.class);+ verify(lifecycleManager).create(specCaptor.capture());++ assertTrue(specCaptor.getValue().binds().stream()+ .noneMatch(b -> b.getVolume().getPath().equals("/opt/aws-config")),+ "no .aws bind mount when awsConfigPath is absent");+ }}diff --git a/src/test/resources/application.yml b/src/test/resources/application.ymlindex 2a6ffff7ab..42a4fabfd3 100644--- a/src/test/resources/application.yml+++ b/src/test/resources/application.yml@@ -64,6 +64,7 @@ floci:enabled: truelambda:enabled: true+ # aws-config-path:hot-reload:enabled: trueapigateway: