OverlayFS Docker explicado: capas, copy-up y trampas

OverlayFS es el filesystem de unión que Docker usa para apilar capas de imágenes y ejecutar contenedores sin duplicar gigabytes innecesariamente. Cuando hacés docker run, el kernel Linux monta un overlay donde conviven los directorios lower —las capas de tu imagen, solo lectura— y un upper —tu capa de escritura efímera—, todo combinado en una vista merged. A junio de 2026, sigue siendo el corazón del storage de Docker, y entender cómo funciona te salva de dolores de cabeza con el espacio en disco y el rendimiento de tus contenedores.

OverlayFS es un filesystem de unión del kernel Linux que permite superponer múltiples directorios de solo lectura y uno de escritura en una única vista jerárquica. Docker lo implementa mediante el controlador overlay2 para construir imágenes en capas inmutables y darle a cada contenedor un espacio de escritura temporal, llamado upperdir, sin tocar las capas base. Es la tecnología que hace posible que cientos de contenedores compartan la misma imagen de Ubuntu ocupando el espacio en disco una sola vez.

¿Qué son los cuatro directorios clave en un montaje OverlayFS?

Todo montaje OverlayFS se arma con cuatro directorios. Si alguna vez tuviste que debuggear storage de Docker a mano, los vas a reconocer:

• lowerdir: las capas de solo lectura. Acá viven los archivos de la imagen base y de cada instrucción de tu Dockerfile. Se pueden apilar varios lowerdirs, separados por dos puntos, y el orden define la precedencia —el último listado tiene prioridad más alta—.
• upperdir: la capa de escritura del contenedor. Cualquier modificación, creación o eliminación de archivos dentro del contenedor se registra acá. Es el único directorio writable del overlay.
• merged: la vista unificada. El kernel combina lowerdir y upperdir en una sola jerarquía de archivos. Es lo que ves cuando hacés ls dentro del contenedor.
• workdir: un directorio interno que usa el kernel para operaciones atómicas. No se toca, no se inspecciona, pero sin él el montaje no funciona. Tiene que residir en el mismo filesystem que upperdir.

El comando mount -t overlay overlay -o lowerdir=/capas,upperdir=/cambios,workdir=/trabajo /merged es la forma manual de hacer todo esto. Docker, por suerte, lo gestiona automáticamente con el driver overlay2, pero el principio es exactamente el mismo.

¿Cómo realiza OverlayFS las operaciones de copia en escritura (copy-up)?

Acá está el corazón del asunto. Cuando un contenedor necesita escribir en un archivo que pertenece a la imagen —es decir, que está en lowerdir—, OverlayFS no modifica el original. Lo que hace es el famoso copy-up: copia el archivo completo de lowerdir a upperdir, y la escritura ocurre ahí. Complementá con nuestra comparativa de pipelines CI/CD.

Esto es a nivel de archivo, no de bloque. Si tu imagen tiene un dump de base de datos de 500 MB y tu aplicación solo toca un registro al arrancar (sí, en serio), el kernel copia los 500 MB completos a upperdir antes de meter el cambio. Las escrituras subsiguientes sobre ese archivo son rápidas, porque ya está en upperdir, pero la primera operación duele.

El impacto es brutal con archivos grandes y accesos esporádicos. ¿Por qué? Porque el copy-up agrega latencia de entrada/salida y consume espacio en el disco del host. Todo eso para modificar un par de bytes. Después, el archivo queda duplicado —el original en lowerdir sigue ocupando espacio, y la versión modificada en upperdir también—.

Ojo: esto no es un bug, es el diseño del sistema. Y tiene sentido para imágenes de aplicaciones donde los binarios no cambian. El problema aparece cuando tratás al contenedor como una VM chiquita y le metés datos mutables.

¿Cómo maneja OverlayFS la eliminación de archivos y directorios?

Borrar archivos en un contenedor no borra nada de la imagen. Lo que OverlayFS hace es crear un whiteout en upperdir: un archivo especial de tipo character device con número mayor y menor 0,0. Cuando el kernel lo encuentra en la vista merged, oculta el archivo original que está en lowerdir. Eso es todo. El original sigue ahí, inalterado, ocupando el mismo espacio que antes.

Para directorios la cosa cambia un poco. ¿Qué pasa si querés borrar un directorio entero que existe en lowerdir? Un whiteout no alcanza, porque no podés esconder un directorio con un archivo. Entonces OverlayFS crea un directorio opaco en upperdir: un directorio con el mismo nombre pero con el atributo “opaco” activado. El kernel interpreta eso como “acá no hay nada que ver, ignorá todo lo que venga de lowerdir para esta ruta”. Para más detalles técnicos, mirá el análisis entre Jenkins y GitHub Actions.

¿Cuál es el límite de capas y cómo afecta a las imágenes Docker?

En kernels anteriores a la versión 5.2, OverlayFS solo puede manejar 128 capas inferiores. Superado ese número, el montaje falla y el contenedor ni arranca. Esto no es un problema teórico: si heredás una imagen con muchas capas y tu Dockerfile agrega decenas de RUN, COPY y ADD sin consolidar, te podés comer el error de frente.

La solución clásica es encadenar instrucciones RUN con && para que ocupen una sola capa en vez de varias. Cuesta un poco más de legibilidad, pero achica la cantidad de lowerdirs y mantiene la imagen final más compacta.

A la fecha de publicación (junio 2026), la mayoría de las distros relevantes ya están en kernel 5.15 o 6.x, donde el límite subió considerablemente. Pero si operás máquinas con CentOS 7 heredado o kernels viejos de proveedores cloud, todavía podés morder ese límite. Y Docker no te avisa hasta que falla el montaje, así que mejor contás las capas antes.

¿Qué requisitos de sistema necesita el controlador overlay2 de Docker?

overlay2 es el driver por defecto desde Docker 18.06 y necesita condiciones bastante específicas para funcionar. Si alguna vez viste el error “backing filesystem without d_type support”, ya sabés de qué hablo.

• Kernel Linux 4.0 o superior. En RHEL y CentOS, el kernel mínimo es 3.10.0-514, que incluye backports de las features necesarias.
• Filesystem subyacente con d_type=true. Esto es fundamental. El kernel necesita que los directorios del filesystem host expongan el tipo de cada entrada (d_type) para armar la vista merged. ext4 lo soporta nativamente. xfs lo soporta solo si se formateó con ftype=1. Si formateaste el xfs sin esa opción, estás frito —no hay vuelta atrás sin reformatear—.
• overlay2 soportado en el kernel. Podés verificarlo con docker info | grep -i storage y con xfs_info /var/lib/docker para confirmar que ftype=1.

¿Cómo optimizar el rendimiento de Docker con OverlayFS?

La regla de oro es: datos que cambian van en volúmenes, no en el overlay. Cada vez que un contenedor escribe por primera vez en un archivo de la imagen, pagás el costo del copy-up. Con un volumen montado directamente en el host o en un proveedor externo, el overlay no intermedia, y las escrituras van directo al storage sin copias extra. En consejos de SEO internacional con hreflang profundizamos sobre esto.

Acá van las tres optimizaciones que más impacto tienen en producción:

• Usá volúmenes para cargas intensivas de escritura. Bases de datos, colas de mensajes, logs de alta frecuencia, datasets de entrenamiento. Si tu contenedor escribe seguido, el overlay es el lugar equivocado.
• SSD siempre que puedas. El copy-up dispara operaciones de lectura y escritura secuenciales sobre archivos potencialmente grandes. Un disco mecánico te agrega milisegundos por operación; un SSD lo resuelve en microsegundos.
• Aprovechá la caché de páginas compartida. Todos los contenedores que arrancan de la misma imagen leen del mismo lowerdir. El kernel cachea esas páginas una vez y las sirve a todos. Mientras menos escriban en el overlay, más eficiente es esa caché.

¿Qué limitaciones adicionales tiene OverlayFS y cómo solucionarlas?

OverlayFS resuelve un montón, pero tiene asperezas que en producción duelen. Estas son las que más veces vi en la calle:

• rename(2) entre capas devuelve EXDEV. No podés mover archivos entre un directorio que está en lowerdir y uno que está en upperdir con rename. La solución que funciona es copy + unlink, aunque sea más tosco.
• open(2) puede apuntar a archivos distintos después de un copy-up. Si un proceso abre un archivo en lowerdir y otro proceso dispara una escritura que fuerza el copy-up, el primer proceso se queda mirando la versión vieja. La solución práctica es hacer un touch antes del open si sabés que va a haber escritura.
• Hard links entre capas no funcionan. Si un archivo en lowerdir tiene hard links y después se copia a upperdir, los enlaces se rompen. OverlayFS no cruza esa frontera.
• d_type obligatorio. Si el filesystem del host no expone d_type, overlay2 directamente no se levanta. Lo cubrí antes, pero vale repetirlo porque es una de esas cosas que descubrís con el servicio caído un domingo a las 2 AM.

Operación	Comportamiento en OverlayFS	Impacto
Lectura de archivo existente	Sirve desde merged (lee lowerdir o upperdir según dónde esté)	Mínimo. Cache compartida entre contenedores.
Primera escritura en archivo de la imagen	Copy-up del archivo entero de lowerdir a upperdir	Alto en archivos grandes. Latencia de I/O y duplicación temporal.
Escrituras posteriores en el mismo archivo	Directo sobre la copia en upperdir	Bajo, similar a escritura nativa.
Eliminación de archivo	Crea whiteout en upperdir; el original en lowerdir sigue intacto	No libera espacio en la imagen. Solo oculta.
Creación de archivo nuevo	Va directo a upperdir	Bajo. Sin copy-up.

Errores comunes al trabajar con OverlayFS y Docker

Mitos y pifies que veo seguido, incluso en equipos con años de experiencia:

Creer que borrar archivos en el contenedor reduce el tamaño de la imagen. Lo expliqué antes: el whiteout solo esconde. La imagen sigue pesando exactamente lo mismo, y encima el upperdir crece porque el whiteout ocupa un inodo. Si querés reducir una imagen, tenés que rebuildearla con menos capas y menos binarios.

Correr bases de datos en el overlay sin volumen. Es la receta perfecta para disparar copy-ups de varios gigabytes en la primera consulta de escritura. Postgres, MySQL y MongoDB meten escrituras apenas arrancan (WAL, logs internos). Con un volumen en donweb.com u otro proveedor de VPS, esquivás el problema de raíz.

Asumir que todos los filesystems soportan d_type. xfs sin ftype=1 es un clásico de instalaciones heredadas. Si migraste un servidor de ext4 a xfs sin verificar la opción, overlay2 se niega a arrancar y Docker se va a devicemapper, que es más lento y tiene otros problemas. Siempre chequeá con xfs_info antes de confiar.

No consolidar RUN en el Dockerfile. Cada RUN genera una capa nueva. Si heredaste una imagen con 90 capas y tu Dockerfile suma 40 RUN sueltos, estás a 2 de reventar el límite de 128 en kernels viejos. Encadenar con && no cuesta nada y te ahorra el debugging de un montaje roto en producción.

Preguntas Frecuentes

¿Qué es OverlayFS y para qué se usa en Docker?

OverlayFS es un filesystem de unión del kernel Linux que permite montar múltiples directorios en capas con una sola vista unificada. Docker lo usa a través del driver overlay2 para construir imágenes por capas y darle a cada contenedor un espacio de escritura temporal sin modificar la imagen base. Es la razón por la que 50 contenedores pueden compartir la misma imagen sin ocupar 50 veces el espacio en disco. Más contexto en ejecutar agentes locales sin API con OpenClaw.

¿Cómo se organizan las capas lowerdir, upperdir, merged y workdir?

lowerdir contiene las capas de solo lectura de la imagen, apiladas en orden de precedencia. upperdir recibe todas las modificaciones, creaciones y eliminaciones del contenedor. merged es el resultado de combinar ambas jerarquías: lo que ve el contenedor. workdir es un espacio interno que el kernel necesita para operaciones atómicas; debe estar en el mismo filesystem que upperdir.

¿Qué ocurre cuando un contenedor escribe por primera vez en un archivo de la imagen?

Se dispara un copy-up: el archivo completo se copia de lowerdir a upperdir antes de aplicar la escritura. Es una operación a nivel de archivo, no de bloque. Si el archivo pesa 2 GB, se copian 2 GB. Por eso las bases de datos y los workloads con escritura intensiva deberían usar volúmenes en lugar del overlay.

¿Cuál es el límite de capas en OverlayFS y cómo evitarlo?

El límite histórico es de 128 capas inferiores en kernels anteriores a 5.2. Se evita consolidando instrucciones RUN con && en el Dockerfile para generar menos capas. En kernels modernos (5.15+) el límite es mucho más alto, pero si trabajás con sistemas heredados conviene contar las capas para no llevarse una sorpresa en producción.

¿Por qué eliminar archivos en un contenedor no reduce el tamaño de la imagen?

Porque OverlayFS no borra el archivo original. Crea un archivo especial llamado whiteout en upperdir que oculta el original en lowerdir. El archivo sigue ocupando espacio en las capas de la imagen. Para reducir el tamaño real de una imagen, hay que hacer un rebuild eliminando los archivos durante la construcción con un nuevo RUN.

Conclusión

OverlayFS es de esas piezas de infraestructura que funcionan tan bien en el día a día que rara vez les prestamos atención, hasta que una mañana el build de CI explota por el límite de capas o un contenedor de Postgres se arrastra porque cada checkpoint dispara un copy-up de 4 GB. En 2026, con kernels modernos y almacenamiento SSD siendo la norma, el driver overlay2 de Docker es sólido y eficiente para la mayoría de los workloads.

La clave está en entender cuándo el modelo de capas juega a favor y cuándo te empieza a cobrar caro. Imágenes de aplicación con binarios que no cambian: perfecto. Datos mutables, logs de alta frecuencia, bases de datos: ahí OverlayFS no es el lugar, y los volúmenes pasan de ser una buena práctica a ser la diferencia entre un sistema que responde y uno que se arrastra. Contá tus capas, verificá el d_type del filesystem y mantené los datos calientes fuera del overlay. Haciendo eso, Docker y OverlayFS van a convivir con vos sin hacer ruido.

Fuentes

• Documentación oficial de Docker – controlador overlay2
• OverlayFS Explained: How Docker’s Filesystem Layers Actually Work (dev.to)
• OverlayFS Deep Dive (opslog.dev)
• Análisis técnico de OverlayFS (whitesolutionit.com)