How many hours of outage can the business tolerate during a migration? Migrations can cause multi-hour outages when Windows-only features break. Plan for auth, ISAPI, COM+, and registry failures so downtime and extra cost do not surprise stakeholders.
Risk Analysis: Migrating Legacy IIS Apps to Linux. Migrating legacy IIS apps to Linux carries clear technical and business risks. The plan gives probability×impact risk analysis, an RPN matrix by IIS feature, prioritized mitigations, a compliance impact matrix, a cost-delta model, and test/rollback playbooks with KPIs and pilot acceptance criteria.
Risk factors for migrating IIS apps to Linux containers
The main decision factor is platform dependency and outage business impact. Assess Windows features in use and map them to needed work: refactor, bridge, or keep on Windows.
Short-term operational differences change runtimes and monitoring needs. Containers alter image patching, log collection, and secret storage. Plan for new tools and staff time to learn them.
Prepare for compliance and security scope shifts when leaving Windows. Confirm which controls the cloud provider covers and which the customer keeps. Also confirm audit evidence after migration.
A short pause for the reader.
Windows-only APIs often block a straight port to Linux. ISAPI filters, P/Invoke into native DLLs, and COM objects usually need refactor or Windows hosts.
The most frequent error at this point is assuming binaries behave the same on Linux. Those binaries call Windows APIs and then fail silently or log cryptic errors.
Identity, sessions, and auth flows
Integrated Authentication uses Active Directory and Kerberos flows that do not carry over unchanged to Linux containers. Assess end-to-end auth early in discovery and map token paths.
This works well in theory. In practice, Kerberos tokens, SPNs, and delegation break unless a translation layer or reauth path exists.
Operational model and observability
Containers use ephemeral processes and different metrics than Perf counters. Inventory current monitors and map them to container-friendly tools such as Prometheus and Grafana.
Prepare for differences in patch cadence and image scanning. Adopt image signing and registry policies before running production containers.
A short pause for the reader.
Which legacy IIS apps qualify for containerization
Not every IIS app should move to Linux containers. Focus on apps with few Windows-only calls, clear separation of concerns, and testable interfaces.
Apps that use only managed code and the standard HTTP stack are good candidates. Apps on .NET Core or .NET 5+ without native dependencies usually need minimal changes.
Apps that embed COM, call the registry, or use ISAPI usually do not qualify. Those need substantial refactor or Windows container hosts and should be treated as high risk.
Qualification checklist
Create a feature-level checklist: registry use, P/Invoke, Windows auth, COM, scheduled tasks, and file ACLs. Mark each item Yes or No and score effort.
A sample result line:
- Uses Windows auth: Yes
- P/Invoke: No
- COM: No
- Estimated work: 8 dev-days
- RPN recommended: 432
Keep one row per app for audit.
Case: mid-size retailer
A common case: a retailer moved an inventory web app and lost SSO for 6 hours during the pilot. Customer login failed because Windows auth was mis-scored and no DNS rollback plan existed.
The lesson learned was to treat auth as high impact. Stage auth changes behind a toggle and canary to reduce blast radius.
Choose hosting from compliance, latency, and cost needs. VPS or VMs keep compatibility but often cost more for licensing and ops.
Cloud containers lower host cost but increase integration effort. For regulated workloads use government cloud regions or on-prem where audits meet requirements.
Kubernetes orchestration adds complexity but lowers per-app ops at scale. For a few apps a managed container service or single-node container host may be simpler.
A short pause for the reader.
VPS and Windows VM path
Keeping apps on Windows VMs avoids code change but keeps Windows licensing and larger instance sizes. Use this path when an app's RPN exceeds the allowed threshold.
Windows containers reduce refactor work but still require Windows licensing and Windows host ops. They help when native APIs cannot be removed.
Cloud containers and Kubernetes path
Linux containers on managed Kubernetes lower per-instance cost and improve portability. They require refactor for Windows-specific features and a stronger CI/CD pipeline.
Expect to spend initial engineering time to map secrets, identity, and storage. Plan for runtime security and CIS hardening in the cluster.
Common failure points and mitigation
Broken authentication and hidden Windows-only features cause the most operational failures. Score each item with RPN and require mitigations where RPN exceeds thresholds.
Set RPN thresholds and stop criteria before the pilot. Use RPN above 200 to block migration of that component, 100 to 200 to require mitigation, and below 100 to proceed with standard tests.
Maintain a clear rollback plan tied to measurable thresholds: error rate, auth failures, and latency increases. Automate traffic switch and have a tested DNS or LB rollback.
RPN scoring method with worked example
RPN equals Probability times Impact times Detectability on a 1 to 10 scale. Use specific anchors for each number and document reviewer initials.
Example: Windows Integrated Auth.
- Probability=8
- Impact=9
- Detectability=6 → RPN=432
RPN 432 is greater than 200, so block migration until reauth is in place.
Audit note: document the scoring rationale and acceptance criteria for each component. This lets reviewers replay decisions later.
Technical mitigations by failure type
Auth: move to OAuth or OIDC with Azure AD or deploy a Kerberos-to-OIDC bridge. Use token-based flows when possible.
Native binaries: extract business logic to a Windows service and call it via REST, or keep that component on Windows. For many apps that is the least risky path.
CI/CD gating and canary rollback snippet
Apply a CI rule that blocks deploys if acceptance tests fail. Use staged canary percentages: 5% for 1 hour, 20% for 6 hours, then 100% if metrics stay within thresholds.
Example policy line: "CI blocks image push if scan shows critical CVEs; deployment aborts and DNS flips back if auth failures exceed 0.1% of requests over 10 minutes." Use feature flags to disable new auth flows.
Use RPN >200 to stop migration of any component until a compensating control or design change reduces risk. Document the mitigation owner and expected completion date for audit trails.
Compatibility mapping and quick reference
Map common IIS features to Linux and container alternatives. Label effort as Low, Medium, High, or Block to score migration feasibility per app.
Below is a compact mapping to use during discovery and to present to stakeholders as a one-page decision guide.
| Feature |
Linux Alternative |
Estimated Work |
RPN Guidance |
| Windows Integrated Auth (Kerberos/NTLM) |
OAuth/OIDC (Azure AD) or Kerberos bridge |
High |
Block unless reauth implemented |
| ISAPI / Native DLLs |
Refactor to managed or host on Windows service |
High/Block |
Block or Windows containers |
| URL Rewrite / Authorization rules |
NGINX/Traefik rules + middleware |
Low-Medium |
Proceed with tests |
| COM / DCOM |
Refactor to service API or keep on Windows |
High |
Block or service migration |
Discovery completeness
Target: 90% of feature inventory
Auth risk index
High if Kerberos in use
Refactor effort
Estimate dev-days per app
Mitigation patterns and playbooks
Mitigation reduces RPN by lowering probability, impact, or detectability. Pick the cheapest effective control and record it in the RPN register.
For high-auth risk apps the common pattern is a reauth gateway or a switch to token-based identity and short-lived sessions. Test end-to-end before cutover.
For native code the strangler pattern works: expose current logic via a network service and replace it incrementally. This lowers impact and allows rollback to Windows during incidents.
A short pause for the reader.
Playbook: pilot, test, and rollback
Pilot: pick one representative app, copy data to read-only staging, and run a full CI pipeline with acceptance and load tests. Use canary traffic control and feature flags.
Test: require functional parity of 99 percent or more and P95 latency within 10 percent of baseline. Also require zero critical CVEs after image scan and successful end-to-end auth.
Rollback: if metrics breach thresholds flip traffic back to the Windows pool using LB or DNS. Restore the previous image and mark the incident for an RPN review.
CI/CD policy template
Use an automated gate: "CI pipeline fails image push if scanner finds critical CVE or if acceptance tests show more than 0.1% error rate." Enforce RBAC on registries and sign images.
Code example snippet:
if image.scan.critical > 0:
abort
if acceptance.errors_rate > 0.001:
rollout.abort()
canary.percentages = [5,20,100]
Cost delta and operational impact model
Compare one-time engineering, licensing, and monthly runtime to compute the TCO delta. Include incident ops and monitoring as steady-state costs.
A simple formula is: Total = One-time engineering + (Monthly infra + Monthly ops + License fees) × months. Use real quotes for precision.
Example numbers for planning: refactoring a medium app often takes 10 to 30 dev-days, about $12,000 to $36,000 at common market rates in 2026 USD. Monthly per-host delta often ranges $50 to $120 when moving from Windows VM to Linux container hosts.
Per-1,000-requests cost example:
Assume 100k requests per day, which equals 3M per month. Linux container infra cost estimate is about $0.05 per 1,000 requests. VM hosting estimate is about $0.07 per 1,000 requests. The delta is $0.02 per 1,000 requests.
Numbers are illustrative; vendor pricing and region will affect totals.
Compliance and security mapping
Platform change often moves responsibility for controls and evidence. Update control mappings for PCI DSS, HIPAA, SOC 2, and NIST controls. Have evidence collectors ready before audit.
NIST SP 800-190 (2018) and NIST SP 800-53 revision 5 (2020) give container and control guidance to map to audit evidence. Use them to justify control changes.
For regulated workloads in the United States consider provider compliance offerings and region choices such as AWS GovCloud or Azure Government to keep data within required boundaries.
Compliance matrix sample
Control → Pre-migration evidence → Post-migration evidence → Reviewer sign-off.
Example: Access control → Active Directory logs (pre) → Azure AD logs and container audit logs (post) → signature and date.
Security policies to apply
Require image scanning and block images with critical CVEs. Use secrets managers such as HashiCorp Vault or AWS Secrets Manager and avoid filesystem secrets.
Implement least-privilege RBAC for cluster and registry.
Microsoft Containers documentation provides vendor guidance for teams keeping Windows compatibility.
For a pilot scoping review include the RPN register, an inventory CSV, and proposed acceptance criteria so reviewers can approve the pilot quickly.
Policy template:
- Container Image, Registry and Runtime Hardening. For enterprise migrations from IIS to Linux containers it helps to capture policies in concrete rules. Example policy lines: "Image provenance: all images must be signed with Cosign or Notary v2 and pushed to the private registry with immutable tags; no unsigned images allowed in production." "Registry RBAC: developers may push to dev/; release engineers may promote images to prod/; only the CI service account can write prod/*." "Scanning policy: CI blocks any image with High or Critical CVEs; monthly SBOM export required." "Runtime hardening: containers run as non-root; file systems mount read-only where possible; drop capabilities such as CAP_SYS_ADMIN and CAP_NET_RAW; enforce CIS container benchmark profiles on hosts." "Secrets: disallow env/plaintext secrets; require HashiCorp Vault, Azure Key Vault, or equivalent with DefaultAzureCredential for retrieval." Including these policy lines in the migration pack gives auditors and operators exact enforceable rules during the IIS migration.
Frequently asked questions
What is the single biggest risk when moving IIS?
Authentication tied to Active Directory and Kerberos causes the most outages during migration. If SSO breaks, many flows fail and rollback becomes mandatory.
Plan to treat auth as high-impact and pilot any auth change behind feature flags and canaries. The legal or compliance owner should review auth evidence before go-live.
How is RPN calculated and what thresholds should be used?
RPN equals Probability times Impact times Detectability on a 1 to 10 scale. Use thresholds: greater than 200 is critical, 100 to 200 is conditional, and less than 100 proceeds with standard testing.
Document the numeric anchors for each score and require reviewer initials for any rating. This makes the decision auditable for stakeholders.
Can all .NET Framework apps run on Linux?
No. Only apps that remove Windows-only APIs and reference cross-platform libraries can run on Linux. Some apps need moderate refactor and others require keeping Windows components.
A realistic approach is the strangler pattern: keep Windows-hosted services for native calls while moving the web tier to Linux containers.
When should a Windows container be chosen instead?
Choose Windows containers when native dependencies are business-critical and refactor cost or risk is too high. Windows containers reduce engineering work but keep licensing and Windows ops.
Use Windows containers when RPN blocking items cannot be mitigated within acceptable budget or time.
What test metrics should gate a pilot acceptance?
Gate on functional parity of 99 percent or more, P95 latency within 10 percent of baseline, error rate below 0.1 percent, and zero critical image CVEs. Also verify compliance evidence is available.
Require load and chaos tests and a successful rollback drill before expanding the pilot scope.
How long does a typical pilot take?
A focused pilot often runs 3 to 8 weeks: 1 week for inventory, 1 to 3 weeks for refactor and CI gating, 1 to 3 weeks for testing, and 1 week for review and sign-off. Timelines vary by app complexity.
What should be included in the migration?
Include app name, team owner, IIS features used, P/Invoke use, COM use, Windows auth flag, estimated dev-days, initial RPN, mitigation, and pilot test assigned. This creates traceable evidence for decisions.
This guidance does not apply when the app is a simple static site or a self-contained .NET app with no Windows-only dependencies, or when policy forbids leaving the Windows OS or using containers. In those cases keep the app on Windows VM or Windows containers and adjust operational controls accordingly.
The concrete next steps
Create the RPN register and run a short inventory across all IIS apps to score dependencies and exposures. Prioritize a pilot of one representative app with initial RPN under 100 and document mitigations for items scoring 100 to 200.
Assign clear owners, set acceptance metrics, and schedule a rollback drill. Use the mapping tables and CI/CD policy snippets above so the pilot is auditable and repeatable.
The evidence to bring to stakeholders is simple: the inventory CSV, the RPN register with reviewer initials, pilot acceptance test results, and cost delta numbers for the chosen hosting path.
Metric-backed case study (illustrative): An online retailer migrated a medium-complexity IIS app (Windows Integrated Authentication, light ISAPI usage) to Linux containers using a reauth gateway. Pre-migration baseline: monthly hosting $4,300; P95 latency 420ms; SSO auth error rate 1.2% during pilot.
A short pause for the reader.
