Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
index 32fdb4f6a2..0751863fe2 100644
--- a/docs/services/lambda.md
+++ b/docs/services/lambda.md
@@ -287,6 +287,51 @@ FLOCI_DNS_EXTRA_SUFFIXES=localhost.localstack.cloud
FLOCI_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 authentication
Container 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.java
index 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.java
index 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.java
index 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 exec
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 808b21f330..552b5db3ae 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -122,6 +122,7 @@ floci:
container-idle-timeout-seconds: 300
region-concurrency-limit: 1000
unreserved-concurrency-min: 100
+ # aws-config-path: # Host path to bind-mount (read-only) at /opt/aws-config for real credential discovery
hot-reload:
enabled: false
apigateway:
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 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.yml
index 2a6ffff7ab..42a4fabfd3 100644
--- a/src/test/resources/application.yml
+++ b/src/test/resources/application.yml
@@ -64,6 +64,7 @@ floci:
enabled: true
lambda:
enabled: true
+ # aws-config-path:
hot-reload:
enabled: true
apigateway: