Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

[docs-scanner] Conflicting guidance on when to use overlay2 vs containerd

Cerrado Apto para principiantes
  • ¿Algo no está bien?
#26,165 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
75/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Área
documentation

Línea de trabajo

El issue señala dos archivos específicos: content/manuals/engine/storage/drivers/select-storage-driver.md y content/manuals/engine/storage/drivers/overlayfs-driver.md. Comience leyendo estos archivos para comprender la orientación contradictoria actual. Luego, redacte una sección de decisión clara para la página select-storage-driver, que explique cuándo usar overlay2 frente a containerd, y actualice la página overlayfs-driver para aclarar su declaración. Verifique los cambios compilando la documentación localmente o revisando la salida renderizada.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Files:

  • content/manuals/engine/storage/drivers/select-storage-driver.md
  • content/manuals/engine/storage/drivers/overlayfs-driver.md
Issue

The select-storage-driver page says:

For systems using classic storage drivers, overlay2 provides broad compatibility across Linux distributions. Use Docker volumes for write-heavy workloads instead of relying on writing data to the container's writable layer.

This guidance presents overlay2 as a recommended choice "for systems using classic storage drivers," but doesn't explain when or why a user would choose to use classic storage drivers instead of the containerd image store (the default for 29.0+).

Meanwhile, overlayfs-driver.md says:

In most cases you should use the overlay2 storage driver - it's not required to use the btrfs storage driver simply because your system uses Btrfs as its root filesystem.

But then immediately contradicts this with:

Docker Engine 29.0 and later uses the containerd image store by default. The overlay2 driver is a legacy storage driver that is superseded by the overlayfs containerd snapshotter.

Why this matters

A reader following these pages will be confused about whether they should be using overlay2 or the containerd image store. The guidance says "in most cases you should use overlay2" but then says it's "legacy" and "superseded." There's no clear decision tree for when to use which system.

Suggested fix

Add a clear decision section to select-storage-driver.md that explains:

  • Docker Engine 29.0+ uses containerd image store by default for fresh installations (recommended)
  • Classic storage drivers (including overlay2) are still available for:
    • Systems upgraded from earlier versions that haven't migrated
    • Specific compatibility requirements (list them if any exist)
  • How to determine which system you're currently using
  • When and why you might need to stay on classic storage drivers vs migrating to containerd

Remove or update the "in most cases you should use overlay2" statement in overlayfs-driver.md to clarify it only applies to users who must use classic storage drivers.

Found by nightly documentation quality scanner

Lenguaje dominante
Markdown
Estrellas
4.7k
Forks
8.5k
Merge medio
1 d 22 h
PR fusionados (30 d)
110

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de docker/docs

Todos los issues de docker/docs

Issues similares

Más issues de Documentation

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.