Dockerfile in Windows
De Docker engine bevat hulpprogramma's die het maken van containerafbeeldingen automatiseren. Hoewel u containerinstallatiekopieën handmatig kunt maken door de opdracht docker commit uit te voeren, heeft het maken van een geautomatiseerde installatiekopie veel voordelen, waaronder:
- Containerafbeeldingen opslaan als code.
- Snelle en nauwkeurige hercreatie van containerafbeeldingen voor onderhouds- en upgrade doeleinden.
- Continue integratie tussen containerafbeeldingen en de ontwikkelingscyclus.
De Docker-onderdelen die deze automatisering aandrijven, zijn de Dockerfile en de opdracht docker build.
De Dockerfile is een tekstbestand met de instructies die nodig zijn om een nieuwe containerimage te maken. Deze instructies omvatten de identificatie van een bestaande installatiekopie die moet worden gebruikt als basis, opdrachten die moeten worden uitgevoerd tijdens het maken van de installatiekopie en een opdracht die wordt uitgevoerd wanneer nieuwe exemplaren van de containerinstallatiekopie worden geïmplementeerd.
Docker build is het Docker Engine-commando dat een Dockerfile gebruikt en het proces voor het maken van de image activeert.
In dit onderwerp wordt beschreven hoe u Dockerfiles gebruikt met Windows-containers, hoe u de basissyntaxis begrijpt en wat de meest voorkomende Dockerfile-instructies zijn.
In dit document wordt het concept van containerbeelden en containerbeeldlagen besproken. Als u meer wilt weten over containerbasisafbeeldingen en afbeeldingslagen, zie containerbasisafbeeldingen.
Raadpleeg de Dockerfile-referentievoor een compleet overzicht van Dockerfiles.
Basissyntaxis
In de meest eenvoudige vorm kan een Dockerfile heel eenvoudig zijn. In het volgende voorbeeld wordt een nieuwe image gemaakt, die IIS en een 'Hello World'-site bevat. Dit voorbeeld bevat opmerkingen (aangegeven met een #), waarin elke stap wordt uitgelegd. In volgende secties van dit artikel vindt u meer informatie over de syntaxisregels van Dockerfile en instructies voor Dockerfile.
Notitie
Er moet een Dockerfile worden gemaakt zonder extensie. Als u dit in Windows wilt doen, maakt u het bestand met de gewenste editor en slaat u het op met de notatie Dockerfile (inclusief de aanhalingstekens).
# 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" ]
Zie de Dockerfile voor Windows-opslagplaatsvoor meer voorbeelden van Dockerfiles voor Windows.
Aanwijzingen
Dockerfile-instructies geven de Docker Engine de instructies die het nodig heeft om een containerimage te maken. Deze instructies worden één voor één uitgevoerd en in volgorde. De volgende voorbeelden zijn de meestgebruikte instructies in Dockerfiles. Zie de Dockerfile-verwijzingvoor een volledige lijst met Dockerfile-instructies.
VAN
Met de FROM instructie wordt de containerafbeelding ingesteld die wordt gebruikt tijdens het maken van de nieuwe afbeelding. Wanneer u bijvoorbeeld de instructie FROM mcr.microsoft.com/windows/servercoregebruikt, is de resulterende afbeelding afgeleid van, en afhankelijk van, de basis-OS-afbeelding van Windows Server Core. Als de opgegeven installatiekopieën niet aanwezig zijn op het systeem waarop het Docker-buildproces wordt uitgevoerd, probeert de Docker-engine de installatiekopieën te downloaden uit een openbaar of persoonlijk installatiekopieënregister.
De indeling van de FROM-instructie ziet er als volgt uit:
FROM <image>
Hier volgt een voorbeeld van de OPDRACHT FROM:
De windows server core van de ltsc2019-versie downloaden uit het Microsoft Container Registry (MCR):
FROM mcr.microsoft.com/windows/servercore:ltsc2019
Zie de FROM-verwijzingvoor meer gedetailleerde informatie.
RENNEN
De RUN-instructie specificeert opdrachten die moeten worden uitgevoerd en vastgelegd in de nieuwe containerafbeelding. Deze opdrachten kunnen items bevatten, zoals het installeren van software, het maken van bestanden en mappen en het maken van de omgevingsconfiguratie.
De RUN-instructie gaat als volgt:
# exec form
RUN ["<executable>", "<param 1>", "<param 2>"]
# shell form
RUN <command>
Het verschil tussen het exec- en shell-formulier is de wijze waarop de RUN instructie wordt uitgevoerd. Wanneer u het exec-formulier gebruikt, wordt het opgegeven programma expliciet uitgevoerd.
Hier volgt een voorbeeld van het exec-formulier:
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN ["powershell", "New-Item", "c:/test"]
De resulterende afbeelding voert de opdracht powershell New-Item c:/test uit.
docker history doc-exe-method
IMAGE CREATED CREATED BY SIZE COMMENT
b3452b13e472 2 minutes ago powershell New-Item c:/test 30.76 MB
In het volgende voorbeeld wordt dezelfde bewerking uitgevoerd in shell-vorm:
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN powershell New-Item c:\test
De resulterende afbeelding heeft een uitvoeringsinstructie van 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
Overwegingen voor het gebruik van RUN met Windows
Wanneer u in Windows de instructie RUN met de exec-indeling gebruikt, moeten backslashes worden geëscaped.
RUN ["powershell", "New-Item", "c:\\test"]
Wanneer het doelprogramma een Windows Installer is, moet u de installatie extraheren via de /x:<directory> vlag voordat u de daadwerkelijke (stille) installatieprocedure kunt starten. U moet ook wachten totdat de opdracht wordt afgesloten voordat u iets anders doet. Anders wordt het proces voortijdig beëindigd zonder iets te installeren. Raadpleeg het onderstaande voorbeeld voor meer informatie.
Voorbeelden van het gebruik van RUN met Windows
Het volgende voorbeeld-Dockerfile gebruikt DISM om IIS te installeren in de container-image.
RUN dism.exe /online /enable-feature /all /featurename:iis-webserver /NoRestart
In dit voorbeeld wordt het herdistribueerbare Pakket van Visual Studio geïnstalleerd.
Start-Process en de parameter -Wait worden gebruikt om het installatieprogramma uit te voeren. Dit zorgt ervoor dat de installatie is voltooid voordat u verdergaat met de volgende instructie in het Dockerfile.
RUN powershell.exe -Command Start-Process c:\vcredist_x86.exe -ArgumentList '/quiet' -Wait
Zie de RUN-verwijzingvoor gedetailleerde informatie over de RUN-instructie.
KOPIËREN
De COPY instructie kopieert bestanden en mappen naar het bestandssysteem van de container. De bestanden en mappen moeten zich in een pad bevinden ten opzichte van het Dockerfile.
De indeling van de COPY-instructie ziet er als volgt uit:
COPY <source> <destination>
Als een bron of bestemming witruimte bevat, plaatst u het pad tussen vierkante haken en dubbele aanhalingstekens, zoals wordt weergegeven in het volgende voorbeeld:
COPY ["<source>", "<destination>"]
Overwegingen voor het gebruik van COPY met Windows
In Windows moet de doelindeling schuine strepen gebruiken. Dit zijn bijvoorbeeld geldige COPY instructies:
COPY test1.txt /temp/
COPY test1.txt c:/temp/
Ondertussen werkt de volgende indeling met backslashes niet:
COPY test1.txt c:\temp\
Voorbeelden van het gebruik van COPY met Windows
In het volgende voorbeeld wordt de inhoud van de bronmapdirectory toegevoegd aan een directory genaamd sqllite in de containerimage.
COPY source /sqlite/
In het volgende voorbeeld worden alle bestanden die beginnen met config toegevoegd aan de map c:\temp van de container-image.
COPY config* c:/temp/
Zie de COPY-verwijzingvoor meer gedetailleerde informatie over de instructie COPY.
TOEVOEGEN
De INSTRUCTIE ADD is net als de COPY-instructie, maar met nog meer mogelijkheden. Naast het kopiëren van bestanden van de host naar de containerinstallatiekopie, kan de ADD instructie ook bestanden kopiëren vanaf een externe locatie met een URL-specificatie.
De indeling van de ADD-instructie ziet er als volgt uit:
ADD <source> <destination>
Als de bron of het doel witruimte bevat, plaatst u het pad tussen vierkante haken en dubbele aanhalingstekens:
ADD ["<source>", "<destination>"]
Overwegingen voor het uitvoeren van ADD met Windows
Op Windows moet het doelformaat voorwaartse schuine strepen gebruiken. Dit zijn bijvoorbeeld geldige ADD instructies:
ADD test1.txt /temp/
ADD test1.txt c:/temp/
Ondertussen werkt het volgende formaat met backslashes niet:
ADD test1.txt c:\temp\
Bovendien zal op Linux de ADD-instructie gecomprimeerde pakketten tijdens het kopiëren uitpakken. Deze functionaliteit is niet beschikbaar in Windows.
Voorbeelden van het gebruik van ADD met Windows
In het volgende voorbeeld wordt de inhoud van de bronmap geplaatst in een map met de naam sqllite in de containerimage.
ADD source /sqlite/
In het volgende voorbeeld worden alle bestanden die beginnen met 'config' toegevoegd aan de c:\temp-map van de containerimage.
ADD config* c:/temp/
In het volgende voorbeeld wordt Python voor Windows gedownload naar de c:\temp directory van de containerimage.
ADD https://www.python.org/ftp/python/3.5.1/python-3.5.1.exe /temp/python-3.5.1.exe
Zie de ADD-verwijzingvoor meer gedetailleerde informatie over de ADD instructie.
WORKDIR
De WORKDIR-instructie stelt een werkmap in voor andere Dockerfile-instructies, zoals RUNen CMD, evenals de werkmap voor het uitvoeren van instanties van de containerimage.
De indeling van de WORKDIR-instructie ziet er als volgt uit:
WORKDIR <path to working directory>
Overwegingen voor het gebruik van WORKDIR met Windows
Als in Windows de werkmap een backslash bevat, moet deze worden ontsnapt.
WORKDIR c:\\windows
voorbeelden
WORKDIR c:\\Apache24\\bin
Zie de WORKDIR-verwijzingvoor gedetailleerde informatie over de WORKDIR instructie.
CMD
Met de instructie CMD wordt de standaardopdracht ingesteld die moet worden uitgevoerd bij het implementeren van een exemplaar van de containerinstallatiekopie. Als de container bijvoorbeeld als host fungeert voor een NGINX-webserver, bevat de CMD mogelijk instructies voor het starten van de webserver met een opdracht zoals nginx.exe. Als er meerdere CMD instructies zijn opgegeven in een Dockerfile, wordt alleen de laatste geëvalueerd.
De indeling van de CMD-instructie ziet er als volgt uit:
# exec form
CMD ["<executable", "<param>"]
# shell form
CMD <command>
Overwegingen voor het gebruik van CMD met Windows
In Windows moeten bestandspaden die zijn opgegeven in de instructie CMD voorwaartse schuine strepen gebruiken of ontsnapte backslashes \\. Hier volgen geldige CMD instructies:
# exec form
CMD ["c:\\Apache24\\bin\\httpd.exe", "-w"]
# shell form
CMD c:\\Apache24\\bin\\httpd.exe -w
De volgende indeling zonder de juiste slashes werkt echter niet:
CMD c:\Apache24\bin\httpd.exe -w
Zie de CMD-verwijzingvoor meer gedetailleerde informatie over de CMD instructie.
Escape-teken
In veel gevallen moet een Dockerfile-instructie meerdere regels omvatten. Hiervoor kunt u een escape-teken gebruiken. Het standaard escapeteken in een Dockerfile is een backslash \. Omdat de backslash echter ook als scheidingsteken voor bestandspaden in Windows wordt gebruikt, kan het gebruik ervan om meerdere regels te overspannen problemen veroorzaken. U kunt dit omzeilen door een parser-instructie te gebruiken om het standaard escape-teken te wijzigen. Zie Parser-instructiesvoor meer informatie over parserrichtlijnen.
In het volgende voorbeeld ziet u één RUN-instructie die meerdere regels omvat met behulp van het standaard escape-teken:
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
Als u het escape-teken wilt wijzigen, plaatst u een escape parser-instructie op de eerste regel van het Dockerfile. Dit is te zien in het volgende voorbeeld.
Notitie
Er kunnen slechts twee waarden worden gebruikt als escapetekens: \ en `.
# 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
Zie Escape parser directivevoor meer informatie over de escape parser richtlijn.
PowerShell in Dockerfile
PowerShell-cmdlets
PowerShell-cmdlets kunnen worden uitgevoerd in een Dockerfile met de RUN bewerking.
FROM mcr.microsoft.com/windows/servercore:ltsc2019
RUN powershell -command Expand-Archive -Path c:\apache.zip -DestinationPath c:\
REST-aanroepen
De Invoke-WebRequest cmdlet van PowerShell kan handig zijn bij het verzamelen van gegevens of bestanden van een webservice. Als u bijvoorbeeld een image met Python maakt, kunt u $ProgressPreference naar SilentlyContinue instellen om snellere downloads te bereiken, zoals in het volgende voorbeeld wordt weergegeven.
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
Notitie
Invoke-WebRequest werkt ook in Nano Server.
Een andere optie voor het gebruik van PowerShell voor het downloaden van bestanden tijdens het maken van de installatiekopie is het gebruik van de .NET WebClient-bibliotheek. Dit kan de downloadprestaties verbeteren. In het volgende voorbeeld wordt de Python-software gedownload met behulp van de WebClient-bibliotheek.
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
Notitie
Nano Server biedt momenteel geen ondersteuning voor WebClient.
PowerShell-scripten
In sommige gevallen kan het handig zijn om een script te kopiëren naar de containers die u gebruikt tijdens het maken van de installatiekopie en vervolgens het script vanuit de container uit te voeren.
Notitie
Hierdoor wordt de cache van de afbeeldingslaag beperkt en wordt de leesbaarheid van Dockerfile verminderd.
In dit voorbeeld wordt een script van de buildcomputer gekopieerd naar de container met behulp van de instructie ADD. Dit script wordt vervolgens uitgevoerd met behulp van de RUN-instructie.
FROM mcr.microsoft.com/windows/servercore:ltsc2019
ADD script.ps1 /windows/temp/script.ps1
RUN powershell.exe -executionpolicy bypass c:\windows\temp\script.ps1
Docker build
Zodra een Dockerfile is gemaakt en opgeslagen op schijf, kunt u docker build uitvoeren om de nieuwe afbeelding te maken. De opdracht docker build gebruikt verschillende optionele parameters en een pad naar het Dockerfile. Zie de build-verwijzingvoor volledige documentatie over Docker Build, inclusief een lijst met alle buildopties.
De indeling van de opdracht docker build gaat als volgt:
docker build [OPTIONS] PATH
Bijvoorbeeld, de volgende opdracht maakt een image met de naam "iis".
docker build -t iis .
Wanneer het buildproces is gestart, geeft de uitvoer de status aan en retourneert de gegenereerde fouten.
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
Het resultaat is een nieuwe containerafbeelding, die in dit voorbeeld 'iis' heet.
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