You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by ha...@apache.org on 2015/12/02 21:27:47 UTC
[1/4] incubator-brooklyn git commit: Docs: adds blueprinting-tips
Repository: incubator-brooklyn
Updated Branches:
refs/heads/master c45fdcd04 -> 45690e3de
Docs: adds blueprinting-tips
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/f87b2bf5
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/f87b2bf5
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/f87b2bf5
Branch: refs/heads/master
Commit: f87b2bf56e1f9d0d7ed18da14c759750e21be5cd
Parents: ed2ad81
Author: Aled Sage <al...@gmail.com>
Authored: Mon Nov 23 13:57:53 2015 +0000
Committer: Aled Sage <al...@gmail.com>
Committed: Tue Nov 24 14:30:02 2015 +0000
----------------------------------------------------------------------
docs/guide/yaml/blueprinting-tips.md | 105 ++++++++++++++++++++++++++++++
docs/guide/yaml/index.md | 1 +
2 files changed, 106 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/f87b2bf5/docs/guide/yaml/blueprinting-tips.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/blueprinting-tips.md b/docs/guide/yaml/blueprinting-tips.md
new file mode 100644
index 0000000..6f02746
--- /dev/null
+++ b/docs/guide/yaml/blueprinting-tips.md
@@ -0,0 +1,105 @@
+---
+title: Blueprinting Tips
+layout: website-normal
+---
+
+## YAML Recommended
+
+The recommended way to write a blueprint is as a YAML file. This is true both for building
+an application out of existing blueprints, and for building new integrations.
+
+The use of Java is reserved for those use-cases where the provisioning or configuration logic
+is very complicated.
+
+
+## Faster Dev-Test
+
+Writing a blueprint is most efficient and simple when testing is fast, and when testing is
+done incrementally as features of the blueprint are written.
+
+The slowest stages of deploying a blueprint are usually VM provisioning and downloading/installing
+of artifacts (e.g. RPMs, zip files, etc).
+
+Options for speeding up provisioning include those below.
+
+### Deploying to the "localhost" location
+
+This is fast and simple, but has some obvious downsides:
+
+* Artifacts are installed directly on your desktop/server.
+
+* The artifacts installed during previous runs can interfere with subsequent runs.
+
+* Some entities require `sudo` rights, which must be granted to the user running Brooklyn.
+
+
+### Deploying to Bring Your Own Nodes (BYON)
+
+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.
+
+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.
+
+
+### Deploying to Clocker
+
+Docker containers provide a convenient way to test blueprints (and also to run blueprints in
+production!).
+
+The [Clocker project](www.clocker.io) allows the simple setup of Docker Engine(s), and for Docker
+containers to be used instead of VMs. For testing, this allows each run to start from a fresh
+container (i.e. no install artifacts from previous runs), while taking advantage of the speed
+of starting containers.
+
+
+### Caching 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 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/`).
+
+Where installation used something like `apt-get install` or `yum install`, then re-testing the
+install phase will require uninstalling these artifacts manually.
+
+
+## Custom Entity Development
+
+If writing a custom integration, the following recommendations may be useful:
+
+* 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.
+
+* Where there is a choice of installation approaches, use the approach that is most appropriate for
+ production use-cases (even if this is harder to test on locahost). For example,
+ prefer the use of RPMs versus unpacking zip files, and prefer the use of services versus invoking
+ a `bin/start` script.
+
+* Ensure every step is scriptable (e.g. manual install does not involve using a text editor to
+ modify configuration files, or clicking on things in a web-console).
+
+* Write scripts (or Chef recipes, or Puppet manifests, etc), and test these by executing manually.
+ Only once these work in isolation, add them to the entity blueprint.
+
+* Externalise the configuration where appropriate. For example, if there is a configuration file
+ then include a config key for the URL of the configuration file to use. Consider using FreeMarker
+ templating for such configuration files.
+
+* Focus on a single OS distro/version first, and clearly document these assumptions.
+
+* Breakdown the integration into separate components, where possible (and thus develop/test them separately).
+ 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!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/f87b2bf5/docs/guide/yaml/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/index.md b/docs/guide/yaml/index.md
index b0303cb..d299073 100644
--- a/docs/guide/yaml/index.md
+++ b/docs/guide/yaml/index.md
@@ -8,6 +8,7 @@ children:
- clusters.md
- multiple-services.md
- clusters-and-policies.md
+- blueprinting-tips.md
- custom-entities.md
- winrm/
- chef/
[2/4] incubator-brooklyn git commit: Docs: remove guide/dev/rest/
Posted by ha...@apache.org.
Docs: remove guide/dev/rest/
This is covered by docs/guide/ops/rest.md
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/ed2ad81b
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/ed2ad81b
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/ed2ad81b
Branch: refs/heads/master
Commit: ed2ad81b81f975f12375a6a6aa303a157fef82e4
Parents: c89d136
Author: Aled Sage <al...@gmail.com>
Authored: Mon Nov 23 13:57:22 2015 +0000
Committer: Aled Sage <al...@gmail.com>
Committed: Tue Nov 24 14:30:02 2015 +0000
----------------------------------------------------------------------
docs/guide/dev/index.md | 1 -
.../guide/dev/rest/images/rest-api-gui-link.png | Bin 43426 -> 0 bytes
docs/guide/dev/rest/rest-api-doc.md | 19 -------------------
3 files changed, 20 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ed2ad81b/docs/guide/dev/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/index.md b/docs/guide/dev/index.md
index e2d3ed7..2c294b6 100644
--- a/docs/guide/dev/index.md
+++ b/docs/guide/dev/index.md
@@ -14,7 +14,6 @@ children:
- tips/
- tips/logging.md
- tips/debugging-remote-brooklyn.md
-- rest/rest-api-doc.md
- { link: "https://brooklyn.apache.org/v/latest/misc/javadoc", title: "Javadoc" }
---
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ed2ad81b/docs/guide/dev/rest/images/rest-api-gui-link.png
----------------------------------------------------------------------
diff --git a/docs/guide/dev/rest/images/rest-api-gui-link.png b/docs/guide/dev/rest/images/rest-api-gui-link.png
deleted file mode 100644
index f77bf10..0000000
Binary files a/docs/guide/dev/rest/images/rest-api-gui-link.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ed2ad81b/docs/guide/dev/rest/rest-api-doc.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/rest/rest-api-doc.md b/docs/guide/dev/rest/rest-api-doc.md
deleted file mode 100644
index c05750c..0000000
--- a/docs/guide/dev/rest/rest-api-doc.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: REST API Documentation
-layout: website-normal
----
-
-## API Overview
-
-Brooklyn has a comprehensive REST API which can be used to perform all of the actions that
-are possible through the web console, as well as additional functionality exclusive to the API.
-
-Brooklyn uses [Swagger](http://swagger.io/) to generate its REST API and documentation.
-
-## Accessing the API Documentation
-
-The complete REST API can be found in the web console (link pictured below) of your running
-Brooklyn instance.
-Here you can view, as well as execute, every API call that Brooklyn has to offer.
-
-
\ No newline at end of file
[3/4] incubator-brooklyn git commit: Docs: adds security-guidelines
Posted by ha...@apache.org.
Docs: adds security-guidelines
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/4e0a82a0
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/4e0a82a0
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/4e0a82a0
Branch: refs/heads/master
Commit: 4e0a82a0086a6f2279311515b2fa03a49dbd3e5e
Parents: f87b2bf
Author: Aled Sage <al...@gmail.com>
Authored: Mon Nov 23 13:58:14 2015 +0000
Committer: Aled Sage <al...@gmail.com>
Committed: Tue Nov 24 15:08:50 2015 +0000
----------------------------------------------------------------------
docs/guide/ops/index.md | 1 +
docs/guide/ops/security-guidelines.md | 102 +++++++++++++++++++++++++++++
2 files changed, 103 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e0a82a0/docs/guide/ops/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/index.md b/docs/guide/ops/index.md
index bf40c1b..0123997 100644
--- a/docs/guide/ops/index.md
+++ b/docs/guide/ops/index.md
@@ -13,6 +13,7 @@ children:
- externalized-configuration.md
- requirements.md
- production-installation.md
+- security-guidelines.md
- troubleshooting/
---
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4e0a82a0/docs/guide/ops/security-guidelines.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/security-guidelines.md b/docs/guide/ops/security-guidelines.md
new file mode 100644
index 0000000..d8c919d
--- /dev/null
+++ b/docs/guide/ops/security-guidelines.md
@@ -0,0 +1,102 @@
+---
+title: Security Guidelines
+layout: website-normal
+---
+
+## Brooklyn Server
+
+### Web-console and REST api
+
+Users are strongly encouraged to use HTTPS, rather than HTTP.
+
+The use of LDAP is encouraged, rather than basic auth.
+
+Configuration of "entitlements" is encouraged, to lock down access to the REST api for different
+users.
+
+
+### Brooklyn user
+
+Users are strongly discouraged from running Brooklyn as root.
+
+For production use-cases (i.e. where Brooklyn will never deploy to "localhost"), the user under
+which Brooklyn is running should not have `sudo` rights.
+
+
+### Persisted State
+
+Use of an object store is recommended (e.g. using S3 compliant or Swift API) - thus making
+use of the security features offered by the chosen object store.
+
+File-based persistence is also supported. Permissions of the files will automatically
+be 600 (i.e. read-write only by the owner). Care should be taken for permissions of the
+relevant mount points, disks and directories.
+
+
+## Credential Storage
+
+For credential storage, users are strongly encouraged to consider using the "externalised
+configuration" feature. This allows credentials to be retrieved from a store managed by you,
+rather than being stored within YAML blueprints or brooklyn.properties.
+
+A secure credential store is strongly recommended, such as use of
+[HashiCorp's Vault](www.vaultproject.io) - see
+`org.apache.brooklyn.core.config.external.vault.VaultExternalConfigSupplier`.
+
+
+## Infrastructure Access
+
+### Cloud Credentials and Access
+
+Users are strongly encouraged to create separate cloud credentials for Brooklyn's API access.
+
+Users are also encouraged to (where possible) configure the cloud provider for only minimal API
+access (e.g. using AWS IAM).
+
+<!--
+TODO: We should document the minimum requirements for AWS IAM required by Brooklyn
+-->
+
+
+### VM Image Credentials
+
+Users are strongly discouraged from using hard-coded passwords within VM images. Most cloud
+providers/APIs provide a mechanism to instead set an auto-generated password or to create an
+entry in `~/.ssh/authorized_keys` (prior to the VM being returned by the cloud provider).
+
+If a hard-coded credential is used, then Brooklyn can be configured with this "loginUser" and
+"loginUser.password" (or "loginUser.privateKeyData"), and can change the password and disable
+root login.
+
+
+### VM Users
+
+It is strongly discouraged to use the root user on VMs being created or managed by Brooklyn.
+
+
+### SSH keys
+
+Users are strongly encouraged to use SSH keys for VM access, rather than passwords.
+
+This SSH key could be a file on the Brooklyn server. However, a better solution is to use the
+"externalised configuration" to return the "privateKeyData". This better supports upgrading of
+credentials.
+
+
+## Install Artifact Downloads
+
+When Brooklyn executes scripts on remote VMs to install software, it often requires downloading
+the install artifacts. For example, this could be from an RPM repository or to retrieve `.zip`
+installers.
+
+By default, the RPM repositories will be whatever the VM image is configured with. For artifacts
+to be downloaded directly, these often default to the public site (or mirror) for that software
+product.
+
+Where users have a private RPM repository, it is strongly encouraged to ensure the VMs are
+configured to point at this.
+
+For other artifacts, users should consider hosting these artifacts in their own web-server and
+configuring Brooklyn to use this. See the documentation for
+`org.apache.brooklyn.core.entity.drivers.downloads.DownloadProducerFromProperties`.
+
[4/4] incubator-brooklyn git commit: This closes #1064
Posted by ha...@apache.org.
This closes #1064
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/45690e3d
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/45690e3d
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/45690e3d
Branch: refs/heads/master
Commit: 45690e3de367be2dc25cdc3648b0eadd72511959
Parents: c45fdcd 4e0a82a
Author: Hadrian Zbarcea <ha...@apache.org>
Authored: Wed Dec 2 14:54:56 2015 -0500
Committer: Hadrian Zbarcea <ha...@apache.org>
Committed: Wed Dec 2 14:54:56 2015 -0500
----------------------------------------------------------------------
docs/guide/dev/index.md | 1 -
.../guide/dev/rest/images/rest-api-gui-link.png | Bin 43426 -> 0 bytes
docs/guide/dev/rest/rest-api-doc.md | 19 ----
docs/guide/ops/index.md | 1 +
docs/guide/ops/security-guidelines.md | 102 ++++++++++++++++++
docs/guide/yaml/blueprinting-tips.md | 105 +++++++++++++++++++
docs/guide/yaml/index.md | 1 +
7 files changed, 209 insertions(+), 20 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/45690e3d/docs/guide/ops/index.md
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/45690e3d/docs/guide/yaml/index.md
----------------------------------------------------------------------