Build Windows-based workloads

When you generate artifacts for Windows workloads, the artifacts are copied into a Cloud Storage bucket as an intermediate location that you can download. This file contains a Dockerfile, the deployment_spec.yaml file, and several directories from the source that you then use to build the Windows container.

Before you begin

Before building the Windows container, you should have first:

• Executed a migration.

Note: For a complete step-by-step tutorial on this process, see the hands-on lab Migrate to Containers: Windows. The lab walks you through the entire migration process. See the section "Building a Windows container image" in the lab for specific information on building the container image.

Download the migration's artifacts

To download the migration artifacts, use the following steps:

migctl

1. When the migration completes, you should see a message such as the following when you request status:

   migctl migration status my-migration
   
   NAME            CURRENT-OPERATION       PROGRESS        STEP            STATUS    AGE
   my-migration    GenerateArtifacts       [1/1]           ExtractImage    Completed 14m23s

2. After the migration has completed, use migctl migration get-artifacts to obtain the generated artifacts file:

   migctl migration get-artifacts my-migration
   
   Downloaded artifacts for Migration my-migration. The artifacts are located in "PATH"`

Console

When the migration completes, you see Artifacts generated in the Status column of the migration. To download all migration artifacts:

1. Open the Migrate to Containers page in the Google Cloud console.

   Go to the Migrate to Containers page

2. Click the Migrations tab to display a table containing the available migrations.

3. Choose the migration row with a Name matching the desired migration.

4. Select the Artifacts link.

Build the container image

The procedure shown below builds a Windows container multi-arch image from the migration artifacts.

The build process is done using the Windows Cloud Builder, documented here:

• Building Windows Server multi-arch images.

The build process is done using Windows Cloud builder. Ensure you complete all tasks in this section:

• Preparing the environment

You can deploy a container running the resulting image on any cluster with a Windows node-pool.

Build the image

Skaffold can also handle the workflow for building, pushing and deploying your application. For more information, see Build and deploy Windows workloads using Skaffold.

To build the image manually, use the following steps:

1. Create a workspace directory on your work machine, for example: ~/gke-windows-builder/migrated-image.

2. Cd into the directory belonging to the image you wish you build. For example:

   cd  migrated-image-ax_eq
   

3. In the same directory, create a cloudbuild.yaml file. It will contain the build's configuration.

   Copy the following example to the file, and replace <REGISTRY_REGION> and <REPOSITORY> with the Artifact Registry repository region and name, respectively. At build time, Cloud Build automatically replaces $PROJECT_ID with your project ID. Make sure to change the version number to the target GKE cluster where the artifacts will be deployed (for example, windows:ltsc2019).

   windows/windows-multi-arch/cloudbuild.yaml

   View on GitHub

   timeout: 3600s
   steps:
   - name: 'us-docker.pkg.dev/gke-windows-tools/docker-repo/gke-windows-builder:latest'
     args:
     - --container-image-name
     # Replace <REGISTRY_REGION> and <REPOSITORY>.
     - '<REGISTRY_REGION>-docker.pkg.dev/$PROJECT_ID/<REPOSITORY>/multiarch-helloworld:latest'
     # Specify specific variants of images to be built. Or, remove the following 2 lines to default to all available variants.
     - --versions
     - '20H2,ltsc2019'

   Note: If you receive an error that the Dockerfile cannot pull mcr.microsoft.com/windows:ltsc2019, change the file to the correct version where the artifacts will be deployed (for example, ltsc2022). Or delete the final two lines in order to default to all available versions.

4. To build the image, run the following command:

   gcloud builds submit --config=cloudbuild.yaml .
   

   Note: This command takes a while to run.

5. You'll see logs similar to the following example. The last line in the log shows that the build succeeded:

   Creating temporary tarball archive of 2 file(s) totalling 492 bytes before compression.
   Uploading tarball of [.] to [gs://PROJECT_ID_cloudbuild/source/1600082502.509759-b949721a922d462c94a75da9be9f1181.tgz]
   Created [https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/builds/ec333452-1301-47e8-90e2-716aeb2f5650].
   Logs are available at [https://console.cloud.google.com/cloud-build/builds/ec333452-1301-47e8-90e2-716aeb2f5650?project=840737568665].
   ------------------------ REMOTE BUILD OUTPUT---------------------------------------
   ...
   ...
   
   Created manifest list REGISTRY_REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/multiarch-helloworld:latest
   sha256:3ecbbc9f5144f358f81f7c7f1a7e28f069c98423d59c40eaff72bf184af0be02
   2020/09/14 11:34:25 Instance: 35.184.178.49 shut down successfully
   PUSH
   DONE
   -----------------------------------------------------------------------------------
   
   ID                                    CREATE_TIME                DURATION  SOURCE                                                                                      IMAGES  STATUS
   ec333452-1301-47e8-90e2-716aeb2f5650  2020-09-14T11:21:43+00:00  12M43S    gs://PROJECT_ID_cloudbuild/source/1600082502.509759-b949721a922d462c94a75da9be9f1181.tgz  -                 SUCCESS
   

You've just built the image using the build config file and pushed the image to Artifact Registry at REGISTRY_REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/multiarch-helloworld:latest.

Build and deploy Windows workloads using Skaffold

Skaffold handles the workflow for building, pushing and deploying your application. You can use Skaffold for Windows in the same manner as other platforms.

If you use Cloud Shell, Skaffold is already installed. If you need to install Skaffold, see Installing Skaffold.

For Windows, set the following environment variables.

• Mandatory
  • CLOUDBUILD_PROJECT = the project where you want Cloud Build to run
  • REGION = the region in which Cloud Build will run
  • ZONE = the zone in which Cloud Build will run
• Optional - If the network and subnetwork are not specified, the default VPC and default subnetwork are used.
  • NETWORK = the network in which the Windows builder VMs will be created (VPC name)
  • SUBNETWORK = the subnetwork in which the Windows builders will be created

Follow the instructions in Building multi-arch images.

If you want to use custom worker pools for Cloud Build (to avoid firewall rules creation for example), set the following environment variables:

• Mandatory
  • WORKERPOOL = the name of the workerpool
  • WORKERPOOL_REGION = the region of the workerpool
• Optional
  • USE_INTERNAL_IP = true if the workerpool is connected with shared VPC to NETWORK

The commands to run a Windows build follows this format:

export CLOUDBUILD_PROJECT=CLOUDBUILD_PROJECT
export REGION=REGION
export ZONE=ZONE

skaffold build -d eu.gcr.io/PROJECT_ID

Replace PROJECT_ID with the ID of the project which contains your workload cluster.

If your Windows image build fails, to learn how to troubleshoot the issue, see Skaffold build for Windows images fails.

Configure logging to Cloud Logging

Migrate to Containers uses the LogMonitor tool to extract logs from a Windows container and forward them to your GKE cluster. These logs are then automatically forwarded to Cloud Logging, which provides a suite of tools to monitor your containers.

By default Migrate to Containers enables IIS logging to monitor the IIS logs, and also forwards the Application/System event logs to Cloud Logging.

Configure logging

Expanding the generated artifacts.zip file creates several directories, including the m4a directory. The directory contains a folder for every image. Included in the m4a directory is the LogMonitorConfig.json file that you can edit to control logging.

For more on editing LogMonitorConfig.json, see Authoring a Config File.

Set ACLs

Some IIS applications require that you set specific access control lists (ACL) permissions on files and folders in order for the applications to perform correctly. Migrate to Containers automatically scans all migrated IIS applications and adds any specific permissions defined in the source VM that apply to IIS accounts (the IUSR account and the IIS_IUSRS group) and applies them to the copied files and directories in the generated container image.

Because Windows container images do not support setting ACLs as part of the Docker COPY command, the ACLs are set in a script called set_acls.bat. Migrate to Containers automatically creates set_acls.bat in the directory of the gnerated image for your specific windows application. Migrate to Containers then calls set_acls.bat when you execute the docker build command.

Edit set_acls.bat to add or remove custom permissions, or edit permissions that are not related to specific IIS users and therefore were not detected by Migrate to Containers.

The script uses the Windows built-in icacls tool to set permissions.

About the .NET Global Assembly Cache

Migrate to Containers scans the source image .NET Global Assembly Cache (GAC) for .NET resources that are installed on the source machine and not available as part of the official images. Any discovered DLL is copied into the Docker context and installed as part of the building of the target image by a utility script install_gac.ps1.

All .NET assemblies are copied into the Docker context under the m4a\gac directory. To remove assemblies from the image, delete them from the m4a\gac directory.

What's next

• Learn how to deploy Windows-based workloads.