Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
index 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.md
index 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.java
index 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.java
index 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;
-
@ApplicationScoped
public 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.yml
index 43140afca8..9270131bbf 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -502,6 +502,8 @@ floci:
proxy-max-port: 9499
keep-running-on-shutdown: false
ec2:
+ # Optional complete catalog override for locally built guest images.
+ image-catalog-path: ${FLOCI_SERVICES_EC2_IMAGE_CATALOG_PATH:}
enabled: true
imds-port: 9169
# Sweep EC2 containers left on the daemon by a previous run that died mid-launch or
diff --git a/src/test/java/io/github/hectorvent/floci/services/ec2/Ec2ExternalImageCatalogTest.java b/src/test/java/io/github/hectorvent/floci/services/ec2/Ec2ExternalImageCatalogTest.java
new file mode 100644
index 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.yml
index 712036cb0b..44bf251d09 100644
--- a/src/test/resources/application.yml
+++ b/src/test/resources/application.yml
@@ -276,6 +276,8 @@ floci:
proxy-base-port: 9400
proxy-max-port: 9499
ec2:
+ # Optional complete catalog override for locally built guest images.
+ image-catalog-path: ${FLOCI_SERVICES_EC2_IMAGE_CATALOG_PATH:}
enabled: true
imds-port: 9169
ssh-port-range-start: 2200