diff --git a/docs/docsite/rst/user_guide/windows.rst b/docs/docsite/rst/user_guide/windows.rst index 4e01c3a44e3..242771899f3 100644 --- a/docs/docsite/rst/user_guide/windows.rst +++ b/docs/docsite/rst/user_guide/windows.rst @@ -17,4 +17,5 @@ some of the differences between Linux/Unix hosts and hosts running Windows. windows_winrm windows_usage windows_dsc + windows_performance windows_faq diff --git a/docs/docsite/rst/user_guide/windows_performance.rst b/docs/docsite/rst/user_guide/windows_performance.rst new file mode 100644 index 00000000000..5eb5dbbdc5c --- /dev/null +++ b/docs/docsite/rst/user_guide/windows_performance.rst @@ -0,0 +1,61 @@ +.. _windows_performance: + +Windows performance +=================== +This document offers some performance optimizations you might like to apply to +your Windows hosts to speed them up specifically in the context of using Ansible +with them, and generally. + +Optimise PowerShell performance to reduce Ansible task overhead +--------------------------------------------------------------- +To speed up the startup of PowerShell by around 10x, run the following +PowerShell snippet in an Administrator session. Expect it to take tens of +seconds. + +.. note:: + + If native images have already been created by the ngen task or service, you + will observe no difference in performance (but this snippet will at that + point execute faster than otherwise). + +.. code-block:: powershell + + function Optimize-PowershellAssemblies { + # NGEN powershell assembly, improves startup time of powershell by 10x + $old_path = $env:path + try { + $env:path = [Runtime.InteropServices.RuntimeEnvironment]::GetRuntimeDirectory() + [AppDomain]::CurrentDomain.GetAssemblies() | % { + if (! $_.location) {continue} + $Name = Split-Path $_.location -leaf + if ($Name.startswith("Microsoft.PowerShell.")) { + Write-Progress -Activity "Native Image Installation" -Status "$name" + ngen install $_.location | % {"`t$_"} + } + } + } finally { + $env:path = $old_path + } + } + Optimize-PowershellAssemblies + +PowerShell is used by every Windows Ansible module. This optimisation reduces +the time PowerShell takes to start up, removing that overhead from every invocation. + +This snippet uses `the native image generator, ngen `_ +to pre-emptively create native images for the assemblies that PowerShell relies on. + +Fix high-CPU-on-boot for VMs/cloud instances +-------------------------------------------- +If you are creating golden images to spawn instances from, you can avoid a disruptive +high CPU task near startup via `processing the ngen queue `_ +within your golden image creation, if you know the CPU types won't change between +golden image build process and runtime. + +Place the following near the end of your playbook, bearing in mind the factors that can cause native images to be invalidated (`see MSDN `_). + +.. code-block:: yaml + + - name: generate native .NET images for CPU + win_dotnet_ngen: + diff --git a/lib/ansible/modules/windows/win_dotnet_ngen.py b/lib/ansible/modules/windows/win_dotnet_ngen.py index ae8f3799c35..db682c98ecf 100644 --- a/lib/ansible/modules/windows/win_dotnet_ngen.py +++ b/lib/ansible/modules/windows/win_dotnet_ngen.py @@ -20,6 +20,7 @@ description: - After .NET framework is installed/updated, Windows will probably want to recompile things to optimise for the host. - This happens via scheduled task, usually at some inopportune time. - This module allows you to run this task on your own schedule, so you incur the CPU hit at some more convenient and controlled time. + - U(https://docs.microsoft.com/en-us/dotnet/framework/tools/ngen-exe-native-image-generator#native-image-service) - U(http://blogs.msdn.com/b/dotnet/archive/2013/08/06/wondering-why-mscorsvw-exe-has-high-cpu-usage-you-can-speed-it-up.aspx) options: {} notes: