Light, fluffy, and always free - The AWS Local Emulator alternative
docs(ecs): document task-role credentials configuration (#4500)
Priamo Germosen81e646b86d92
diff --git a/docs/configuration/advanced/application-yml.md b/docs/configuration/advanced/application-yml.mdindex aa2bb8dd10..3ba8ad1d2b 100644--- a/docs/configuration/advanced/application-yml.md+++ b/docs/configuration/advanced/application-yml.md@@ -261,6 +261,11 @@ floci:ecs:enabled: truemock: false # true = tasks go to RUNNING without Docker (useful for CI)+ docker-network: floci-net # required for task-role credentials; must be user-defined+ task-role-credentials:+ enabled: false # vend real task IAM role credentials to task containers+ ttl-seconds: 21600 # six hours, matching AWS+ port: 51679 # Floci-side port; containers always use 169.254.170.2:80appsync:enabled: truediff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.mdindex e9f4f2a771..3ae89de950 100644--- a/docs/configuration/environment-variables.md+++ b/docs/configuration/environment-variables.md@@ -476,6 +476,10 @@ These services spawn Docker containers. They require access to the Docker socket| `FLOCI_SERVICES_ECS_DOCKER_NETWORK` | _(none)_ | Docker network for ECS task containers || `FLOCI_SERVICES_ECS_HOST_VOLUME_ROOTS` | _(none)_ | Comma-separated allowlist of parent directories host volume `sourcePath`s must resolve under. By default (unset, and `ALLOW_UNSAFE_HOST_VOLUMES=false`) every host volume `sourcePath` is rejected || `FLOCI_SERVICES_ECS_ALLOW_UNSAFE_HOST_VOLUMES` | `false` | Allow any host path, bypassing `HOST_VOLUME_ROOTS`; traversal, the bare root, and the Docker socket (or an ancestor directory of it, e.g. `/var/run`) are still always rejected |+| `FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_ENABLED` | `false` | Vend real task IAM role credentials to task containers over the AWS container-credentials contract. Requires `FLOCI_SERVICES_ECS_DOCKER_NETWORK` to name a user-defined Docker network: the default bridge will not work |+| `FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_TTL_SECONDS` | `21600` | Lifetime of the vended credentials. Matches the six hours AWS documents for task-role credentials |+| `FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_PORT` | `51679` | Port on the Floci host serving the credentials endpoint. Not the address task containers use, which is always `169.254.170.2:80` |+| `FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_PROXY_IMAGE` | `floci/network-helper:local` | Image for the per-network proxy that holds `169.254.170.2` and forwards to the port above |### EC2diff --git a/docs/services/ecs.md b/docs/services/ecs.mdindex 3b5558c611..4287c6eb62 100644--- a/docs/services/ecs.md+++ b/docs/services/ecs.md@@ -695,6 +695,61 @@ Every `awsvpc` task receives an ENI in its subnet. With `FLOCI_NETWORK_SECURITY_| `FLOCI_SERVICES_ECS_DEFAULT_CPU_UNITS` | `256` | Default CPU units when the task definition omits it || `FLOCI_SERVICES_ECS_HOST_VOLUME_ROOTS` | *(unset)* | Approved parent directories for host volume bind mounts (`volumes[].host.sourcePath`) || `FLOCI_SERVICES_ECS_ALLOW_UNSAFE_HOST_VOLUMES` | `false` | Allow any host path, bypassing the `HOST_VOLUME_ROOTS` allowlist; traversal, the bare root, and the Docker socket are still always rejected |+| `FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_ENABLED` | `false` | Vend real task IAM role credentials to task containers |+| `FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_TTL_SECONDS` | `21600` | Lifetime of the vended credentials |+| `FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_PORT` | `51679` | Floci-side port serving the credentials endpoint |+| `FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_PROXY_IMAGE` | `floci/network-helper:local` | Image for the per-network credentials proxy |++### Task IAM role credentials++Off by default. With `FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_ENABLED=true`, a task whose+definition sets a resolvable `taskRoleArn` gets credentials for that role the way real ECS vends+them: Floci+writes `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` into every container in the task, pointing at one+`/v2/credentials/{id}` path per task, and the AWS SDKs pick it up with no code change.++**A user-defined Docker network is required.** Set `FLOCI_SERVICES_ECS_DOCKER_NETWORK` to a network+you created; the default bridge will not work. The SDKs hardcode `169.254.170.2` for this endpoint,+so Floci runs a small proxy container that holds that address on the task's network and forwards to+`FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_PORT`. Each task container is also given its own address+in `169.254.0.0/16`, without which it would have no route to the endpoint at all. Docker only+allows both of those on a user-defined network.++```bash+docker network create floci-net++docker run -d --name floci \+ -p 4566:4566 \+ -v /var/run/docker.sock:/var/run/docker.sock \+ --network floci-net \+ -e FLOCI_SERVICES_ECS_DOCKER_NETWORK=floci-net \+ -e FLOCI_SERVICES_ECS_TASK_ROLE_CREDENTIALS_ENABLED=true \+ floci/floci:latest+```++Credentials a task sets for itself always win. Floci drops only the baseline `AWS_ACCESS_KEY_ID`,+`AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` it would otherwise inject, because the SDKs read+environment credentials before the container endpoint and leaving them in place would silently+shadow the role. Anything the task definition sets explicitly is left alone.++In three cases a task that asks for a role gets none. It starts without the relative URI and keeps+whatever baseline credentials Floci would have injected anyway. Usually that is the emulator's+default account, but if Floci itself was started with AWS credentials in its environment those are+forwarded into the task instead, and Floci logs a warning once per process when it does that.++Either way the task is not running as the role it asked for, so a policy test against it says+nothing about that role: the call is evaluated against a different identity and may succeed or fail+for reasons that have nothing to do with the role's policy.++- **The role does not resolve.** It does not exist in the account, the ARN is malformed, or it+ names a different account: Floci looks the role up in the account the request authenticated as+ and requires an exact ARN match, so a cross-account `taskRoleArn` never resolves.+- **No user-defined Docker network is configured.** The endpoint has nowhere to listen.+- **The task runs under security-group enforcement.** Its containers join an isolated helper+ namespace rather than the shared network the proxy sits on, so the endpoint would not be+ reachable.++Each of these logs a warning naming the task and the role it asked for.### Host volume safetydiff --git a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.javaindex 59ba255020..ca9fe16755 100644--- a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java+++ b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java@@ -2066,9 +2066,9 @@ public interface EmulatorConfig {interface EcsTaskRoleCredentialsConfig {/*** Opt-in: vends real task-role credentials over the AWS container-credentials wire- * contract. Off by default: reaching it from a task container needs a Docker network the- * task and Floci both have real access to, which the follow-up wiring this feeds into- * establishes; this alone has no way to satisfy it.+ * contract. Off by default: reaching it from a task container needs a user-defined Docker+ * network that both the task and the credentials proxy join, so the default bridge is not+ * enough. Set {@code floci.services.ecs.docker-network} alongside this.*/@WithDefault("false")boolean enabled();@@ -2084,10 +2084,10 @@ public interface EmulatorConfig {/*** Port on the Floci host serving the credentials endpoint itself. Not the address a task* container talks to: real ECS SDKs hardcode 169.254.170.2, which nothing in Floci's own- * process can bind without also owning that address on the task's Docker network. A- * follow-up piece launches a small proxy container that holds that address and forwards- * to this port, the same way Lambda and ECS containers already reach Floci's other- * endpoints over {@code host.docker.internal}.+ * process can bind without also owning that address on the task's Docker network. A small+ * proxy container holds that address on each task network and forwards to this port, the+ * same way Lambda and ECS containers already reach Floci's other endpoints over+ * {@code host.docker.internal}.*/@WithDefault("51679")int port();diff --git a/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsContainerManager.java b/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsContainerManager.javaindex 1b8fc20967..6de4d15219 100644--- a/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsContainerManager.java+++ b/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsContainerManager.java@@ -1528,11 +1528,6 @@ public class EcsContainerManager {}return "127.0.0.1";}- /**- * Tears down the firewall registration of a protected task. The ENI itself outlives this:- * it belongs to the task, not to its containers, and {@link #releaseTaskNetwork} frees it when- * the task reaches STOPPED.- *//*** Issues the task's role credentials and makes sure the endpoint that serves them is up,* before any of its containers start.@@ -1629,6 +1624,11 @@ public class EcsContainerManager {}}+ /**+ * Tears down the firewall registration of a protected task. The ENI itself outlives this:+ * it belongs to the task, not to its containers, and {@link #releaseTaskNetwork} frees it when+ * the task reaches STOPPED.+ */private void cleanupProtectedNetwork(EcsTaskHandle handle) {if (firewallManager != null && handle.getNetworkInterfaceId() != null) {firewallManager.unregister(handle.getNetworkInterfaceId());diff --git a/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsCredentialsProxy.java b/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsCredentialsProxy.javaindex f254b72b13..ec5acbdc47 100644--- a/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsCredentialsProxy.java+++ b/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsCredentialsProxy.java@@ -26,10 +26,10 @@ import java.util.concurrent.ConcurrentHashMap;/*** Owns the small proxy container, one per Docker network, that holds the ECS container-credentials* address (169.254.170.2) and forwards to {@link EcsTaskRoleCredentialsServer}. A task container- * needs its own address in 169.254.0.0/16 to reach this proxy at all (see the follow-up wiring- * that gives it one): without a connected route for that range, the kernel routes toward the- * default gateway instead of resolving the peer directly, and the connection is refused before it- * reaches this proxy's socket.+ * needs its own address in 169.254.0.0/16 to reach this proxy at all, which+ * {@code EcsTaskLinkLocalAddresses} hands out: without a connected route for that range, the+ * kernel routes toward the default gateway instead of resolving the peer directly, and the+ * connection is refused before it reaches this proxy's socket.** <p>Docker accepts a link-local address request even on a runtime that then does not honour it* (see the review discussion on #4063), so a bind is never trusted from the API call alone: afterdiff --git a/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsTaskRoleCredentialsServer.java b/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsTaskRoleCredentialsServer.javaindex ac4b0c799d..4ae30217b7 100644--- a/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsTaskRoleCredentialsServer.java+++ b/src/main/java/io/github/hectorvent/floci/services/ecs/container/EcsTaskRoleCredentialsServer.java@@ -26,8 +26,8 @@ import java.util.concurrent.CompletableFuture;* <p>Bound to a normal Floci-host port, not to 169.254.170.2: the AWS SDK hardcodes that address* (it is not configurable, unlike EC2's {@code AWS_EC2_METADATA_SERVICE_ENDPOINT}), and nothing in* Floci's own process can bind an address it does not otherwise own on a task's Docker network.- * A follow-up piece is what actually holds 169.254.170.2, one small proxy container per ECS- * network, forwarding here over {@code host.docker.internal}.+ * {@link EcsCredentialsProxy} is what actually holds 169.254.170.2, one small proxy container per+ * ECS network, forwarding here over {@code host.docker.internal}.*/@ApplicationScopedpublic class EcsTaskRoleCredentialsServer {