Upgrade containers to a new version of the Windows operating system

Article
03/17/2023

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.

Note

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:
```
docker 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.

Note

If you want to upgrade the image for any container that's currently running, you'll need to stop the containers using docker stop and then run docker rm to remove the containers.

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.

Share via