Define y administra volúmenes en Docker Compose

Los volúmenes son almacenes de datos persistentes implementados por el motor de contenedores. Compose ofrece una forma neutral para que los servicios monten volúmenes, así como parámetros de configuración para asignarlos a la infraestructura. La declaración de nivel superior volumes te ayuda a configurar volúmenes con nombre que se pueden reutilizar en múltiples servicios.

Para usar un volumen en varios servicios, debes otorgar acceso explícitamente a cada servicio utilizando el atributo volumes dentro del elemento de nivel superior services. El atributo volumes tiene una sintaxis adicional que proporciona un control más detallado.

Tip

¿Trabajas con repositorios grandes o monorepos, o con sistemas de archivos virtuales que ya no escalan con tu base de código? Compose ahora aprovecha el uso compartido de archivos sincronizados ( Synchronized file shares) y crea automáticamente usos compartidos de archivos para montajes de tipo bind (bind mounts). Asegúrate de haber iniciado sesión en Docker con una suscripción de pago y de haber habilitado tanto Access experimental features como Manage Synchronized file shares with Compose en la configuración de Docker Desktop.

Ejemplo

El siguiente ejemplo muestra una configuración de dos servicios donde el directorio de datos de una base de datos se comparte con otro servicio como un volumen llamado db-data, de modo que se pueda realizar una copia de seguridad periódicamente.

services:
  backend:
    image: example/database
    volumes:
      - db-data:/etc/data

  backup:
    image: backup-service
    volumes:
      - db-data:/var/lib/backup/data

volumes:
  db-data:

El volumen db-data se monta en las rutas de contenedor /var/lib/backup/data y /etc/data para backup y backend respectivamente.

Al ejecutar docker compose up se crea el volumen si no existe. De lo contrario, se utiliza el volumen existente y se vuelve a crear si se elimina manualmente fuera de Compose.

Atributos

Una entrada bajo la sección volumes de nivel superior puede estar vacía, en cuyo caso utiliza la configuración predeterminada del motor de contenedores para crear un volumen. Opcionalmente, puedes configurarla con las siguientes claves:

driver

Especifica qué controlador de volumen se debe usar. Si el controlador no está disponible, Compose devuelve un error y no despliega la aplicación.

volumes:
  db-data:
    driver: foobar

driver_opts

driver_opts especifica una lista de opciones como pares clave-valor para pasar al controlador para este volumen. Las opciones dependen del controlador.

volumes:
  example:
    driver_opts:
      type: "nfs"
      o: "addr=10.40.0.199,nolock,soft,rw"
      device: ":/docker/example"

Si deseas un montaje bind (bind mount) con nombre, usa el controlador local con driver_opts. Este patrón le da al volumen de Compose un nombre estable al mismo tiempo que lo mapea a una ruta de host específica:

volumes:
  app-data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /srv/app-data # debe ser la ruta absoluta del host y ya debe existir

Las claves type, o y device se pasan al controlador local. Para un montaje de ruta de host único en un solo servicio, consulta montajes bind (bind mounts).

external

Si se establece en true:

• external especifica que este volumen ya existe en la plataforma y su ciclo de vida se administra fuera del de la aplicación. En este caso, Compose no crea el volumen y devuelve un error si el volumen no existe.
• Todos los demás atributos, excepto name, son irrelevantes. Si Compose detecta cualquier otro atributo, rechaza el archivo de Compose por considerarlo inválido.

En el siguiente ejemplo, en lugar de intentar crear un volumen llamado {nombre_proyecto}_db-data, Compose busca un volumen existente llamado db-data y lo monta en los contenedores del servicio backend.

services:
  backend:
    image: example/database
    volumes:
      - db-data:/etc/data

volumes:
  db-data:
    external: true

labels

labels se utiliza para añadir metadatos a los volúmenes. Puedes usar un array o un diccionario.

Se recomienda utilizar la notación DNS inversa para evitar que las etiquetas entren en conflicto con las utilizadas por otro software.

volumes:
  db-data:
    labels:
      com.example.description: "Database volume"
      com.example.department: "IT/Ops"
      com.example.label-with-empty-value: ""

volumes:
  db-data:
    labels:
      - "com.example.description=Database volume"
      - "com.example.department=IT/Ops"
      - "com.example.label-with-empty-value"

Compose establece las etiquetas com.docker.compose.project y com.docker.compose.volume.

Note

Las etiquetas definidas aquí se aplican únicamente a volúmenes con nombre. Se almacenan en el recurso de volumen y se pueden ver mediante docker volume inspect. No se aplican a montajes bind (bind mounts) ni cambian la semántica del montaje.

name

name establece un nombre personalizado para un volumen. El campo de nombre se puede usar para hacer referencia a volúmenes que contienen caracteres especiales. El nombre se usa tal cual y no tiene como prefijo el nombre del proyecto.

volumes:
  db-data:
    name: "my-app-data"

Esto permite hacer de este nombre de búsqueda un parámetro del archivo de Compose, de modo que el ID del modelo para el volumen esté codificado pero el ID del volumen real en la plataforma se configure en tiempo de ejecución durante el despliegue.

Por ejemplo, si DATABASE_VOLUME=my_volume_001 está en tu archivo .env:

volumes:
  db-data:
    name: ${DATABASE_VOLUME}

Al ejecutar docker compose up se utiliza el volumen llamado my_volume_001.

También se puede utilizar junto con la propiedad external. Esto significa que el nombre utilizado para buscar el volumen real en la plataforma se establece de forma independiente del nombre utilizado para referirse al volumen dentro del archivo de Compose:

volumes:
  db-data:
    external: true
    name: actual-name-of-volume