Light, fluffy, and always free - The AWS Local Emulator alternative
fix(ecr): pull rewritten ECS and Lambda images from localhost (#5882)
Alessandro Lattao553411bc702e
diff --git a/docs/services/ecr.md b/docs/services/ecr.mdindex 4b7ef2673a..54df05647a 100644--- a/docs/services/ecr.md+++ b/docs/services/ecr.md@@ -40,7 +40,7 @@- **TLS registry data plane.** Real AWS ECR is HTTPS-only. When TLS is enabled (`FLOCI_TLS_ENABLED=true`), Floci serves the registry data plane over TLS at `<account>.dkr.ecr.<region>.localhost.floci.io:<port>/<repo>`. The server certificate automatically includes regional wildcards `*.dkr.ecr.<region>.localhost.floci.io` for every advertised AWS region as Subject Alternative Names (SANs). Container runtimes and tools (Docker, containerd, nerdctl, podman) connect over HTTPS after trusting Floci's root CA certificate (`GET /_floci/ca.pem` or system trust store). The plain HTTP loopback path (`<account>.dkr.ecr.<region>.localhost:<port>`) remains fully supported without changes.- **Advertise TLS addresses.** Set `FLOCI_SERVICES_ECR_TLS_URI=true` together with `FLOCI_TLS_ENABLED=true` to return the TLS hostname in `repositoryUri` and an HTTPS `proxyEndpoint` from `GetAuthorizationToken`. This opt-in defaults to `false`. With `uri-style: path`, the URI becomes `localhost.floci.io:<port>/<account>/<region>/<repo>` and the login endpoint is `https://localhost.floci.io:<port>`. Existing repository records acquire the current URI when described or returned by deletion. If global TLS is disabled, the option has no effect. Clients must trust the Floci CA, or the configured certificate must cover the advertised names.- **Storage cleanup.** `DeleteRepository --force` removes repository manifests, including untagged manifests. When it deletes the final repository, or when a non-retained runtime stops, Floci removes the named registry volume only in `memory` mode or when `prune-volumes-on-delete: true`.-- **Loopback URI scheme.** Repository URIs follow `<account>.dkr.ecr.<region>.localhost:<flociPort>/<repoName>`. RFC 6761 reserves `*.localhost` to resolve to the loopback address, and the docker daemon auto-trusts loopback as an insecure registry, so `docker push` and `docker pull` work without daemon configuration. A `path` URI style fallback (`localhost:<flociPort>/<account>/<region>/<repo>`) is available via `floci.services.ecr.uri-style: path` for environments where `*.localhost` resolution misbehaves.+- **Loopback URI scheme.** Repository URIs follow `<account>.dkr.ecr.<region>.localhost:<flociPort>/<repoName>`. RFC 6761 reserves `*.localhost` to resolve to the loopback address, and a Docker daemon with the classic image store auto-trusts loopback as an insecure registry, so `docker push` and `docker pull` work without daemon configuration. A daemon with the containerd image store, the default from Docker Engine 29, reaches only `localhost` and `127.0.0.1` over plain HTTP and takes `*.localhost` for an HTTPS registry: use the `path` URI style (`localhost:<flociPort>/<account>/<region>/<repo>`, `floci.services.ecr.uri-style: path`) there, as well as where `*.localhost` resolution misbehaves.- **Image tag mutability.** `IMMUTABLE` repositories allow the first manifest write for a tag and reject every replacement, including a replacement with the same manifest. The proxy forwards blob uploads and digest-addressed manifests unchanged.- **Authorization.** `GetAuthorizationToken` returns `Base64("AWS:floci")` plus a proxy endpoint. The backing `registry:2` runs without auth, so any `aws ecr get-login-password | docker login` succeeds.- **Pull through cache rule configuration.** Pull-through cache rule actions persist AWS-compatible rule metadata with account and Region isolation. `UpdatePullThroughCacheRule` preserves fields omitted by the request and refreshes `updatedAt`. `ValidatePullThroughCacheRule` checks that the rule exists and reports it as valid; Floci does not contact the upstream registry or validate credentials. Rules do not proxy or cache images from the configured upstream registry.@@ -48,7 +48,7 @@- **Cross-account / cross-region isolation.** Internally the registry namespaces repositories as `<account>/<region>/<repoName>`, so the same repository name in different accounts or regions cannot collide.- **Reconcile on first start.** When the registry container starts, Floci queries `GET /v2/_catalog` and recreates `Repository` metadata entries for any namespaces present in the registry but missing from local storage. This means image bytes are never orphaned across restarts.- **Upgrade from direct registry access.** Floci recreates an older backing container with the same volume and a loopback-only port binding. Repositories written through the former direct endpoint retain their physical paths and map to the default account and Region; their returned URI moves to port `4566`.-- **Lambda and ECS integration.** Image-backed Lambda functions (`PackageType=Image`) and ECS task containers reference the same loopback `repositoryUri`. Floci rewrites real-AWS-shaped `<account>.dkr.ecr.<region>.amazonaws.com/...` URIs to the loopback registry at pull time, so CDK's `DockerImageFunction` (which generates AWS-shaped URIs in CloudFormation templates) works without any user-side rewriting.+- **Lambda and ECS integration.** Image-backed Lambda functions (`PackageType=Image`) and ECS task containers reference the same loopback `repositoryUri`. Floci rewrites real-AWS-shaped `<account>.dkr.ecr.<region>.amazonaws.com/...` URIs to the loopback registry at pull time, path style on `localhost` (`localhost:<flociPort>/<account>/<region>/<repo>`) in either URI style and with or without TLS, the one address every Docker daemon pulls from over plain HTTP, so CDK's `DockerImageFunction` (which generates AWS-shaped URIs in CloudFormation templates) works without any user-side rewriting.- **Locally built images win.** An AWS-shaped URI that names an image already present on the Docker daemon is used as-is instead of being rewritten (`FLOCI_SERVICES_ECR_PREFER_LOCAL_IMAGES`, default `true`). Build the image under the exact URI your function or task definition declares (`docker build -t <account>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag> .`) and it runs without a push to the emulated registry, and without the registry container being started. The check uses the reference Floci would launch, so with `FLOCI_DOCKER_IMAGE_REGISTRY_BASE` set the image must be present as `<base>/<account>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag>`.## Configuration@@ -88,7 +88,7 @@ services:`docker login 000000000000.dkr.ecr.us-east-1.localhost:4566` works once Floci starts the registry sidecar.-When Floci runs in a container that publishes its port on another host port (for example `docker run -p 54321:4566`), the `repositoryUri`, the `GetAuthorizationToken` `proxyEndpoint` and the rewritten Lambda and ECS image URIs all name that host port (`000000000000.dkr.ecr.us-east-1.localhost:54321`), because the Docker daemon performs login, push and pull through it. Floci reads the published port from its own container through the mounted Docker socket, and uses `floci.port` (`4566`) when it does not run in a container or the port is not published.+When Floci runs in a container that publishes its port on another host port (for example `docker run -p 54321:4566`), the `repositoryUri`, the `GetAuthorizationToken` `proxyEndpoint` and the rewritten Lambda and ECS image URIs all name that host port (`000000000000.dkr.ecr.us-east-1.localhost:54321`, and `localhost:54321/...` for a rewrite), because the Docker daemon performs login, push and pull through it. Floci reads the published port from its own container through the mounted Docker socket, and uses `floci.port` (`4566`) when it does not run in a container or the port is not published.## Examples@@ -189,8 +189,8 @@ and restart Docker Desktop, following [Docker's CA certificate instructions](httWhen TLS URI advertising is enabled, newly configured EKS registry mirrors accept boththe loopback and TLS names and forward them to the same internal HTTP endpoint. Recreateexisting clusters to pick up changed registry mirror settings. Automatic rewrites of- AWS-shaped Lambda/ECS image references continue using loopback URIs; an explicitly supplied- TLS image reference is used as supplied.+ AWS-shaped Lambda/ECS image references continue using the plain HTTP loopback address; an+ explicitly supplied TLS image reference is used as supplied.## SDK Example (Java)diff --git a/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryDataPlane.java b/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryDataPlane.javaindex d6093d20fb..d67b811bdf 100644--- a/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryDataPlane.java+++ b/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryDataPlane.java@@ -1,6 +1,7 @@package io.github.hectorvent.floci.services.ecr.registry;import io.github.hectorvent.floci.config.EmulatorConfig;+import io.github.hectorvent.floci.config.NetworkExposureGuard;import io.github.hectorvent.floci.services.ecr.EcrService;import io.vertx.core.Vertx;import io.vertx.core.http.HttpClient;@@ -10,6 +11,7 @@ import io.vertx.core.http.HttpMethod;import io.vertx.core.http.RequestOptions;import io.vertx.core.json.JsonArray;import io.vertx.core.json.JsonObject;+import io.vertx.core.net.HostAndPort;import io.vertx.ext.web.Router;import io.vertx.ext.web.RoutingContext;import jakarta.enterprise.context.ApplicationScoped;@@ -245,7 +247,9 @@ public class EcrRegistryDataPlane {storageRepositoryName, repository, backendUri,tag(path)));}- if (!"path".equalsIgnoreCase(uriStyle)) {+ // A loopback host is the address Floci itself hands the Docker daemon for the ECS and+ // Lambda images it pulls, path style in either URI style (see rewriteImageUri).+ if (!"path".equalsIgnoreCase(uriStyle) && !isLoopbackHost(host)) {return Optional.empty();}@@ -265,6 +269,11 @@ public class EcrRegistryDataPlane {registryPath + querySuffix(query, true), tag(registryPath)));}+ private static boolean isLoopbackHost(String host) {+ HostAndPort authority = host == null ? null : HostAndPort.parseAuthority(host, -1);+ return authority != null && NetworkExposureGuard.isLoopback(authority.host());+ }+private static String querySuffix(String query, boolean removeNamespace) {if (query == null || query.isEmpty()) {return "";diff --git a/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManager.java b/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManager.javaindex c41c79abc3..066aeb69ef 100644--- a/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManager.java+++ b/src/main/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManager.java@@ -139,7 +139,12 @@ public class EcrRegistryManager {String region = m.group(2);String repoAndTag = m.group(3);ensureStarted();- String rewritten = repositoryUri(account, region, repoAndTag, "localhost");+ // Path style on localhost whatever style the API advertises. A daemon with the+ // containerd image store, the default from Docker Engine 29, reaches only localhost and+ // 127.0.0.1 over plain HTTP and takes every other name, *.localhost included, for an+ // HTTPS registry: Floci's plain port cannot answer that, and its TLS port cannot prove+ // itself to a daemon that does not trust Floci's CA.+ String rewritten = "localhost:" + advertisedPort() + "/" + internalRepoName(account, region, repoAndTag);LOG.infov("Rewriting ECR image URI {0} -> {1}", image, rewritten);return rewritten;}diff --git a/src/test/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryDataPlaneTest.java b/src/test/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryDataPlaneTest.javaindex 9305cf9e6d..507366d761 100644--- a/src/test/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryDataPlaneTest.java+++ b/src/test/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryDataPlaneTest.java@@ -131,6 +131,36 @@ class EcrRegistryDataPlaneTest {assertEquals("/v2/000000000000/us-east-1/platform/api/manifests/v1", request.backendUri());}+ /**+ * The address Floci hands the Docker daemon for the ECS and Lambda images it pulls is path+ * style on localhost in either URI style: a daemon with the containerd image store reaches+ * only localhost and 127.0.0.1 over plain HTTP, and takes {@code *.localhost} for HTTPS.+ */+ @Test+ void pathStyleOnALoopbackHostIsClaimedInHostnameStyle() {+ EcrRegistryDataPlane.RegistryRequest request = EcrRegistryDataPlane.requestFor("localhost:4566",+ "/v2/000000000000/us-east-1/platform/api/manifests/v1", null, "hostname").orElseThrow();++ assertEquals("000000000000", request.accountId());+ assertEquals("us-east-1", request.region());+ assertEquals("platform/api", request.repositoryName());+ assertEquals("v1", request.tag());+ assertEquals("/v2/000000000000/us-east-1/platform/api/manifests/v1", request.backendUri());+ assertTrue(EcrRegistryDataPlane.requestFor("127.0.0.1:443",+ "/v2/000000000000/us-east-1/platform/api/blobs/sha256:abc", null, "hostname").isPresent());+ assertTrue(EcrRegistryDataPlane.requestFor("[::1]:4566", "/v2/", null, "hostname").isPresent());+ assertTrue(EcrRegistryDataPlane.requestFor("localhost:4566", "/v2/", null, "hostname").isPresent());+ }++ @Test+ void pathStyleOnAnotherHostIsNotClaimedInHostnameStyle() {+ assertFalse(EcrRegistryDataPlane.requestFor("floci:4566",+ "/v2/000000000000/us-east-1/platform/api/manifests/v1", null, "hostname").isPresent());+ assertFalse(EcrRegistryDataPlane.requestFor("localhost.floci.io:4566",+ "/v2/000000000000/us-east-1/platform/api/manifests/v1", null, "hostname").isPresent());+ assertFalse(EcrRegistryDataPlane.requestFor("localhost:4566", "/v2/apis", null, "hostname").isPresent());+ }+@Testvoid unrelatedV2RouteDoesNotClaimTheRequest() {assertFalse(EcrRegistryDataPlane.requestFor("localhost:4566", "/v2/apis", null, "hostname").isPresent());diff --git a/src/test/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManagerTest.java b/src/test/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManagerTest.javaindex 8fe8056a6b..86ae3074b4 100644--- a/src/test/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManagerTest.java+++ b/src/test/java/io/github/hectorvent/floci/services/ecr/registry/EcrRegistryManagerTest.java@@ -392,7 +392,7 @@ class EcrRegistryManagerTest {String rewritten = manager.rewriteImageUri("123456789012.dkr.ecr.cn-north-1.amazonaws.com.cn/backend-user:1");- assertEquals("123456789012.dkr.ecr.cn-north-1.localhost:4566/backend-user:1", rewritten);+ assertEquals("localhost:4566/123456789012/cn-north-1/backend-user:1", rewritten);}@Test@@ -402,7 +402,7 @@ class EcrRegistryManagerTest {String rewritten = manager.rewriteImageUri("123456789012.dkr.ecr.us-east-1.amazonaws.com/backend-user:1");- assertEquals("123456789012.dkr.ecr.us-east-1.localhost:4566/backend-user:1", rewritten);+ assertEquals("localhost:4566/123456789012/us-east-1/backend-user:1", rewritten);verify(lifecycleManager).createAndStart(any());}@@ -432,7 +432,7 @@ class EcrRegistryManagerTest {@ParameterizedTest@CsvSource({- "hostname, 123456789012.dkr.ecr.us-east-1.localhost:4566/backend-user:1",+ "hostname, localhost:4566/123456789012/us-east-1/backend-user:1","path, localhost:4566/123456789012/us-east-1/backend-user:1"})void automaticImageRewritesKeepLoopbackWhenTlsUrisAreAdvertised(String style, String expectedImage) {@@ -494,7 +494,7 @@ class EcrRegistryManagerTest {@ParameterizedTest@CsvSource({- "hostname, 123456789012.dkr.ecr.us-east-1.localhost:54321/backend-user:1",+ "hostname, localhost:54321/123456789012/us-east-1/backend-user:1","path, localhost:54321/123456789012/us-east-1/backend-user:1"})void rewriteImageUri_flociPublishedOnAnotherHostPort_pointsTheDaemonAtThePublishedPort(String style,@@ -517,7 +517,7 @@ class EcrRegistryManagerTest {assertEquals("000000000000.dkr.ecr.us-east-1.localhost:4577/app",manager.getRepositoryUri("000000000000", "us-east-1", "app"));assertEquals("http://000000000000.dkr.ecr.us-east-1.localhost:4577", manager.getProxyEndpoint());- assertEquals("123456789012.dkr.ecr.us-east-1.localhost:4577/backend-user:1",+ assertEquals("localhost:4577/123456789012/us-east-1/backend-user:1",manager.rewriteImageUri(AWS_ECR_IMAGE));verify(currentContainerNetworkResolver, Mockito.atLeastOnce()).resolvePublishedPort(4577);}@@ -576,7 +576,7 @@ class EcrRegistryManagerTest {String rewritten = manager.rewriteImageUri(AWS_ECR_IMAGE);- assertEquals("123456789012.dkr.ecr.us-east-1.localhost:4566/backend-user:1", rewritten);+ assertEquals("localhost:4566/123456789012/us-east-1/backend-user:1", rewritten);verify(dockerClient, Mockito.never()).inspectImageCmd(anyString());}@@ -606,7 +606,7 @@ class EcrRegistryManagerTest {String rewritten = manager.rewriteImageUri(AWS_ECR_IMAGE);- assertEquals("123456789012.dkr.ecr.us-east-1.localhost:4566/backend-user:1", rewritten);+ assertEquals("localhost:4566/123456789012/us-east-1/backend-user:1", rewritten);verify(dockerClient).inspectImageCmd(mirrored);verify(lifecycleManager).createAndStart(any());}@@ -619,7 +619,7 @@ class EcrRegistryManagerTest {String rewritten = manager.rewriteImageUri(AWS_ECR_IMAGE);- assertEquals("123456789012.dkr.ecr.us-east-1.localhost:4566/backend-user:1", rewritten);+ assertEquals("localhost:4566/123456789012/us-east-1/backend-user:1", rewritten);verify(lifecycleManager).createAndStart(any());}