Customize migration plan for Windows IIS services
Review the migration plan file that was populated during the creation of the migration. You can customize it before proceeding to execute the migration. The details of your migration plan are used to extract the workload container artifacts from the source VM.
This section describes the contents of the migration plan and the kinds of customizations that you might consider before you execute the migration, and generate deployment artifacts.
Before you begin
This document assumes that you've already created a migration plan and have the resulting migration plan file.
Migration plan structure
Following is the full migration plan structure. The next sections discuss this structure, explain what each part is, and how to modify it.
globalSettings: globalIis: enablegmsa: string apppools: - enable32bitapponwin64: bool identitytype: string managedruntimeversion: string name: string connectionStrings: add: - connectionstring: string name: string providername: string security: authentication: windowsAuthentication: enabled: bool providers: - value: string authorization: add: - access_type: string roles: string users: string verbs: string remove: - roles: string users: string verbs: string image: extraFeatures: - string target: baseVersion: string requirements: - string warnings: - string msvcRuntimes: - string pathEnvVarAdditionalEntries: - string images: - name: string probes: livenessProbe: probehandler: exec: command: - string - string initialdelayseconds: int timeoutseconds: int periodseconds: int successthreshold: int failurethreshold: int terminationgraceperiodseconds: optional[int] readinessProbe: probehandler: exec: command: - string - string initialdelayseconds: int timeoutseconds: int periodseconds: int successthreshold: int failurethreshold: int terminationgraceperiodseconds: optional[int] useractions: files: - source: string target: string registry: currentcontrolset: - path: string software: - path: string workloads: sites: site: - applications: - applicationpool: string path: string virtualdirectories: - path: string physicalpath: string bindings: - port: int protocol: string sslflags: int connectionstrings: - connectionstring: string name: string providername: string name: string security: authentication: windowsAuthentication: enabled: bool providers: - value: string authorization: add: - access_type: string roles: string users: string verbs: string remove: - roles: string users: string verbs: string serverautostart: bool version: string
globalSettings section describes basic requirements for pods running IIS
sites from this VM. The discovery process searches for general configurations
in the source VM, and uses them to populate this section. These configurations
contain fields present in the specific image configurations as described in
the following section, and affects all images at the same time.
image section following
globalSettings describes the list of
to install on the pods. The discovery process populates this section with all
Windows features which exist on the original VM, and can be installed on a
Windows IIS Applications can have versions of Microsoft Visual C++ runtimes
installed. Runtimes are automatically detected on the source VM and included in
the migration plan. You can modify the list of runtimes in the migration plan
by editing members of
msvcRuntimes: - MSVC2012_x64 - MSVC2013_x64 - MSVC2015_x64 - MSVC2012_x86 - MSVC2013_x86 - MSVC2015_x86
Windows IIS applications might have non-default
PATH environment variable
entries, which are automatically detected on the source VM and included in the
migration plan. You can modify the
PATH environment variables by editing the
pathEnvVarAdditionalEntries: - "C:\\myDllsFolder" - "C:\\ProgramData\\SomeSoftware"
Edit the image section
You might want to edit the
image section in the following cases:
Some suggested features are not be required by the migrated sites. This happens if the source VM has usages other than hosting IIS sites.
You modified the IIS sections in the migration plan, and added configurations that depend on additional Windows features. (For example, Windows authentication depends on the Window authentication feature).
target section specifies which base Windows image you're using (for
example 1909). You should rarely need to edit this field.
Each subitem of the
images section specifies a single output image.
In the artifacts zip, each such image has a separate subdirectory, with its own
deployment_spec.yaml (see Deploying the container image).
name field describes the image name.
It affects the name of the image subdirectory and the
file in the artifacts.
probes field describes the health probe configuration of the image. To
learn more about kubelet probes, see
Configure Liveness, Readiness and Startup Probes.
Edit IIS health probes
Health probes can monitor the downtime and ready status of your managed containers. Health probe monitoring can help reduce the downtime of migrated containers and provide better monitoring.
Unknown health states can create availability degradation, false-positive availability monitoring, and potential data loss. Without a health probe, kubelet can only assume the health of a container and might send traffic to a container instance that is not ready. If the instance is not ready, it can cause traffic loss. Kubelet might also not detect containers that are in a frozen state and doesn't restart them.
A health probe functions by running a small scripted statement when the
container starts. The script checks for successful conditions, which are
defined by the type of probe used, every period. The period is defined in the
migration plan by a
periodSeconds field. You can define these probes manually
when you customize the migration plan.
*Liveness probe - Liveness probes are used to know when to restart a container.
Readiness probe - Readiness probes are used to know when a container is ready to start accepting traffic. To start sending traffic to a pod only when a probe succeeds, specify a readiness probe. A readiness probe might act similarly to a liveness probe. However, a readiness probe indicates that a pod starts without receiving any traffic and only start receiving traffic after the probe succeeds.
Startup probe - The kubelet uses startup probes to know when a container application has started. If such a probe is configured, it disables liveness and readiness checks until it succeeds, making sure that those probes don't interfere with the application startup.
After discovery, the probe configuration is added to the migration plan. The
probes can be used in their default configuration as shown in the following
example. The default configuration uses
exec command for the liveness and
readiness probes. Both are using a PowerShell script called
calls IIS command-line tool appcmd to check the status of the IIS sites.
To disable probes, remove the
probes section from the YAML.
images: name: IMAGE_NAME probes: livenessProbe: probehandler: exec: command: - powershell.exe - C:\m4a\probe.ps1 initialdelayseconds: 0 timeoutseconds: 1 periodseconds: 10 successthreshold: 1 failurethreshold: 3 terminationgraceperiodseconds: null readinessProbe: probehandler: exec: command: - powershell.exe - C:\m4a\probe.ps1 initialdelayseconds: 0 timeoutseconds: 1 periodseconds: 10 successthreshold: 1 failurethreshold: 3 terminationgraceperiodseconds: null
useractions section specifies additional files and registry keys that you
might want to migrate.
useractions: files: - source: DRIVE:\FOLDER-OR-FILE-PATH target: DRIVE:\FOLDER-OR-FILE-PATH - source: C:\myfolder target: C:\myfolder - source: D:\myfile target: D:\myfile - source: D:\myfile target: C:\myfile ... registry: currentcontrolset: - path: KEY ... software: - path: KEY ...
The paths specified for
software are to keys in the
HKEY_LOCAL_MACHINE\System\CurrentControlSet registry hive
or in the
HKEY_LOCAL_MACHINE\Software registry hive.
By default the only files copied to the image are the virtual directories of
sites in the specified image.
If your code or configurations import files from outside this directory, you should add them to the
Also, any registry values that your code depends on should be added by editing the
Settings related specifically to IIS
The IIS related settings are divided into settings related to specific sites,
which are part of the image specification, and settings related to all sites,
which are following the
The sites section describes the sites that are migrated to a specific image. It's possible for several images to contain the same site.
apppools section describes the Application Pools created on the migrated pods.
Connection strings define a connection from the migrated container workload to a .NET Framework data provider.
Migrate to Containers supports connection strings at the site and global scope.
To add a connection string to a site, edit the
site definition in the
AppXGenerateArtifactsFlow file that
represents the migration plan to set the
sites: site: # Add the site connection strings here. connectionstrings: - name: connectionname1 providername: System.Data.SqlClient connectionstring: Database=connectedDB1;Password=Welcome1;User=admin; - name: connectionname2 providername: System.Data.OleDb connectionstring: Database=connectedDB2;Password=Welcome2;User=admin; - applications: - path: / virtualdirectories: ...
To add a connection string to the global scope (making it accessible to all
sites), edit the connection strings directly following
globalIis: enablegmsa: auto connectionStrings: connectionstring: - name: connectionname3 providername: System.Data.SqlClient connectionstring: Database=connectedDB3;Password=Welcome3;User=admin; applicationhost: ...
namespecifies the connection name.
providernameoptionally specifies the data provider type. Migrate to Containers only supports a value of
System.Data.SqlClient. supports the .NET Framework data provider:
connectionstringspecifies the Connection Strings used to connect to the data provider.
Edit the connection strings sections
Migrate to Containers automatically copies connection strings detected in the migrated VM to the migration plan.
Some connection strings might not be detected and should be added by editing
the migration plan as shown preceding. (For example, if the connection
strings are in an encrypted section of the
For guidance on determining which connection strings to add to your migration plan, see Retrieving Connection Strings at Run Time in the Microsoft documentation.
Connection string External dependencies
- Connection strings can contain dependencies, such as a reference to a file at or to a Windows user associated with the site. You can add custom user actions to the migration plan to copy an extra file in the file system. Manually edit the Dockerfile to add a Windows user.
- Connection strings can contain dependencies, such as a reference to an external data source. These dependencies must be migrated manually to ensure that the migrated container workload has access to the data source.
The security sections contain the authentication and authorization subsections.
- Windows authentication verifies Active Directory users.
- Windows authorization is the mechanism for specifying which users are allowed which types of access to an IIS website. The access types are the HTTP verbs (POST, GET, PUT, PATCH, DELETE).
Similar to connection strings, to set authorization or authentication for all
globalIis as in the following example. To set authorization or
authentication for a specific site, edit the site element.
globalIis: security: authentication: windowsAuthentication: providers: - NTLM authorization: - add: user:John access: role: - remove: user:Jane access: GET role: ...
providersspecifies the provider of your security protocols.
userspecies the username.
accessspecies the permissions of the user. The access types are the HTTP verbs (POST, GET, PUT, PATCH, DELETE).
rolespecies a specific permission role.
- Learn how to execute the migration.