You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by al...@apache.org on 2015/09/21 18:51:18 UTC
[1/2] incubator-brooklyn git commit: Improve winrm docs
Repository: incubator-brooklyn
Updated Branches:
refs/heads/master 6aefffd59 -> 8c269d5be
Improve winrm docs
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/25af0230
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/25af0230
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/25af0230
Branch: refs/heads/master
Commit: 25af0230a6115ad4a1e854f4d45c976ecfa1889c
Parents: 6aefffd
Author: Aled Sage <al...@gmail.com>
Authored: Fri Sep 18 13:02:59 2015 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Mon Sep 21 17:50:23 2015 +0100
----------------------------------------------------------------------
docs/guide/yaml/winrm/index.md | 226 +++++++++++++++++++-----
docs/guide/yaml/winrm/re-authentication.md | 36 ----
docs/guide/yaml/winrm/stdout-and-stderr.md | 25 ---
3 files changed, 186 insertions(+), 101 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/25af0230/docs/guide/yaml/winrm/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/winrm/index.md b/docs/guide/yaml/winrm/index.md
index 0f95bd9..e18ae52 100644
--- a/docs/guide/yaml/winrm/index.md
+++ b/docs/guide/yaml/winrm/index.md
@@ -1,14 +1,11 @@
---
title: Windows Blueprints
layout: website-normal
-children:
-- re-authentication.md
-- stdout-and-stderr.md
---
-In addition to controlling UNIX-like servers with SSH, Brooklyn has support for blueprints that deploy to Windows
-servers using WinRM to run commands. These deployments can be expressed in pure YAML, and utilise PowerShell to install
-and manage the software process.
+Brooklyn can deploy to Windows servers using WinRM to run commands. These deployments can be
+expressed in pure YAML, and utilise PowerShell to install and manage the software process.
+This approach is similar to the use of SSH for UNIX-like servers.
About WinRM
@@ -41,16 +38,7 @@ In particular, you will most likely want to set these properties on your locatio
* `templateOptions` - you may also wish to request a larger disk size. This setting is cloud specific; on AWS, you can
request a 100GB disk by setting this property to `{mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]}`.
-For example, you may place the following in `brooklyn.properties`:
-
- brooklyn.location.named.AWS\ Oregon\ Win=jclouds:aws-ec2:us-west-2
- brooklyn.location.named.AWS\ Oregon\ Win.displayName = AWS Oregon (Windows)
- brooklyn.location.named.AWS\ Oregon\ Win.imageNameRegex = Windows_Server-2012-R2_RTM-English-64Bit-Base
- brooklyn.location.named.AWS\ Oregon\ Win.hardwareId = m3.medium
- brooklyn.location.named.AWS\ Oregon\ Win.useJcloudsSshInit=false
- brooklyn.location.named.AWS\ Oregon\ Win.templateOptions={mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]}
-
-Alternatively, in your YAML blueprint:
+In your YAML blueprint:
...
location:
@@ -58,12 +46,24 @@ Alternatively, in your YAML blueprint:
region: us-west-2
identity: AKA_YOUR_ACCESS_KEY_ID
credential: <access-key-hex-digits>
- imageNameRegex: Windows_Server-2012-R2_RTM-English-64Bit-Base
+ imageNameRegex: Windows_Server-2012-R2_RTM-English-64Bit-Base-.*
+ imageOwner: 801119661308
hardwareId: m3.medium
useJcloudsSshInit: false
templateOptions: {mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]}
...
+Alternatively, you can define a new named location in `brooklyn.properties`:
+
+ brooklyn.location.named.AWS\ Oregon\ Win = jclouds:aws-ec2:us-west-2
+ brooklyn.location.named.AWS\ Oregon\ Win.displayName = AWS Oregon (Windows)
+ brooklyn.location.named.AWS\ Oregon\ Win.imageNameRegex = Windows_Server-2012-R2_RTM-English-64Bit-Base-.*
+ brooklyn.location.named.AWS\ Oregon\ Win.imageOwner = 801119661308
+ brooklyn.location.named.AWS\ Oregon\ Win.hardwareId = m3.medium
+ brooklyn.location.named.AWS\ Oregon\ Win.useJcloudsSshInit = false
+ brooklyn.location.named.AWS\ Oregon\ Win.templateOptions = {mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]}
+
+
A Sample Blueprint
------------------
@@ -73,7 +73,7 @@ to `VanillaSoftwareProcess`, but adapted to work for Windows and WinRM instead o
[documentation for VanillaSoftwareProcess](../custom-entities.html#vanilla-software-using-bash) to find out what you
can do with this entity.
-For example - here is a blueprint:
+For example - here is a simplified blueprint (but see [Tips and Tricks](#tips-and-tricks) below!):
name: Server with 7-Zip
@@ -82,7 +82,8 @@ For example - here is a blueprint:
region: us-west-2
identity: AKA_YOUR_ACCESS_KEY_ID
credential: <access-key-hex-digits>
- imageNameRegex: Windows_Server-2012-R2_RTM-English-64Bit-Base
+ imageNameRegex: Windows_Server-2012-R2_RTM-English-64Bit-Base-.*
+ imageOwner: 801119661308
hardwareId: m3.medium
useJcloudsSshInit: false
templateOptions: {mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]}
@@ -115,40 +116,185 @@ This is only a very simple example. A core complex example can be found in the [
Brooklyn source code]({{ site.brooklyn.url.git }}/software/database/src/main/resources/org/apache/brooklyn/entity/database/mssql).
-Known Limitations and Special Cases
------------------------------------
+Tips and Tricks
+---------------
+
+The best practices for other entities (e.g. using [VanillaSoftwareProcess](../custom-entities.html#vanilla-software-using-bash))
+apply for WinRM as well.
+
+### Execution Phases
+
+Blueprint authors are strongly encouraged to provide an implementation for install, launch, stop
+and checkRunning. These are vital for the generic effectors such as stopping and restarting the
+process.
+
+### Powershell
+
+Powershell commands can be supplied directly using config options such as `launch.powershell.command`.
+
+### Rebooting
+
+Where a reboot is required as part of the entity setup, this can be configured using
+config like `pre.install.reboot.required` and `install.reboot.required`. If required, the
+installation commands can be split between the pre-install, install and post-install phases
+in order to do a reboot at the appropriate point of the VM setup.
+
+## Powershell scripts and configuration files on classpath
+
+Often, blueprints will require that (parameterized) scripts and configuration files are available to be copied to the
+target VM. These must be URLs resolvable from the Brooklyn instance, or on the Brooklyn classpath. One simple way
+to achieve this is to compile the support files into a .jar, which is then added to AMP's 'dropins' folder. Alternatively,
+an OSGi bundle can be used, referenced from the catalog item.
+
+Ensure that these scripts end each line with "\r\n", rather than just "\n".
+
+### Install Location
+
+Blueprint authors are encouraged to explicitly specify the full path for file uploads, and
+for paths in their Powershell scripts (e.g. for installation, configuration files, log files, etc).
+
+
+### How and Why to re-authenticate within a powershell script
+
+Brooklyn will run powershell scripts by making a WinRM call over HTTP. For most scripts this will work, however for
+some scripts (e.g. MSSQL installation), this will fail even if the script can be run locally (e.g. by using RDP to
+connect to the machine and running the script manually)
+
+For example in the case of MS SQL server installation, there was no clear indication of why this would not work.
+The only clue was a security exception in the installation log.
+
+When a script is run over WinRM over HTTP, the credentials under which the script are run are marked as
+'remote' credentials, which are prohibited from running certain security-related operations. The solution was to obtain
+a new set of credentials within the script and use those credentials to execute the installer, so this:
+
+ ( $driveLetter + "setup.exe") /ConfigurationFile=C:\ConfigurationFile.ini
+
+became this:
+
+ $pass = '${attribute['windows.password']}'
+ $secpasswd = ConvertTo-SecureString $pass -AsPlainText -Force
+ $mycreds = New-Object System.Management.Automation.PSCredential ($($env:COMPUTERNAME + "\Administrator"), $secpasswd)
+
+ Invoke-Command -ComputerName localhost -credential $mycreds -scriptblock {
+ param($driveLetter)
+ Start-Process ( $driveLetter + "setup.exe") -ArgumentList "/ConfigurationFile=C:\ConfigurationFile.ini" -RedirectStandardOutput "C:\sqlout.txt" -RedirectStandardError "C:\sqlerr.txt" -Wait
+ } -Authentication CredSSP -argumentlist $driveLetter
+
+The `$pass=` line simply reads the Windows password from the entity before the script is copied to the server. This is
+then encrypted on the next line before being used to create a new credential object. Then, rather than calling the executable
+directly, the `Start-Process` scriptlet is used. This allows us to pass in the newly created credentials, under which
+the process will be run.
+
+Certain registry keys must be reconfigured in order to support re-authentication. Brooklyn will take care of this at
+instance boot time, as part of the setup script. Please ensure that Brooklyn's changes are compatible with your
+organisation's security policy.
+
+Re-authentication also requires that the password credentials are passed in plain text in the blueprint's script files.
+Please be aware that it is normal for script files - and therefore the plaintext password - to be saved to the VM's
+disk.
+
+### Windows AMIs on AWS
+
+Windows AMIs in AWS change regularly (to include the latest Windows updates). If using the community
+AMI, it is recommended to use an AMI name regex, rather than an image id, so that the latest AMI is
+always picked up. If an image id is used, it may fail as Amazon will delete their old Windows AMIs.
+
+If using an image regex, it is recommended to include the image owner in case someone else uploads
+a similarly named AMI. For example:
+
+ brooklyn.location.named.AWS\ Oregon\ Win = jclouds:aws-ec2:us-west-2
+ brooklyn.location.named.AWS\ Oregon\ Win.imageNameRegex = Windows_Server-2012-R2_RTM-English-64Bit-Base-.*
+ brooklyn.location.named.AWS\ Oregon\ Win.imageOwner = 801119661308
+ ...
+
+## stdout and stderr in a PowerShell script
+
+When calling an executable in a PowerShell script, the stdout and stderr will usually be output to the console.
+This is captured by Brooklyn, and shown in the activities view under the specific tasks.
+
+An alternative is to redirect stdout and stderr to a file on the VM, which can be helpful if one expects sys admins
+to log into the VM. However, be warned that this would hide the stdout/stderr from Brooklyn's activities view.
+
+For example, instead of running the following:
+
+ D:\setup.exe /ConfigurationFile=C:\ConfigurationFile.ini
+
+ The redirect can be achieved by using the `Start-Process` scriptlet:
+
+ Start-Process D:\setup.exe -ArgumentList "/ConfigurationFile=C:\ConfigurationFile.ini" -RedirectStandardOutput "C:\sqlout.txt" -RedirectStandardError "C:\sqlerr.txt" -PassThru -Wait
+
+The `-ArgumentList` is simply the arguments that are to be passed to the executable, `-RedirectStandardOutput` and
+`RedirectStandardError` take file locations for the output (if the file already exists, it will be overwritten). The
+`-PassThru` argument indicates that PowerShell should write to the file *in addition* to the console, rather than
+*instead* of the console. The `-Wait` argument will cause the scriptlet to block until the process is complete.
+
+Further details can be found on the [Start-Process documentation page](https://technet.microsoft.com/en-us/library/hh849848.aspx)
+on the Microsoft TechNet site.
+
+
+Troubleshooting
+---------------
+
+Much of the [operations troubleshooting guide](../../ops/troubleshooting/) is applicable for Windows blueprints.
### User metadata service requirement
WinRM requires activation and configuration before it will work in a standard Windows Server deployment. To automate
this, Brooklyn will place a setup script in the user metadata blob. Services such as Amazon EC2's `Ec2ConfigService`
will automatically load and execute this script. If your chosen cloud provider does not support `Ec2ConfigService` or
-a similar package, or if you cloud provider does not support user metadata, then you must pre-configure a Windows image
+a similar package, or if your cloud provider does not support user metadata, then you must pre-configure a Windows image
with the required WinRM setup and make Brooklyn use this image.
-### Use of unencrypted HTTP
-
-Brooklyn is currently using unencrypted HTTP for WinRM communication. This means that the login credentials will be
-transmitted in clear text.
-
-In future we aim to improve Brooklyn to support HTTPS. However this does involve issues are certificate creation and
-verification.
-
-### Standard output and error streams
+If the configuration options `userMetadata` or `userMetadataString` are used on the location, then this will override
+the default setup script. This allows one to supply a custom setup script. However, if userMetadata contains something
+else then the setup will not be done and the VM may not not be accessible remotely over WinRM.
-These are not made available to Brooklyn like they are on Linux. For a workaround, please refer to [Redirecting
-stdout/stderr](stdout-and-stderr.html). We hope to resolve this in a future version of Brooklyn.
### Credentials issue requiring special configuration
-It appears that when a script is run over WinRM over HTTP, the credentials under which the script are run are marked as
+When a script is run over WinRM over HTTP, the credentials under which the script are run are marked as
'remote' credentials, which are prohibited from running certain security-related operations. This may prevent certain
operations. The installer from Microsoft SQL Server is known to fail in this case, for example. For a workaround, please
-refer to [Re-authenticating within a PowerShell script](re-authentication.html).
+refer to [How and Why to re-authenticate withing a powershell script](#how-and-why-to-re-authenticate-within-a-powershell-script) above.
-Certain registry keys must be reconfigured in order to support re-authentication. Brooklyn will take care of this at
-instance boot time. Please ensure that Brooklyn's changes are compatible with your organisation's security policy.
+### AMIs not found
-Re-authentication also requires that the password credentials are passed in plain text in the blueprint's script files.
-Please be aware that it is normal for script files - and therefore the plaintext password - to be saved to the VM's
-disk.
+If using the imageId of a Windows community AMI, you may find that the AMI is deleted after a few weeks.
+See [Windows AMIs on AWS](#windows-amis-on-aws) above.
+
+### Windows log files
+
+Details of the commands executed, and their results, can be found in the Brooklyn log and in the Brooklyn
+web-console's activity view.
+
+There will also be log files on the Windows Server. System errors in Windows are usually reported in the Windows Event Log -
+see [https://technet.microsoft.com/en-us/library/cc766042.aspx](https://technet.microsoft.com/en-us/library/cc766042.aspx)
+for more information.
+
+Additional logs may be created by some Windows programs. For example, MSSQL creates a log in
+`%programfiles%\Microsoft SQL Server\130\Setup Bootstrap\Log\` - for more information see
+[https://msdn.microsoft.com/en-us/library/ms143702.aspx](https://msdn.microsoft.com/en-us/library/ms143702.aspx).
+
+
+Known Limitations
+-----------------
+
+### Use of unencrypted HTTP
+
+Brooklyn is currently using unencrypted HTTP for WinRM communication. This means that the login credentials will be
+transmitted in clear text.
+
+In future we aim to improve Brooklyn to support HTTPS. However this requires adding support to the underlying
+WinRM library, and also involves certificate creation and verification.
+
+### Install location
+
+Work is required to better configure a default install location on the VM (e.g. so that
+environment variables are set). The installation pattern for linux-based blueprints,
+of using brooklyn-managed-processes/installs, is not used or recommended on Windows.
+Files will be uploaded to C:\ if no explicit directory is supplied, which is untidy,
+unnecessarily exposes the scripts to the user, and could cause conflicts if multiple
+entities are installed.
+
+Blueprint authors are strongly encourages to explicitly specific directories for file
+uploads and in their Powershell scripts.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/25af0230/docs/guide/yaml/winrm/re-authentication.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/winrm/re-authentication.md b/docs/guide/yaml/winrm/re-authentication.md
deleted file mode 100644
index db7a551..0000000
--- a/docs/guide/yaml/winrm/re-authentication.md
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: Re-authenticating within a PowerShell script
-title_in_menu: Re-authentication
-layout: website-normal
----
-
-## How and Why to re-authenticate withing a powershell script
-
-Brooklyn will run powershell scripts by making a WinRM call over HTTP. For most scripts this will work, however for
-some scripts (e.g. MSSQL installation), this will fail even if the script can be run locally (e.g. by using RDP to
-connect to the machine and running the script manually)
-
-In the case of MS SQL server installation, there was no clear indication of why this would not work. The only clue was
-a security exception in the installation log
-
-It appears that when a script is run over WinRM over HTTP, the credentials under which the script are run are marked as
-'remote' credentials, which are prohibited from running certain security-related operations. The solution was to obtain
-a new set of credentials within the script and use those credentials to exeute the installer, so this:
-
- ( $driveLetter + "setup.exe") /ConfigurationFile=C:\ConfigurationFile.ini
-
-became this:
-
- $pass = '${attribute['windows.password']}'
- $secpasswd = ConvertTo-SecureString $pass -AsPlainText -Force
- $mycreds = New-Object System.Management.Automation.PSCredential ($($env:COMPUTERNAME + "\Administrator"), $secpasswd)
-
- Invoke-Command -ComputerName localhost -credential $mycreds -scriptblock {
- param($driveLetter)
- Start-Process ( $driveLetter + "setup.exe") -ArgumentList "/ConfigurationFile=C:\ConfigurationFile.ini" -RedirectStandardOutput "C:\sqlout.txt" -RedirectStandardError "C:\sqlerr.txt" -Wait
- } -Authentication CredSSP -argumentlist $driveLetter
-
-The `$pass=` line simply reads the Windows password from the entity before the script is copied to the server. This is
-then encrypted on the next line before being used to create a new credential object. Then, rather than calling the executable
-directly, the `Start-Process` scriptlet is used. This allows us to pass in the newly created credentials, under which
-the process will be run
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/25af0230/docs/guide/yaml/winrm/stdout-and-stderr.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/winrm/stdout-and-stderr.md b/docs/guide/yaml/winrm/stdout-and-stderr.md
deleted file mode 100644
index 5a27c67..0000000
--- a/docs/guide/yaml/winrm/stdout-and-stderr.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-title: Redirecting stdout and stderr
-title_in_menu: Redirecting stdout/stderr
-layout: website-normal
----
-
-## Redirecting stdout and stderr in a PowerShell script
-
-When calling an executable in a PowerShell script, the stdout and stderr will usually be output to the console,
-which is not currently captured by Brooklyn. In order to facilitate debugging, it is usually possible to redirect
-stdout and stderr to a file by using the `Start-Process` scriptlet. So instead of running the following:
-
- D:\setup.exe /ConfigurationFile=C:\ConfigurationFile.ini
-
-You would run the following:
-
- Start-Process D:\setup.exe -ArgumentList "/ConfigurationFile=C:\ConfigurationFile.ini" -RedirectStandardOutput "C:\sqlout.txt" -RedirectStandardError "C:\sqlerr.txt" -PassThru -Wait
-
-The `-ArgumentList` is simply the arguments that are to be passed to the executable, `-RedirectStandardOutput` and
-`RedirectStandardError` take file locations for the output (if the file already exists, it will be overwritten). The
-`-PassThru` argument indicates that PowerShell should write to the file *in addition* to the console, rather than
-*instead* of the console. The `-Wait` argument will cause the scriptlet to block until the process is complete.
-
-Further details can be found on the [Start-Process documentation page](https://technet.microsoft.com/en-us/library/hh849848.aspx)
-on the Microsoft TechNet site.
[2/2] incubator-brooklyn git commit: This closes #907
Posted by al...@apache.org.
This closes #907
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/8c269d5b
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/8c269d5b
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/8c269d5b
Branch: refs/heads/master
Commit: 8c269d5bed1bba3fecd814135c0be7449c6d06fc
Parents: 6aefffd 25af023
Author: Aled Sage <al...@gmail.com>
Authored: Mon Sep 21 17:51:06 2015 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Mon Sep 21 17:51:06 2015 +0100
----------------------------------------------------------------------
docs/guide/yaml/winrm/index.md | 226 +++++++++++++++++++-----
docs/guide/yaml/winrm/re-authentication.md | 36 ----
docs/guide/yaml/winrm/stdout-and-stderr.md | 25 ---
3 files changed, 186 insertions(+), 101 deletions(-)
----------------------------------------------------------------------