Skip to content

armgit / floci

Public Imported from GitHub
0

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

feat(lambda): allow per-runtime image reference overrides (#4552)

vamsiakf074dd3c40db
diff --git a/docs/configuration/advanced/application-yml.md b/docs/configuration/advanced/application-yml.md
index 70c25af738..9c4f1c67cd 100644
--- a/docs/configuration/advanced/application-yml.md
+++ b/docs/configuration/advanced/application-yml.md
@@ -156,6 +156,8 @@ floci:
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)
+ runtime-images: # Optional per-runtime image references
+ "python3.12": "registry.example/lambda-python:3.12"
honour-architectures: false # true = select the declared Lambda Docker architecture
default-memory-mb: 128
default-timeout-seconds: 3
@@ -329,6 +331,7 @@ All keys in this table are declared on `EmulatorConfig` and accept environment v
| `FLOCI_DEFAULT_AVAILABILITY_ZONE` | `us-east-1a` | Default AZ reported by EC2, RDS, and other AZ-aware services |
| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Default AWS account ID used in ARNs |
| `FLOCI_SERVICES_LAMBDA_ECR_BASE_URI` | `public.ecr.aws` | Registry used when pulling Lambda runtime images (legacy: `FLOCI_ECR_BASE_URI`) |
+| `FLOCI_SERVICES_LAMBDA_RUNTIME_IMAGES__PYTHON3_12__` | *(unset)* | Image reference for `python3.12`; double underscores quote the dotted runtime key |
| `FLOCI_DNS_EXTRA_SUFFIXES` | *(unset)* | Comma-separated extra hostname suffixes the embedded DNS server resolves to Floci's container IP. E.g. `localhost.localstack.cloud,localhost.example.internal` |
| `FLOCI_SERVICES_SSM_MAX_PARAMETER_HISTORY` | `5` | Max parameter versions kept |
| `FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT` | `30` | Default visibility timeout (seconds) |
diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md
index aa2ebdf4b5..d3d99adc4a 100644
--- a/docs/configuration/environment-variables.md
+++ b/docs/configuration/environment-variables.md
@@ -239,6 +239,7 @@ See [Initialization Hooks](./initialization-hooks.md) for lifecycle phases and s
| `FLOCI_SERVICES_LAMBDA_ENABLED` | `true` | Enable the Lambda service |
| `FLOCI_SERVICES_LAMBDA_EPHEMERAL` | `false` | Remove Lambda containers immediately after each invocation |
| `FLOCI_SERVICES_LAMBDA_ECR_BASE_URI` | `public.ecr.aws` | Registry (optionally with a path prefix) the Lambda runtime images are pulled from, e.g. `public.ecr.aws/lambda/python:3.12`. Legacy name `FLOCI_ECR_BASE_URI` still works |
+| `FLOCI_SERVICES_LAMBDA_RUNTIME_IMAGES__PYTHON3_12__` | *(unset)* | Override the `python3.12` runtime image, for example with `registry.example/lambda-python:3.12`. The double underscores quote the runtime key; the unquoted form `FLOCI_SERVICES_LAMBDA_RUNTIME_IMAGES_PYTHON3_12` does not bind. Use the same form for other dotted runtime keys. |
| `FLOCI_SERVICES_LAMBDA_DEFAULT_MEMORY_MB` | `128` | Default memory allocation for functions that don't specify one |
| `FLOCI_SERVICES_LAMBDA_DEFAULT_TIMEOUT_SECONDS` | `3` | Default invocation timeout in seconds |
| `FLOCI_SERVICES_LAMBDA_RUNTIME_API_BASE_PORT` | `12000` | First port in the Lambda Runtime API port range |
diff --git a/docs/services/lambda.md b/docs/services/lambda.md
index b9993435b1..aab408b28f 100644
--- a/docs/services/lambda.md
+++ b/docs/services/lambda.md
@@ -1049,3 +1049,19 @@ of `{}` or with an empty `Filters` array clears any existing filters.
## Supported Runtimes
Any runtime that has an official AWS Lambda container image works with Floci (e.g. `nodejs22.x`, `python3.13`, `java21`, `go1.x`, `provided.al2023`).
+
+By default, Floci builds each runtime image reference from `floci.services.lambda.ecr-base-uri`
+and the runtime tag. To pin one runtime to a full image reference, set
+`floci.services.lambda.runtime-images` in the Floci configuration:
+
+```yaml
+floci:
+ services:
+ lambda:
+ runtime-images:
+ "python3.12": "public.ecr.aws/lambda/python:3.12@sha256:<digest>"
+```
+
+Replace `<digest>` with the image's full SHA-256 digest. The override applies to
+zip-based functions using that runtime; other runtimes retain their default images.
+Custom image URI passthrough and image-package functions are unaffected.
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 cb02f7ddd2..ea7827b44d 100644
--- a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
+++ b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
@@ -4,6 +4,7 @@ import io.smallrye.config.ConfigMapping;
import io.smallrye.config.WithDefault;
import java.net.URI;
import java.util.List;
+import java.util.Map;
import java.util.Optional;
import java.util.OptionalInt;
@@ -2699,6 +2700,9 @@ public interface EmulatorConfig {
@WithDefault("public.ecr.aws") // partition-literal: configurable; ECR Public exists only in the commercial partition
String ecrBaseUri();
+ /** Full image references for individual runtimes, keyed by Lambda runtime identifier. */
+ Map<String, String> runtimeImages();
+
@WithDefault("128")
int defaultMemoryMb();
diff --git a/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolver.java b/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolver.java
index 6fbc35f16c..b258c1b0ea 100644
--- a/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolver.java
+++ b/src/main/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolver.java
@@ -45,9 +45,11 @@ public class ImageResolver {
);
private final String baseUri;
+ private final Map<String, String> runtimeImages;
public ImageResolver(EmulatorConfig config) {
this.baseUri = config.services().lambda().ecrBaseUri();
+ this.runtimeImages = config.services().lambda().runtimeImages();
}
public String resolve(String runtime) {
@@ -63,6 +65,9 @@ public class ImageResolver {
throw new AwsException("InvalidParameterValueException",
"The runtime parameter " + runtime + " is not supported.", 400);
}
+ if (runtimeImages != null && runtimeImages.containsKey(runtime)) {
+ return runtimeImages.get(runtime);
+ }
return baseUri + "/lambda/" + image;
}
}
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index daba00bcf8..ed918f59dd 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -357,6 +357,8 @@ floci:
# 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)
+ # runtime-images: # Optional full image references keyed by Lambda runtime
+ # "python3.12": "public.ecr.aws/lambda/python:3.12@sha256:<digest>"
honour-architectures: false # Select the Lambda architecture for Docker pull and create
default-memory-mb: 128
default-timeout-seconds: 3
diff --git a/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolverConfigIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolverConfigIntegrationTest.java
new file mode 100644
index 0000000000..9cf78d07c8
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolverConfigIntegrationTest.java
@@ -0,0 +1,47 @@
+package io.github.hectorvent.floci.services.lambda.launcher;
+
+import io.github.hectorvent.floci.config.EmulatorConfig;
+import io.quarkus.test.junit.QuarkusTest;
+import io.quarkus.test.junit.QuarkusTestProfile;
+import io.quarkus.test.junit.TestProfile;
+import io.smallrye.config.source.yaml.YamlConfigSource;
+import jakarta.inject.Inject;
+import org.junit.jupiter.api.Test;
+
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+@QuarkusTest
+@TestProfile(ImageResolverConfigIntegrationTest.RuntimeImageProfile.class)
+class ImageResolverConfigIntegrationTest {
+
+ private static final String DIGEST_IMAGE = "public.ecr.aws/lambda/python:3.12@sha256:" + "a".repeat(64);
+
+ @Inject
+ EmulatorConfig config;
+
+ @Inject
+ ImageResolver resolver;
+
+ @Test
+ void quotedRuntimeKeySelectsExactImageReference() {
+ assertEquals(DIGEST_IMAGE, config.services().lambda().runtimeImages().get("python3.12"));
+ assertEquals(DIGEST_IMAGE, resolver.resolve("python3.12"));
+ assertEquals("public.ecr.aws/lambda/python:3.11", resolver.resolve("python3.11"));
+ }
+
+ public static class RuntimeImageProfile implements QuarkusTestProfile {
+ @Override
+ public Map<String, String> getConfigOverrides() {
+ YamlConfigSource source = new YamlConfigSource("runtime-images", """
+ floci:
+ services:
+ lambda:
+ runtime-images:
+ "python3.12": "%s"
+ """.formatted(DIGEST_IMAGE));
+ return source.getProperties();
+ }
+ }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolverEnvConfigTest.java b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolverEnvConfigTest.java
new file mode 100644
index 0000000000..3dd3e80345
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolverEnvConfigTest.java
@@ -0,0 +1,41 @@
+package io.github.hectorvent.floci.services.lambda.launcher;
+
+import io.github.hectorvent.floci.config.EmulatorConfig;
+import io.smallrye.config.EnvConfigSource;
+import io.smallrye.config.SmallRyeConfig;
+import io.smallrye.config.SmallRyeConfigBuilder;
+import org.junit.jupiter.api.Test;
+
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+class ImageResolverEnvConfigTest {
+
+ @Test
+ void dottedRuntimeKeyBindsFromEnvironment() {
+ String image = "registry.example/lambda-python:3.12";
+ SmallRyeConfig config = new SmallRyeConfigBuilder()
+ .withSources(new EnvConfigSource(Map.of(
+ "FLOCI_SERVICES_LAMBDA_RUNTIME_IMAGES__PYTHON3_12__", image), 300))
+ .withMapping(EmulatorConfig.class)
+ .build();
+
+ assertEquals(image, config.getConfigMapping(EmulatorConfig.class)
+ .services().lambda().runtimeImages().get("python3.12"));
+ }
+
+ @Test
+ void unquotedRuntimeKeyDoesNotBind() {
+ SmallRyeConfig config = new SmallRyeConfigBuilder()
+ .withSources(new EnvConfigSource(Map.of(
+ "FLOCI_SERVICES_LAMBDA_RUNTIME_IMAGES_PYTHON3_12",
+ "registry.example/lambda-python:3.12"), 300))
+ .withMapping(EmulatorConfig.class)
+ .build();
+
+ assertNull(config.getConfigMapping(EmulatorConfig.class)
+ .services().lambda().runtimeImages().get("python3.12"));
+ }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolverTest.java b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolverTest.java
index b293b73525..b423577b61 100644
--- a/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolverTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/lambda/launcher/ImageResolverTest.java
@@ -6,6 +6,8 @@ import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
+import java.util.Map;
+
import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.Mockito.*;
@@ -142,6 +144,24 @@ class ImageResolverTest {
assertEquals(customImage, resolver.resolve(customImage));
}
+ @Test
+ void resolvesConfiguredRuntimeImageByDigest() {
+ String digestImage = "public.ecr.aws/lambda/python:3.12@sha256:" + "a".repeat(64);
+ when(config.services().lambda().runtimeImages()).thenReturn(Map.of("python3.12", digestImage));
+ ImageResolver configuredResolver = new ImageResolver(config);
+
+ assertEquals(digestImage, configuredResolver.resolve("python3.12"));
+ assertEquals("public.ecr.aws/lambda/python:3.11", configuredResolver.resolve("python3.11"));
+ }
+
+ @Test
+ void unknownRuntimeCannotBeOverridden() {
+ when(config.services().lambda().runtimeImages()).thenReturn(Map.of("unknown", "example.com/unknown:1"));
+ ImageResolver configuredResolver = new ImageResolver(config);
+
+ assertThrows(AwsException.class, () -> configuredResolver.resolve("unknown"));
+ }
+
@Test
void throwsForUnknownRuntime() {
AwsException ex = assertThrows(AwsException.class, () -> resolver.resolve("dotnet7"));