http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/salt/creating-salt-blueprints.md ---------------------------------------------------------------------- diff --git a/guide/yaml/salt/creating-salt-blueprints.md b/guide/yaml/salt/creating-salt-blueprints.md deleted file mode 100644 index f00d687..0000000 --- a/guide/yaml/salt/creating-salt-blueprints.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: Creating Blueprints with Salt -title_in_menu: Creating Blueprints with Salt -layout: website-normal ---- - -To write a blueprint to use Salt with Brooklyn it will help to have a degree of familiarity with Salt itself. In the -sections below, when the Brooklyn configuration is described, the underlying Salt operation is also noted briefly, for -clarity for readers who know Salt. - -To manage a node with Salt, create a blueprint containing a service of type `org.apache.brooklyn.entity.cm.salt.SaltEntity` -and define the `formulas` and `start_states` -For example: - - name: Salt Example setting up Apache httpd - location: my-cloud - services: - - id: httpd-from-salt - type: org.apache.brooklyn.entity.cm.salt.SaltEntity - formulas: - - https://github.com/saltstack-formulas/apache-formula/archive/master.tar.gz - start_states: - - apache - -This example specifies that Brooklyn should use Salt to download the `apache-formula` from the Saltstack repository on -Github. The apache formula contains the Apache web server with a simple "it worked" style index page. To start the -entity, Brooklyn will use Salt to apply the `apache` state, which will bring up the web server. - -A typical usage of the Salt entity might be to include a formula from the Saltstack repository, such as `apache` above, -and another formula created by the blueprint author, with additional states, such as web site content for the apache -server. - -### Start States - -The `start_states` configuration key defines the top level list of states that will be applied using Salt. These values -are added to the Salt `top.sls` file and applied using `state.apply`. This configuration key is mandatory. - -### Stop States - -The `stop_states` configuration key is used to specify states that should be applied when the 'stop' effector -is invoked on the entity. For example, the Saltstack `mysql` [formula](https://github.com/saltstack-formulas/mysql-formula) -supplies a state `mysql.disabled` that will shut down the database server. - -If the Saltstack formula does not supply a suitable stop state, the blueprint author can create a suitable state and -include it in an additional formula to be supplied in the `formulas` section. - -The `stop_states` configuration key is optional; -if it is not provided, Brooklyn assumes that each state `S` in the `start_states` will have a matching `S.stop` state. -If any `S` does not have such a state, the stop effector will fail stopping processes. -Note that on a machine created for this entity, Brooklyn's default behaviour may be to proceed to destroy the VM, -so stop states are not always needed unless there is a cleaner shutdown process or you are using long-running servers. - - -### Restart States - -For completeness, Brooklyn also provides a `restart_states` configuration key. These states are applied by the restart -effector, and blueprint authors may choose to provide custom states to implement restart if that is applicable for their -application. - -This key is again optional. -If not supplied, Brooklyn will go through each of the states `S` in `start_states` -looking for a matching `S.restart` state defined in the formulas. -If all exist, these will be applied by the restart effector. -If none exist, Brooklyn will invoke the `stop` and then `start` effectors -- -so `restart` states are not required for Brooklyn to use Salt. -(If some but not all have matching `restart` states, -Brooklyn will fail the restart, on the assumption that the configuration is incomplete.) - -### Formulas - -The `formulas` key provides the URLs for archives containing the Salt formulas that defined the required states. These -archives are downloaded to the `/srv/formula` directory on the minion and added to the state filesystem roots -configuration in Salt's minion config, so that their states are available for a `state.apply`. - -### Pillar Configuration - -A typical Salt deployment will include both states (provided via Salt formulas) and configuration data, provided through -Salt's "Pillar" component. Brooklyn provides configuration keys for the Salt entity to specify where to get the Pillar -configuration data. For example: - - name: Salt Example setting up MySQL with a Pillar - location: my-cloud - services: - - id: mysql-from-salt-with-my-pillar - type: org.apache.brooklyn.entity.cm.salt.SaltEntity - - formulas: - - https://github.com/saltstack-formulas/mysql-formula/archive/master.tar.gz - - http://myhost:8080/my-mysql-formula.tar.gz - - start_states: - - mysql - stop_states: - - mysql.disabled - - pillars: - - mysql - pillarUrls: - - http://myhost:8080/my-mysql-pillar.tar.gz - - -This blueprint contains the MySQL database, and includes a formula available from `myhost` which includes the schema -information for the DB. The MySQL formula from Saltstack has extensive configurability through Salt Pillars. In the -blueprint above, Brooklyn is instructed to apply the pillars defined in the `pillars` configuration key. (This will -add these values to the Salt Pillars `top.sls` file.) The pillar data must be downloaded; for this, the `pillarUrls` key -provides the address of an archive containing the Pillar data. The contents of the archive will be extracted and put -in the `/srv/pillar` directory on the minion, in order to be available to Salt when applying the pillar. For example, -the archive above can simply have the structure - - pillar/ - | - +- mysql/ - | - +- init.sls - -The init.sls contains the pillar configuration values, such as - - # Manage databases - database: - - orders - schema: - orders: - load: True - source: salt://mysql/files/orders.schema - -Meanwhile the `my-mysql-formula.tar.gz` formula archive contains the schema: - - my-mysql-formula/ - | - +- mysql/ - | - +- files/ - | - +- orders.schema - -Note that the blueprint above defines an `id` for the Salt entity. This id, if provided, is set as the minion id in -the Salt configuration file. This is useful particularly for Pillar configuration, as, if there are more than one -Salt managed nodes in the application, they can share a common Pillar file, with appropriate subdivisions of pillar -data based on minion id. - -### Highstate Sensors - -The Salt entity exposes the Salt "highstate" on the node via Brooklyn sensors. Firstly a single sensor `salt.states` -contains a list of all the top level Salt state ID declarations in the highstate. For example, for the mysql case -above, this might look like: - - ["mysql_additional_config", "mysql_config", "mysql_db_0", "mysql_db_0_load", "mysql_db_0_schema", "mysql_debconf", - "mysql_debconf_utils", "mysql_python", "mysql_user_frank_localhost", "mysql_user_frank_localhost_0", - "mysql_user_nopassuser_localhost", "mysqld"] - -Then, for each ID and each Salt state function in that ID, a Brooklyn sensor is created, containing a map of the data -from the highstate. For example, the `salt.state.mysqld.service.running` sensor would have a value like: - - {"name":"mysql", "enable":true, "watch":[{"pkg":"mysqld"}, {"file":"mysql_config"}], "order":10005} - - -### saltCall Effector - -The Salt entity includes a general purpose Salt effector, `saltCall`, which permits execution of Salt commands via -`salt-call --local`. It contains a single parameter, `spec`, which specifies the command to invoke. For example, -invoking the effector with a `spec` value of `network.interfaces --out=yaml` would return a YAML formatted map of the -network interfaces on the minion. -
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/salt/index.md ---------------------------------------------------------------------- diff --git a/guide/yaml/salt/index.md b/guide/yaml/salt/index.md deleted file mode 100644 index 265e07f..0000000 --- a/guide/yaml/salt/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Salt in YAML Blueprints -layout: website-normal -children: -- about-salt.md -- creating-salt-blueprints.md ---- - -This guide describes how Brooklyn entities can be created using the Salt infrastructure management tool - ([saltstack.com](https://saltstack.com/)). -At present Brooklyn provides basic support for Salt, operating in a 'masterless' mode. -Comments on this support and suggestions for further development are welcome. - -This guide assumes you are familiar with the basics of [creating YAML blueprints](../). - -{% include list-children.html %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/setting-locations.md ---------------------------------------------------------------------- diff --git a/guide/yaml/setting-locations.md b/guide/yaml/setting-locations.md deleted file mode 100644 index 906a194..0000000 --- a/guide/yaml/setting-locations.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Setting Locations -layout: website-normal -toc: ../guide_toc.json -categories: [use, guide, defining-applications] ---- - -{% include fields.md %} - -Brooklyn supports a very wide range of target locations. -With deep integration to [Apache jclouds](https://jclouds.apache.org), most well-known clouds -and cloud platforms are supported. See the [Locations guide]({{ site.path.guide }}/ops/locations/) -for details and more examples. - -### Cloud Example - -The following example is for Amazon EC2: - -{% highlight yaml %} -{% readj example_yaml/simple-appserver-with-location.yaml %} -{% endhighlight %} - -(You'll need to replace the `identity` and `credential` with the -"Access Key ID" and "Secret Access Key" for your account, -as configured in the [AWS Console](https://console.aws.amazon.com/iam/home?#security_credential).) - -Other popular public clouds include `softlayer`, `google-compute-engine`, and `rackspace-cloudservers-us`. -Private cloud systems including `openstack-nova` and `cloudstack` are also supported, -although for these you'll supply an `endpoint: https://9.9.9.9:9999/v2.0/` -(or `client/api/` in the case of CloudStack) instead of the `region`. - - -### "Bring Your Own Nodes" (BYON) Example - -You can also specify pre-existing servers to use -- "bring-your-own-nodes". -The example below shows a pool of machines that will be used by the entities within the -application. - -{% highlight yaml %} -{% readj example_yaml/simple-appserver-with-location-byon.yaml %} -{% endhighlight %} - - -### Single Line and Multi Line Locations - -A simple location can be specified on a single line. Alternatively, it can be split to have one -configuration option per line (recommended for all but the simplest locations). - -For example, the two examples below are equivalent: - -{% highlight yaml %} -location: byon(name="my loc",hosts="1.2.3.4",user="bob",privateKeyFile="~/.ssh/bob_id_rsa") -{% endhighlight %} - -{% highlight yaml %} -location: - byon: - name: "my loc" - hosts: - - "1.2.3.4" - user: "bob" - privateKeyFile: "~/.ssh/bob_id_rsa" -{% endhighlight %} - - -### Specific Locations for Specific Entities - -One can define specific locations on specific entities within the blueprint (instead of, or as -well as, defining the location at the top-level of the blueprint). - -The example below will deploy Tomcat and JBoss App Server to different Bring Your Own Nodes -locations: - -{% highlight yaml %} -{% readj example_yaml/simple-appserver-with-location-per-entity.yaml %} -{% endhighlight %} - -The rules for precedence when defining a location for an entity are: - -* The location defined on that specific entity. -* If no location is defined, then the first ancestor that defines an explicit location. -* If still no location is defined, then the location defined at the top-level of the blueprint. - -This means, for example, that if you define an explicit location on a cluster then it will be used -for all members of that cluster. - - -### Multiple Locations - -Some entities are written to expect a set of locations. For example, a `DynamicFabric` will -create a member entity in each location that it is given. To supply multiple locations, simply -use `locations` with a yaml list. - -In the example below, it will create a cluster of app-servers in each location. One location is -used for each `DynamicCluster`; all app-servers inside that cluster will obtain a machine from -that given location. - -{% highlight yaml %} -{% readj example_yaml/fabric-with-multiple-locations.yaml %} -{% endhighlight %} - -The entity hierarchy at runtime will have a `DynamicFabric` with two children, each of type -`DynamicCluster` (each running in different locations), each of which initially has three -app-servers. - -For brevity, this example excludes the credentials for aws-ec2. These could either be specificed -in-line or defined as named locations in the catalog (see below). - - -### Adding Locations to the Catalog - -The examples above have given all the location details within the application blueprint. -It is also possible (and indeed preferred) to add the location definitions to the catalog -so that they can be referenced by name in any blueprint. - -For more information see the [Operations: Catalog]({{ site.path.guide }}/ops/catalog/) section of -the User Guide. - - -### Externalized Configuration - -For simplicity, the examples above have included the cloud credentials. For a production system, -it is strongly recommended to use [Externalized Configuration]({{ site.path.guide }}/ops/externalized-configuration.html) -to retrieve the credentials from a secure credentials store, such as [Vault](https://www.vaultproject.io). - - -### Use of provisioning.properties - -An entity that represents a "software process" can use the configuration option -`provisioning.properties` to augment the location's configuration. For more information, see -[Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#entity-provisioningproperties-overriding-and-merging) -details. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/entities/infrastructuredeploymenttestcase-entity.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/entities/infrastructuredeploymenttestcase-entity.yaml b/guide/yaml/test/example_yaml/entities/infrastructuredeploymenttestcase-entity.yaml deleted file mode 100644 index 6b344da..0000000 --- a/guide/yaml/test/example_yaml/entities/infrastructuredeploymenttestcase-entity.yaml +++ /dev/null @@ -1,11 +0,0 @@ -- type: org.apache.brooklyn.test.framework.InfrastructureDeploymentTestCase - brooklyn.config: - infrastructure.deployment.location.sensor: entity.dynamicLocation - infrastructure.deployment.spec: - $brooklyn:entitySpec: - - type: docker-cloud-calico - ... - infrastructure.deployment.entity.specs: - - $brooklyn:entitySpec: - type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess - ... \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/entities/loopovergroupmembers-entity.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/entities/loopovergroupmembers-entity.yaml b/guide/yaml/test/example_yaml/entities/loopovergroupmembers-entity.yaml deleted file mode 100644 index 713ffbc..0000000 --- a/guide/yaml/test/example_yaml/entities/loopovergroupmembers-entity.yaml +++ /dev/null @@ -1,6 +0,0 @@ -- type: org.apache.brooklyn.test.framework.LoopOverGroupMembersTestCase - target: $brooklyn:entity("infrastructure").component("child", "DockerHosts") - testSpec: - $brooklyn:entitySpec: - type: org.apache.brooklyn.test.framework.TestSensor - ... \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/entities/paralleltestcase-entity.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/entities/paralleltestcase-entity.yaml b/guide/yaml/test/example_yaml/entities/paralleltestcase-entity.yaml deleted file mode 100644 index ccd0c0b..0000000 --- a/guide/yaml/test/example_yaml/entities/paralleltestcase-entity.yaml +++ /dev/null @@ -1,6 +0,0 @@ -- type: org.apache.brooklyn.test.framework.ParallelTestCase - brooklyn.children: - - type: org.apache.brooklyn.entity.database.mysql.MySqlNode - ... - - type: org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster - ... \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/entities/script1.sh ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/entities/script1.sh b/guide/yaml/test/example_yaml/entities/script1.sh deleted file mode 100644 index 2a98304..0000000 --- a/guide/yaml/test/example_yaml/entities/script1.sh +++ /dev/null @@ -1,2 +0,0 @@ -#!/bin/sh -echo hello world \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/entities/testcase-entity.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/entities/testcase-entity.yaml b/guide/yaml/test/example_yaml/entities/testcase-entity.yaml deleted file mode 100644 index 0e1aa00..0000000 --- a/guide/yaml/test/example_yaml/entities/testcase-entity.yaml +++ /dev/null @@ -1,6 +0,0 @@ -- type: org.apache.brooklyn.test.framework.TestCase - brooklyn.children: - - type: org.apache.brooklyn.entity.database.mysql.MySqlNode - ... - - type: org.apache.brooklyn.test.framework.TestSensor - ... \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/entities/testeffector-entity.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/entities/testeffector-entity.yaml b/guide/yaml/test/example_yaml/entities/testeffector-entity.yaml deleted file mode 100644 index e9d570e..0000000 --- a/guide/yaml/test/example_yaml/entities/testeffector-entity.yaml +++ /dev/null @@ -1,8 +0,0 @@ -- type: org.apache.brooklyn.test.framework.TestEffector - name: Invoke Deploy Effector - target: $brooklyn:entity("tomcat") - effector: deploy - timeout: 5m - params: - url: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war - targetName: newcontext \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/entities/testhttpcall-entity.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/entities/testhttpcall-entity.yaml b/guide/yaml/test/example_yaml/entities/testhttpcall-entity.yaml deleted file mode 100644 index e719b82..0000000 --- a/guide/yaml/test/example_yaml/entities/testhttpcall-entity.yaml +++ /dev/null @@ -1,7 +0,0 @@ -- type: org.apache.brooklyn.test.framework.TestHttpCall - name: Check HTTP Response Status Code - url: $brooklyn:entity("tomcat").attributeWhenReady("webapp.url") - timeout: 60s - applyAssertionTo: status - assert: - - isEqualTo: 200 \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/entities/testsensor-entity.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/entities/testsensor-entity.yaml b/guide/yaml/test/example_yaml/entities/testsensor-entity.yaml deleted file mode 100644 index 91f55a5..0000000 --- a/guide/yaml/test/example_yaml/entities/testsensor-entity.yaml +++ /dev/null @@ -1,7 +0,0 @@ -- type: org.apache.brooklyn.test.framework.TestSensor - name: Check tomcat isUp - target: $brooklyn:entity("tomcat") - sensor: service.isUp - timeout: 10m - assert: - - equals: true \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/entities/testsshcommand-entity.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/entities/testsshcommand-entity.yaml b/guide/yaml/test/example_yaml/entities/testsshcommand-entity.yaml deleted file mode 100644 index 6bbffc0..0000000 --- a/guide/yaml/test/example_yaml/entities/testsshcommand-entity.yaml +++ /dev/null @@ -1,28 +0,0 @@ -services: -- type: org.apache.brooklyn.test.framework.TestCase - name: testcase1 - brooklyn.children: - - type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer - id: testprocess - - - type: org.apache.brooklyn.test.framework.TestSshCommand - name: Check tomcat process running with ps - targetId: testprocess - command: ps -ef - assertStatus: - equals: 0 - assertOut: - contains: tomcat - assertErr: - isEmpty: true - - - type: org.apache.brooklyn.test.framework.TestSshCommand - name: Check hello world script - targetId: testprocess - downloadUrl: https://github.com/apache/brooklyn-docs/raw/master/guide/yaml/test/example_yaml/entities/script1.sh - assertStatus: - equals: 0 - assertOut: - equals: hello world - assertErr: - isEmpty: true http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/testcases/effector-test-snippet.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/testcases/effector-test-snippet.yaml b/guide/yaml/test/example_yaml/testcases/effector-test-snippet.yaml deleted file mode 100644 index 2e01ba5..0000000 --- a/guide/yaml/test/example_yaml/testcases/effector-test-snippet.yaml +++ /dev/null @@ -1,28 +0,0 @@ -- type: org.apache.brooklyn.test.framework.TestCase - name: Check Deploy Effector - brooklyn.children: - - type: org.apache.brooklyn.test.framework.TestSensor - name: Check webappcluster isUp - targetId: webappcluster - sensor: service.isUp - timeout: 10m - assert: - - equals: true - - type: org.apache.brooklyn.test.framework.TestEffector - name: Invoke Deploy Effector - targetId: webappcluster - effector: deploy - timeout: 5m - params: - url: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war - targetName: newcontext - - type: org.apache.brooklyn.test.framework.TestHttpCall - name: Check Deployed Webapp Status Code - timeout: 5m - url: > - $brooklyn:formatString("http://%s:%s/newcontext/";, - $brooklyn:entity("webappcluster").attributeWhenReady("host.address"), - $brooklyn:entity("webappcluster").attributeWhenReady("proxy.http.port")) - applyAssertionTo: status - assert: - - isEqualTo: 200 \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/testcases/getting-started-test-example.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/testcases/getting-started-test-example.yaml b/guide/yaml/test/example_yaml/testcases/getting-started-test-example.yaml deleted file mode 100644 index d6740ec..0000000 --- a/guide/yaml/test/example_yaml/testcases/getting-started-test-example.yaml +++ /dev/null @@ -1,71 +0,0 @@ -name: Getting Started Blueprint Test - -location: - jclouds:aws-ec2: - identity: ABCDEFGHIJKLMNOPQRST - credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l - -services: -- type: org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster - name: My Web - id: webappcluster - brooklyn.config: - wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war - java.sysprops: - brooklyn.example.db.url: > - $brooklyn:formatString("jdbc:%s%s?user=%s&password=%s", - entity("db").attributeWhenReady("datastore.url"), - "visitors", "brooklyn", "br00k11n") -- type: org.apache.brooklyn.entity.database.mysql.MySqlNode - id: db - name: My DB - brooklyn.config: - creationScriptUrl: https://bit.ly/brooklyn-visitors-creation-script -- type: org.apache.brooklyn.test.framework.TestHttpCall - name: Check HTTP Response Status Code - url: > - $brooklyn:formatString("http://%s:%s";, - $brooklyn:entity("webappcluster").attributeWhenReady("host.address"), - $brooklyn:entity("webappcluster").attributeWhenReady("proxy.http.port")) - timeout: 10m - applyAssertionTo: status - assert: - - isEqualTo: 200 -- type: org.apache.brooklyn.test.framework.TestHttpCall - name: Check HTTP Response Body - url: > - $brooklyn:formatString("http://%s:%s";, - $brooklyn:entity("webappcluster").attributeWhenReady("host.address"), - $brooklyn:entity("webappcluster").attributeWhenReady("proxy.http.port")) - timeout: 10m - applyAssertionTo: body - assert: - - matches: "(?s).*Br[o]{2}klyn Deployed.*" -- type: org.apache.brooklyn.test.framework.TestCase - name: Check Deploy Effector - brooklyn.children: - - type: org.apache.brooklyn.test.framework.TestSensor - name: Check webappcluster isUp - targetId: webappcluster - sensor: service.isUp - timeout: 10m - assert: - - equals: true - - type: org.apache.brooklyn.test.framework.TestEffector - name: Invoke Deploy Effector - targetId: webappcluster - effector: deploy - timeout: 5m - params: - url: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war - targetName: newcontext - - type: org.apache.brooklyn.test.framework.TestHttpCall - name: Check Deployed Webapp Status Code - timeout: 5m - url: > - $brooklyn:formatString("http://%s:%s/newcontext/";, - $brooklyn:entity("webappcluster").attributeWhenReady("host.address"), - $brooklyn:entity("webappcluster").attributeWhenReady("proxy.http.port")) - applyAssertionTo: status - assert: - - isEqualTo: 200 \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/testcases/http-test-snippet.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/testcases/http-test-snippet.yaml b/guide/yaml/test/example_yaml/testcases/http-test-snippet.yaml deleted file mode 100644 index 0a7a953..0000000 --- a/guide/yaml/test/example_yaml/testcases/http-test-snippet.yaml +++ /dev/null @@ -1,20 +0,0 @@ -- type: org.apache.brooklyn.test.framework.TestHttpCall - name: Check HTTP Response Status Code - url: > - $brooklyn:formatString("http://%s:%s/newcontext/";, - $brooklyn:component("webappcluster").attributeWhenReady("host.address"), - $brooklyn:component("webappcluster").attributeWhenReady("proxy.http.port")) - timeout: 10m - applyAssertionTo: status - assert: - - equals: 200 -- type: org.apache.brooklyn.test.framework.TestHttpCall - name: Check HTTP Response Body - url: > - $brooklyn:formatString("http://%s:%s/newcontext/";, - $brooklyn:component("webappcluster").attributeWhenReady("host.address"), - $brooklyn:component("webappcluster").attributeWhenReady("proxy.http.port")) - timeout: 10m - applyAssertionTo: body - assert: - - matches: "(?s).*Br[o]{2}klyn Deployed.*" \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/example_yaml/testcases/sensor-test-snippet.yaml ---------------------------------------------------------------------- diff --git a/guide/yaml/test/example_yaml/testcases/sensor-test-snippet.yaml b/guide/yaml/test/example_yaml/testcases/sensor-test-snippet.yaml deleted file mode 100644 index da58cd1..0000000 --- a/guide/yaml/test/example_yaml/testcases/sensor-test-snippet.yaml +++ /dev/null @@ -1,7 +0,0 @@ -- type: org.apache.brooklyn.test.framework.TestSensor - name: Check webappcluster isUp - targetId: webappcluster - sensor: service.isUp - timeout: 10m - assert: - - equals: true \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/images/getting-started-blueprint-test-large.png ---------------------------------------------------------------------- diff --git a/guide/yaml/test/images/getting-started-blueprint-test-large.png b/guide/yaml/test/images/getting-started-blueprint-test-large.png deleted file mode 100644 index 655e4f0..0000000 Binary files a/guide/yaml/test/images/getting-started-blueprint-test-large.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/images/getting-started-blueprint-test.png ---------------------------------------------------------------------- diff --git a/guide/yaml/test/images/getting-started-blueprint-test.png b/guide/yaml/test/images/getting-started-blueprint-test.png deleted file mode 100644 index 09d23e8..0000000 Binary files a/guide/yaml/test/images/getting-started-blueprint-test.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/index.md ---------------------------------------------------------------------- diff --git a/guide/yaml/test/index.md b/guide/yaml/test/index.md deleted file mode 100644 index 8b10f01..0000000 --- a/guide/yaml/test/index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testing YAML Blueprints -layout: website-normal -children: -- test-entities.md -- usage-examples.md ---- - -Brooklyn provides a selection of test entities which can be used to validate Blueprints via YAML. The basic building block is a TargetableTestComponent, which is used to resolve a target. There are two different groups of entities that inherit from TargetableTestComponent. The first is structural, which effects how the tests are run, for example by affecting the order they are run in. The second group is validation, which is used to confirm the application is deployed as intended, for example by checking some sensor value. - -Structural test entities include: - -- `TestCase` - starts child entities sequentially. -- `ParallelTestCase` - starts child entities in parallel. -- `LoopOverGroupMembersTestCase` - creates a TargetableTestComponent for each member of a group. -- `InfrastructureDeploymentTestCase` - will create the specified Infrastructure and then deploy the target entity specifications there. - -Validation test entities include: - -- `TestSensor` - perform assertion on a specified sensor. -- `TestEffector` - perform assertion on response to effector call. -- `TestHttpCall` - perform assertion on response to specified HTTP GET Request. -- `TestSshCommand` - test assertions on the result of an ssh command on the same machine as the target entity. -- `TestWinrmCommand` - test assertions on the result of a WinRM command on the same machine as the target entity. -- `TestEndpointReachable` - assert that a TCP endpoint is reachable. The endpoint can be in a - number of different formats: a string in the form of `ip:port` or URI format; or a - `com.google.common.net.HostAndPort` instance; or a `java.net.URI` instance; or a `java.net.URL` instance. - -TargetableTestComponents can be chained together, with the target being inherited by the components children. For example, a ParallelTestCase could be created that has a TestHttpCall as a child. As long as the TestHttpCall itself does not have a target, it will use the target of it's parent, ParallelTestCase. Using this technique, we can build up complex test scenarios. - -The following sections provide details on each test entity along with examples of their use. - -{% include list-children.html %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/test-entities.md ---------------------------------------------------------------------- diff --git a/guide/yaml/test/test-entities.md b/guide/yaml/test/test-entities.md deleted file mode 100644 index 37604a1..0000000 --- a/guide/yaml/test/test-entities.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: Blueprint Test Entities -title_in_menu: Test Entities -layout: website-normal ---- - -{% include fields.md %} - - -## Structural Test Entities - -### TestCase -The `TestCase` entity acts as a container for a list of child entities which are started *sequentially*. - -{% highlight yaml %} -{% readj example_yaml/entities/testcase-entity.yaml %} -{% endhighlight %} - -This can be used to enforce a strict ordering, for example ensuring a sensor has a certain value before attempting to invoke an effector. - -Timeouts on child entities should be set relative to the completion of the preceding entity. - -The `ParallelTestCase` entity can be added as a child to run a subset of entities in parallel as a single step. - - -### ParallelTestCase -The `ParallelTestCase` entity acts as a container for a list of child entities which are started in *parallel*. - -{% highlight yaml %} -{% readj example_yaml/entities/paralleltestcase-entity.yaml %} -{% endhighlight %} - -This can be used to run a subset of entities in parallel as a single step when nested under a `TestCase` entity. - -Timeouts on child entities should be set relative to the start of the `ParallelTestCase`. - - -### LoopOverGroupMembersTestCase -The `LoopOverGroupMembersTestCase` entity is configured with a target group and a test specification. For each member of the targeted group, the test case will create a TargetableTestComponent entity from the supplied test specification and set the components target to be the group member. - -{% highlight yaml %} -{% readj example_yaml/entities/loopovergroupmembers-entity.yaml %} -{% endhighlight %} - -#### Parameters -- `target` - group who's members are to be tested, specified via DSL. For example, `$brooklyn:entity("tomcat")`. See also the `targetId` parameter. -- `targetId` - alternative to the `target` parameter which wraps the DSL component lookup requiring only the `id` be supplied. For example, `tomcat`. Please note, this must point to a group. -- `test.spec` - The TargetableTestComponent to create for each child. - - -### InfrastructureDeploymentTestCase -The `InfrastructureDeploymentTestCase` will first create and deploy an infrastructure from the `infrastructure.deployment.spec` config. It will then retrieve a deployment location by getting the value of the infrastructures `infrastructure.deployment.location.sensor` sensor. It will then create and deploy all entities from the `infrastructure.deployment.spec` config to the deployment location. - -{% highlight yaml %} -{% readj example_yaml/entities/infrastructuredeploymenttestcase-entity.yaml %} -{% endhighlight %} - -#### Parameters - -- `infrastructure.deployment.spec` - the infrastructure to be deployed. -- `infrastructure.deployment.entity.specs` - the entities to be deployed to the infrastructure -- `infrastructure.deployment.location.sensor` - the name of the sensor on the infrastructure to retrieve the deployment location - - -## Validation Test Entities - -### TestSensor -The `TestSensor` entity performs an assertion on a specified sensors value. - -{% highlight yaml %} -{% readj example_yaml/entities/testsensor-entity.yaml %} -{% endhighlight %} - -#### Parameters -- `target` - entity whose sensor will be tested, specified via DSL. For example, `$brooklyn:entity("tomcat")`. See also the `targetId` parameter. -- `targetId` - alternative to the `target` parameter which wraps the DSL component lookup requiring only the `id` be supplied. For example, `tomcat`. -- `sensor` - sensor to evaluate. For example `service.isUp`. -- `timeout` - duration to wait on assertion to return a result. For example `10s`, `10m`, etc -- `assert` - assertion to perform on the specified sensor value. See section on assertions below. - -<div class="alert alert-info"> - <strong>Tip:</strong> If the <code>TestSensor</code> is wrapped within a <code>TestCase</code>, - <code>ParallelTestCase</code> or <code>LoopOverGroupMembersTestCase</code> that set the target, - <strong>you don't need to specify the target</strong>, unless you want to test a different entity. -</div> - - -### TestEffector -The `TestEffector` entity invokes the specified effector on a target entity. If the result of the effector is a String, it will then perform assertions on the result. -{% highlight yaml %} -{% readj example_yaml/entities/testeffector-entity.yaml %} -{% endhighlight %} - -#### Parameters -- `target` - entity whose effector will be invoked, specified via DSL. For example, `$brooklyn:entity("tomcat")`. See also the `targetId` parameter. -- `targetId` - alternative to the `target` parameter which wraps the DSL component lookup requiring only the `id` be supplied. For example, `tomcat`. -- `timeout` - duration to wait on the effector task to complete. For example `10s`, `10m`, etc -- `effector` - effector to invoke, for example `deploy`. -- `params` - parameters to pass to the effector, these will depend on the entity and effector being tested. The example above shows the `url` and `targetName` parameters being passed to Tomcats `deploy` effector. -- `assert` - assertion to perform on the returned result. See section on assertions below. - -<div class="alert alert-info"> - <strong>Tip:</strong> If the <code>TestEffector</code> is wrapped within a <code>TestCase</code>, - <code>ParallelTestCase</code> or <code>LoopOverGroupMembersTestCase</code> that set the target, - <strong>you don't need to specify the target</strong>, unless you want to test a different entity. -</div> - - -### TestHttpCall -The `TestHttpCall` entity performs a HTTP GET on the specified URL and performs an assertion on the response. -{% highlight yaml %} -{% readj example_yaml/entities/testhttpcall-entity.yaml %} -{% endhighlight %} - -#### Parameters -- `url` - URL to perform GET request on, this can use DSL for example `$brooklyn:entity("tomcat").attributeWhenReady("webapp.url")`. -- `timeout` - duration to wait on a HTTP response. For example `10s`, `10m`, etc -- `applyAssertionTo` - The filed to apply the assertion to. For example `status`, `body` -- `assert` - assertion to perform on the response. See section on assertions below. - -<div class="alert alert-info"> - <strong>Tip:</strong> If the <code>TestHttpCall</code> is wrapped within a <code>TestCase</code>, - <code>ParallelTestCase</code> or <code>LoopOverGroupMembersTestCase</code> that set the target, - <strong>you don't need to specify the target</strong>, unless you want to test a different entity. -</div> - - -### TestSshCommand -The TestSshCommand runs a command on the host of the target entity. -The script is expected not to run indefinitely, but to return a result (process exit code), along with its -standard out and error streams, which can then be tested using assertions. -If no assertions are explicitly configured, the default is to assert a non-zero exit code. - -Either a bash command may be provided in the YAML, or a URL for a script which will be executed. - -{% highlight yaml %} -{% readj example_yaml/entities/testsshcommand-entity.yaml %} -{% endhighlight %} - -#### Parameters -- `command` - The shell command to execute. (This and `downloadUrl` are mutually exclusive.) -- `downloadUrl` - URL for a script to download and execute. (This and `command` are mutually exclusive.) -- `shell.env` - Map of environment variables to be set. -- `scriptDir` - if `downloadUrl` is used. The directory on the target host where downloaded scripts should be copied to. -- `runDir` - the working directory where the command or script will be executed on the target host. -- `assertStatus` - Assertions on the exit code of the command or script. See section on assertions below. -- `assertOut` - Assertions on the standard output of the command as a String. -- `assertErr` - Assertions on the standard error of the command as a String. - -<div class="alert alert-info"> - <strong>Tip:</strong> If the <code>TestSshCommand</code> is wrapped within a <code>TestCase</code>, - <code>ParallelTestCase</code> or <code>LoopOverGroupMembersTestCase</code> that set the target, - <strong>you don't need to specify the target</strong>, unless you want to test a different entity. -</div> - - -## Assertions - -The following conditions are provided by those test entities above that include assertions - -- `isNull` - asserts that the actual value is `null`. -- `notNull` - asserts that the actual value is NOT `null`. -- `isEqualTo` - asserts that the actual value equals an expected value. -- `equalTo` - a synonym for `isEqualTo` -- `equals` - a synonym for `isEqualTo` -- `notEqual` - asserts that the actual value does not equal the expected value. -- `matches` - asserts that the actual value matches a [regex pattern](http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html?is-external=true), for example `".*hello.*"`. - Note that regular expressions follow the Java defaults, e.g. for [line terminators](http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#lt). - One can use `"(?m)"` for multi-line mode (so that `^` and `$` also match just after/before line terminators, - rather than just the start/end of the entire input sequence). The dotall mode, set with `"(?s)"`, can also - be useful (so that `.` matches any character, including line terminators). -- `containsMatch` - asserts that the value contains a string that matches a regex. It follow the behaviour of - the [Matcher.find() method](http://docs.oracle.com/javase/7/docs/api/java/util/regex/Matcher.html#find()). - This can be useful for simplifying matching in multi-line input. -- `contains` - asserts that the actual value contains the supplied value -- `isEmpty` - asserts that the actual value is an empty string -- `notEmpty` - asserts that the actual value is a non empty string -- `hasTruthValue` - asserts that the actual value has the expected interpretation as a boolean -- `greaterThan` - asserts that the actual value is greater than the expected value according to Java's - [Comparable](https://docs.oracle.com/javase/8/docs/api/java/lang/Comparable.html) interface. Actual and - expected must be instances of the same type and implement `Comparable`. -- `lessThan` - asserts that the actual value is less than the expected value according to Java's - [Comparable](https://docs.oracle.com/javase/8/docs/api/java/lang/Comparable.html) interface. Actual and - expected must be instances of the same type and implement `Comparable`. - -Assertions may be provided as a simple map: - - assert: - contains: 2 users - matches: .*[\d]* days.* - - -If there is the need to make multiple assertions with the same key, the assertions can be specified -as a list of such maps: - - assert: - - contains: 2 users - - contains: 2 days http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/test/usage-examples.md ---------------------------------------------------------------------- diff --git a/guide/yaml/test/usage-examples.md b/guide/yaml/test/usage-examples.md deleted file mode 100644 index 08d88e3..0000000 --- a/guide/yaml/test/usage-examples.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Example Blueprint Tests -title_in_menu: Example Tests -layout: website-normal ---- - -{% include fields.md %} - -## Introduction -This section describes some simple tests based on the [Getting Started]({{ site.path.guide }}/start/blueprints.html#launching-from-a-blueprint) example blueprint: - -{% highlight yaml %} -{% readj /guide/start/_my-web-cluster.yaml %} -{% endhighlight %} - -The following sections contain yaml snippets that be appended to the list of services in the blueprint above, a complete blueprint is also provided [below](#full-example). - -Note that unless otherwise specified the following tests are executed in parallel with the deployment of the application services, all `timeout` values are set accordingly. - -### Sensor Test - -Demonstrates the following sensor assertion: - -- asserts that the `webappcluster` entity `service.isUp` sensor is `true` within 10 minutes of blueprint being deployed. - -{% highlight yaml %} -{% read example_yaml/testcases/sensor-test-snippet.yaml %} -{% endhighlight %} - -### HTTP Call Tests -Demonstrates the following HTTP Call assertions against the specified `url`, which in these examples are being built from the `webappcluster` entities `host.address` and `proxy.http.port` sensors (the tester having flexibility in how the test URL is to be constructed): - -- asserts the response status code is 200 within 10 minutes of the blueprint being deployed. -- asserts the response body matches the regex `(?s).*Br[o]{2}klyn Deployed.*` within 10 minutes of the blueprint being deployed. Note the presence of the `(?s)` dotall flag to test a multiline response. - -{% highlight yaml %} -{% readj example_yaml/testcases/http-test-snippet.yaml %} -{% endhighlight %} - -### Effector Test (via TestCase entity) - -This `TestEffector` example demonstrates the use of the `TestCase` and `TestSensor` entities to ensure the service has started before invoking an effector using the `TestEffector` entity. - -- `TestCase` entity starts its children sequentially - - asserts that the `webappcluster` entity `service.isUp` sensor is `true` within 10 minutes of the parent `TestCase` entity starting. Blocks start of the next child until it obtains a result (or times out). - - `deploy` effector invoked to deploy war to a `newcontext` with a 5 minute timeout to allow completion of the deploy task. - - asserts `/newcontext` url returns a HTTP status code 200 within 5 minutes of the effector being invoked (Note that this timeout is relative to the preceding test entity as they are being sequentially run as children of a `TestCase` entity). - -{% highlight yaml %} -{% readj example_yaml/testcases/effector-test-snippet.yaml %} -{% endhighlight %} - -### Full Example -A sample blueprint containing all the tests described above is available [here](./example_yaml/testcases/getting-started-test-example.yaml). - -This blueprint will deploy the [Getting Started]({{ site.path.guide }}/start/blueprints.html#launching-from-a-blueprint) application and run all of the test entities, which if successful should appear in the web console as follows. - -[](images/getting-started-blueprint-test-large.png) http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/web-console-yaml-700.png ---------------------------------------------------------------------- diff --git a/guide/yaml/web-console-yaml-700.png b/guide/yaml/web-console-yaml-700.png deleted file mode 100644 index d6a2249..0000000 Binary files a/guide/yaml/web-console-yaml-700.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/web-console-yaml.png ---------------------------------------------------------------------- diff --git a/guide/yaml/web-console-yaml.png b/guide/yaml/web-console-yaml.png deleted file mode 100644 index 3d65a99..0000000 Binary files a/guide/yaml/web-console-yaml.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/winrm/client.md ---------------------------------------------------------------------- diff --git a/guide/yaml/winrm/client.md b/guide/yaml/winrm/client.md deleted file mode 100644 index e02c092..0000000 --- a/guide/yaml/winrm/client.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Winrm4j Client -layout: website-normal ---- - -## Winrm4j parameters - -Check [org.apache.brooklyn.location.winrm.WinRmMachineLocation](https://github.com/apache/brooklyn-server/blob/master/software/winrm/src/main/java/org/apache/brooklyn/location/winrm/WinRmMachineLocation.java#L82-L112) -parameters available for WinRM. - -* host <String>: Host to connect to (required).Default value `null` -* port <Integer>: WinRM port to use when connecting to the remote machine.<br> - If no port is specified then it defaults to a port depending on the `winrm.useHttps` flag. -* winrm.useHttps <Boolean>: The parameter tells the machine sensors whether the winrm port is over https. If the parameter is true then 5986 will be used as a winrm port.<br> - Default value: `false` -* retriesOfNetworkFailures <Integer>: The parameter sets the number of retries for connection failures. If you use high value, consider taking care for the machine's network.<br> - Default value: `4` -* winrm.useNtlm <Boolean>: The parameter configures tells the machine sensors whether the winrm port is over https. If the parameter is true then 5986 will be used as a winrm port.<br> - Default value: `true` -* winrm.computerName <String>: Windows Computer Name to use for authentication.<br> - Default value: `null` -* user <String>: User to connect as<br> - Default value: `null` -* password <String>: Password to use to connect.<br> - Default value: `null` -* waitWindowsToStart <Duration>: By default Brooklyn will return the machine immediately after Brooklyn is able to WinRM. Sometimes restart could happen after a Windows VM is provisioned. - This could be because of System Upgrade or other. - By setting this config key to 60s, 5m or other X Duration of time Brooklyn will wait X amount of time for disconnect to occur. - If connection failure occurs it will wait X amount of time for the machine to come up.<br> - Default value: `null` - -If there are location config keys prefixed with `brooklyn.winrm.config.` prefix will be removed -and it will be used to instantiate a `org.apache.brooklyn.util.core.internal.winrm.WiRmTool` implementation. - -## WinRM Connectivity Diagnostics - -If you are experiencing problems with a windows blueprint against a jclouds location -where Apache Brooklyn complains about failing to connect to the IP you should check those things. - -1. Apache Brooklyn is using correct username and password -1. Apache Brooklyn can reach the IP of the provisioned machine. WinRM port 5985 or 5986 is also reachable from Apache Brooklyn. -1. Check whether `WinRmMachineLocation#getDefaultUserMetadataString(ConfigurationSupportInternal)` is applied on the VM. - This script should be passed to the cloud and executed in order to configure WinRM according to Apache Brooklyn requirements for authentication. - So far windows startup script are known to be supported on AWS EC2 and VCloud Director. - If your cloud doesn't use this script then tune WinRM parameters accordingly. -1. Check whether you use winrm over http or over https. - 1. If you are using WinRM over http then make sure WinRM service on target VM has `AllowUnencrypted = true` - -If the quick list above doesn't help then follow the steps bellow. - -To speed up diagnosing the problem we advice to trigger a deployment with the JcloudsLocation flag `destroyOnFailure: false` so you can check status of the provisioned machine -or try later different WinRM parameters with a Apache Brooklyn [BYON Location](../../ops/locations/index.html#byon). - -After you determined what is the username and the password you can proceed with next steps. -*(Notice that for cloud providers which use Auto Generated password will not be logged. -For these cases use Java Debug to retrieve ot or provision a VM manually with the same parameters when using Apache Brooklyn to provision a jclouds location.)* - -The first step is to find what is the winrm service configuration on the target host. - -1. If you have RDP access or KVM like access to the VM then check the winrm service status with the command bellow. - `winrm get winrm/config/service` - If you are using http you should have AllowUnencrypted to false. - Encryption is supported only over https. - Sample output: - - MaxConcurrentOperations = 4294967295 - MaxConcurrentOperationsPerUser = 1500 - EnumerationTimeoutms = 240000 - MaxConnections = 300 - MaxPacketRetrievalTimeSeconds = 120 - AllowUnencrypted = true - Auth - Basic = false - Kerberos = true - Negotiate = true - Certificate = false - CredSSP = true - CbtHardeningLevel = Relaxed - DefaultPorts - HTTP = 5985 - HTTPS = 5986 - IPv4Filter = * - IPv6Filter = * - EnableCompatibilityHttpListener = false - EnableCompatibilityHttpsListener = false - CertificateThumbprint - AllowRemoteAccess = true - -Use an Apache Brooklyn BYON blueprint to try easily other connection options. - - location: - byon: - hosts: - - winrm: 10.0.0.1 - user: Administrator - password: pa55w0rd - osFamily: windows - services: - - type: org.apache.brooklyn.entity.software.base.VanillaWindowsProcess - brooklyn.config: - checkRunning.command: echo checkRunning - install.command: echo installCommand - -1. Check IP is reachable from Apache Brooklyn instance - Check whether `telnet 10.0.0.1 5985` makes successfully a socket. -1. If AllowUnencrypted is false and you are using winrm over http then apply `winrm set winrm/config/service @{AllowUnencrypted="true"}` - *If jclouds or the cloud provider doesn't support passing `sysprep-specialize-script-cmd` then consider modifying Windows VM Image.* -1. Check your username and password. Notice in Windows passwords are case sensitive. - Here is how it looks log from a wrong password: - - INFO: Authorization loop detected on Conduit "{http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd}WinRmPort.http-conduit"; on URL "http://192.168.122.1:5985/wsman"; with realm "null" - Oct 21, 2016 10:43:11 AM org.apache.cxf.phase.PhaseInterceptorChain doDefaultLogging - WARNING: Interceptor for {http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd}WinRmService#{http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd}Create has thrown exception, unwinding now - org.apache.cxf.interceptor.Fault: Could not send Message. - at org.apache.cxf.interceptor.MessageSenderInterceptor$MessageSenderEndingInterceptor.handleMessage(MessageSenderInterceptor.java:64) - -1. When having wrong password you may want to try logging on a different domain - This is possible from `brooklyn.winrm.config.winrm.computerName` location config. -1. If you want to configure Windows target host with https then check the article [Configuring WINRM for HTTPS](https://support.microsoft.com/en-us/kb/2019527) -1. If you are still seeing authorization errors then try connecting via winrm with the embedded winrs client. - First make sure you have the server in trusted hosts. - -Then execute a simple command like - - winrs -r:10.0.2.15 -unencrypted -u:Administrator -p:pa55w0rd ipconfig http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/yaml/winrm/index.md ---------------------------------------------------------------------- diff --git a/guide/yaml/winrm/index.md b/guide/yaml/winrm/index.md deleted file mode 100644 index 168dded..0000000 --- a/guide/yaml/winrm/index.md +++ /dev/null @@ -1,630 +0,0 @@ ---- -title: Windows Blueprints -layout: website-normal -children: -- client.md ---- - -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 ------------ - -WinRM - or *Windows Remote Management* to give its full title - is a system administration service provided in all -recent Windows Server operating systems. It allows remote access to system information (provided via WMI) and the -ability to execute commands. For more information refer to [Microsoft's MSDN article on Windows Remote -Management](https://msdn.microsoft.com/en-us/library/aa384426(v=vs.85).aspx). - -WinRM is available by default in Windows Server, but is not enabled by default. Brooklyn will, in most cases, be able -to switch on WinRM support, but this is dependent on your cloud provider supporting a user metadata service with script -execution (see [below](#user-metadata-service-requirement)). - - -Locations for Windows ---------------------- - -You must define a new location in Brooklyn for Windows deployments. Windows deployments require a different VM image -ID to Linux, as well as some other special configuration, so you must have separate Brooklyn locations for Windows and -Linux deployments. - -In particular, you will most likely want to set these properties on your location: - -* `imageId` or `imageNameRegex` - select your preferred Windows Server image from your cloud provider. -* `hardwareId` or `minRam`/`minCores` - since Windows machines generally require more powerful servers, ensure you get - a machine with the required specification. -* `useJcloudsSshInit` - this must be set to `false`. Without this setting, jclouds will attempt to connect to the new - VMs using SSH, which will fail on Windows Server. -* `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]}`. - -In your YAML blueprint: - - ... - location: - jclouds:aws-ec2: - region: us-west-2 - identity: AKA_YOUR_ACCESS_KEY_ID - credential: <access-key-hex-digits> - 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 ------------------- - -Creating a Windows VM is done using the `org.apache.brooklyn.entity.software.base.VanillaWindowsProcess` entity type. This is very similar -to `VanillaSoftwareProcess`, but adapted to work for Windows and WinRM instead of Linux. We suggest you read the -[documentation for VanillaSoftwareProcess]({{ site.path.guide }}/yaml/custom-entities.html#vanilla-software-using-bash) to find out what you -can do with this entity. - -Entity authors are strongly encouraged to write Windows Powershell or Batch scripts as separate -files, to configure these to be uploaded, and then to configure the appropriate command as a -single line that executes given script. - -For example - here is a simplified blueprint (but see [Tips and Tricks](#tips-and-tricks) below!): - - name: Server with 7-Zip - - location: - jclouds:aws-ec2: - region: us-west-2 - identity: AKA_YOUR_ACCESS_KEY_ID - credential: <access-key-hex-digits> - imageNameRegex: Windows_Server-2012-R2_RTM-English-64Bit-Base-.* - imageOwner: 801119661308 - hardwareId: m3.medium - useJcloudsSshInit: false - templateOptions: {mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]} - - services: - - type: org.apache.brooklyn.entity.software.base.VanillaWindowsProcess - brooklyn.config: - templates.preinstall: - file:///Users/richard/install7zip.ps1: "C:\\install7zip.ps1" - install.command: powershell -command "C:\\install7zip.ps1" - customize.command: echo true - launch.command: echo true - stop.command: echo true - checkRunning.command: echo true - installer.download.url: http://www.7-zip.org/a/7z938-x64.msi - -The installation script - referred to as `/Users/richard/install7zip.ps1` in the example above - is: - - $Path = "C:\InstallTemp" - New-Item -ItemType Directory -Force -Path $Path - - $Url = "${config['installer.download.url']}" - $Dl = [System.IO.Path]::Combine($Path, "installer.msi") - $WebClient = New-Object System.Net.WebClient - $WebClient.DownloadFile( $Url, $Dl ) - - Start-Process "msiexec" -ArgumentList '/qn','/i',$Dl -RedirectStandardOutput ( [System.IO.Path]::Combine($Path, "stdout.txt") ) -RedirectStandardError ( [System.IO.Path]::Combine($Path, "stderr.txt") ) -Wait - -Where security-related operation are to be executed, it may require the use of `CredSSP` to obtain -the correct Administrator privileges: you may otherwise get an access denied error. See the sub-section -[How and Why to re-authenticate within a powershell script](#how-and-why-to-re-authenticate-within-a-powershell-script) for more details. - -This is only a very simple example. A more complex example can be found in the [Microsoft SQL Server blueprint in the -Brooklyn source code]({{ site.brooklyn.url.git }}/software/database/src/main/resources/org/apache/brooklyn/entity/database/mssql). - - -Tips and Tricks ---------------- - -The best practices for other entities (e.g. using [VanillaSoftwareProcess]({{ site.path.guide }}/yaml/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 using config options such as `launch.powershell.command`. - -This is an alternative to supplying a standard batch command using config such as `launch.command`. -For a given phase, only one of the commands (Powershell or Batch) should be supplied. - -### Getting the Right Exit Codes - -WinRM (or at least the chosen WinRM client!) can return a zero exit code even on error in certain -circumstances. It is therefore advisable to follow the guidelines below. - -*For a given command, write the Powershell or Batch script as a separate multi-command file. -Upload this (e.g. by including it in the `files.preinstall` configuration). For the configuration -of the given command, execute the file.* - -When you have a command inside the powershell script which want to report its non zero exiting, -please consider adding a check for its exit code after it. -Example: - - & "C:\install.exe" - If ($lastexitcode -ne 0) { - exit $lastexitcode - } - -For Powershell files, consider including - - $ErrorActionPreference = "Stop" - -at the start of the file. -`$ErrorActionPreference` Determines how Windows PowerShell responds to a non-terminating -error (an error that does not stop the cmdlet processing) at the -command line or in a script, cmdlet, or provider, such as the -errors generated by the Write-Error cmdlet. -https://technet.microsoft.com/en-us/library/hh847796.aspx - -See [Incorrect Exit Codes](#incorrect-exit-codes) under Known Limitations below. - -### Executing Scripts From Batch Commands - -In a batch command, you can execute a batch file or Powershell file. For example: - - install.command: powershell -NonInteractive -NoProfile -Command "C:\\install7zip.ps1" - -Or alternatively: - - install.command: C:\\install7zip.bat - -### Executing Scripts From Powershell - -In a Powershell command, you can execute a batch file or Powershell file. There are many ways -to do this (see official Powershell docs). For example: - - install.powershell.command: "& C:\\install7zip.ps1" - -Or alternatively: - - install.powershell.command: "& C:\\install7zip.bat" - -Note the quotes around the command. This is because the "&" has special meaning in a YAML value. - -### Uploading Script and Configuration Files - -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". - -There are two types of file that can be uploaded: plain files and templated files. A plain -file is uploaded unmodified. A templated file is interpreted as a [FreeMarker](http://freemarker.org) -template. This supports a powerful set of substitutions. In brief, anything (unescaped) of the form -`${name}` will be substituted, in this case looking up "name" for the value to use. - -Templated files (be they configuration files or scripts) gives a powerful way to inject dependent -configuration when installing an entity (e.g. for customising the install, or for referencing the -connection details of another entity). A common substitution is of the form `${config['mykey']}`. -This looks up a config key (in this case named "mykey") and will insert the value into the file. -Another common substitution is is of the form `${attribute['myattribute']}` - this looks up the -attribute named "myattribute" of this entity. - -Files can be referenced as URLs. This includes support for things like `classpath://mypath/myfile.bat`. -This looks for the given (fully qualified) resource on the Brooklyn classpath. - -The destination for the file upload is specified in the entity's configuration. Note that "\" must -be escaped. For example `"C:\\install7zip.ps1"`. - -A list of plain files to be uploaded can be configured under `files.preinstall`, `files.install` and -`files.runtime`. These are uploaded respectively prior to executing the `pre.install.command`, -prior to `install.command` and prior to `pre.launch.command`. - -A list of templated files to be uploaded can be configured under `templates.preinstall`, `templates.install` -and `templates.runtime`. The times these are uploaded is as for the plain files. The templates -substitutions will be resolved only at the point when the file is to be uploaded. - -For example: - - files.preinstall: - - classpath://com/acme/installAcme.ps1 - - classpath://com/acme/acme.conf - -### Parameterised Scripts - -Calling parameterised Batch and Powershell scripts is done in the normal Windows way - see -offical Microsoft docs. For example: - - install.command: "c:\\myscript.bat myarg1 myarg2" - -Or as a Powershell example: - - install.powershell.command: "& c:\\myscript.ps1 -key1 myarg1 -key2 myarg2" - -It is also possible to construct the script parameters by referencing attributes of this or -other entities using the standard `attributeWhenReady` mechanism. For example: - - install.command: $brooklyn:formatString("c:\\myscript.bat %s", component("db").attributeWhenReady("datastore.url")) - -### Powershell - Using Start-Process - -When you are invoking a command from a powershell script with `Start-Process` cmdlet, -please use the `-Wait` and the `-PassThru` arguments. -Example `Start-Process C:\mycommand -Wait -PassThru` - -Using `-Wait` guarantees that the script process and its children and thus the winrm session won't be terminated until it is finished. -`-PassThru` Returns a process object for each process that the cmdlet started. By default, this cmdlet does not generate any output. -See https://technet.microsoft.com/en-us/library/hh849848.aspx - -### 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. - -We Strongly recommend to **write blueprints in a way that they do NOT restart automatically windows** and -use one of the `pre.install.reboot.required` or `install.reboot.required` parameters to perform restart. - -### 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 - -Some installation scripts require the use of security-related operations. In some environments, -these fail by default when executed over WinRM, even though the script may succeed when run locally -(e.g. by using RDP to connect to the machine and running the script manually). There may be no -clear indication from Windows why it failed (e.g. for MSSQL install, the only clue is a -security exception in the installation log). - -When a script is run over WinRM, the credentials under which the script are run are marked as -'remote' credentials, which are prohibited from running certain security-related operations. The -solution is to obtain a new set of credentials within the script and use those credentials to -required commands. - -The WinRM client uses Negotiate+NTLM to authenticate against the machine. -This mechanism applies certain restrictions to executing commands on the windows host. - -For this reason you should enable CredSSP on the windows host which grants all privileges available to the user. - https://technet.microsoft.com/en-us/library/hh849719.aspx#sectionSection4 - -To use `Invoke-Command -Authentication CredSSP` the Windows Machine has to have: -- Up and running WinRM over http. The custom-enable-credssp.ps1 script enables winrm over http because `Invoke-Command` use winrm over http by default. - Invoke-Command can be used with -UseSSL option but this will lead to modifying powershell scripts. - With always enabling winrm over http on the host, blueprint's powershell scripts remain consistent and not depend on the winrm https/http environments. - We hope future versions of winrm4j will support CredSSP out of the box and wrapping commands in Invoke-Command will not be needed. -- Added trusted host entries which will use Invoke-Command -- Allowed CredSSP - -All the above requirements are enabled in Apache Brooklyn through [brooklyn-server/software/base/src/main/resources/org/apache/brooklyn/software/base/custom-enable-credssp.ps1](https://github.com/apache/brooklyn-server/blob/master/software/base/src/main/resources/org/apache/brooklyn/software/base/custom-enable-credssp.ps1) -script which enables executing commands with CredSSP in the general case. -The script works for most of the Windows images out there version 2008 and later. - -Please ensure that Brooklyn's changes are compatible with your organisation's security policy. - -Check Microsoft Documentation for more information about [Negotiate authenticate mechanism on technet.microsoft.com](https://msdn.microsoft.com/en-us/library/windows/desktop/aa378748(v=vs.85).aspx) - -Re-authentication also requires that the password credentials are passed in plain text within the -script. Please be aware that it is normal for script files - and therefore the plaintext password - -to be saved to the VM's disk. The scripts are also accessible via the Brooklyn web-console's -activity view. Access to the latter can be controlled via -[Entitlements]({{site.path.guide}}/java/entitlements.html). - -As an example (taken from MSSQL install), the command below works when run locally, but fails over -WinRM: - - ( $driveLetter + "setup.exe") /ConfigurationFile=C:\ConfigurationFile.ini - -The code below can be used instead (note this example uses Freemarker templating): - - & winrm set winrm/config/service/auth '@{CredSSP="true"}' - & winrm set winrm/config/client/auth '@{CredSSP="true"}' - # - $pass = '${attribute['windows.password']}' - $secpasswd = ConvertTo-SecureString $pass -AsPlainText -Force - $mycreds = New-Object System.Management.Automation.PSCredential ($($env:COMPUTERNAME + "\${location.user}"), $secpasswd) - # - $exitCode = Invoke-Command -ComputerName $env:COMPUTERNAME -Credential $mycreds -ScriptBlock { - param($driveLetter) - $process = Start-Process ( $driveLetter + "setup.exe") -ArgumentList "/ConfigurationFile=C:\ConfigurationFile.ini" -RedirectStandardOutput "C:\sqlout.txt" -RedirectStandardError "C:\sqlerr.txt" -Wait -PassThru -NoNewWindow - $process.ExitCode - } -Authentication CredSSP -ArgumentList $driveLetter - # - exit $exitCode - -In this example, the `${...}` format is FreeMarker templating. Those sections will be substituted -before the script is uploaded for execution. To explain this example in more detail: - -* `${attribute['windows.password']}` is substituted for the entity's attribute "windows.password". - This (clear-text) password is sent as part of the script. Assuming that HTTPS and NTLM is used, - the script will be encrypted while in-flight. - -* The `${location.user}` gets (from the entity's machine location) the username, substituting this - text for the actual username. In many cases, this will be "Administrator". However, on some - clouds a different username (with admin privileges) will be used. - -* The username and password are used to create a new credential object (having first converted the - password to a secure string). - -* Credential Security Service Provider (CredSSP) is used for authentication, to pass the explicit - credentials when using `Invoke-Command`. - - -### 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]({{ site.path.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 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. - -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. - -### Credentials issue requiring special configuration - -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 [How and Why to re-authenticate withing a powershell script](#how-and-why-to-re-authenticate-within-a-powershell-script) -above. - -### WebServiceException: Could not send Message - -We detected a `WebServiceException` and different `SocketException` -during deployment of long lasting Application Blueprint against VcloudDirector. - -Launching the blueprint bellow was giving constantly this type of error on launch step. - - services: - type: org.apache.brooklyn.entity.software.base.VanillaWindowsProcess - brooklyn.config: - pre.install.command: echo preInstallCommand - install.command: echo installCommand > C:\\install.txt - post.install.command: echo postInstallCommand - customize.command: echo customizeCommand - pre.launch.command: echo preLaunchCommand - launch.powershell.command: | - Start-Sleep -s 400 - Write-Host Test Completed - post.launch.command: echo postLaunchCommand - checkRunning.command: echo checkRunningCommand - stop.command: echo stopCommand - -With series of tests we concluded that on the Vcloud Director environment we were using -a restart was happening ~2 minutes after the VM is provisioned. -Logging in the host and search for System event of type 1074 in Windows Event Viewer, we found two 1074 events where the second one was - - The process C:\Windows\system32\winlogon.exe (W2K12-STD) has initiated the restart of computer WIN-XXXX on behalf of user - NT AUTHORITY\SYSTEM for the following reason: Operating System: Upgrade (Planned) Reason Code: 0x80020003 Shutdown Type: restart Comment: - -Normally on other clouds only one restart event is registered and the first time winrm connection is made the Windows VM is ready for use. - -For this particular case when you want this second restart to finish we made `waitWindowsToStart` location parameter -which basically adds additional check assuring the Windows VM provisioning is done. - - -For example when using `waitWindowsToStart: 5m` location parameter, Apache Brooklyn will wait 5 minutes to see if a disconnect occurs. -If it does, then it will again wait 5m for the machine to come back up. -The default behaviour in Apache Brooklyn is to consider provisioning done on the first successful winrm connection, without waiting for restart. - - -To determine whether you should use this parameter you should carefully inspect how the image you choose to provision is behaving. -If the description above matches your case and you are getting **connection failure message in the middle of the installation process** for your blueprints, -a restart probably occurred and you should try this parameter. - -Before using this parameter we advice to check whether this is really your case. -To verify the behavior check as described above. - -### AMIs not found - -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. - -### VM Provisioning Times Out - -In some environments, provisioning of Windows VMs can take a very long time to return a usable VM. -If the image is old, it may install many security updates (and reboot several times) before it is -usable. - -On a VMware vCloud Director environment, the guest customizations can cause the VM to reboot (sometimes -several times) before the VM is usable. - -This could cause the WinRM connection attempts to timeout. The location configuration option -`waitForWinRmAvailable` defaults to `30m` (i.e. 30 minutes). This can be increased if required. - -Incorrectly prepared Windows template can cause the deployment to time-out expecting an interaction by the user. -You can verify if this is the case by RDP to the deployment which is taking to much time to complete. -It is recommended to manually deploy a single VM for every newly created Windows template to verify that it can be -used for unattended installations and it doesn't wait and/or require an input by the user. -See [Windows template settings for an Unattended Installation](#windows-template-settings-for-an-unattended-installation) under Known Limitations below. - -### 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 ------------------ - -WinRM 2.0 supports encryption mechanisms on top of HTTP. However those are not supported in Apache Brooklyn. -For production adoptions please make sure you follow Microsoft Guidelines https://msdn.microsoft.com/en-us/library/ee309366(v=vs.85).aspx - -### Apache Brooklyn limitations on using WinRM over HTTP and HTTPS - -By default Apache Brooklyn is currently using unencrypted HTTP for WinRM communication. It does not support encrypted HTTP for WinRM. - -HTTPS is supported but there is no mechanism of specifying which certificates to trust. -Currently Apache Brooklyn will accept any certificate used in a HTTPS WinRM connection. - -### Incorrect Exit Codes - -Some limitations with WinRM (or at least the chosen WinRM Client!) are listed below: - -##### Single-line Powershell files - -When a Powershell file contains just a single command, the execution of that file over WinRM returns exit code 0 -even if the command fails! This is the case for even simple examples like `exit 1` or `thisFileDoesNotExist.exe`. - -A workaround is to add an initial command, for example: - - Write-Host dummy line for workaround - exit 1 - -##### Direct Configuration of Powershell commands - -If a command is directly configured with Powershell that includes `exit`, the return code over WinRM -is not respected. For example, the command below will receive an exit code of 0. - - launch.powershell.command: | - echo first - exit 1 - -##### Direct Configuration of Batch commands - -If a command is directly configured with a batch exit, the return code over WinRM -is not respected. For example, the command below will receive an exit code of 0. - - launch.command: exit /B 1 - -##### Non-zero Exit Code Returned as One - -If a batch or Powershell file exits with an exit code greater than one (or negative), this will -be reported as 1 over WinRM. - -We advise you to use native commands (non-powershell ones) since executing it as a native command -will return the exact exit code rather than 1. -For instance if you have installmssql.ps1 script use `install.command: powershell -command "C:\\installmssql.ps1"` -rather than using `install.powershell.command: "C:\\installmssql.ps1"` -The first will give you an exact exit code rather than 1 - -### PowerShell "Preparing modules for first use" - -The first command executed over WinRM has been observed to include stderr saying "Preparing -modules for first use", such as that below: - - < CLIXML - <Objs Version="1.1.0.1" xmlns="http://schemas.microsoft.com/powershell/2004/04";><Obj S="progress" RefId="0"><TN RefId="0"><T>System.Management.Automation.PSCustomObject</T><T>System.Object</T></TN><MS><I64 N="SourceId">1</I64><PR N="Record"><AV>Preparing modules for first use.</AV><AI>0</AI><Nil /><PI>-1</PI><PC>-1</PC><T>Completed</T><SR>-1</SR><SD> </SD></PR></MS></Obj><Obj S="progress" RefId="1"><TNRef RefId="0" /><MS><I64 N="SourceId">2</I64><PR N="Record"><AV>Preparing modules for first use.</AV><AI>0</AI><Nil /><PI>-1</PI><PC>-1</PC><T>Completed</T><SR>-1</SR><SD> </SD></PR></MS></Obj></Objs> - -The command still succeeded. This has only been observed on private clouds (e.g. not on -AWS). It could be related to the specific Windows images in use. It is recommended that -VM images are prepared carefully, e.g. so that security patches are up-to-date and the -VM is suitably initialised. - -### WinRM executeScript failed: httplib.BadStatusLine: '' - -As described in https://issues.apache.org/jira/browse/BROOKLYN-173, a failure has been -observed where the 10 attempts to execute the command over WinRM failed with: - - httplib.BadStatusLine: '' - -Subsequently retrying the command worked. It is unclear what caused the failure, but could -have been that the Windows VM was not yet in the right state. - -One possible workaround is to ensure the Windows VM is in a good state for immediate use (e.g. -security updates are up-to-date). Another option is to increase the number of retries, -which defaults to 10. This is a configuration option on the machine location, so can be set on -the location's brooklyn.properties or in the YAML: - - execTries: 20 - -### Direct Configuration of Multi-line Batch Commands Not Executed - -If a command is directly configured with multi-line batch commands, then only the first line -will be executed. For example the command below will only output "first": - - launch.command: | - echo first - echo second - -The workaround is to write a file with the batch commands, have that file uploaded, and execute it. - -Note this is not done automatically because that could affect the capture and returning -of the exit code for the commands executed. - -### 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. - -### Windows template settings for an Unattended Installation - -Windows template needs certain configuration to be applied to prevent windows setup UI from being displayed. -The default behavior is to display it if there are incorrect or empty settings. Showing Setup UI will prevent the proper -deployment, because it will expect interaction by the user such as agreeing on the license agreement or some of the setup dialogs. - -Detailed instruction how to prepare an Unattended installation are provided at [https://technet.microsoft.com/en-us/library/cc722411%28v=ws.10%29.aspx](https://technet.microsoft.com/en-us/library/cc722411%28v=ws.10%29.aspx). -
