Windows Setup doc; offer 10x perf improvement

[petemounce]

SUMMARY

Add a section to the Windows Setup documentation about how to get a 10x performance improvement over cleanly installed Windows.

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

lib/ansible/plugins/connection/ssh.py
lib/ansible/plugins/shell/powershell.py

ADDITIONAL INFORMATION

We found that when we did this, tasks that were taking ~6s dropped to low hundreds-of-milliseconds.

One playbook (over winrm) went from 25m35s to 8m9s. SSH connection benefits similarly.

Thought you might like to offer it to users, and this seemed like an appropriate place.

All credit to @ca-johnson for the diligent profiling work he did!

[ansibot]

@petemounce This PR contains @ mentions in at least one commit message. Those mentions can cause cascading notifications through GitHub and need to be removed. Please squash or amend your commits to remove the mentions.

click here for bot help

[ansibot]

cc @acozine @jborean93 @nitzmahone
click here for bot help

[nitzmahone]

Hrm, I think this is a good thing to have in our docs, but I'm thinking we might need a "troubleshooting / performance" page, rather than plopping it in the middle of the (already scarily large) "initial setup" page... This is only a problem if your install/imaging process has somehow invalidated the NI cache- Powershell is always ngen'd "out of the box" on 2012R2+ in my testing...

[petemounce]

@nitzmahone happy to do that - please tell me where I should place the new documentation file and how to name it, and I'll slice and dice?

I've observed this optimisation to be necessary with out-of-the-box GCE Windows 2016 images and AWS AMIs (the latter in circa 2015, though; might have moved on, I haven't needed to know in a little while).

[jborean93]

@acozine or @samccann do you have a suggestion for @petemounce to place performance tips and tricks for Windows?

[acozine]

@jborean93 yep!
@petemounce could you create a new file called docs/docsite/rst/user_guide/windows_performance.rst, put this content (and any additions) there, and add it to the TOC for the Windows guide below the windows_dsc entry on the main Windows page? Ping me with questions, here or in #ansible-docs on freenode IRC.

[acozine]

@petemounce see also https://docs.ansible.com/ansible/latest/dev_guide/style_guide/index.html for some pointers/help on creating rst pages.

[petemounce]

@acozine @jborean93 - sure; how's this?

[ansibot]

The test ansible-test sanity --test docs-build [explain] failed with 1 error:

docs/docsite/rst/index.rst:55:0: literal-block-lex-error: Could not lex literal_block as "powershell". Highlighting skipped.

click here for bot help

[ansibot]

cc @ShachafGoldstein @if-meaton @jhawkesworth
click here for bot help

[jborean93]

Just a few minor points. I will let @acozine and @samccann comment on the actual text. From a dev perspective this is all good to me.

[acozine]

@petemounce are you still working on this material?

[petemounce]

Yes

[jhawkesworth]

Nice, lets have this.
Didn't speed anything up on my vms but good to have documented way to get ngen cache up to date.
It might be nice to present the Optimize-PowershellAssemblies function as a win_shell task but wouldn't want to hold up merging this for that.

[samccann]

Thanks @petemounce for the addition to Ansible documentation.

[petemounce]

Thanks for review and merge!