Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 94C54200D4C for ; Wed, 25 Oct 2017 23:04:52 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id 931A9160BDA; Wed, 25 Oct 2017 21:04:52 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 690D7160BE0 for ; Wed, 25 Oct 2017 23:04:48 +0200 (CEST) Received: (qmail 48033 invoked by uid 500); 25 Oct 2017 21:04:47 -0000 Mailing-List: contact commits-help@brooklyn.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@brooklyn.apache.org Delivered-To: mailing list commits@brooklyn.apache.org Received: (qmail 48012 invoked by uid 99); 25 Oct 2017 21:04:47 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 25 Oct 2017 21:04:47 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id E761BDFCF9; Wed, 25 Oct 2017 21:04:46 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: m4rkmckenna@apache.org To: commits@brooklyn.apache.org Date: Wed, 25 Oct 2017 21:04:49 -0000 Message-Id: <0ee50148355143acbc19c5aa1c25c662@git.apache.org> In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [04/50] [abbrv] brooklyn-docs git commit: Adapt doc to make compile with gitbook archived-at: Wed, 25 Oct 2017 21:04:52 -0000 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/blueprints/test/test-entities.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/test/test-entities.md b/guide/blueprints/test/test-entities.md index 37604a1..d723643 100644 --- a/guide/blueprints/test/test-entities.md +++ b/guide/blueprints/test/test-entities.md @@ -12,9 +12,7 @@ layout: website-normal ### 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 %} +!CODEFILE "example_yaml/entities/testcase-entity.yaml" This can be used to enforce a strict ordering, for example ensuring a sensor has a certain value before attempting to invoke an effector. @@ -26,9 +24,7 @@ The `ParallelTestCase` entity can be added as a child to run a subset of entitie ### 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 %} +!CODEFILE "example_yaml/entities/paralleltestcase-entity.yaml" This can be used to run a subset of entities in parallel as a single step when nested under a `TestCase` entity. @@ -38,9 +34,7 @@ Timeouts on child entities should be set relative to the start of the `ParallelT ### 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 %} +!CODEFILE "example_yaml/entities/loopovergroupmembers-entity.yaml' #### Parameters - `target` - group who's members are to be tested, specified via DSL. For example, `$brooklyn:entity("tomcat")`. See also the `targetId` parameter. @@ -51,9 +45,7 @@ The `LoopOverGroupMembersTestCase` entity is configured with a target group and ### 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 %} +!CODEFILE "example_yaml/entities/infrastructuredeploymenttestcase-entity.yaml" #### Parameters @@ -67,9 +59,7 @@ The `InfrastructureDeploymentTestCase` will first create and deploy an infrastru ### TestSensor The `TestSensor` entity performs an assertion on a specified sensors value. -{% highlight yaml %} -{% readj example_yaml/entities/testsensor-entity.yaml %} -{% endhighlight %} +!CODEFILE "example_yaml/entities/testsensor-entity.yaml" #### Parameters - `target` - entity whose sensor will be tested, specified via DSL. For example, `$brooklyn:entity("tomcat")`. See also the `targetId` parameter. @@ -87,9 +77,8 @@ The `TestSensor` entity performs an assertion on a specified sensors value. ### 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 %} + +!CODEFILE "example_yaml/entities/testeffector-entity.yaml" #### Parameters - `target` - entity whose effector will be invoked, specified via DSL. For example, `$brooklyn:entity("tomcat")`. See also the `targetId` parameter. @@ -108,9 +97,8 @@ The `TestEffector` entity invokes the specified effector on a target entity. If ### 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 %} + +!CODEFILE "example_yaml/entities/testhttpcall-entity.yaml" #### Parameters - `url` - URL to perform GET request on, this can use DSL for example `$brooklyn:entity("tomcat").attributeWhenReady("webapp.url")`. @@ -133,9 +121,7 @@ If no assertions are explicitly configured, the default is to assert a non-zero 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 %} +!CODEFILE "example_yaml/entities/testsshcommand-entity.yaml" #### Parameters - `command` - The shell command to execute. (This and `downloadUrl` are mutually exclusive.) http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/blueprints/test/usage-examples.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/test/usage-examples.md b/guide/blueprints/test/usage-examples.md index 08d88e3..6c5114a 100644 --- a/guide/blueprints/test/usage-examples.md +++ b/guide/blueprints/test/usage-examples.md @@ -7,11 +7,9 @@ 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: +This section describes some simple tests based on the [Getting Started]({{ book.path.guide }}/start/blueprints.html#launching-from-a-blueprint) example blueprint: -{% highlight yaml %} -{% readj /guide/start/_my-web-cluster.yaml %} -{% endhighlight %} +!CODEFILE "/guide/start/_my-web-cluster.yaml" 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). @@ -23,9 +21,7 @@ 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 %} +!CODEFILE "example_yaml/testcases/sensor-test-snippet.yaml" ### 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): @@ -33,9 +29,7 @@ Demonstrates the following HTTP Call assertions against the specified `url`, whi - 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 %} +!CODEFILE "example_yaml/testcases/http-test-snippet.yaml" ### Effector Test (via TestCase entity) @@ -46,13 +40,11 @@ This `TestEffector` example demonstrates the use of the `TestCase` and `TestSens - `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 %} +!CODEFILE "example_yaml/testcases/effector-test-snippet.yaml" ### 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. +This blueprint will deploy the [Getting Started]({{ book.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. [![Successful Getting Started App deployment and Test execution.](images/getting-started-blueprint-test.png)](images/getting-started-blueprint-test-large.png) http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/blueprints/winrm/index.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/winrm/index.md b/guide/blueprints/winrm/index.md index 6155c60..9b52fcb 100644 --- a/guide/blueprints/winrm/index.md +++ b/guide/blueprints/winrm/index.md @@ -72,7 +72,7 @@ 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 }}/blueprints/custom-entities.html#vanilla-software-using-bash) to find out what you +[documentation for VanillaSoftwareProcess]({{ book.path.guide }}/blueprints/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 @@ -123,13 +123,13 @@ the correct Administrator privileges: you may otherwise get an access denied err [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). +Brooklyn source code]({{ book.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 }}/blueprints/custom-entities.html#vanilla-software-using-bash)) +The best practices for other entities (e.g. using [VanillaSoftwareProcess]({{ book.path.guide }}/blueprints/custom-entities.html#vanilla-software-using-bash)) apply for WinRM as well. ### Execution Phases @@ -279,7 +279,7 @@ Re-authentication also requires that the password credentials are passed in plai 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}}/blueprints/java/entitlements.html). +[Entitlements]({{book.path.guide}}/blueprints/java/entitlements.html). As an example (taken from MSSQL install), the command below works when run locally, but fails over WinRM: @@ -363,7 +363,7 @@ on the Microsoft TechNet site. Troubleshooting --------------- -Much of the [operations troubleshooting guide]({{ site.path.guide }}/ops/troubleshooting/) is applicable for Windows blueprints. +Much of the [operations troubleshooting guide]({{ book.path.guide }}/ops/troubleshooting/) is applicable for Windows blueprints. ### User metadata service requirement http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/blueprints/yaml-reference.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/yaml-reference.md b/guide/blueprints/yaml-reference.md index 7a46970..c5398e8 100644 --- a/guide/blueprints/yaml-reference.md +++ b/guide/blueprints/yaml-reference.md @@ -20,7 +20,7 @@ defining types: * `com.acme.brooklyn.package.JavaEntityClass` * `java:com.acme.brooklyn.package.JavaEntityClass` -* `java-entity-class` (where this has been added to the [catalog]({{ site.path.guide }}/blueprints/catalog/)) +* `java-entity-class` (where this has been added to the [catalog]({{ book.path.guide }}/blueprints/catalog/)) A reference of some of the common service `type` instances used is included in a section below. @@ -79,7 +79,7 @@ the entity being defined, with these being the most common: * `default`: a default value; this will be coerced to the declared `type` * `pinned`: mark the parameter as pinned (always displayed) for the UI. The default is `true` * `constraints`: a list of constraints the parameter should meet; - for details, see [Entity Configuration]({{ site.path.guide }}/blueprints/entity-configuration.html#config-key-constraints). + for details, see [Entity Configuration]({{ book.path.guide }}/blueprints/entity-configuration.html#config-key-constraints). A shorthand notation is also supported where just the name of the parameter is supplied as an item in the list, with the other values being unset or the default. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/concepts/dependent-configuration.md ---------------------------------------------------------------------- diff --git a/guide/concepts/dependent-configuration.md b/guide/concepts/dependent-configuration.md index 1d08e1a..ec796cd 100644 --- a/guide/concepts/dependent-configuration.md +++ b/guide/concepts/dependent-configuration.md @@ -7,10 +7,10 @@ categories: [use, guide, defining-applications] Under the covers Brooklyn has a sophisticated sensor event and subscription model, but conveniences around this model make it very simple to express cross-entity dependencies. Consider the example where Tomcat instances need to know the URL of a database (or a set of URLs to connect to a Monterey processing fabric, or other entities) -{% highlight java %} +```java setConfiguration(UsesJava.JAVA_OPTIONS, ImmutableMap.of("mysql.url", attributeWhenReady(mysql, MySqlNode.MY_SQL_URL) )) -{% endhighlight %} +``` The ``attributeWhenReady(Entity, Sensor)`` call (a static method on the class ``DependentConfiguration``) causes the configuration value to be set when that given entity's attribue is ready. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/concepts/index.md ---------------------------------------------------------------------- diff --git a/guide/concepts/index.md b/guide/concepts/index.md index b27ea8c..6f323f6 100644 --- a/guide/concepts/index.md +++ b/guide/concepts/index.md @@ -19,4 +19,4 @@ intended for people who are using brooklyn-supported application components (suc to be able to use brooklyn to easily start their application in multiple locations with off-the-shelf management policies. -{% include list-children.html %} + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/dev/env/ide/index.md ---------------------------------------------------------------------- diff --git a/guide/dev/env/ide/index.md b/guide/dev/env/ide/index.md index 94bbfba..0072737 100644 --- a/guide/dev/env/ide/index.md +++ b/guide/dev/env/ide/index.md @@ -25,7 +25,7 @@ working with the Brooklyn project. Optionally you can install the Groovy and TestNG plugins, but they are not required for building the project. You can install these using Help -> Install New Software, or from the Eclipse Marketplace: -{% readj eclipse.include.md %} +{% include 'eclipse.include.md' %} As of this writing, Eclipse 4.5 and Eclipse 4.4 are commonly used, and the codebase can be imported (Import -> Existing Maven Projects) @@ -52,20 +52,20 @@ If you encounter issues, the following hints may be helpful: or the filesystem, or use the following command to remove these rogue blocks in the generated `.classpath` files: -{% highlight bash %} +```bash % find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {} \; -{% endhighlight %} +``` * You may need to ensure ``src/main/{java,resources}`` is created in each project dir, if (older versions) complain about missing directories, and the same for ``src/test/{java,resources}`` *if* there are tests (``src/test`` exists): -{% highlight bash %} +```bash find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mkdir -p {}/{java,resources} \; -{% endhighlight %} +``` If the pain starts to be too much, come find us on IRC #brooklyncentral or -[elsewhere]({{site.path.website}}/community/) and we can hopefully share our pearls. +[elsewhere]({{book.path.website}}/community/) and we can hopefully share our pearls. (And if you have a tip we haven't mentioned please let us know that too!) http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/dev/env/maven-build.md ---------------------------------------------------------------------- diff --git a/guide/dev/env/maven-build.md b/guide/dev/env/maven-build.md index bc5a79b..2b1bc65 100644 --- a/guide/dev/env/maven-build.md +++ b/guide/dev/env/maven-build.md @@ -15,15 +15,15 @@ The full build requires the following software to be installed: With these in place, you should be able to build everything with a: -{% highlight bash %} +```bash % mvn clean install -{% endhighlight %} +``` Alternatively you can build most things with just Java and Maven installed using: -{% highlight bash %} +```bash mvn clean install -Dno-go-client -Dno-rpm` -{% endhighlight %} +``` Other tips: @@ -90,7 +90,7 @@ including a few warnings (which we have looked into and understand to be benign and hard to get rid of them, although we'd love to if anyone can help!): -{% highlight bash %} +```bash % mvn clean install [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ @@ -188,4 +188,4 @@ although we'd love to if anyone can help!): [INFO] Final Memory: 66M/554M [INFO] ------------------------------------------------------------------------ -{% endhighlight %} +``` http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/dev/index.md ---------------------------------------------------------------------- diff --git a/guide/dev/index.md b/guide/dev/index.md index f0cf45e..00c5e8d 100644 --- a/guide/dev/index.md +++ b/guide/dev/index.md @@ -7,7 +7,7 @@ breadcrumbs: - /website/documentation/index.md - /guide/dev/index.md children: -- { link: "{{ site.path.website }}/developers/code/", title: "Get the Code" } +- { link: "{{ book.path.website }}/developers/code/", title: "Get the Code" } - env/maven-build.md - env/ide/ - code/structure.md @@ -39,4 +39,4 @@ And for the Brooklyn codebase itself, see: (All links are TODO.) {% endcomment %} -{% include list-children.html %} + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/dev/tips/debugging-remote-brooklyn.md ---------------------------------------------------------------------- diff --git a/guide/dev/tips/debugging-remote-brooklyn.md b/guide/dev/tips/debugging-remote-brooklyn.md index 5056fd8..b33b486 100644 --- a/guide/dev/tips/debugging-remote-brooklyn.md +++ b/guide/dev/tips/debugging-remote-brooklyn.md @@ -23,21 +23,21 @@ instance. The git commit that was used to build Brooklyn is available via the RE This should return details of the build as a JSON string similar to the following (formatted for clarity): -{% highlight json %} +```json { "version": "1.0.0-SNAPSHOT", {% comment %}BROOKLYN_VERSION{% endcomment %} "buildSha1": "c0fdc15291702281acdebf1b11d431a6385f5224", "buildBranch": "UNKNOWN" } -{% endhighlight %} +``` The value that we're interested in is `buildSha1`. This is the git commit that was used to build Brooklyn. We can now checkout and build the Brooklyn code at this commit by running the following in the root of your Brooklyn repo: -{% highlight bash %} +```bash % git checkout c0fdc15291702281acdebf1b11d431a6385f5224 % mvn clean install -DskipTests -{% endhighlight %} +``` Whilst building the code isn't strictly necessary, it can help prevent some IDE issues. @@ -46,12 +46,12 @@ By default, Brooklyn does not listen for a debugger to be attached, however this which will require a restart of the Brooklyn node. To do this, SSH to the remote Brooklyn node and run the following in the root of the Brooklyn installation: -{% highlight bash %} +```bash # NOTE: Running this kill command will lose existing apps and machines if persistence is disabled. % kill `cat pid_java` % export JAVA_OPTS="-Xms256m -Xmx1g -agentlib:jdwp=transport=dt_socket,address=127.0.0.1:8888,server=y,suspend=n" % bin/brooklyn launch & -{% endhighlight %} +``` If `JAVA_OPTS` is not set, Brooklyn will automatically set it to `"-Xms256m -Xmx1g"`, which is why we have prepended the agentlib settings with these values here. @@ -71,7 +71,7 @@ usually simpler to create an SSH tunnel. This will create an open SSH connection on a local interface via SSH to a port on the remote machine. To create the tunnel, run the following on your local machine: -{% highlight bash %} +```bash # replace this with the address or IP of the remote Brooklyn node REMOTE_HOST= # if you wish to use a different port, this value must match the port specified in the JAVA_OPTS @@ -84,7 +84,7 @@ SSH_USER=root PRIVATE_KEY_FILE=~/.ssh/id_rsa % ssh -YNf -i $PRIVATE_KEY_FILE -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST -{% endhighlight %} +``` If you use a password to SSH to the remote Brooklyn node, simply remove the `-i $PRIVATE_KEY_FILE` section like so: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/dev/tips/index.md ---------------------------------------------------------------------- diff --git a/guide/dev/tips/index.md b/guide/dev/tips/index.md index 417a42f..bfacfcf 100644 --- a/guide/dev/tips/index.md +++ b/guide/dev/tips/index.md @@ -12,7 +12,7 @@ title: Miscellaneous Tips and Tricks * When debugging an entity, make sure the [brooklyn.SSH logger](logging.html) is set to DEBUG and accessible. -* Use tests heavily! These are pretty good to run in the IDE (once you've completed [IDE setup]({{site.path.guide}}/dev/env/ide/)), +* Use tests heavily! These are pretty good to run in the IDE (once you've completed [IDE setup]({{book.path.guide}}/dev/env/ide/)), and far quicker to spot problems than runtime, plus we get early-warning of problems introduced in the future. (In particular, Groovy's laxity with compilation means it is easy to introduce silly errors which good test coverage will find much faster.) @@ -46,7 +46,7 @@ title: Miscellaneous Tips and Tricks Clusters will take such a ``MachineProvisioningLocation`` (or a singleton list); fabircs take a list of locations. Some PaaS systems have their own location model, such as ``OpenShiftLocation``. -* Finally, don't be shy about [talking with others]({{site.path.website}}/community/), +* Finally, don't be shy about [talking with others]({{book.path.website}}/community/), that's far better than spinning your wheels (or worse, having a bad experience), plus it means we can hopefully improve things for other people! http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/dev/tips/logging.md ---------------------------------------------------------------------- diff --git a/guide/dev/tips/logging.md b/guide/dev/tips/logging.md index a6e9a71..d6d9347 100644 --- a/guide/dev/tips/logging.md +++ b/guide/dev/tips/logging.md @@ -65,7 +65,7 @@ For the most common customizations, simply create a ``logback-custom.xml`` on yo (ensuring it is loaded *before* brooklyn classes in classpath ordering in the pom) and supply your customizations there: -{% highlight xml %} +```xml @@ -73,7 +73,7 @@ and supply your customizations there: -{% endhighlight %} +``` For other configuration, you can override individual files listed above. For example: @@ -99,9 +99,9 @@ If you wish to supply your own ``logback.xml``, do **not** include ``brooklyn-lo You can set a specific logback config file to use with: -{% highlight bash %} +```bash -Dlogback.configurationFile=/path/to/config.xml -{% endhighlight %} +``` #### Assemblies http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/index.md ---------------------------------------------------------------------- diff --git a/guide/index.md b/guide/index.md deleted file mode 100644 index 9d9392a..0000000 --- a/guide/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: User Guide -layout: website-normal -breadcrumbs: -- /website/documentation/index.md -- index.md -children: -- { path: /guide/start/index.md } -- { path: /guide/misc/download.md } -- { path: /guide/concepts/index.md } -- { path: /guide/blueprints/index.md } -- { path: /guide/locations/index.md } -- { path: /guide/ops/index.md } -- { path: /guide/misc/index.md } ---- - -This is the Brooklyn User Guide for v{{ site.brooklyn-version }}: - -{% include list-children.html %} - -If you are working with the Brooklyn codebase itself, also see the [Developer Guide](dev/) for this version. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/list-children.html ---------------------------------------------------------------------- diff --git a/guide/list-children.html b/guide/list-children.html new file mode 100644 index 0000000..e69de29 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_AWS.md ---------------------------------------------------------------------- diff --git a/guide/locations/_AWS.md b/guide/locations/_AWS.md index 7f592d2..633d627 100644 --- a/guide/locations/_AWS.md +++ b/guide/locations/_AWS.md @@ -26,7 +26,7 @@ An example of the expected format is shown below: credential: abcdefghijklmnopqrstu+vwxyzabcdefghijklm Users are strongly recommended to use -[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better +[externalized configuration]({{ book.path.guide }}/ops/externalized-configuration.html) for better credential management, for example using [Vault](https://www.vaultproject.io/). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_GCE.md ---------------------------------------------------------------------- diff --git a/guide/locations/_GCE.md b/guide/locations/_GCE.md index 8fdf3ed..9167ab7 100644 --- a/guide/locations/_GCE.md +++ b/guide/locations/_GCE.md @@ -56,7 +56,7 @@ However, this can make it harder to setup and manage multiple Brooklyn servers ( when using high availability mode). Users are strongly recommended to use -[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better +[externalized configuration]({{ book.path.guide }}/ops/externalized-configuration.html) for better credential management, for example using [Vault](https://www.vaultproject.io/). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_azure-ARM.md ---------------------------------------------------------------------- diff --git a/guide/locations/_azure-ARM.md b/guide/locations/_azure-ARM.md index 3fced19..917d4d9 100644 --- a/guide/locations/_azure-ARM.md +++ b/guide/locations/_azure-ARM.md @@ -217,7 +217,7 @@ stored in protected .PFX file. It needs to be prepared upfront or created with t Placeholders surrounded with `<>` have to be replcaced with their respective values. -{% highlight yaml %} +```yaml brooklyn.catalog: id: my-azure-arm-location name: "My Azure ARM location" @@ -257,7 +257,7 @@ brooklyn.catalog: certificateUrl: "" additionalUnattendContent: null enableAutomaticUpdates: true -{% endhighlight %} +``` #### Known issues There are currently two known issues with Azure ARM: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_azure-classic.md ---------------------------------------------------------------------- diff --git a/guide/locations/_azure-classic.md b/guide/locations/_azure-classic.md index 18604a2..e32a6ed 100644 --- a/guide/locations/_azure-classic.md +++ b/guide/locations/_azure-classic.md @@ -19,7 +19,7 @@ for details. Microsoft Azure requests are signed by SSL certificate. You need to upload one into your account in order to use an Azure location. -{% highlight bash %} +```bash # create the certificate request mkdir -m 700 $HOME/.brooklyn openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout $HOME/.brooklyn/azure.pem -out $HOME/.brooklyn/azure.pem @@ -27,7 +27,7 @@ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout $HOME/.brooklyn/azur openssl pkcs12 -export -out $HOME/.brooklyn/azure.p12 -in $HOME/.brooklyn/azure.pem -name "brooklyn :: $USER" # create a cer file openssl x509 -inform pem -in $HOME/.brooklyn/azure.pem -outform der -out $HOME/.brooklyn/azure.cer -{% endhighlight %} +``` Finally, upload .cer file to the management console at https://manage.windowsazure.com/@myId#Workspaces/AdminTasks/ListManagementCertificates to authorize this certificate. @@ -40,7 +40,7 @@ Please note, you can find the "myId" value for this link by looking at the URL w First, in your `brooklyn.properties` define a location as follows: -{% highlight properties %} +```properties brooklyn.location.jclouds.azurecompute.identity=$HOME/.brooklyn/azure.p12 brooklyn.location.jclouds.azurecompute.credential= brooklyn.location.jclouds.azurecompute.endpoint=https://management.core.windows.net/ @@ -48,7 +48,7 @@ brooklyn.location.jclouds.azurecompute.vmNameMaxLength=45 brooklyn.location.jclouds.azurecompute.jclouds.azurecompute.operation.timeout=120000 brooklyn.location.jclouds.azurecompute.user= brooklyn.location.jclouds.azurecompute.password= -{% endhighlight %} +``` During the VM provisioning, Azure will set up the account with `` and `` automatically. Notice, `` must be a minimum of 8 characters and must contain 3 of the following: a lowercase character, an uppercase @@ -85,14 +85,14 @@ rather than "classic". For convenience, you can define a named location, like: -{% highlight properties %} +```properties brooklyn.location.named.azure-west-europe=jclouds:azurecompute:West Europe brooklyn.location.named.azure-west-europe.displayName=Azure West Europe brooklyn.location.named.azure-west-europe.imageId=b39f27a8b8c64d52b05eac6a62ebad85__Ubuntu-14_04_1-LTS-amd64-server-20150123-en-us-30GB brooklyn.location.named.azure-west-europe.hardwareId=BASIC_A2 brooklyn.location.named.azure-west-europe.user=test brooklyn.location.named.azure-west-europe.password=MyPassword1! -{% endhighlight %} +``` This will create a location named `azure-west-europe`. It will inherit all the configuration defined on `brooklyn.location.jclouds.azurecompute`. It will also augment and override this @@ -158,7 +158,7 @@ The following configuration options are important for provisioning Windows VMs i Below is an example for provisioning a Windows-based entity on Azure. Note the placeholder values for the identity, credential and password. -{% highlight yaml %} +```yaml name: Windows Test @ Azure location: jclouds:azurecompute:West Europe: @@ -182,12 +182,12 @@ services: install.command: echo install phase launch.command: echo launch phase checkRunning.command: echo launch phase -{% endhighlight %} +``` Below is an example named location for Azure, configured in `brooklyn.properties`. Note the placeholder values for the identity, credential and password. -{% highlight properties %} +```properties brooklyn.location.named.myazure=jclouds:azurecompute:West Europe brooklyn.location.named.myazure.displayName=Azure West Europe (windows) brooklyn.location.named.myazure.identity=$HOME/.brooklyn/azure.p12 @@ -203,7 +203,7 @@ brooklyn.location.named.myazure.winrm.useHttps=true brooklyn.location.named.myazure.user=brooklyn brooklyn.location.named.myazure.password=secretPass1! brooklyn.location.named.myazure.templateOptions={ overrideLoginUser: amp, overrideLoginPassword: secretPass1! } -{% endhighlight %} +``` ###### User and Password Configuration http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_byon.md ---------------------------------------------------------------------- diff --git a/guide/locations/_byon.md b/guide/locations/_byon.md index 948994d..b815072 100644 --- a/guide/locations/_byon.md +++ b/guide/locations/_byon.md @@ -17,7 +17,7 @@ Your nodes must meet the following prerequisites: To deploy to machines with known IP's in a blueprint, use the following syntax: -{% highlight yaml %} +```yaml location: byon: user: brooklyn @@ -25,7 +25,7 @@ location: hosts: - 192.168.0.18 - 192.168.0.19 -{% endhighlight %} +``` Some of the login properties as described above for jclouds are supported, but not `loginUser` (as no users are created), and not any of the @@ -40,22 +40,22 @@ Named locations can also be configured in your `brooklyn.properties`, using the format `byon:(key=value,key2=value2)`. For convenience, for hosts wildcard globs are supported. -{% highlight bash %} +```bash brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}") brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1 brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase -{% endhighlight %} +``` Alternatively, you can create a specific BYON location through the location wizard tool available within the web console. -This location will be saved as a [catalog entry]({{ site.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) for easy reusability. +This location will be saved as a [catalog entry]({{ book.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) for easy reusability. For more complex host configuration, one can define custom config values per machine. In the example below, there will be two machines. The first will be a machine reachable on `ssh -i ~/.ssh/brooklyn.pem -p 8022 myuser@50.51.52.53`. The second is a windows machine, reachable over WinRM. Each machine has also has a private address (e.g. for within a private network). -{% highlight yaml %} +```yaml location: byon: hosts: @@ -68,7 +68,7 @@ location: password: mypassword user: myuser osFamily: windows -{% endhighlight %} +``` The BYON location also supports a machine chooser, using the config key `byon.machineChooser`. This allows one to plugin logic to choose from the set of available machines in the pool. For http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_clouds.md ---------------------------------------------------------------------- diff --git a/guide/locations/_clouds.md b/guide/locations/_clouds.md index b590014..25bb66d 100644 --- a/guide/locations/_clouds.md +++ b/guide/locations/_clouds.md @@ -19,27 +19,27 @@ The identifiers for some of the most commonly used jclouds-supported clouds are For any of these, of course, Brooklyn needs to be configured with an `identity` and a `credential`: -{% highlight yaml %} +```yaml location: jclouds:aws-ec2: identity: ABCDEFGHIJKLMNOPQRST credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l -{% endhighlight %} +``` The above YAML can be embedded directly in blueprints, either at the root or on individual services. -If you prefer to keep the credentials separate, you can instead store them as a [catalog entry]({{ site.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) or set them in `brooklyn.properties` +If you prefer to keep the credentials separate, you can instead store them as a [catalog entry]({{ book.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) or set them in `brooklyn.properties` in the `jclouds.` namespace: -{% highlight bash %} +```bash brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l -{% endhighlight %} +``` And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`. Alternatively, you can use the location wizard tool available within the web console to create any cloud location supported by Apache jclouds. -This location will be saved as a [catalog entry]({{ site.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) for easy reusability. +This location will be saved as a [catalog entry]({{ book.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) for easy reusability. Brooklyn irons out many of the differences between clouds so that blueprints run similarly in a wide range of locations, including setting up access and configuring images and machine specs. @@ -88,7 +88,7 @@ These steps can be skipped or customized as described below. The following is a subset of the most commonly used configuration keys used to customize cloud provisioning. For more keys and more detail on the keys below, see -{% include java_link.html class_name="JcloudsLocationConfig" package_path="org/apache/brooklyn/location/jclouds" project_subpath="locations/jclouds" %}. +[JcloudsLocationConfig](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/location/jclouds/JcloudsLocationConfig.html). ###### VM Creation @@ -115,10 +115,10 @@ For more keys and more detail on the keys below, see including the ID of the app and of the entity. (As many cloud portals let you filter views, this can help find a specific entity or all machines for a given application.) For more sophisticated control over host naming, you can supply a custom - {% include java_link.html class_name="CloudMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %}, + [CloudMachineNamer](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/core/location/cloud/names/CloudMachineNamer.html), for example `cloudMachineNamer: CustomMachineNamer`. - {% include java_link.html class_name="CustomMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %} + [CustomMachineNamer](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/core/location/cloud/names/CustomMachineNamer.html) will use the entity's name or following a template you supply. On many clouds, a random suffix will be appended to help guarantee uniqueness; this can be removed by setting `vmNameSaltLength: 0` (selected clouds only). @@ -138,7 +138,7 @@ For more keys and more detail on the keys below, see machines with `machineCreateAttempts` (jclouds only). This is useful as an efficient low-level fix for those occasions when cloud providers give machines that are dead on arrival. You can of course also resolve it at a higher level with a policy such as - {% include java_link.html class_name="ServiceRestarter" package_path="org/apache/brooklyn/policy/ha" project_subpath="policy" %}. + [ServiceRestarter](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/policy/ha/ServiceRestarter.html). - If you want to investigate failures, set `destroyOnFailure: false` to keep failed VM's around. (You'll have to manually clean them up.) @@ -297,7 +297,7 @@ Clouds vary in the format of the identity, credential, endpoint, and region. Some also have their own idiosyncracies. More details for configuring some common clouds is included below. You may also find these sources helpful: -* The **[template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties)** file +* The **[template brooklyn.properties]({{ book.path.guide }}/start/brooklyn.properties)** file in the Getting Started guide contains numerous examples of configuring specific clouds, including the format of credentials and options for sometimes-fiddly private clouds. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_cloudstack.md ---------------------------------------------------------------------- diff --git a/guide/locations/_cloudstack.md b/guide/locations/_cloudstack.md index 50a7e0c..e56cad6 100644 --- a/guide/locations/_cloudstack.md +++ b/guide/locations/_cloudstack.md @@ -21,7 +21,7 @@ the CloudStack gui: under accounts, select "view users", then "generate key". credential: mycred-abcdefghijklmnopqrstuvwxyz01234567890-abcdefghijklmnopqrstuvwxyz01234567890-abc Users are strongly recommended to use -[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better +[externalized configuration]({{ book.path.guide }}/ops/externalized-configuration.html) for better credential management, for example using [Vault](https://www.vaultproject.io/). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_ibm-softlayer.md ---------------------------------------------------------------------- diff --git a/guide/locations/_ibm-softlayer.md b/guide/locations/_ibm-softlayer.md index e1a5d40..5300944 100644 --- a/guide/locations/_ibm-softlayer.md +++ b/guide/locations/_ibm-softlayer.md @@ -20,7 +20,7 @@ For example: credential: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef Users are strongly recommended to use -[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better +[externalized configuration]({{ book.path.guide }}/ops/externalized-configuration.html) for better credential management, for example using [Vault](https://www.vaultproject.io/). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_inheritance-and-named-locations.md ---------------------------------------------------------------------- diff --git a/guide/locations/_inheritance-and-named-locations.md b/guide/locations/_inheritance-and-named-locations.md index bf237f3..f7f0d5d 100644 --- a/guide/locations/_inheritance-and-named-locations.md +++ b/guide/locations/_inheritance-and-named-locations.md @@ -15,7 +15,7 @@ These can be accessed at runtime using the syntax `named:your-group-name` as the Some illustrative examples using named locations and showing the syntax and properties above are as follows: -{% highlight bash %} +```bash # Production pool of machines for my application (deploy to named:prod1) brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}") brooklyn.location.named.prod1.user=produser1 @@ -36,7 +36,7 @@ brooklyn.location.named.AWS\ Virginia\ Large\ Centos.region = us-east-1 brooklyn.location.named.AWS\ Virginia\ Large\ Centos.imageId=us-east-1/ami-7d7bfc14 brooklyn.location.named.AWS\ Virginia\ Large\ Centos.user=root brooklyn.location.named.AWS\ Virginia\ Large\ Centos.minRam=4096 -{% endhighlight %} +``` Named locations can refer to other named locations using `named:xxx` as their value. These will inherit the configuration and can override selected keys. @@ -58,17 +58,17 @@ an additional public key in all AWS machines, and no extra public key in `prod1`: -{% highlight bash %} +```bash brooklyn.location.extraSshPublicKeyUrls=http://me.com/public_key brooklyn.location.jclouds.aws-ec2.extraSshPublicKeyUrls="[ \"http://me.com/public_key\", \"http://me.com/aws_public_key\" ]" brooklyn.location.named.prod1.extraSshPublicKeyUrls= -{% endhighlight %} +``` And in the example below, a config key is repeatedly overridden. Deploying `location: named:my-extended-aws` will result in an `aws-ec2` machine in `us-west-1` (by inheritance) with `VAL6` for `KEY`: -{% highlight bash %} +```bash brooklyn.location.KEY=VAL1 brooklyn.location.jclouds.KEY=VAL2 brooklyn.location.jclouds.aws-ec2.KEY=VAL3 @@ -77,4 +77,4 @@ brooklyn.location.named.my-aws=jclouds:aws-ec2:us-west-1 brooklyn.location.named.my-aws.KEY=VAL5 brooklyn.location.named.my-extended-aws=named:my-aws brooklyn.location.named.my-extended-aws.KEY=VAL6 -{% endhighlight %} \ No newline at end of file +``` \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_localhost.md ---------------------------------------------------------------------- diff --git a/guide/locations/_localhost.md b/guide/locations/_localhost.md index d2daf33..98183e4 100644 --- a/guide/locations/_localhost.md +++ b/guide/locations/_localhost.md @@ -19,7 +19,7 @@ If you use a passphrase or prefer a different key, these can be configured as fo Alternatively, you can create a specific localhost location through the location wizard tool available within the web console. -This location will be saved as a [catalog entry]({{ site.path.guide }}/blueprints/catalog/index.html#locations-in-the-catalog) +This location will be saved as a [catalog entry]({{ book.path.guide }}/blueprints/catalog/index.html#locations-in-the-catalog) for easy reusability. @@ -31,18 +31,18 @@ For some blueprints, passwordless sudo is required. (Try executing `sudo whoami` To enable passwordless `sudo` for your account, a line must be added to the system `/etc/sudoers` file. To edit the file, use the `visudo` command: -{% highlight bash %} +```bash sudo visudo -{% endhighlight %} +``` Add this line at the bottom of the file, replacing `username` with your own user: -{% highlight bash %} +```bash username ALL=(ALL) NOPASSWD: ALL -{% endhighlight %} +``` If executing the following command does not ask for your password, then `sudo` has been setup correctly: -{% highlight bash %} +```bash sudo whoami -{% endhighlight %} +``` http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_openstack.md ---------------------------------------------------------------------- diff --git a/guide/locations/_openstack.md b/guide/locations/_openstack.md index 942eaa5..3a04fe7 100644 --- a/guide/locations/_openstack.md +++ b/guide/locations/_openstack.md @@ -31,7 +31,7 @@ as an openrc.sh file. It is usually available from API Access tab in "Access & S This file will normally contain the identity and credential. Users are strongly recommended to use -[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better +[externalized configuration]({{ book.path.guide }}/ops/externalized-configuration.html) for better credential management, for example using [Vault](https://www.vaultproject.io/). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_special-locations.md ---------------------------------------------------------------------- diff --git a/guide/locations/_special-locations.md b/guide/locations/_special-locations.md index a06b0ae..536829b 100644 --- a/guide/locations/_special-locations.md +++ b/guide/locations/_special-locations.md @@ -14,11 +14,11 @@ The spec `host`, taking a string argument (the address) or a map (`host`, `user` provides a convenient syntax when specifying a single host. For example: -{% highlight yaml %} +```yaml location: host:(192.168.0.1) services: - type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server -{% endhighlight %} +``` Or, in `brooklyn.properties`, set `brooklyn.location.named.host1=host:(192.168.0.1)`. @@ -37,7 +37,7 @@ machines available. In the example below, it provisions the first node to `192.168.0.1`, then it provisions into AWS us-east-1 region (because the bring-your-own-nodes region will have run out of nodes). -{% highlight yaml %} +```yaml location: multi: targets: @@ -50,7 +50,7 @@ services: dynamiccluster.memberspec: $brooklyn:entitySpec: type: org.apache.brooklyn.entity.machine.MachineEntity -{% endhighlight %} +``` ##### Round-Robin Consumption and Availability Zones for Clustered Applications @@ -67,7 +67,7 @@ In the example below, the cluster will request VMs round-robin across three diff locations (in this case, the locations were already added to the catalog, or defined in `brooklyn.properties`). -{% highlight yaml %} +```yaml location: multi: targets: @@ -82,7 +82,7 @@ services: dynamiccluster.memberspec: $brooklyn:entitySpec: type: org.apache.brooklyn.entity.machine.MachineEntity -{% endhighlight %} +``` Of course, clusters can also be deployed round-robin to real availability zones offered by cloud providers, as long as their locations support `AvailabilityZoneExtension`. Currently, only @@ -91,7 +91,7 @@ AWS EC2 locations support this feature. In the example below, the cluster will request VMs round-robin across the availability zones provided by AWS EC2 in the "us-east-1" region. -{% highlight yaml %} +```yaml location: jclouds:aws-ec2:us-east-1 services: - type: org.apache.brooklyn.entity.group.DynamicCluster @@ -101,7 +101,7 @@ services: dynamiccluster.memberspec: $brooklyn:entitySpec: type: org.apache.brooklyn.entity.machine.MachineEntity -{% endhighlight %} +``` For more information about AWS EC2 availability zones, see [this guide](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). @@ -112,6 +112,6 @@ Custom alternatives to round-robin are also possible using the configuration opt #### The Server Pool -The {% include java_link.html class_name="ServerPool" package_path="org/apache/brooklyn/entity/machine/pool" project_subpath="software/base" %} +The [ServerPool](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/entity/machine/pool/ServerPool.html) entity type allows defining an entity which becomes available as a location. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/_ssh-keys.md ---------------------------------------------------------------------- diff --git a/guide/locations/_ssh-keys.md b/guide/locations/_ssh-keys.md index acf30d7..007bdaf 100644 --- a/guide/locations/_ssh-keys.md +++ b/guide/locations/_ssh-keys.md @@ -28,9 +28,9 @@ and no one snooping on the network can decrypt of any of the traffic. If you don't have an SSH key, create one with: -{% highlight bash %} +```bash $ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa -{% endhighlight %} +``` #### Localhost Setup @@ -38,10 +38,10 @@ $ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa If you want to deploy to `localhost`, ensure that you have a public and private key, and that your key is authorized for ssh access: -{% highlight bash %} +```bash # _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected. $ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys -{% endhighlight %} +``` Now verify that your setup by running the command: `ssh localhost echo hello world` @@ -85,4 +85,4 @@ If this isn't the case, see below. if command-line `ssh` and `scp` work, but Brooklyn/java does not, check the versions enabled in Java and on both servers. * Missing entropy: creating and using ssh keys requires randomness available on the servers, - usually in `/dev/random`; see [here]({{ site.path.guide }}/ops/troubleshooting/increase-entropy.html) for more information + usually in `/dev/random`; see [here]({{ book.path.guide }}/ops/troubleshooting/increase-entropy.html) for more information http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/index.md ---------------------------------------------------------------------- diff --git a/guide/locations/index.md b/guide/locations/index.md index 9092ada..b371baf 100644 --- a/guide/locations/index.md +++ b/guide/locations/index.md @@ -12,10 +12,180 @@ to a pre-provisioned network or to localhost (primarily useful for testing bluep See also: -* The [Locations yaml guide]({{ site.path.guide }}/blueprints/setting-locations.html) +* The [Locations yaml guide]({{ book.path.guide }}/blueprints/setting-locations.html) * Use within an entity of the configuration option - [provisioning.properties]({{ site.path.guide }}/blueprints/entity-configuration.html#entity-provisioningproperties-overriding-and-merging) -* How to add location definitions to the [Catalog]({{ site.path.guide }}/blueprints/catalog/); and -* How to use [Externalized Configuration]({{ site.path.guide }}/ops/externalized-configuration.html). + [provisioning.properties]({{ book.path.guide }}/blueprints/entity-configuration.html#entity-provisioningproperties-overriding-and-merging) +* How to add location definitions to the [Catalog]({{ book.path.guide }}/blueprints/catalog/); and +* How to use [Externalized Configuration]({{ book.path.guide }}/ops/externalized-configuration.html). -{% child_content %} +The requirements for how a provisioned machine should behave will depend on the +entites subsequently deployed there. + +Below are a set of common assumptions, made by many entity implementations, which +could cause subsequent errors if they do not hold. These relate to the machine's +configuration, rather than additional networking or security that a given Cloud +might offer. + +Also see the [Troubleshooting]({{ book.path.guide }}/ops/troubleshooting/) docs. + + +## Remote Access + +### SSH or WinRM Access + +Many entities require ssh'ing (or using WinRM for Windows), to install and configure +the software. + +An example of disabling all ssh'ing is shown below: + + location: + aws-ec2:us-east-1: + identity: XXXXXXXX + credential: XXXXXXXX + waitForSshable: false + pollForFirstReachableAddress: false + services: + - type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess + brooklyn.config: + onbox.base.dir.skipResolution: true + sshMonitoring.enabled: false + + +### Parsing SSH stdout: No Extra Lines + +For entities that execute ssh commands, these sometimes parse the resulting stdout. + +It is strongly recommended that VMs are configured so that no additional stdout is written when executing +remote ssh (or WinRM) commands. Such stdout risks interfering with the response parsing in some blueprints. + +For example, if configuring the VM to write out "Last login" information, this should be done for only +"interactive" shells (see [Stackoverflow](http://stackoverflow.com/a/415444/1393883) for more details). + + +### Passwordless Sudo + +Does passwordless sudo work? + +Try executing: + + sudo whoami + +See [Passwordless Sudo]({{ book.path.guide }}/locations/index.html#passwordless-sudo). + + +## Advertised Addresses + +### Hostname Resolves Locally + +Does the hostname known at the box resolve at the box? + +Try executing: + + ping $(hostname) + +if not, consider setting `generate.hostname: true` in the location config, for jclouds-based locations. + + +### IP Resolves Locally + +For the IP address advertised in Brooklyn using the sensor `host.addresses.private` (or `host.subnet.address`), +can the machine reach that IP? + +Get the sensor value, and then try executing: + + ping ${PRIVATE_IP} + +Is there a public IP (advertised using the sensor `host.addresses.public`, or `host.address`), and can the +machine reach it? + +Get the sensor value, and then try executing: + + ping ${PUBLIC_IP} + + +## Networking + +### Public Internet Access + +Can the machine reach the public internet, and does DNS resolve? + +Try executing: + + ping www.example.org + + +### Machine's Hostname in DNS + +Is the machine hostname well-known? If ones does a DNS lookup, e.g. from the Brooklyn server, does it resolve and +does it return the expected IP (e.g. the same IP as the `host.addresses.public` sensor)? Try using the hostname +that the machine reports when you execute `hostname`. + +Many blueprints do not require this, instead using IP addresses directly. Some blueprints may include registration +with an appropriate DNS server. Some clouds do this automatically. + + +### Reachability + +When provisioning two machines, can these two machines reach each other on the expected IP(s) and hostname(s)? + +Try using `ping` from one machine to another using the public or subnet ip or hostname. +However, note that `ping` requires access over ICMP, which may be disabled. Alternatively, +try connecting to a specific TCP port using `telnet
`. + + +### Firewalls + +What firewall(s) are running on the machine, and are the required ports open? +On linux, check things like `iptables`, `firewalld`, `ufw` or other commercial +firewalls. On Windows, check the settings of the +[Windows Firewall](https://en.wikipedia.org/wiki/Windows_Firewall). + +Consider using `openIptables: true`, or even `stopIptables: true`. + + +## Sufficient Entropy for /dev/random + +Is there sufficient entropy on the machine, for `/dev/random` to respond quickly? + +Try executing: + + { cat /dev/random > /tmp/x & } ; sleep 10 ; kill %1 ; { cat /dev/random > /tmp/x & } ; sleep 1 ; kill %1 ; wc /tmp/x | awk '{print $3}' + +The result should be more than 1M. + +If not, consider setting `installDevUrandom: true` for jclouds-based locations. + +See instructions to [Increase Entropy]({{ book.path.guide }}/ops/troubleshooting/increase-entropy.html). + + +## File System + +### Permissions of /tmp + +Is `/tmp` writable? + +Try executing: + + touch /tmp/amp-test-file ; rm /tmp/amp-test-file + +Are files in `/tmp` executable (e.g. some places it has been mounted NO_EXECUTE)? + +Try executing: + + echo date > /tmp/brooklyn-test.sh && chmod +x /tmp/brooklyn-test.sh && /tmp/brooklyn-test.sh && rm /tmp/brooklyn-test.sh + +{% include '_clouds.md' %} +{% include '_AWS.md' %} +{% include '_azure-ARM.md' %} +{% include '_azure-classic.md' %} +{% include '_cloudstack.md' %} +{% include '_GCE.md' %} +{% include '_ibm-softlayer.md' %} +{% include '_openstack.md' %} +{% include '_inheritance-and-named-locations.md' %} +{% include '_byon.md' %} +{% include '_ssh-keys.md' %} +{% include '_localhost.md' %} +{% include '_location-customizers.md' %} +{% include '_location-customizer-security-groups.md' %} +{% include '_special-locations.md' %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/locations/provisioned-machine-requirements.md ---------------------------------------------------------------------- diff --git a/guide/locations/provisioned-machine-requirements.md b/guide/locations/provisioned-machine-requirements.md deleted file mode 100644 index 5b5bf99..0000000 --- a/guide/locations/provisioned-machine-requirements.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Provisioned Machine Requirements -layout: website-normal ---- - -The requirements for how a provisioned machine should behave will depend on the -entites subsequently deployed there. - -Below are a set of common assumptions, made by many entity implementations, which -could cause subsequent errors if they do not hold. These relate to the machine's -configuration, rather than additional networking or security that a given Cloud -might offer. - -Also see the [Troubleshooting]({{ site.path.guide }}/ops/troubleshooting/) docs. - - -## Remote Access - -### SSH or WinRM Access - -Many entities require ssh'ing (or using WinRM for Windows), to install and configure -the software. - -An example of disabling all ssh'ing is shown below: - - location: - aws-ec2:us-east-1: - identity: XXXXXXXX - credential: XXXXXXXX - waitForSshable: false - pollForFirstReachableAddress: false - services: - - type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess - brooklyn.config: - onbox.base.dir.skipResolution: true - sshMonitoring.enabled: false - - -### Parsing SSH stdout: No Extra Lines - -For entities that execute ssh commands, these sometimes parse the resulting stdout. - -It is strongly recommended that VMs are configured so that no additional stdout is written when executing -remote ssh (or WinRM) commands. Such stdout risks interfering with the response parsing in some blueprints. - -For example, if configuring the VM to write out "Last login" information, this should be done for only -"interactive" shells (see [Stackoverflow](http://stackoverflow.com/a/415444/1393883) for more details). - - -### Passwordless Sudo - -Does passwordless sudo work? - -Try executing: - - sudo whoami - -See [Passwordless Sudo]({{ site.path.guide }}/locations/index.html#passwordless-sudo). - - -## Advertised Addresses - -### Hostname Resolves Locally - -Does the hostname known at the box resolve at the box? - -Try executing: - - ping $(hostname) - -if not, consider setting `generate.hostname: true` in the location config, for jclouds-based locations. - - -### IP Resolves Locally - -For the IP address advertised in Brooklyn using the sensor `host.addresses.private` (or `host.subnet.address`), -can the machine reach that IP? - -Get the sensor value, and then try executing: - - ping ${PRIVATE_IP} - -Is there a public IP (advertised using the sensor `host.addresses.public`, or `host.address`), and can the -machine reach it? - -Get the sensor value, and then try executing: - - ping ${PUBLIC_IP} - - -## Networking - -### Public Internet Access - -Can the machine reach the public internet, and does DNS resolve? - -Try executing: - - ping www.example.org - - -### Machine's Hostname in DNS - -Is the machine hostname well-known? If ones does a DNS lookup, e.g. from the Brooklyn server, does it resolve and -does it return the expected IP (e.g. the same IP as the `host.addresses.public` sensor)? Try using the hostname -that the machine reports when you execute `hostname`. - -Many blueprints do not require this, instead using IP addresses directly. Some blueprints may include registration -with an appropriate DNS server. Some clouds do this automatically. - - -### Reachability - -When provisioning two machines, can these two machines reach each other on the expected IP(s) and hostname(s)? - -Try using `ping` from one machine to another using the public or subnet ip or hostname. -However, note that `ping` requires access over ICMP, which may be disabled. Alternatively, -try connecting to a specific TCP port using `telnet
`. - - -### Firewalls - -What firewall(s) are running on the machine, and are the required ports open? -On linux, check things like `iptables`, `firewalld`, `ufw` or other commercial -firewalls. On Windows, check the settings of the -[Windows Firewall](https://en.wikipedia.org/wiki/Windows_Firewall). - -Consider using `openIptables: true`, or even `stopIptables: true`. - - -## Sufficient Entropy for /dev/random - -Is there sufficient entropy on the machine, for `/dev/random` to respond quickly? - -Try executing: - - { cat /dev/random > /tmp/x & } ; sleep 10 ; kill %1 ; { cat /dev/random > /tmp/x & } ; sleep 1 ; kill %1 ; wc /tmp/x | awk '{print $3}' - -The result should be more than 1M. - -If not, consider setting `installDevUrandom: true` for jclouds-based locations. - -See instructions to [Increase Entropy]({{ site.path.guide }}/ops/troubleshooting/increase-entropy.html). - - -## File System - -### Permissions of /tmp - -Is `/tmp` writable? - -Try executing: - - touch /tmp/amp-test-file ; rm /tmp/amp-test-file - -Are files in `/tmp` executable (e.g. some places it has been mounted NO_EXECUTE)? - -Try executing: - - echo date > /tmp/brooklyn-test.sh && chmod +x /tmp/brooklyn-test.sh && /tmp/brooklyn-test.sh && rm /tmp/brooklyn-test.sh - http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/misc/download.md ---------------------------------------------------------------------- diff --git a/guide/misc/download.md b/guide/misc/download.md index 73d500b..fabfefa 100644 --- a/guide/misc/download.md +++ b/guide/misc/download.md @@ -2,117 +2,105 @@ layout: website-normal title: Downloads --- -{% include fields.md %} -{% if site.brooklyn.is_snapshot %} + +{% if book.brooklyn.is_snapshot %} **The downloads on this page have not been voted on and should be used at your own risk. -The latest stable release can be accessed on the [main download page]({{ site.path.website }}/download/).** +The latest stable release can be accessed on the [main download page]({{ book.path.website }}/download/).** {% endif %} -## Download Version {{ site.brooklyn-version }} +## Download Version {{ book.brooklyn-version }} - + - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1 - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1 - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1 - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1 - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1 - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1 - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1 - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1 - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1 - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1 - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1 - + + {% if book.brooklyn.is_release %}PGP, {% endif %} + SHA1
Download File/Formatchecksums (?)checksums (?)
Binary distribution
Server & client		apache-brooklyn-{{ site.brooklyn-version }}-bin.tar.gzapache-brooklyn-{{ book.brooklyn-version }}-bin.tar.gz - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
apache-brooklyn-{{ site.brooklyn-version }}-bin.zipapache-brooklyn-{{ book.brooklyn-version }}-bin.zip - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
RPM package
CentOS7, RHEL7, etc.		apache-brooklyn-{{ site.brooklyn-version }}-1.noarch.rpmapache-brooklyn-{{ book.brooklyn-version }}-1.noarch.rpm - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
DEB package
Ubuntu, Debian, etc.		apache-brooklyn-{{ site.brooklyn-version }}.debapache-brooklyn-{{ book.brooklyn-version }}.deb - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
Client CLI onlyapache-brooklyn-{{ site.brooklyn-version }}-client-cli-linux.tar.gzapache-brooklyn-{{ book.brooklyn-version }}-client-cli-linux.tar.gz - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
apache-brooklyn-{{ site.brooklyn-version }}-client-cli-linux.zipapache-brooklyn-{{ book.brooklyn-version }}-client-cli-linux.zip - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
apache-brooklyn-{{ site.brooklyn-version }}-client-cli-macosx.tar.gzapache-brooklyn-{{ book.brooklyn-version }}-client-cli-macosx.tar.gz - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
apache-brooklyn-{{ site.brooklyn-version }}-client-cli-macosx.zipapache-brooklyn-{{ book.brooklyn-version }}-client-cli-macosx.zip - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
apache-brooklyn-{{ site.brooklyn-version }}-client-cli-windows.tar.gzapache-brooklyn-{{ book.brooklyn-version }}-client-cli-windows.tar.gz - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
apache-brooklyn-{{ site.brooklyn-version }}-client-cli-windows.zipapache-brooklyn-{{ book.brooklyn-version }}-client-cli-windows.zip - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
Source codeapache-brooklyn-{{ site.brooklyn-version }}-src.tar.gzapache-brooklyn-{{ book.brooklyn-version }}-src.tar.gz - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
apache-brooklyn-{{ site.brooklyn-version }}-src.zipapache-brooklyn-{{ book.brooklyn-version }}-src.zip - {% if site.brooklyn.is_release %}PGP, {% endif %} - SHA1
## Release Notes -Release notes can be found [here]({{ site.path.guide }}/misc/release-notes.html). - -{% comment %} -TODO - - -## Examples - -Examples can be found in the main Brooklyn codebase, in the `/examples` directory. - -A good example to start with is the [Elastic Web Cluster]({{site.path.guide}}/use/examples/webcluster.html). - -{% endcomment %} +Release notes can be found [here]({{ book.path.guide }}/misc/release-notes.html). @@ -123,16 +111,16 @@ If you use Maven, you can add Brooklyn with the following in your pom: -{% highlight xml %} +```xml org.apache.brooklyn brooklyn-all - {{ site.brooklyn-version }} + {{ book.brooklyn-version }} -{% endhighlight %} +``` `brooklyn-all` brings in all dependencies, including jclouds. If you prefer a smaller repo you might want just ``brooklyn-core``, ``brooklyn-policies``, @@ -141,7 +129,7 @@ and some of ``brooklyn-software-webapp``, ``brooklyn-software-database``, ``bro If you wish to use the Apache snapshot repo, you can add this to you `pom.xml`: -{% highlight xml %} +```xml @@ -152,7 +140,7 @@ If you wish to use the Apache snapshot repo, you can add this to you `pom.xml`: true -{% endhighlight %} +``` {% if SNAPSHOT %} **Please note**: to add a snapshot version of Brooklyn as a dependency to your project, @@ -165,8 +153,8 @@ you must either have Brooklyn built locally or one of these snapshot repositorie ## Source Code Source code is hosted at [github.com/apache/brooklyn](http://github.com/apache/brooklyn), -with this version in branch [{{ site.brooklyn.git_branch }}]({{ site.brooklyn.url.git }}). +with this version in branch [{{ book.brooklyn.git_branch }}]({{ book.brooklyn.url.git }}). These locations have a `README.md` in the root which explains how to get the code including submodules. -Useful information on working with the source is [here]({{ site.path.guide }}/dev/code). +Useful information on working with the source is [here]({{ book.path.guide }}/dev/code). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/misc/index.md ---------------------------------------------------------------------- diff --git a/guide/misc/index.md b/guide/misc/index.md index a1f8827..674758b 100644 --- a/guide/misc/index.md +++ b/guide/misc/index.md @@ -17,4 +17,4 @@ Further documentation specific to this version of Brooklyn includes: * [{{ item.title_in_menu }}]({{ item.url }}) {% endfor %} -Also see the [other versions]({{ site.path.website }}/meta/versions.html) or [general documentation]({{ site.path.website }}/documentation/). +Also see the [other versions]({{ book.path.website }}/meta/versions.html) or [general documentation]({{ book.path.website }}/documentation/). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/misc/release-notes.md ---------------------------------------------------------------------- diff --git a/guide/misc/release-notes.md b/guide/misc/release-notes.md index 970b86f..b36fcab 100644 --- a/guide/misc/release-notes.md +++ b/guide/misc/release-notes.md @@ -3,7 +3,7 @@ layout: website-normal title: Release Notes --- -## Version {{ site.brooklyn-version }} +## Version {{ book.brooklyn-version }} {% if SNAPSHOT %} **You are viewing a SNAPSHOT release (master branch), so this list is in progress!** @@ -21,4 +21,4 @@ Changes since 0.12.0: For changes in prior versions, please refer to the release notes for -[0.12.0]({{ site.path.v }}/0.12.0/misc/release-notes.html). +[0.12.0]({{ book.path.v }}/0.12.0/misc/release-notes.html). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/18c248c5/guide/ops/cli/cli-ref-guide.md ---------------------------------------------------------------------- diff --git a/guide/ops/cli/cli-ref-guide.md b/guide/ops/cli/cli-ref-guide.md index 09ea9b3..596f895 100644 --- a/guide/ops/cli/cli-ref-guide.md +++ b/guide/ops/cli/cli-ref-guide.md @@ -18,19 +18,19 @@ children: --- ## Usage -{% highlight text %} +```text NAME: br - A Brooklyn command line client application USAGE: br [global options] command [command options] [arguments...] -{% endhighlight %} +``` ## List of Commands Commands whose description begins with a `*` character are particularly experimental and likely to change in upcoming releases. -{% highlight text %} +```text COMMANDS: Commands whose description begins with a "*" character are particularly experimental and likely to change in upcoming @@ -74,7 +74,7 @@ GLOBAL OPTIONS: --skipSslChecks Skip verification of server's certificate chain and hostname (for use with self-signed certs) --help, -h show help --version, -v print the version -{% endhighlight %} +``` ## Scopes @@ -103,12 +103,12 @@ The various scopes should be replaced on the command line as: ## Abbreviations Many of the commands and scopes have shortened aliases: -{% highlight text %} +```text activity act application app entity ent policy pol -{% endhighlight %} +``` ## Command Reference