Light, fluffy, and always free - The AWS Local Emulator alternative
feat(ec2): support an external image catalog (#4144)
luisetercdf68eebaeff5
diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.mdindex 1200f00b5a..36b3323117 100644--- a/docs/configuration/environment-variables.md+++ b/docs/configuration/environment-variables.md@@ -480,6 +480,7 @@ These services spawn Docker containers. They require access to the Docker socket|---|---|---|| `FLOCI_SERVICES_EC2_ENABLED` | `true` | Enable the EC2 service || `FLOCI_SERVICES_EC2_MOCK` | `false` | When `true`, instances are registered in state but no containers are spawned |+| `FLOCI_SERVICES_EC2_IMAGE_CATALOG_PATH` | (unset) | Path to a complete YAML image catalog replacing the bundled EC2 catalog; mount the file at this path when running in Docker || `FLOCI_SERVICES_EC2_IMDS_PORT` | `9169` | Port for the EC2 Instance Metadata Service (IMDS) endpoint || `FLOCI_SERVICES_EC2_SSH_PORT_RANGE_START` | `2200` | First port in the SSH port range for EC2 instances || `FLOCI_SERVICES_EC2_SSH_PORT_RANGE_END` | `2299` | Last port in the SSH port range |diff --git a/docs/services/ec2.md b/docs/services/ec2.mdindex a681504971..e3c6d208ca 100644--- a/docs/services/ec2.md+++ b/docs/services/ec2.md@@ -885,3 +885,12 @@ aws ec2 associate-address \- `DescribeImages` returns AMIs from the EC2 image catalog, including common AMIs and Floci-native AMI IDs.- Security group rules are not enforced as a firewall (Docker bridge networking handles routing), but TCP ingress rules opened to a CIDR source are published on the host via socat sidecars so the instance's app is reachable from `localhost` — see [Security Group Port Publishing](#security-group-port-publishing).- The IMDS server identifies which instance is calling via IMDSv2 tokens (mapped at token issuance time) or by the container's bridge IP for IMDSv1.++### External image catalog++Set `FLOCI_SERVICES_EC2_IMAGE_CATALOG_PATH` (`floci.services.ec2.image-catalog-path`)+to a readable YAML file to replace the bundled image catalog for a Floci process.+The file uses the same schema as `src/main/resources/ec2/image-catalog.yaml` and must+include every image that process should expose. Missing or invalid files fail on first+catalog use; leaving the setting unset preserves the bundled catalog. Containerized+Floci needs the file mounted at the configured container path.diff --git a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.javaindex 7d94f7d675..b2d5372fc7 100644--- a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java+++ b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java@@ -2594,6 +2594,9 @@ public interface EmulatorConfig {}interface Ec2ServiceConfig {+ /** Optional full EC2 catalog file for locally built guest images. */+ Optional<String> imageCatalogPath();+@WithDefault("true")boolean enabled();diff --git a/src/main/java/io/github/hectorvent/floci/services/ec2/Ec2ImageCatalog.java b/src/main/java/io/github/hectorvent/floci/services/ec2/Ec2ImageCatalog.javaindex 9f4d01f594..bf7821d275 100644--- a/src/main/java/io/github/hectorvent/floci/services/ec2/Ec2ImageCatalog.java+++ b/src/main/java/io/github/hectorvent/floci/services/ec2/Ec2ImageCatalog.java@@ -1,7 +1,18 @@package io.github.hectorvent.floci.services.ec2;+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;+import com.fasterxml.jackson.databind.ObjectMapper;+import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;+import io.github.hectorvent.floci.config.EmulatorConfig;+import io.github.hectorvent.floci.services.ec2.model.Image;+import io.quarkus.runtime.annotations.RegisterForReflection;+import jakarta.enterprise.context.ApplicationScoped;+import jakarta.inject.Inject;+import java.io.IOException;import java.io.InputStream;+import java.nio.file.Files;+import java.nio.file.Path;import java.util.ArrayList;import java.util.Collections;import java.util.LinkedHashMap;@@ -9,29 +20,33 @@ import java.util.List;import java.util.Map;import java.util.Optional;-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;-import com.fasterxml.jackson.databind.ObjectMapper;-import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;--import io.github.hectorvent.floci.services.ec2.model.Image;-import io.quarkus.runtime.annotations.RegisterForReflection;-import jakarta.enterprise.context.ApplicationScoped;-@ApplicationScopedpublic class Ec2ImageCatalog {private static final String CATALOG_RESOURCE_NAME = "ec2/image-catalog.yaml";private static final ObjectMapper YAML_MAPPER = new ObjectMapper(new YAMLFactory());+ private final Path catalogPath;private volatile Loaded loaded;+ @Inject+ public Ec2ImageCatalog(EmulatorConfig config) {+ this.catalogPath = config.services().ec2().imageCatalogPath().filter(path -> !path.isBlank()).map(Path::of).orElse(null);+ }+public Ec2ImageCatalog() {+ this.catalogPath = null;// The catalog is parsed lazily on first access rather than at bean// construction. Mock mode never reads it, so eager loading would fail// EC2 bean creation needlessly when the resource is unavailable.}+ Ec2ImageCatalog(Path catalogPath) {+ this.catalogPath = catalogPath;+ }+Ec2ImageCatalog(Catalog catalog) {+ this.catalogPath = null;this.loaded = new Loaded(catalog);}@@ -72,7 +87,8 @@ public class Ec2ImageCatalog {synchronized (this) {result = loaded;if (result == null) {- result = new Loaded(readResource(CATALOG_RESOURCE_NAME, Catalog.class));+ result = new Loaded(catalogPath == null+ ? readResource(CATALOG_RESOURCE_NAME, Catalog.class) : readFile(catalogPath));loaded = result;}}@@ -97,6 +113,14 @@ public class Ec2ImageCatalog {}}+ private static Catalog readFile(Path path) {+ try (InputStream input = Files.newInputStream(path)) {+ return YAML_MAPPER.readValue(input, Catalog.class);+ } catch (IOException e) {+ throw new IllegalStateException("Failed to load EC2 image catalog file: " + path, e);+ }+ }+private static <T> T readResource(String resourceName, Class<T> type) {ClassLoader loader = Thread.currentThread().getContextClassLoader();try (InputStream input = loader.getResourceAsStream(resourceName)) {diff --git a/src/main/resources/application.yml b/src/main/resources/application.ymlindex 43140afca8..9270131bbf 100644--- a/src/main/resources/application.yml+++ b/src/main/resources/application.yml@@ -502,6 +502,8 @@ floci:proxy-max-port: 9499keep-running-on-shutdown: falseec2:+ # Optional complete catalog override for locally built guest images.+ image-catalog-path: ${FLOCI_SERVICES_EC2_IMAGE_CATALOG_PATH:}enabled: trueimds-port: 9169# Sweep EC2 containers left on the daemon by a previous run that died mid-launch ordiff --git a/src/test/java/io/github/hectorvent/floci/services/ec2/Ec2ExternalImageCatalogTest.java b/src/test/java/io/github/hectorvent/floci/services/ec2/Ec2ExternalImageCatalogTest.javanew file mode 100644index 0000000000..430a5359e2--- /dev/null+++ b/src/test/java/io/github/hectorvent/floci/services/ec2/Ec2ExternalImageCatalogTest.java@@ -0,0 +1,46 @@+package io.github.hectorvent.floci.services.ec2;++import org.junit.jupiter.api.Test;+import org.junit.jupiter.api.io.TempDir;++import java.nio.file.Files;+import java.nio.file.Path;++import static org.junit.jupiter.api.Assertions.*;++class Ec2ExternalImageCatalogTest {+ @TempDir+ Path directory;++ @Test+ void externalCatalogSelectsLocalSystemdImageWithoutChangingBundledCatalog() throws Exception {+ Path catalog = directory.resolve("images.yaml");+ Files.writeString(catalog, """+ defaultDockerImage: example/base:1+ images:+ - imageId: ami-local-worker+ aliases: [ami-worker-alias]+ dockerImage: example/worker:1+ name: local-worker+ description: local worker+ architecture: arm64+ creationDate: '2025-11-05T00:00:00.000Z'+ guestRuntime: systemd+ """);+ Ec2ImageCatalog external = new Ec2ImageCatalog(catalog);+ assertEquals("example/worker:1", external.findByIdOrAlias("ami-worker-alias").orElseThrow().dockerImage);+ assertEquals("systemd", external.findByIdOrAlias("ami-local-worker").orElseThrow().guestRuntime);+ assertEquals("example/base:1", external.defaultDockerImage());+ assertTrue(new Ec2ImageCatalog().findByIdOrAlias("ami-amazonlinux2023").isPresent());+ assertTrue(new Ec2ImageCatalog().findByIdOrAlias("ami-local-worker").isEmpty());+ }++ @Test+ void missingOrInvalidFileFailsInsteadOfSilentlyUsingBundledImages() throws Exception {+ assertThrows(IllegalStateException.class,+ () -> new Ec2ImageCatalog(directory.resolve("missing.yaml")).images());+ Path invalid = directory.resolve("invalid.yaml");+ Files.writeString(invalid, "images: [not-valid");+ assertThrows(IllegalStateException.class, () -> new Ec2ImageCatalog(invalid).images());+ }+}diff --git a/src/test/resources/application.yml b/src/test/resources/application.ymlindex 712036cb0b..44bf251d09 100644--- a/src/test/resources/application.yml+++ b/src/test/resources/application.yml@@ -276,6 +276,8 @@ floci:proxy-base-port: 9400proxy-max-port: 9499ec2:+ # Optional complete catalog override for locally built guest images.+ image-catalog-path: ${FLOCI_SERVICES_EC2_IMAGE_CATALOG_PATH:}enabled: trueimds-port: 9169ssh-port-range-start: 2200