Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
index aa2bb8dd10..3ba8ad1d2b 100644
--- a/docs/configuration/advanced/application-yml.md
+++ b/docs/configuration/advanced/application-yml.md
@@ -261,6 +261,11 @@ floci:
ecs:
enabled: true
mock: 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:80
appsync:
enabled: true
diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md
index 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 |
### EC2
diff --git a/docs/services/ecs.md b/docs/services/ecs.md
index 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 safety
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 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.java
index 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.java
index 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: after
diff --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.java
index 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}.
*/
@ApplicationScoped
public class EcsTaskRoleCredentialsServer {