Upgrade containers to a new version of the Windows operating system
Applies to: Windows Server 2022, Windows Server 2019, Windows Server 2016
This topic describes how to upgrade Windows containers to a new Windows or Windows Server operating system version. There are two steps for upgrading containers:
- Upgrade the container host to the new operating system version.
- Create new container instances using the new operating system version.
If you just need to update (or patch) your current Windows base OS container image, see update your containers to pull the latest patch image for your containers.
Upgrade the container host
To upgrade the container host to a newer Windows or Windows Server version, you can either perform an in-place upgrade or a clean installation. Since the container host and the Windows containers share a single kernel, you should make sure the container's base image OS version matches that of the host. However, you can still have a newer version of the container host with an older base image with Hyper-V isolation. In Windows Server 2022, you can implement this scenario with process isolation (in preview).
Create new container instances using the new OS version
To create the new container instances, you need to:
- Pull the container base image
- Edit the Dockerfile to point to the new base image
- Build and run the new app image
- Tag and push the image to your registry
Pull the container base image
After you have pulled the new Windows OS version on the container host, follow the steps below to upgrade the base image:
Select the container base image you want to upgrade to.
Open a PowerShell session as an administrator and, depending on the OS version you chose, run the docker pull command to pull an image:
PS C:\> docker pull mcr.microsoft.com/windows/servercore:ltsc2022
This example pulls the Server Core version 20H2 base image.
When the image is finished downloading, you can verify that the new image has been pulled by running the docker images command to return a list of pulled images:
Edit the Dockerfile to point to the new base image
Next, you want to create and start new container instances using the new base image you pulled. To automate this process, edit the Dockerfile to redirect it to the new image.
Open the Dockerfile in a text editor and make the updates. In the following example, the Dockerfile is updated to Server Core 20H2 with the IIS application.
FROM mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2022 AS build-env WORKDIR /app COPY *.csproj ./ RUN PowerShell Install-WindowsFeature NET-Framework-45-ASPNET FROM mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2022 WORKDIR /app COPY --from=build-env /app/out . ENTRYPOINT ["ServiceMonitor.exe", "w3svc"]
Build and run the new app image
Once the Dockerfile is updated, you need to build and run the app image.
Use docker build to build your image as shown below:
docker build -t iss .
To run the newly built container, run the docker run command:
docker run -d -p 8080:80 --name iss-app iss
Tag and push the image to your registry
To allow other hosts to reuse the new image, you should tag and then push the container image to your registry.
Use docker tag to tag the image as follows:
docker tag mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2022 <login-server>/iss
Use docker push to push the image to the container registry as follows:
docker push <login-server> iss
Upgrade containers using an orchestrator
You can also redeploy your Windows containers using an orchestrator, such as Azure Kubernetes Service and AKS on Azure Stack HCI. The orchestrator provides powerful automation for doing this at scale. For details, see Tutorial: Update an application in Azure Kubernetes Service or Tutorial: Update an application in Azure Kubernetes Service on Azure Stack HCI.