You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by al...@apache.org on 2016/07/20 12:59:17 UTC
[1/2] brooklyn-docs git commit: Add to blueprinting-tips
Repository: brooklyn-docs
Updated Branches:
refs/heads/master 8567739e2 -> 95e2ce5a4
Add to blueprinting-tips
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/cf24d4a0
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/cf24d4a0
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/cf24d4a0
Branch: refs/heads/master
Commit: cf24d4a0b61da5138b3ee10ed1a29407a75195ef
Parents: 4a2aead
Author: Aled Sage <al...@gmail.com>
Authored: Fri Jul 15 15:48:39 2016 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Wed Jul 20 13:58:00 2016 +0100
----------------------------------------------------------------------
guide/yaml/blueprinting-tips.md | 114 +++++++++++++++++++++++++++++------
1 file changed, 96 insertions(+), 18 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/cf24d4a0/guide/yaml/blueprinting-tips.md
----------------------------------------------------------------------
diff --git a/guide/yaml/blueprinting-tips.md b/guide/yaml/blueprinting-tips.md
index c918174..bbca6f7 100644
--- a/guide/yaml/blueprinting-tips.md
+++ b/guide/yaml/blueprinting-tips.md
@@ -12,6 +12,19 @@ The use of Java is reserved for those use-cases where the provisioning or config
is very complicated.
+## Be Familiar with Brooklyn
+
+Be familiar with the stock entities available in Brooklyn. For example, prove you understand
+the concepts by making a deployment of a cluster of Tomcat servers before you begin writing your
+own blueprints.
+
+
+## Ask For Help
+
+Ask for help early. The community is keen to help, and also keen to find out what people find
+hard and how people use the product. Such feedback is invaluable for improving future versions.
+
+
## Faster Dev-Test
Writing a blueprint is most efficient and simple when testing is fast, and when testing is
@@ -22,28 +35,30 @@ of artifacts (e.g. RPMs, zip files, etc).
Options for speeding up provisioning include those below.
-### Deploying to the "localhost" location
+#### Deploying to Bring Your Own Nodes (BYON)
-This is fast and simple, but has some obvious downsides:
+A [BYON location]({{ site.path.guide }}/ops/locations/#byon) can be defined, which avoids the time
+required to provision VMs. This is fast, but has the downside that artifacts installed during a
+previous run can interfere with subsequent runs.
-* Artifacts are installed directly on your desktop/server.
+A variant of this is to [use Vagrant]({{ site.path.guide }}/start/running.html) (e.g. with VirtualBox)
+to create VMs on your local machine, and to use these as the target for a BYON location.
-* The artifacts installed during previous runs can interfere with subsequent runs.
+These VMs should mirror the target environment as much as possible.
-* Some entities require `sudo` rights, which must be granted to the user running Brooklyn.
+#### Deploying to the "localhost" location
+
+This is fast and simple, but has some obvious downsides:
-### Deploying to Bring Your Own Nodes (BYON)
+* Artifacts are installed directly on your desktop/server.
-A BYON location can be defined, which avoids the time required to provision VMs. This is fast,
-but has the downside that artifacts installed during a previous run can interfere with subsequent
-runs.
+* The artifacts installed during previous runs can interfere with subsequent runs.
-A variant of this is to use Vagrant (e.g. with VirtualBox) to create VMs on your local machine,
-and to use these as the target for a BYON location.
+* Some entities require `sudo` rights, which must be granted to the user running Brooklyn.
-### Deploying to Clocker
+#### Deploying to Clocker
Docker containers provide a convenient way to test blueprints (and also to run blueprints in
production!).
@@ -54,26 +69,65 @@ container (i.e. no install artifacts from previous runs), while taking advantage
of starting containers.
-### Caching Install Artifacts
+#### Local Repository of Install Artifacts
To avoid re-downloading install artifacts on every run, these can be saved to `~/.brooklyn/repository/`.
The file structure is a sub-directory with the entity's simple name, then a sub-directory with the
version number, and then the files to be downloaded. For example,
`~/.brooklyn/repository/TomcatServer/7.0.56/apache-tomcat-7.0.56.tar.gz`.
+If possible, synchronise this directory with your test VMs.
+
+
+#### Re-install on BYON
+
If using BYON or localhost, the install artifacts will by default be installed to a directory like
`/tmp/brooklyn-myname/installs/`. If install completed successfully, then the install stage will
-be subsequently skipped. To re-test the install phase, delete the install directory (e.g. delete
-`/tmp/brooklyn-myname/installs/TomcatServer_7.0.56/`).
+be subsequently skipped (a marker file being used to indicate completion). To re-test the install
+phase, delete the install directory (e.g. delete `/tmp/brooklyn-myname/installs/TomcatServer_7.0.56/`).
Where installation used something like `apt-get install` or `yum install`, then re-testing the
install phase will require uninstalling these artifacts manually.
+## Monitoring and Managing Applications
+
+Think about what it really means for an application to be running. The out-of-the-box default
+for a software process is the lowest common denominator: that the process is still running.
+Consider checking that the app responds over HTTP etc.
+
+If you have control of the app code, then consider adding an explicit health check URL that
+does more than basic connectivity tests. For example, can it reach the database, message broker,
+and other components that it will need for different operations.
+
+
+## Writing Composite Blueprints
+
+Write everything in discrete chunks that can be composed into larger pieces. Do not write a single
+mega-blueprint. For example, ensure each component is added to the catalog independently, along
+with a blueprint for the composite app.
+
+Experiment with lots of small blueprints to test independent areas before combining them into the
+real thing.
+
+
+## Writing Entity Tests
+
+Use the [test framework]({{ site.path.guide }}/yaml/test/) to write test cases. This will make
+automated (regression) testing easier, and will allow others to easily confirm that the entity
+works in their environment.
+
+If using Maven/Gradle then use the [Brooklyn Maven plugin](https://github.com/brooklyncentral/brooklyn-maven-plugin)
+to test blueprints at build time.
+
+
## Custom Entity Development
If writing a custom integration, the following recommendations may be useful:
+* Always be comfortable installing and running the process yourself before attempting to automate
+ it.
+
* For the software to be installed, use its Installation and Admin guides to ensure best practices
are being followed. Use blogs and advice from experts, when available.
@@ -98,8 +152,32 @@ If writing a custom integration, the following recommendations may be useful:
For example, if deploying a MongoDB cluster then first focus on single-node MongoDB, and then make that
configurable and composable for a cluster.
-* Use the test framework to write test cases, so that others can run these to confirm that the
- entity works in their environment.
-
* Where appropriate, share the new entity with the Brooklyn community so that it can be reviewed,
tested and improved by others in the community!
+
+
+## Cloud Portability
+
+You get a lot of support out-of-the-box for deploying blueprints to different clouds. The points
+below may also be of help:
+
+* Test (and regression test) on each target cloud.
+
+* Be aware that images on different clouds can be very different. For example, two CentOS 6.6 VMs
+ might have different pre-installed libraries, different default iptables or SE Linux settings,
+ different repos, different sudo configuration, etc.
+
+* Different clouds handle private and public IPs differently. One must be careful about which
+ address to advertise to for use by other entities.
+
+* VMs on some clouds may not have a well-configured hostname (e.g. `ping $(hostname)` can fail).
+
+* VMs in different clouds have a different number of NICs. This is important when choosing whether
+ to listen on 0.0.0.0 or on a specific NIC.
+
+
+## Investigating Errors
+
+ALWAYS keep logs when there is an error.
+
+See the [Troubleshooting]({{ site.path.guide }}/ops/troubleshooting/) guide for more information.
[2/2] brooklyn-docs git commit: This closes #93
Posted by al...@apache.org.
This closes #93
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/95e2ce5a
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/95e2ce5a
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/95e2ce5a
Branch: refs/heads/master
Commit: 95e2ce5a45f69c132a78b8861f9d10160e7b5e06
Parents: 8567739 cf24d4a
Author: Aled Sage <al...@gmail.com>
Authored: Wed Jul 20 13:59:02 2016 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Wed Jul 20 13:59:02 2016 +0100
----------------------------------------------------------------------
guide/yaml/blueprinting-tips.md | 114 +++++++++++++++++++++++++++++------
1 file changed, 96 insertions(+), 18 deletions(-)
----------------------------------------------------------------------