feat(terraform): support multiple EFS volumes per game server (#37)

## Summary
Refactored the EFS volume configuration to support multiple mount points
per game server, replacing the single `efs_path` field with a flexible
`volumes` list. Each volume entry now creates its own EFS access point
with isolated directory structure.

## Key Changes

- **Variable schema update**: Replaced `efs_path: string` with `volumes:
list(object({ name, container_path }))` in `game_servers` variable
definition
- **New local value**: Added `game_volumes` local that flattens
game-volume pairs into a keyed map (`${game}-${volume.name}`) for EFS
access point creation
- **EFS access point refactor**: Changed from one access point per game
to one per game-volume pair, with root paths now structured as
`/${game}/${volume_name}` instead of `/${game}`
- **Task definition volumes**: Converted static `volume` block to
`dynamic "volume"` block that iterates over `each.value.volumes`,
creating one volume mount per configured volume
- **Container mount points**: Updated `mountPoints` from a single static
entry to a dynamic list comprehension that maps each volume to its
container path
- **Documentation updates**: Updated setup guide, example configs, and
component docs to reflect the new `volumes` structure and explain the
per-volume access point isolation

## Implementation Details

- The flattening logic in `game_volumes` ensures each game-volume
combination gets a unique key while preserving all necessary metadata
(game name, volume name, container path)
- EFS access points maintain UID/GID 1000 ownership per volume, with
each volume isolated under its own directory hierarchy
- The change is backward compatible in behavior—single-volume games
simply have one entry in the `volumes` list
- All example configurations updated to demonstrate the new structure
(Palworld, Satisfactory, FoundryVTT)

https://claude.ai/code/session_01SkWgmzBi8EPkSvpf3shwno

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: CoderCoco

docs/docs/components/terraform.md

@@ -31,7 +31,7 @@ step 3 of the [setup guide](/setup) for details.
 | `aws_region` | `string` | `us-east-1` | AWS region for all resources. |
 | `project_name` | `string` | `game-servers` | Prefix for named resources and the Secrets Manager paths. |
 | `vpc_cidr` | `string` | `10.0.0.0/16` | Parent CIDR; subnets are /24s within it. |
-| `game_servers` | `map(object)` | — | The single source of truth. Per-game: `image`, `cpu`, `memory`, `ports[]`, `environment[]`, `efs_path`, `https`. |
+| `game_servers` | `map(object)` | — | The single source of truth. Per-game: `image`, `cpu`, `memory`, `ports[]`, `environment[]`, `volumes[]` (`name` + `container_path`), `https`. Each `volumes` entry creates its own EFS access point rooted at `/${game}/${name}`. |
 | `hosted_zone_name` | `string` | `codercoco.com` | Existing Route 53 zone looked up as a data source. |
 | `acm_certificate_domain` | `string` | `null` → `*.{hosted_zone_name}` | Wildcard ACM cert for the ALB listener. |
 | `dns_ttl` | `number` | `30` | TTL on Route 53 A records the update-dns Lambda writes. Keep low for fast task churn. |

docs/docs/setup.md

@@ -197,17 +197,21 @@ game_servers = {
       { name = "SERVER_NAME",    value = "My Palworld Server" },
       { name = "ADMIN_PASSWORD", value = "CHANGE_ME" },
     ]
-    efs_path = "/palworld"
-    https    = false
+    volumes = [
+      { name = "saves", container_path = "/palworld" },
+    ]
+    https = false
   }
 }
 ```
 
 Rules worth knowing before you save:
 
-- **`efs_path`** maps to a dedicated EFS access point — each game is isolated
-  in its own directory with UID/GID 1000 ownership. Game images that run as
-  a different UID will fail to mount.
+- **`volumes`** is a list of EFS mount points for the game. Each entry creates
+  a dedicated EFS access point rooted at `/${game}/${name}` and mounts it at
+  `container_path` inside the container. Most games need one entry; add more
+  if the image expects multiple distinct paths. All access points use UID/GID
+  1000 ownership — game images that run as a different UID will fail to mount.
 - **`https = true`** routes the game through an ALB + ACM + Route 53 ALIAS.
   Only set it on games that actually serve HTTP(S); UDP games (most game
   servers) must stay `false`. The ALB is only created if at least one game

terraform/main.tf

@@ -87,6 +87,21 @@ resource "aws_route_table_association" "public" {
 # Dynamic ingress rules — one per port across all configured game servers.
 
 locals {
+  # Flattened map of all game-volume pairs, keyed by "${game}-${volume.name}".
+  # Used to create one EFS access point per volume entry.
+  game_volumes = {
+    for pair in flatten([
+      for game, cfg in var.game_servers : [
+        for vol in cfg.volumes : {
+          key            = "${game}-${vol.name}"
+          game           = game
+          name           = vol.name
+          container_path = vol.container_path
+        }
+      ]
+    ]) : pair.key => pair
+  }
+
   # Ports for non-HTTPS games — open directly to the internet
   direct_game_ports = {
     for pair in distinct(flatten([
@@ -224,9 +239,9 @@ resource "aws_efs_mount_target" "saves" {
   security_groups = [aws_security_group.efs.id]
 }
 
-# One access point per game — isolates each game's save directory
+# One access point per game volume — isolates each volume under /${game}/${volume_name}
 resource "aws_efs_access_point" "game" {
-  for_each       = var.game_servers
+  for_each       = local.game_volumes
   file_system_id = aws_efs_file_system.saves.id
 
   posix_user {
@@ -235,15 +250,15 @@ resource "aws_efs_access_point" "game" {
   }
 
   root_directory {
-    path = "/${each.key}"
+    path = "/${each.value.game}/${each.value.name}"
     creation_info {
       owner_uid   = 1000
       owner_gid   = 1000
       permissions = "0755"
     }
   }
 
-  tags = { Name = "${each.key}-saves" }
+  tags = { Name = each.key }
 }
 
 # ── CloudWatch Log Groups ─────────────────────────────────────────────────────
@@ -308,14 +323,17 @@ resource "aws_ecs_task_definition" "game" {
   memory                   = each.value.memory
   execution_role_arn       = aws_iam_role.ecs_task_execution.arn
 
-  volume {
-    name = "${each.key}-saves"
-    efs_volume_configuration {
-      file_system_id     = aws_efs_file_system.saves.id
-      transit_encryption = "ENABLED"
-      authorization_config {
-        access_point_id = aws_efs_access_point.game[each.key].id
-        iam             = "DISABLED"
+  dynamic "volume" {
+    for_each = each.value.volumes
+    content {
+      name = "${each.key}-${volume.value.name}"
+      efs_volume_configuration {
+        file_system_id     = aws_efs_file_system.saves.id
+        transit_encryption = "ENABLED"
+        authorization_config {
+          access_point_id = aws_efs_access_point.game["${each.key}-${volume.value.name}"].id
+          iam             = "DISABLED"
+        }
       }
     }
   }
@@ -333,9 +351,9 @@ resource "aws_ecs_task_definition" "game" {
 
     environment = each.value.environment
 
-    mountPoints = [{
-      sourceVolume  = "${each.key}-saves"
-      containerPath = each.value.efs_path
+    mountPoints = [for vol in each.value.volumes : {
+      sourceVolume  = "${each.key}-${vol.name}"
+      containerPath = vol.container_path
       readOnly      = false
     }]
 

terraform/outputs.tf

@@ -59,8 +59,11 @@ output "file_manager_security_group_id" {
 }
 
 output "efs_access_points" {
-  description = "Map of game name → EFS access point ID"
-  value       = { for game, ap in aws_efs_access_point.game : game => ap.id }
+  description = "Map of game name → first volume's EFS access point ID (consumed by FileManagerService)"
+  value = {
+    for game, cfg in var.game_servers :
+    game => aws_efs_access_point.game["${game}-${cfg.volumes[0].name}"].id
+  }
 }
 
 output "alb_dns_name" {

terraform/terraform.tfvars.example

@@ -60,8 +60,12 @@ game_servers = {
       { name = "BACKUP_CRON_EXPRESSION", value = "0 */6 * * *" },
       { name = "DIFFICULTY",     value = "Normal" },
     ]
-    efs_path = "/palworld"
-    https   = false
+    # Each entry gets its own EFS access point rooted at /${game}/${name}.
+    # Add more entries if the image expects multiple mount paths.
+    volumes = [
+      { name = "saves", container_path = "/palworld" },
+    ]
+    https = false
   }
 
   # FoundryVTT — web-based virtual tabletop (requires HTTPS)
@@ -83,7 +87,9 @@ game_servers = {
       { name = "CONTAINER_VERBOSE",   value = "true" },
       { name = "FOUNDRY_WORLD",       value = "my-world" },
     ]
-    efs_path = "/data"
-    https   = true
+    volumes = [
+      { name = "data", container_path = "/data" },
+    ]
+    https = true
   }
 }

terraform/variables.tf

@@ -28,10 +28,20 @@ variable "game_servers" {
     memory      = number  # MiB
     ports       = list(object({ container = number, protocol = string }))
     environment = optional(list(object({ name = string, value = string })), [])
-    efs_path    = string  # Mount path inside the container
+    volumes     = list(object({ name = string, container_path = string }))
     https       = optional(bool, false) # If true, traffic is routed through ALB with TLS termination
   }))
 
+  validation {
+    condition = alltrue([
+      for cfg in values(var.game_servers) :
+      length(cfg.volumes) > 0 && alltrue([
+        for v in cfg.volumes : length(v.name) > 0 && length(v.container_path) > 0
+      ])
+    ])
+    error_message = "Each game server must have at least one volume entry with non-empty name and container_path."
+  }
+
   default = {
     palworld = {
       image  = "thijsvanloef/palworld-server-docker:latest"
@@ -53,8 +63,10 @@ variable "game_servers" {
         { name = "BACKUP_CRON_EXPRESSION", value = "0 */6 * * *" },
         { name = "DIFFICULTY",        value = "Normal" },
       ]
-      efs_path = "/palworld"
-      https   = false
+      volumes = [
+        { name = "saves", container_path = "/palworld" },
+      ]
+      https = false
     }
 
     satisfactory = {
@@ -71,8 +83,10 @@ variable "game_servers" {
         { name = "PGID",       value = "1000" },
         { name = "PUID",       value = "1000" },
       ]
-      efs_path = "/config"
-      https   = false
+      volumes = [
+        { name = "config", container_path = "/config" },
+      ]
+      https = false
     }
 
     foundryvtt = {
@@ -87,8 +101,10 @@ variable "game_servers" {
         { name = "FOUNDRY_PROXY_PORT", value = "443" },
         { name = "CONTAINER_VERBOSE",  value = "true" },
       ]
-      efs_path = "/data"
-      https   = true
+      volumes = [
+        { name = "data", container_path = "/data" },
+      ]
+      https = true
     }
   }
 }