Dockerfile en Windows
El motor de Docker incluye herramientas que automatizan la creación de imágenes de contenedor. Aunque puede crear imágenes de contenedor manualmente mediante la ejecución del comando docker commit, la adopción de un proceso de creación de imágenes automatizada tiene muchas ventajas, entre las que se incluyen:
- Almacenamiento de imágenes de contenedor como código.
- Recreación rápida y precisa de imágenes de contenedor con fines de mantenimiento y actualización.
- Integración continua entre imágenes de contenedor y el ciclo de desarrollo.
Los componentes de Docker que controlan esta automatización son dockerfile y el comando docker build.
Dockerfile es un archivo de texto que contiene las instrucciones necesarias para crear una nueva imagen de contenedor. Estas instrucciones incluyen la identificación de una imagen existente que se usará como base, los comandos que se ejecutarán durante el proceso de creación de imágenes y un comando que se ejecutará cuando se implementen nuevas instancias de la imagen de contenedor.
Docker build es el comando del motor de Docker que consume un Dockerfile y desencadena el proceso de creación de una imagen.
En este tema se muestra cómo usar Dockerfiles con contenedores de Windows, comprender su sintaxis básica y cuáles son las instrucciones de Dockerfile más comunes.
En este documento se describe el concepto de imágenes de contenedor y capas de imagen de contenedor. Si quiere obtener más información sobre imágenes y capas de imágenes, veaImágenes base de contenedores.
Para tener una visión completa de los Dockerfiles, vea Referencia de Dockerfile.
Sintaxis básica
En su forma más básica, un Dockerfile puede ser muy sencillo. En el ejemplo siguiente se crea una nueva imagen, que incluye IIS y un sitio "hola mundo". En este ejemplo se incluyen comentarios (indicados con un #), que explican cada paso. En las secciones posteriores de este artículo se detallarán las reglas de sintaxis de Dockerfile y las instrucciones de Dockerfile.
Nota
Se debe crear un Dockerfile sin extensión. Para ello en Windows, cree el archivo con el editor que prefiera y guárdelo con la notación "Dockerfile" (incluidas las comillas).
# Sample Dockerfile
# Indicates that the windowsservercore image will be used as the base image.
FROM mcr.microsoft.com/windows/servercore:ltsc2019
# Metadata indicating an image maintainer.
LABEL maintainer="jshelton@contoso.com"
# Uses dism.exe to install the IIS role.
RUN dism.exe /online /enable-feature /all /featurename:iis-webserver /NoRestart
# Creates an HTML file and adds content to this file.
RUN echo "Hello World - Dockerfile" > c:\inetpub\wwwroot\index.html
# Sets a command or process that will run each time a container is run from the new image.
CMD [ "cmd" ]
A fin de obtener ejemplos adicionales de Dockerfiles para Windows, vea el repositorio de Dockerfile para Windows.
Instrucciones
Las instrucciones de Dockerfile proporcionan al motor de Docker las instrucciones que necesita para crear una imagen de contenedor. Estas instrucciones se realizan uno a uno y en orden. Los ejemplos siguientes son las instrucciones más usadas en Dockerfiles. Para obtener una lista completa de las instrucciones de Dockerfile, consulte la referencia de Dockerfile .
FROM
La FROM instrucción establece la imagen de contenedor que se usará durante el nuevo proceso de creación de imágenes. Por ejemplo, cuando se usa la instrucción FROM mcr.microsoft.com/windows/servercore, la imagen resultante se deriva de y tiene una dependencia de , la imagen del sistema operativo base de Windows Server Core. Si la imagen especificada no está presente en el sistema donde se ejecuta el proceso de compilación de Docker, el motor de Docker intentará descargar la imagen de un registro de imágenes público o privado.
El formato de la instrucción FROM es similar al siguiente:
FROM <image>
Este es un ejemplo del comando FROM:
Para descargar la versión ltsc2019 de Windows Server Core desde Microsoft Container Registry (MCR):
FROM mcr.microsoft.com/windows/servercore:ltsc2019
Para más información, vea la referencia de FROM.
RUN
La instrucción RUN especifica los comandos que se van a ejecutar y que se capturarán en la nueva imagen del contenedor. Estos comandos pueden incluir elementos como instalar software, crear archivos y directorios y crear la configuración del entorno.
La instrucción RUN es similar a la siguiente:
# exec form
RUN ["<executable>", "<param 1>", "<param 2>"]
# shell form
RUN <command>
La diferencia entre el formulario exec y shell es en cómo se ejecuta la instrucción RUN. Al usar el formulario exec, el programa especificado se ejecuta explícitamente.
Este es un ejemplo del formulario exec:
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN ["powershell", "New-Item", "c:/test"]
La imagen resultante ejecuta el comando powershell New-Item c:/test:
docker history doc-exe-method
IMAGE CREATED CREATED BY SIZE COMMENT
b3452b13e472 2 minutes ago powershell New-Item c:/test 30.76 MB
Por el contrario, en el ejemplo siguiente se ejecuta la misma operación en formato de shell:
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN powershell New-Item c:\test
La imagen resultante tiene una instrucción de ejecución de cmd /S /C powershell New-Item c:\test.
docker history doc-shell-method
IMAGE CREATED CREATED BY SIZE COMMENT
062a543374fc 19 seconds ago cmd /S /C powershell New-Item c:\test 30.76 MB
Consideraciones para usar RUN con Windows
En Windows, al usar la instrucción RUN con el formato exec, se debe aplicar escape a las barras diagonales.
RUN ["powershell", "New-Item", "c:\\test"]
Cuando el programa de destino sea un instalador de Windows, deberá extraer la configuración a través de la marca /x:<directory> para poder iniciar el procedimiento de instalación real (silencioso). También debe esperar a que el comando termine antes de realizar cualquier otra operación. De lo contrario, el proceso finalizará prematuramente sin instalar nada. Para obtener más información, consulte el ejemplo siguiente.
Ejemplos de uso de RUN con Windows
En el ejemplo siguiente dockerfile se usa DISM para instalar IIS en la imagen de contenedor:
RUN dism.exe /online /enable-feature /all /featurename:iis-webserver /NoRestart
En este ejemplo se instala el paquete redistribuible de Visual Studio. Start-Process y el parámetro -Wait se usan para ejecutar el instalador. Esto garantiza que la instalación se complete antes de pasar a la siguiente instrucción en el Dockerfile.
RUN powershell.exe -Command Start-Process c:\vcredist_x86.exe -ArgumentList '/quiet' -Wait
Para obtener información detallada sobre la instrucción RUN, consulte la referencia RUN.
COPY
La instrucción COPY copia archivos y directorios en el sistema de archivos del contenedor. Los archivos y directorios deben estar en una ruta de acceso relativa al Dockerfile.
El formato de la instrucción COPY es similar al siguiente:
COPY <source> <destination>
Si el origen o el destino incluyen espacios en blanco, incluya la ruta de acceso entre corchetes y comillas dobles, como se muestra en el ejemplo siguiente:
COPY ["<source>", "<destination>"]
Consideraciones para usar COPY con Windows
En Windows, el formato de destino debe usar barras diagonales. Por ejemplo, estas son instrucciones COPY válidas:
COPY test1.txt /temp/
COPY test1.txt c:/temp/
Por tanto, el siguiente formato con barras diagonales inversas no funcionará:
COPY test1.txt c:\temp\
Ejemplos de uso de COPY con Windows
En el ejemplo siguiente se agrega el contenido del directorio de origen a un directorio denominado sqllite en la imagen del contenedor:
COPY source /sqlite/
En el ejemplo siguiente se agregarán todos los archivos que comienzan con la configuración al directorio c:\temp de la imagen de contenedor:
COPY config* c:/temp/
Para obtener información más detallada sobre la instrucción de COPY, consulte la referencia de COPY.
AGREGAR
La instrucción ADD es como la instrucción COPY, pero con aún más funcionalidades. Además de copiar archivos del host en la imagen de contenedor, la instrucción ADD también puede copiar archivos desde una ubicación remota con una especificación de dirección URL.
El formato de la instrucción ADD es similar al siguiente:
ADD <source> <destination>
Si el origen o el destino incluyen espacios en blanco, incluya la ruta entre corchetes y comillas dobles:
ADD ["<source>", "<destination>"]
Consideraciones para ejecutar ADD con Windows
En Windows, el formato de destino debe usar barras diagonales. Por ejemplo, estas son instrucciones ADD válidas:
ADD test1.txt /temp/
ADD test1.txt c:/temp/
Por tanto, el siguiente formato con barras diagonales inversas no funcionará:
ADD test1.txt c:\temp\
Además, en Linux, la instrucción ADD expandirá los paquetes comprimidos al copiar. Esta funcionalidad no está disponible en Windows.
Ejemplos de uso de ADD con Windows
En el ejemplo siguiente se agrega el contenido del directorio de origen a un directorio denominado sqllite en la imagen del contenedor:
ADD source /sqlite/
En el ejemplo siguiente se agregarán todos los archivos que comienzan por "config" al directorio c:\temp de la imagen de contenedor.
ADD config* c:/temp/
En el ejemplo siguiente se descargará Python para Windows en el directorio c:\temp de la imagen de contenedor.
ADD https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe /temp/python-3.5.1.exe
Para más información sobre la instrucción ADD, vea la referencia de ADD.
WORKDIR
La instrucción WORKDIR establece un directorio de trabajo para otras instrucciones de Dockerfile, como RUN, CMDy también el directorio de trabajo para ejecutar instancias de la imagen de contenedor.
El formato de la instrucción WORKDIR es similar al siguiente:
WORKDIR <path to working directory>
Consideraciones para usar WORKDIR con Windows
En Windows, si el directorio de trabajo incluye una barra diagonal inversa, se le debe aplicar escape.
WORKDIR c:\\windows
Ejemplos
WORKDIR c:\\Apache24\\bin
Para obtener información detallada sobre la instrucción WORKDIR, consulte la referencia de WORKDIR.
CMD
La instrucción CMD establece que se ejecute el comando predeterminado al implementar una instancia de la imagen de contenedor. Por ejemplo, si el contenedor hospedará un servidor web NGINX, el CMD podría incluir instrucciones para iniciar el servidor web con un comando como nginx.exe. Si se especifican varias instrucciones CMD en un Dockerfile, solo se evalúa la última.
El formato de la instrucción CMD es similar al siguiente:
# exec form
CMD ["<executable", "<param>"]
# shell form
CMD <command>
Consideraciones para usar CMD con Windows
En Windows, las rutas de acceso de archivo especificadas en la instrucción CMD deben usar barras diagonales o tener barras diagonales inversas con escape \\. A continuación se muestran instrucciones CMD válidas:
# exec form
CMD ["c:\\Apache24\\bin\\httpd.exe", "-w"]
# shell form
CMD c:\\Apache24\\bin\\httpd.exe -w
Sin embargo, el siguiente formato sin las barras diagonales adecuadas no funcionará:
CMD c:\Apache24\bin\httpd.exe -w
Para obtener información más detallada sobre la instrucción CMD, consulte la referencia de CMD de .
Carácter de escape
En muchos casos, una instrucción Dockerfile tendrá que abarcar varias líneas. Para ello, puede usar un carácter de escape. El carácter de escape predeterminado de Dockerfile es una barra diagonal inversa \. Sin embargo, dado que la barra diagonal inversa también es un separador de rutas de acceso de archivos en Windows, el hecho de usarla para abarcar varias líneas puede causar problemas. Para solucionar este problema, puede usar una directiva de analizador para cambiar el carácter de escape predeterminado. Para obtener más información sobre las directivas de analizador, consulte directivas de analizador.
En el ejemplo siguiente se muestra una única instrucción RUN que abarca varias líneas mediante el carácter de escape predeterminado:
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN powershell.exe -Command \
$ErrorActionPreference = 'Stop'; \
wget https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe -OutFile c:\python-3.5.1.exe ; \
Start-Process c:\python-3.5.1.exe -ArgumentList '/quiet InstallAllUsers=1 PrependPath=1' -Wait ; \
Remove-Item c:\python-3.5.1.exe -Force
Para modificar el carácter de escape, coloque una directiva del analizador de escape en la primera línea del Dockerfile. Esto se puede ver en el ejemplo siguiente.
Nota
Solo se pueden usar dos valores como caracteres de escape: \ y `.
# escape=`
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN powershell.exe -Command `
$ErrorActionPreference = 'Stop'; `
wget https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe -OutFile c:\python-3.5.1.exe ; `
Start-Process c:\python-3.5.1.exe -ArgumentList '/quiet InstallAllUsers=1 PrependPath=1' -Wait ; `
Remove-Item c:\python-3.5.1.exe -Force
Para más información sobre la directiva del analizador de escape, vea Directiva del analizador de escape.
PowerShell en Dockerfile
Cmdlets de PowerShell
Los cmdlets de PowerShell se pueden ejecutar en un Dockerfile con la operación RUN.
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN powershell -command Expand-Archive -Path c:\apache.zip -DestinationPath c:\
Llamadas REST
El cmdlet Invoke-WebRequest de PowerShell puede ser útil al recopilar información o archivos de un servicio web. Por ejemplo, si crea una imagen que incluye Python, puede establecer $ProgressPreference en SilentlyContinue para lograr descargas más rápidas, como se muestra en el ejemplo siguiente.
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN powershell.exe -Command \
$ErrorActionPreference = 'Stop'; \
$ProgressPreference = 'SilentlyContinue'; \
Invoke-WebRequest https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe -OutFile c:\python-3.5.1.exe ; \
Start-Process c:\python-3.5.1.exe -ArgumentList '/quiet InstallAllUsers=1 PrependPath=1' -Wait ; \
Remove-Item c:\python-3.5.1.exe -Force
Nota
Invoke-WebRequest también funciona en Nano Server.
Otra opción para usar PowerShell para descargar archivos durante el proceso de creación de imágenes es usar la biblioteca WebClient de .NET. Esto puede aumentar el rendimiento de la descarga. En el ejemplo siguiente se descarga el software de Python mediante la biblioteca WebClient.
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN powershell.exe -Command \
$ErrorActionPreference = 'Stop'; \
(New-Object System.Net.WebClient).DownloadFile('https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe','c:\python-3.5.1.exe') ; \
Start-Process c:\python-3.5.1.exe -ArgumentList '/quiet InstallAllUsers=1 PrependPath=1' -Wait ; \
Remove-Item c:\python-3.5.1.exe -Force
Nota
Nano Server no admite actualmente WebClient.
Scripts de PowerShell
En algunos casos, puede resultar útil copiar un script en los contenedores que use durante el proceso de creación de imágenes y, a continuación, ejecutar el script desde dentro del contenedor.
Nota
Esto limitará el almacenamiento en caché de cualquier capa de imagen y reducirá la legibilidad de Dockerfile.
En este ejemplo se copia un script de la máquina de compilación en el contenedor mediante la instrucción ADD. A continuación, este script se ejecuta mediante la instrucción RUN.
FROM mcr.microsoft.com/windows/servercore:ltsc2019
ADD script.ps1 /windows/temp/script.ps1
RUN powershell.exe -executionpolicy bypass c:\windows\temp\script.ps1
Compilación de Docker
Una vez creado y guardado un Dockerfile en el disco, puede ejecutar docker build para crear la nueva imagen. El comando docker build toma varios parámetros opcionales y una ruta de acceso al Dockerfile. Para obtener documentación completa sobre La compilación de Docker, incluida una lista de todas las opciones de compilación, consulte la referencia de compilación .
El formato del comando docker build es similar al siguiente:
docker build [OPTIONS] PATH
Por ejemplo, el siguiente comando creará una imagen denominada "iis".
docker build -t iis .
Cuando se haya iniciado el proceso de compilación, la salida indicará el estado y devolverá los errores producidos.
C:\> docker build -t iis .
Sending build context to Docker daemon 2.048 kB
Step 1 : FROM mcr.microsoft.com/windows/servercore:ltsc2019
---> 6801d964fda5
Step 2 : RUN dism /online /enable-feature /all /featurename:iis-webserver /NoRestart
---> Running in ae8759fb47db
Deployment Image Servicing and Management tool
Version: 10.0.10586.0
Image Version: 10.0.10586.0
Enabling feature(s)
The operation completed successfully.
---> 4cd675d35444
Removing intermediate container ae8759fb47db
Step 3 : RUN echo "Hello World - Dockerfile" > c:\inetpub\wwwroot\index.html
---> Running in 9a26b8bcaa3a
---> e2aafdfbe392
Removing intermediate container 9a26b8bcaa3a
Successfully built e2aafdfbe392
El resultado es una nueva imagen de contenedor, que en este ejemplo se denomina "iis".
docker images
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
iis latest e2aafdfbe392 About a minute ago 207.8 MB
windowsservercore latest 6801d964fda5 4 months ago 0 B