Skip to Content
ConfigurationInfrastructureAWS (ECS & Fargate)Persistent Storage (EFS)

Persistent Storage with AWS EFS

By default, AWS Fargate tasks are stateless. This means any data written to the container’s local filesystem is lost when the task restarts or updates.

For stateful services like MongoDB, PostgreSQL, or shared file storage, Nanokit provides automated integration with Amazon EFS (Elastic File System).

How it Works

When you define a volume in your nanokit.yml for an AWS environment, Nanokit orchestration performs the following steps:

  1. Provisioning: Creates a project-wide EFS File System (e.g., nk-efs-mynapp-stage).
  2. Networking: Sets up Mount Targets in all public subnets of your VPC.
  3. Security: Configures Security Group rules to allow NFS (Port 2049) traffic between the Fargate tasks and the EFS cluster.
  4. Mounting: Automatically registers the EFS volume in the ECS Task Definition and mounts it to the specifies path in your container.

Configuration

To enable EFS persistence, add a volumes section to your service definition:

nanokit.yml
services:
  database:
    image: mongo:latest
    volumes:
      - data-store:/data/db # <volume-name>:<container-path>

Volume Syntax

  • Name: A descriptive name for the volume (e.g., data-store). This helps identify the storage in the AWS Console.
  • Path: The internal path in the container where the data should be persisted (e.g., /data/db for MongoDB).

Preparation & Permissions

To allow Nanokit to manage EFS for you, ensured your IAM credentials have the following permission:

  • AmazonElasticFileSystemFullAccess

[!IMPORTANT] If you are using a restricted IAM policy, ensure you allow elasticfilesystem:CreateFileSystem, elasticfilesystem:CreateMountTarget, and elasticfilesystem:Describe*.

Best Practices

Performance

EFS is optimized for concurrent access and high availability. For most Nanokit applications, the default General Purpose performance mode with Bursting throughput is the most cost-effective choice and is what Nanokit uses by default.

Managed vs Self-Hosted

While EFS allows you to run your own database containers (like MongoDB), for production workloads where high availability and backups are critical, we still recommend:

  • AWS RDS: For SQL databases (Postgres, MySQL).
  • MongoDB Atlas: For MongoDB.
  • Neon/Turso: For edge-ready managed databases.

Use EFS primarily for:

  • Shared assets (uploads, images).
  • Legacy applications requiring a persistent disk.
  • Development/Stage environments where a full RDS instance would be overkill.

Troubleshooting

Connectivity

If your task fails to start or stuck in PROVISIONING, check that the Security Group allows inbound traffic on port 2049. Nanokit attempts to configure this automatically, but custom VPC settings might interfere.

Performance Lag

EFS is a network-based filesystem. For extremely high-I/O applications (like high-frequency trading or large video rendering), EFS might introduce latency. In such cases, consider using managed services or EBS (on EC2-based ECS).

Getting StartedCloudflare (DNS)