brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aleds...@apache.org
Subject [1/2] incubator-brooklyn git commit: Improve winrm docs
Date Mon, 21 Sep 2015 16:51:18 GMT
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 <aled.sage@gmail.com>
Authored: Fri Sep 18 13:02:59 2015 +0100
Committer: Aled Sage <aled.sage@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.


Mime
View raw message