Refactor Blueprinting
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/f38b9e7b Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/f38b9e7b Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/f38b9e7b Branch: refs/heads/master Commit: f38b9e7bbcf745fdb6eb2526a334d26fd03cecfb Parents: 05ba6cf Author: Duncan Godwin <[email protected]> Authored: Wed Apr 12 18:02:16 2017 +0100 Committer: Duncan Godwin <[email protected]> Committed: Wed Apr 12 18:02:16 2017 +0100 ---------------------------------------------------------------------- contributing/inline-children.md | 2 +- contributing/ordering.md | 4 +- contributing/site-structure.md | 2 +- guide/blueprints/advanced-example.md | 283 +++++++++ guide/blueprints/ansible/about-ansible.md | 34 + .../ansible/creating-ansible-blueprints.md | 213 +++++++ guide/blueprints/ansible/index.md | 16 + guide/blueprints/blueprinting-tips.md | 183 ++++++ .../catalog/images/add-to-catalog.png | Bin 0 -> 4919 bytes guide/blueprints/catalog/index.md | 400 ++++++++++++ .../catalog/mysql-in-catalog-w700.png | Bin 0 -> 92767 bytes guide/blueprints/catalog/mysql-in-catalog.png | Bin 0 -> 168831 bytes guide/blueprints/chef/about-chef.md | 50 ++ .../chef/advanced-chef-integration.md | 48 ++ guide/blueprints/chef/chef-call-flow.png | Bin 0 -> 36222 bytes guide/blueprints/chef/creating-blueprints.md | 105 ++++ .../chef/example_yaml/mysql-chef-1.yaml | 24 + .../chef/example_yaml/mysql-chef-2.yaml | 28 + guide/blueprints/chef/index.md | 18 + guide/blueprints/chef/writing-chef.md | 79 +++ guide/blueprints/clusters-and-policies.md | 42 ++ guide/blueprints/clusters.md | 34 + guide/blueprints/configuring-vms.md | 31 + guide/blueprints/creating-yaml.md | 78 +++ guide/blueprints/custom-entities.md | 269 ++++++++ guide/blueprints/enrichers.md | 180 ++++++ guide/blueprints/entity-configuration.md | 548 ++++++++++++++++ .../appserver-clustered-w-db-concise.yaml | 15 + .../example_yaml/appserver-clustered-w-db.yaml | 19 + .../appserver-configured-in-config.yaml | 6 + .../example_yaml/appserver-configured.yaml | 5 + .../appserver-w-db-other-flavor.yaml | 17 + .../blueprints/example_yaml/appserver-w-db.yaml | 15 + .../example_yaml/appserver-w-policy.yaml | 27 + guide/blueprints/example_yaml/cluster-vm.yaml | 13 + .../fabric-with-multiple-locations.yaml | 15 + .../simple-appserver-with-location-byon.yaml | 10 + ...mple-appserver-with-location-per-entity.yaml | 8 + .../simple-appserver-with-location.yaml | 8 + .../example_yaml/simple-appserver.yaml | 4 + guide/blueprints/example_yaml/simple-vm.yaml | 8 + ...est-app-with-enrichers-slightly-simpler.yaml | 58 ++ .../vanilla-bash-netcat-catalog.bom | 36 ++ .../vanilla-bash-netcat-cluster.yaml | 12 + .../example_yaml/vanilla-bash-netcat-env.yaml | 12 + .../example_yaml/vanilla-bash-netcat-file.yaml | 6 + .../vanilla-bash-netcat-more-commands.yaml | 16 + .../vanilla-bash-netcat-port-parameter.yaml | 21 + .../example_yaml/vanilla-bash-netcat-port.yaml | 13 + .../vanilla-bash-netcat-reference.yaml | 5 + .../vanilla-bash-netcat-restarter.yaml | 20 + .../vanilla-bash-netcat-w-client.yaml | 78 +++ .../example_yaml/vanilla-bash-netcat.yaml | 8 + guide/blueprints/index.md | 28 + guide/blueprints/java/archetype.md | 114 ++++ guide/blueprints/java/bundle-dependencies.md | 135 ++++ guide/blueprints/java/common-usage.md | 205 ++++++ guide/blueprints/java/defining-and-deploying.md | 177 ++++++ guide/blueprints/java/entities.md | 223 +++++++ guide/blueprints/java/entitlements.md | 42 ++ guide/blueprints/java/entity.md | 104 +++ guide/blueprints/java/feeds.md | 233 +++++++ .../java/gist_generator/GistGenerator.java | 29 + .../java/gist_generator/GistGeneratorImpl.java | 47 ++ .../java/gist_generator/GistGeneratorTest.java | 20 + .../gist_generator/GistGeneratorYamlTest.java | 39 ++ .../java/gist_generator/gist_create_token.png | Bin 0 -> 390046 bytes .../java/gist_generator/gist_generator.bom | 14 + .../java/gist_generator/gist_grant_access.png | Bin 0 -> 411974 bytes guide/blueprints/java/index.md | 36 ++ .../blueprints/java/java_app/ExampleWebApp.java | 62 ++ guide/blueprints/java/service-state.md | 73 +++ guide/blueprints/java/topology-dependencies.md | 53 ++ .../java/wt-deployed-application-700.png | Bin 0 -> 176494 bytes .../blueprints/java/wt-deployed-application.png | Bin 0 -> 127347 bytes guide/blueprints/java/wt-starting-700.png | Bin 0 -> 303892 bytes guide/blueprints/java/wt-starting.png | Bin 0 -> 332710 bytes .../java/wt-tree-jboss-sensors-700.png | Bin 0 -> 268853 bytes guide/blueprints/java/wt-tree-jboss-sensors.png | Bin 0 -> 169929 bytes guide/blueprints/logstash-snapshot.png | Bin 0 -> 80486 bytes guide/blueprints/multiple-services.md | 97 +++ guide/blueprints/policies.md | 198 ++++++ guide/blueprints/salt/about-salt.md | 38 ++ .../blueprints/salt/creating-salt-blueprints.md | 163 +++++ guide/blueprints/salt/index.md | 16 + guide/blueprints/setting-locations.md | 132 ++++ ...infrastructuredeploymenttestcase-entity.yaml | 11 + .../entities/loopovergroupmembers-entity.yaml | 6 + .../entities/paralleltestcase-entity.yaml | 6 + .../test/example_yaml/entities/script1.sh | 2 + .../example_yaml/entities/testcase-entity.yaml | 6 + .../entities/testeffector-entity.yaml | 8 + .../entities/testhttpcall-entity.yaml | 7 + .../entities/testsensor-entity.yaml | 7 + .../entities/testsshcommand-entity.yaml | 28 + .../testcases/effector-test-snippet.yaml | 28 + .../testcases/getting-started-test-example.yaml | 71 +++ .../testcases/http-test-snippet.yaml | 20 + .../testcases/sensor-test-snippet.yaml | 7 + .../getting-started-blueprint-test-large.png | Bin 0 -> 156553 bytes .../images/getting-started-blueprint-test.png | Bin 0 -> 84906 bytes guide/blueprints/test/index.md | 33 + guide/blueprints/test/test-entities.md | 198 ++++++ guide/blueprints/test/usage-examples.md | 58 ++ guide/blueprints/web-console-yaml-700.png | Bin 0 -> 138229 bytes guide/blueprints/web-console-yaml.png | Bin 0 -> 661136 bytes guide/blueprints/winrm/client.md | 125 ++++ guide/blueprints/winrm/index.md | 630 +++++++++++++++++++ guide/blueprints/yaml-reference.md | 253 ++++++++ guide/index.md | 3 +- guide/java/archetype.md | 114 ---- guide/java/bundle-dependencies.md | 135 ---- guide/java/common-usage.md | 205 ------ guide/java/defining-and-deploying.md | 177 ------ guide/java/enrichers.md | 180 ------ guide/java/entities.md | 223 ------- guide/java/entitlements.md | 42 -- guide/java/entity.md | 104 --- guide/java/feeds.md | 233 ------- guide/java/gist_generator/GistGenerator.java | 29 - .../java/gist_generator/GistGeneratorImpl.java | 47 -- .../java/gist_generator/GistGeneratorTest.java | 20 - .../gist_generator/GistGeneratorYamlTest.java | 39 -- guide/java/gist_generator/gist_create_token.png | Bin 390046 -> 0 bytes guide/java/gist_generator/gist_generator.bom | 14 - guide/java/gist_generator/gist_grant_access.png | Bin 411974 -> 0 bytes guide/java/index.md | 38 -- guide/java/java_app/ExampleWebApp.java | 62 -- guide/java/policies.md | 198 ------ guide/java/service-state.md | 73 --- guide/java/topology-dependencies.md | 53 -- guide/java/wt-deployed-application-700.png | Bin 176494 -> 0 bytes guide/java/wt-deployed-application.png | Bin 127347 -> 0 bytes guide/java/wt-starting-700.png | Bin 303892 -> 0 bytes guide/java/wt-starting.png | Bin 332710 -> 0 bytes guide/java/wt-tree-jboss-sensors-700.png | Bin 268853 -> 0 bytes guide/java/wt-tree-jboss-sensors.png | Bin 169929 -> 0 bytes guide/locations/_AWS.md | 141 +++++ guide/locations/_GCE.md | 89 +++ guide/locations/_azure-ARM.md | 102 +++ guide/locations/_azure-classic.md | 233 +++++++ guide/locations/_byon.md | 77 +++ guide/locations/_clouds.md | 302 +++++++++ guide/locations/_cloudstack.md | 143 +++++ guide/locations/_ibm-softlayer.md | 135 ++++ .../_inheritance-and-named-locations.md | 80 +++ guide/locations/_localhost.md | 48 ++ guide/locations/_openstack.md | 269 ++++++++ guide/locations/_special-locations.md | 117 ++++ guide/locations/_ssh-keys.md | 88 +++ guide/locations/cloud-credentials.md | 6 + guide/locations/index.md | 21 + guide/locations/location-customizers.md | 169 +++++ guide/ops/brooklyn_properties.md | 4 +- guide/ops/catalog/images/add-to-catalog.png | Bin 4919 -> 0 bytes guide/ops/catalog/index.md | 400 ------------ guide/ops/catalog/mysql-in-catalog-w700.png | Bin 92767 -> 0 bytes guide/ops/catalog/mysql-in-catalog.png | Bin 168831 -> 0 bytes guide/ops/index.md | 8 +- guide/ops/locations/_AWS.md | 141 ----- guide/ops/locations/_GCE.md | 89 --- guide/ops/locations/_azure-ARM.md | 102 --- guide/ops/locations/_azure-classic.md | 233 ------- guide/ops/locations/_byon.md | 77 --- guide/ops/locations/_clouds.md | 302 --------- guide/ops/locations/_cloudstack.md | 143 ----- guide/ops/locations/_ibm-softlayer.md | 135 ---- .../_inheritance-and-named-locations.md | 80 --- guide/ops/locations/_localhost.md | 48 -- guide/ops/locations/_openstack.md | 269 -------- guide/ops/locations/_special-locations.md | 117 ---- guide/ops/locations/_ssh-keys.md | 88 --- guide/ops/locations/cloud-credentials.md | 6 - guide/ops/locations/index.md | 21 - guide/ops/locations/location-customizers.md | 169 ----- guide/ops/persistence/index.md | 2 +- guide/ops/production-installation.md | 4 +- guide/start/blueprints.md | 6 +- guide/start/brooklyn.properties | 2 +- guide/start/running.md | 2 +- guide/start/running/control.md | 25 + guide/start/running/index.md | 28 + guide/start/running/install.md | 101 +++ guide/start/running/launch.md | 72 +++ guide/yaml/advanced-example.md | 283 --------- guide/yaml/ansible/about-ansible.md | 34 - .../yaml/ansible/creating-ansible-blueprints.md | 213 ------- guide/yaml/ansible/index.md | 16 - guide/yaml/blueprinting-tips.md | 183 ------ guide/yaml/chef/about-chef.md | 50 -- guide/yaml/chef/advanced-chef-integration.md | 48 -- guide/yaml/chef/chef-call-flow.png | Bin 36222 -> 0 bytes guide/yaml/chef/creating-blueprints.md | 105 ---- guide/yaml/chef/example_yaml/mysql-chef-1.yaml | 24 - guide/yaml/chef/example_yaml/mysql-chef-2.yaml | 28 - guide/yaml/chef/index.md | 18 - guide/yaml/chef/writing-chef.md | 79 --- guide/yaml/clusters-and-policies.md | 42 -- guide/yaml/clusters.md | 34 - guide/yaml/configuring-vms.md | 31 - guide/yaml/creating-yaml.md | 78 --- guide/yaml/custom-entities.md | 269 -------- guide/yaml/entity-configuration.md | 548 ---------------- .../appserver-clustered-w-db-concise.yaml | 15 - .../example_yaml/appserver-clustered-w-db.yaml | 19 - .../appserver-configured-in-config.yaml | 6 - .../yaml/example_yaml/appserver-configured.yaml | 5 - .../appserver-w-db-other-flavor.yaml | 17 - guide/yaml/example_yaml/appserver-w-db.yaml | 15 - guide/yaml/example_yaml/appserver-w-policy.yaml | 27 - guide/yaml/example_yaml/cluster-vm.yaml | 13 - .../fabric-with-multiple-locations.yaml | 15 - .../simple-appserver-with-location-byon.yaml | 10 - ...mple-appserver-with-location-per-entity.yaml | 8 - .../simple-appserver-with-location.yaml | 8 - guide/yaml/example_yaml/simple-appserver.yaml | 4 - guide/yaml/example_yaml/simple-vm.yaml | 8 - ...est-app-with-enrichers-slightly-simpler.yaml | 58 -- .../vanilla-bash-netcat-catalog.bom | 36 -- .../vanilla-bash-netcat-cluster.yaml | 12 - .../example_yaml/vanilla-bash-netcat-env.yaml | 12 - .../example_yaml/vanilla-bash-netcat-file.yaml | 6 - .../vanilla-bash-netcat-more-commands.yaml | 16 - .../vanilla-bash-netcat-port-parameter.yaml | 21 - .../example_yaml/vanilla-bash-netcat-port.yaml | 13 - .../vanilla-bash-netcat-reference.yaml | 5 - .../vanilla-bash-netcat-restarter.yaml | 20 - .../vanilla-bash-netcat-w-client.yaml | 78 --- .../yaml/example_yaml/vanilla-bash-netcat.yaml | 8 - guide/yaml/index.md | 25 - guide/yaml/logstash-snapshot.png | Bin 80486 -> 0 bytes guide/yaml/multiple-services.md | 97 --- guide/yaml/salt/about-salt.md | 38 -- guide/yaml/salt/creating-salt-blueprints.md | 163 ----- guide/yaml/salt/index.md | 16 - guide/yaml/setting-locations.md | 132 ---- ...infrastructuredeploymenttestcase-entity.yaml | 11 - .../entities/loopovergroupmembers-entity.yaml | 6 - .../entities/paralleltestcase-entity.yaml | 6 - .../yaml/test/example_yaml/entities/script1.sh | 2 - .../example_yaml/entities/testcase-entity.yaml | 6 - .../entities/testeffector-entity.yaml | 8 - .../entities/testhttpcall-entity.yaml | 7 - .../entities/testsensor-entity.yaml | 7 - .../entities/testsshcommand-entity.yaml | 28 - .../testcases/effector-test-snippet.yaml | 28 - .../testcases/getting-started-test-example.yaml | 71 --- .../testcases/http-test-snippet.yaml | 20 - .../testcases/sensor-test-snippet.yaml | 7 - .../getting-started-blueprint-test-large.png | Bin 156553 -> 0 bytes .../images/getting-started-blueprint-test.png | Bin 84906 -> 0 bytes guide/yaml/test/index.md | 33 - guide/yaml/test/test-entities.md | 198 ------ guide/yaml/test/usage-examples.md | 58 -- guide/yaml/web-console-yaml-700.png | Bin 138229 -> 0 bytes guide/yaml/web-console-yaml.png | Bin 661136 -> 0 bytes guide/yaml/winrm/client.md | 125 ---- guide/yaml/winrm/index.md | 630 ------------------- guide/yaml/yaml-reference.md | 253 -------- website/index.md | 6 +- 260 files changed, 9167 insertions(+), 8943 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/contributing/inline-children.md ---------------------------------------------------------------------- diff --git a/contributing/inline-children.md b/contributing/inline-children.md index 480f451..e16def5 100644 --- a/contributing/inline-children.md +++ b/contributing/inline-children.md @@ -26,7 +26,7 @@ in the YAML front matter of a page causes the site structure plug-in to look thr containing `section_type: inline` in the YAML front matter. The content from these inline sections can then be included in the page content using the liquid tag `child_content`. This is shown below -in an example from [/guide/ops/locations/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/ops/locations/index.md){:target="_blank"}: +in an example from [/guide/locations/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/locations/index.md){:target="_blank"}: <pre> --- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/contributing/ordering.md ---------------------------------------------------------------------- diff --git a/contributing/ordering.md b/contributing/ordering.md index 428360c..2f3a151 100644 --- a/contributing/ordering.md +++ b/contributing/ordering.md @@ -26,8 +26,8 @@ children: - { path: /guide/start/index.md, section_position: 3.1.2 } - { path: /guide/misc/download.md } - { path: /guide/concepts/index.md } -- { path: /guide/yaml/index.md } -- { path: /guide/java/index.md } +- { path: /guide/blueprints/index.md } +- { path: /guide/blueprints/java/index.md } - { path: /guide/ops/index.md, section_position: 2 } - { path: /guide/misc/index.md } {% endhighlight %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/contributing/site-structure.md ---------------------------------------------------------------------- diff --git a/contributing/site-structure.md b/contributing/site-structure.md index c052e1c..0549d95 100644 --- a/contributing/site-structure.md +++ b/contributing/site-structure.md @@ -22,7 +22,7 @@ children: - { path: /guide/start/index.md } - { path: /guide/misc/download.md } - { path: /guide/concepts/index.md } -- { path: /guide/yaml/index.md } +- { path: /guide/blueprints/index.md } - { path: /guide/java/index.md } - { path: /guide/ops/index.md } - { path: /guide/misc/index.md } http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/advanced-example.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/advanced-example.md b/guide/blueprints/advanced-example.md new file mode 100644 index 0000000..6513191 --- /dev/null +++ b/guide/blueprints/advanced-example.md @@ -0,0 +1,283 @@ +--- +title: YAML Blueprint Advanced Example +layout: website-normal +--- + +By this point you should be familiar with the fundamental concepts behind both Apache Brooklyn and YAML blueprints. This section of the documentation is intended to show a complete, advanced example of a YAML blueprint. + +The intention is that this example is used to learn the more in-depth concepts, and also to serve as a reference when writing your own blueprints. This page will first explain what the example application is and how to run it, then it will spotlight interesting features. + + +### ELK Stack Example + +This example demonstrates the deployment of an ELK Stack (Elasticsearch, Logstash and Kibana), using the provided blueprint to deploy, install, run and manage all three. Briefly, the component parts are: + +* Elasticsearch: A clustered search engine +* Logstash: Collects, parses and stores logs. For our example it will store logs in Elasticsearch +* Kibana: A web front end to Elasticsearch + +We also deploy a simple webserver whose logs will be collected. + +* Tomcat 8: Web server whose logs will be stored in Elasticsearch by Logstash. + +For more about the ELK stack, please see the documentation [here](https://www.elastic.co/webinars/introduction-elk-stack). + + +#### The Blueprints +----------- + +There are four blueprints that make up this application. Each of them are used to add one or more catalog items to Brooklyn. You can find them below: + +* [Elasticsearch](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-elasticsearch-catalog.bom) +* [Logstash](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-logstash-catalog.bom) +* [Kibana](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-kibana-catalog.bom) +* [ELK](https://github.com/brooklyncentral/brooklyn-elk/blob/master/brooklyn-elk-catalog.bom) + +#### Running the example +First, add all four blueprints to the Brooklyn Catalog. This can be done by clicking the 'Catalog' tab, clicking the '+' + symbol and pasting the YAML. Once this is done, click the 'Application' tab, then the '+' button to bring up the add +application wizard. A new Catalog application will be available called 'ELK Stack'. Using the add application wizard, +you should be able to deploy an ELK stack to a location of your choosing. Alternatively use the `br` Brooklyn +command line tool and add the files with `br catalog add`. + +#### Exploring the example +After the application has been deployed, you can ensure it is working as expected by checking the following: + +* There is a Kibana sensor called `main.uri`, the value of which points to the Kibana front end. You can explore this +front end, and observe the logs stored in Elasticsearch. Many Brooklyn applications have a `main.uri` set to point you +in the right direction. +* You can also use the Elasticsearch REST API to explore further. The Elasticsearch Cluster entity has a `urls.http.list` +sensor. Using a host:port from that list you will be able to access the REST API. The following URL will give you the +state of the cluster `http://<host:port>/_cluster/health?pretty=true`. As you can see the `number_of_nodes` is +currently 2, indicating that the Elasticsearch nodes are communicating with each other. + +### Interesting Feature Spotlight +We will mainly focus on the Elasticsearch blueprint, and will be clear when another blueprint is being discussed. This blueprint describes a cluster of Elasticsearch nodes. + +#### Provisioning Properties +Our Elasticsearch blueprint has a few requirements of the location in which it is run. Firstly, it must be run on an +Ubuntu machine as the example has been written specifically for this OS. Secondly, two ports must opened to ensure +that the entities can be accessed from the outside world. Both of these requirements are configured via +`provisioning.properties` as follows: + +~~~yaml +brooklyn.config: + elasticsearch.http.port: 9220 + elasticsearch.tcp.port: 9330 + provisioning.properties: + osFamily: ubuntu + inboundPorts: + - $brooklyn:config("elasticsearch.http.port") + - $brooklyn:config("elasticsearch.tcp.port") +~~~ + +#### VanillaSoftwareProcess +When composing a YAML blueprint, the VanillaSoftwareProcess is a very useful entity to be aware of. +A VanillaSoftwareProcess will instruct Brooklyn to provision an instance, and run a series of shell +commands to setup, run, monitor and teardown your program. The commands are specified as configuration +on the VanillaSoftwareProcess and there are several available. We will spotlight a few now. To simplify + this blueprint, we have specified ubuntu only installs so that our commands can be tailored to this + system (e.g. use apt-get rather than yum). + +##### Customize Command +The Customize Command is run after the application has been installed but before it is run. It is the perfect + place to create and amend config files. Please refer to the following section of the Elasticsearch blueprint: + +~~~yaml +customize.command: | + sudo rm -fr sudo tee /etc/elasticsearch/elasticsearch.yml + echo discovery.zen.ping.multicast.enabled: false | sudo tee -a /etc/elasticsearch/elasticsearch.yml + echo discovery.zen.ping.unicast.enabled: true | sudo tee -a /etc/elasticsearch/elasticsearch.yml + echo discovery.zen.ping.unicast.hosts: ${URLS_WITH_BRACKETS} | sudo tee -a /etc/elasticsearch/elasticsearch.yml + echo http.port: ${ES_HTTP_PORT} | sudo tee -a /etc/elasticsearch/elasticsearch.yml + echo transport.tcp.port: ${ES_TCP_PORT} | sudo tee -a /etc/elasticsearch/elasticsearch.yml + echo network.host: ${IP_ADDRESS} | sudo tee -a /etc/elasticsearch/elasticsearch.yml +~~~ + +The purpose of this section is to create a YAML file with all of the required configuration. We use the YAML +literal style `|` indicator to write a multi line command. We start our series of commands by using the `rm` command to remove the +previous config file. We then use `echo` and `tee` to create the new config file and insert the config. Part +of the configuration is a list of all hosts that is set on the parent entity- this is done by using a combination + of the `component` and `attributeWhenReady` DSL commands. More on how this is generated later. + +##### Check running +After an app is installed and run, this command is scheduled to run regularly and used to populate the `service.isUp` +sensor. If this command is not specified, or returns an exit code of anything other than zero, then Brooklyn will +assume that your entity has failed and will display the fire status symbol. Please refer to the following section +of the Elasticsearch blueprint: + +~~~yaml +checkRunning.command: sudo systemctl status kibana.service +~~~ + +There are many different ways to implement this command. For this example, we are simply using the systemctl status +of the appropriate service. + +#### Enrichers + +##### Elasticsearch URLS +To ensure that all Elasticsearch nodes can communicate with each other they need to be configured with the TCP URL +of all other nodes. Similarly, the Logstash instances need to be configured with all the HTTP URLs of the Elasticsearch +nodes. The mechanism for doing this is the same, and involves using Transformers, Aggregators and Joiners, as follows: + +~~~yaml +brooklyn.enrichers: + - type: org.apache.brooklyn.enricher.stock.Transformer + brooklyn.config: + enricher.sourceSensor: $brooklyn:sensor("host.subnet.address") + enricher.targetSensor: $brooklyn:sensor("url.tcp") + enricher.targetValue: $brooklyn:formatString("%s:%s", $brooklyn:attributeWhenReady("host.subnet.address"), $brooklyn:config("elasticsearch.tcp.port")) +~~~ + +In this example, we take the host.subnet.address and append the TCP port, outputting the result as `url.tcp`. +After this has been done, we now need to collect all the URLs into a list in the Cluster entity, as follows: + +~~~yaml +brooklyn.enrichers: + - type: org.apache.brooklyn.enricher.stock.Aggregator + brooklyn.config: + enricher.sourceSensor: $brooklyn:sensor("url.tcp") + enricher.targetSensor: $brooklyn:sensor("urls.tcp.list") + enricher.aggregating.fromMembers: true + +~~~ + +In the preceding example, we aggregated all of the TCP URLs generated in the early example. +These are then stored in a sensor called `urls.tcp.list`. This list is then joined together into one long string: + +~~~yaml +- type: org.apache.brooklyn.enricher.stock.Joiner + brooklyn.config: + enricher.sourceSensor: $brooklyn:sensor("urls.tcp.list") + enricher.targetSensor: $brooklyn:sensor("urls.tcp.string") + uniqueTag: urls.quoted.string +~~~ + +Finally, the string has brackets added to the start and end: + +~~~yaml +- type: org.apache.brooklyn.enricher.stock.Transformer + brooklyn.config: + enricher.sourceSensor: $brooklyn:sensor("urls.tcp.string") + enricher.targetSensor: $brooklyn:sensor("urls.tcp.withBrackets") + enricher.targetValue: $brooklyn:formatString("[%s]", $brooklyn:attributeWhenReady("urls.tcp.string")) +~~~ + +The resulting sensor will be called `urls.tcp.withBrackets` and will be used by all Elasticsearch nodes during setup. + +##### Kibana URL +Kibana also needs to be configured such that it can access the Elasticsearch cluster. However, Kibana can + only be configured to point at one Elasticsearch instance. To enable this, we use another enricher in the + cluster to select the first URL from the list, as follows: + +~~~yaml +- type: org.apache.brooklyn.enricher.stock.Aggregator + brooklyn.config: + enricher.sourceSensor: $brooklyn:sensor("host.subnet.address") + enricher.targetSensor: $brooklyn:sensor("host.address.first") + enricher.aggregating.fromMembers: true + enricher.transformation: + $brooklyn:object: + type: "org.apache.brooklyn.util.collections.CollectionFunctionals$FirstElementFunction" +~~~ + +Similar to the above Aggregator, this Aggregator collects all the URLs from the members of the cluster. +However, this Aggregator specifies a transformation. In this instance a transformation is a Java class that +implements a Guava Function `<? super Collection<?>, ?>>`, i.e. a function that takes in a collection and +returns something. In this case we specify the FirstElementFunction from the CollectionFunctionals to ensure +that we only get the first member of the URL list. + +#### Latches +In the ELK blueprint, there is a good example of a latch. Latches are used to force an entity to wait until +certain conditions are met before continuing. For example: + +~~~yaml +- type: kibana-standalone + id: kibana + name: Kibana Server + customize.latch: $brooklyn:component("es").attributeWhenReady("service.isUp") +~~~ + +This latch is used to stop Kibana customizing until the Elasticsearch cluster is up. We do this to ensure +that the URL sensors have been setup, so that they can be passed into Kibana during the customization phase. + +Latches can also be used to control how many entities can execute the same step at any given moment. When +a latch is given the value of a `MaxConcurrencySensor` it will unblock execution only when there are +available "slots" to execute (think of it as a semaphore). For example to let a single entity execute the +launch step of the start effector: + +~~~yaml +services: +- type: cluster + + brooklyn.initializers: + - type: org.apache.brooklyn.core.sensor.MaxConcurrencySensor + brooklyn.config: + name: single-executor + latch.concurrency.max: 1 + + brooklyn.config: + initialSize: 10 + memberSpec: + $brooklyn:entitySpec: + type: vanilla-bash-server + brooklyn.config: + launch.command: sleep 2 + checkRunning.command: true + launch.latch: $brooklyn:parent().attributeWhenReady("single-executor") +~~~ + +It's important to note that the above setup is not reentrant. This means that users should be careful to +avoid deadlocks. For example having a start and launch latches against the `single-executor` from above. +The launch latch will block forever since the start latch already would've acquired the free slot. + +#### Child entities +The ELK blueprint also contains a good example of a child entity. + +~~~yaml +- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server + brooklyn.config: + children.startable.mode: background_late + ... + brooklyn.children: + - type: logstash-child +~~~ + +In this example, a logstash-child is started as a child of the parent Tomcat server. The Tomcat server needs +to be configured with a `children.startable.mode` to inform Brooklyn when to bring up the child. In this case + we have selected background so that the child is disassociated from the parent entity, and late to specify that + the parent entity should start before we start the child. + +The example also shows how to configure Logstash inputs and filters, if necessary, for a particular application, +in this case Tomcat. + +~~~yaml +- type: logstash-child + name: Logstash + brooklyn.config: + logstash.elasticsearch.hosts: $brooklyn:entity("es").attributeWhenReady("urls.http.withBrackets") + logstash.config.input: + $brooklyn:formatString: + - | + input { + file { + path => "%s/logs/localhost_access_log.*" + start_position => "beginning" + } + } + - $brooklyn:entity("tomcat").attributeWhenReady("run.dir") + logstash.config.filter: | + filter { + grok { + match => { "message" => "%{COMBINEDAPACHELOG}" } + } + date { + match => [ "timestamp" , "dd/MMM/yyyy:HH:mm:ss Z" ] + } + } +~~~ + +Configuring an appropriate visualisation on the Kibana server (access it via the URL on the summary tab for +that entity) allows a dashboard to be created such as + + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/ansible/about-ansible.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/ansible/about-ansible.md b/guide/blueprints/ansible/about-ansible.md new file mode 100644 index 0000000..9886993 --- /dev/null +++ b/guide/blueprints/ansible/about-ansible.md @@ -0,0 +1,34 @@ +--- +title: About Ansible +title_in_menu: About Ansible +layout: website-normal +--- + +## What you need to know about Ansible + +[Ansible](http://docs.ansible.com/ansible/) is a deployment tool designed to work in an agent-less manner, normally +performing its operations on a node over SSH from some central administrating node. Brooklyn can deploy software +via Ansible on one of its managed nodes, by first installing Ansible on the node itself and then using Ansible to deploy +the required software. + +A 'Playbook' in Ansible is a specification of the configuration and deployment of a system. +Playbooks are expressed in YAML format, and contain a number of 'plays', which are in turn lists of tasks to carry out +to achieve the desired configuration on the system. 'Roles' are pre-written modular collections of tasks, and can +be included in playbooks. + +Ansible comes with built-in support for many software systems, and has a community repository of roles exists at +[https://galaxy.ansible.com](https://galaxy.ansible.com). + + +### How Brooklyn interacts with Ansible + +Brooklyn provides a Ansible entity type. An entity of this type can be specified in a blueprint in order to provision the +node through Ansible. The Ansible entity will download Ansible and install it on the node. The entity type supports the +configuration of Ansible playbooks to download, or write inline in the blueprint, for simple playbooks. +Configuration values for the playbooks can be supplied in the blueprint. + +Brooklyn will deploy the software specified in the playbook when the entity starts. In addition, an effector is +provided on the entity that supports general purpose Ansible instructions. + + + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/ansible/creating-ansible-blueprints.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/ansible/creating-ansible-blueprints.md b/guide/blueprints/ansible/creating-ansible-blueprints.md new file mode 100644 index 0000000..845f542 --- /dev/null +++ b/guide/blueprints/ansible/creating-ansible-blueprints.md @@ -0,0 +1,213 @@ +--- +title: Creating Blueprints with Ansible +title_in_menu: Creating Blueprints with Ansible +layout: website-normal +--- + +To write a blueprint to use Ansible with Brooklyn it will help to have a degree of familiarity with Ansible itself. In the +sections below, when the Brooklyn configuration is described, the underlying Ansible operation is also noted briefly, for +clarity for readers who know Ansible. + +To manage a node with Ansible, create a blueprint containing a service of type `org.apache.brooklyn.entity.cm.ansible.AnsibleEntity` +and define and minimum the `playbook` value, and one or other of `playbook.url` or `playbook.yaml`. You must also define +the `service.name` that will be tested in order to determine if the entity is running successfully. + +For example: + + name: myweb + location: ... + services: + - type: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity + id: apache + name: apache + service.name: apache2 + playbook: apache-playbook + playbook.url: http://myhost/projectX/apache-playbook.yaml + + +This example specifies that Brooklyn should use Ansible to download the playbook from the repository on +"myhost". The playbook contains the instructions to install the Apache web server. To start the +entity, Brooklyn will use Ansible's "ansible-playbook" command to run the playbook, which will bring up the web server. + + +### Lifecycle of AnsibleEntity + +The start effector applies the playbook and verifies that it has started the software correctly by checking the service +defined as `service.name` is running. This can be customized, see `ansible.service.start` configuration below. + +The stop effector will stop the service `service.name`. Again, this can be customized, with `ansible.service.stop`. + +The restart effector will apply stop and then start. + + +### Configuration of AnsibleEntity + +The `playbook` configuration key names the top level list of states that will be applied using Ansible. + This configuration key is mandatory. + +The playbook must be defined using one or other (both together are not permitted) of `playbook.yaml` or `playbook.url`. +The former allows the playbook content to be defined inline within the blueprint, using the normal YAML format of an +Ansible playbook. The latter obtains the playbook from an external URL. + +The `ansible.service.start` configuration key allows the blueprint author to override the command used by default to +verify that the service `service.name` is running (or to start it, if the playbook did not specify it should run by +default). The default value is: + + sudo ansible localhost -c local -m service -a "name=<service.name> state=started" + +Similarly the `ansible.service.stop` configuration key permits override of the instruction used to get Ansible to stop the +service, by default + + sudo ansible localhost -c local -m service -a "name=<service.name> state=stopped" + +The `ansible.service.checkPort` configuration key allows the user to override the mechanism used to check that the +service `service.name` is operating. By default Brooklyn checks that the service process is running. However, if the + service is one that listens on a particular port, this configuration key allows the blueprint author to instruct + Brooklyn to check that the port is being listened on, using the Ansible `wait_for` module. The value of the key is + the port number to check. + +The `ansible.vars` configuration key allows the blueprint author to provide entity-specific values for configuration +variables used in the playbook, so that one playbook can be used by multiple entities, each customized appropriately. +The value of `ansible.vars` is an arbitrary block of YAML configuration that will be applied to the playbook using +Ansible's `--extra-vars` mechanism, as described in the +Ansible [documentation](http://docs.ansible.com/ansible/playbooks_variables.html#passing-variables-on-the-command-line). +For example, if the playbook in the example above contained configuration such as: + + - hosts: all + vars: + http_port: 80 + max_clients: 200 + remote_user: root + tasks: + ... + + then to change the port that the webserver in the example above runs on, it would be possible to define the following + in the blueprint: + + name: myweb + location: ... + services: + - type: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity + id: apache + name: apache + service.name: apache2 + playbook: apache-playbook + playbook.url: http://myhost/projectX/apache-playbook.yaml + ansible.vars: + http_port: 8080 + + +### ansibleCall Effector + +The Ansible entity includes a general purpose Ansible effector, `ansibleCommand`, which permits execution of Ansible +commands via `ansible`. It contains a two parameters: +1. `module` specifies the Ansible module to invoke. The default is "command". +2. `args` specifies the argument data for the Ansible module. For example, to download an additional file for the +webserver, the command could be invoked with the following arguments. (For convenience this +example uses the client CLI, "br", but the effector could be invoked by any applicable means, e.g. via the web UI +or REST API.) + + $ br app myweb ent apache effector ansibleCommand invoke \ + -P module=shell -P args='curl http://myhost:8080/additional.html > /var/www/html/additional.html' + +### Roles and Multi-Playbook Installations + +There is no specific configuration in AnsibleEntity for Ansible [Roles](http://docs.ansible.com/ansible/playbooks_roles.html), + or to install multiple playbooks. However, the installation of roles or multiple playbooks can be carried out first + by taking advantage of Brooklyn's SameServerEntity. The installation step can be applied in one child of the same server + entity, while the AnsibleEntity can operate under the second child. It will typically be necessary to delay the start + of the AnsibleEntity until the first child has carried out whatever preparation is required. The examples below + illustrate the concept (with just one playbook, for brevity). + + One way to a achieve this, as with any Brooklyn entity, is to use the idiom of making it a child of a BasicApplication + with a start latch waiting on the first child, such as in the following example, which installs the standalone Tomcat example, + with its playbook and roles, from the "Ansible Examples" Github site. + (Note, this is designed for installation on Redhat/Centos 6.) + The first child in the SameServerEntity downloads + and unpacks the Ansible examples. This might also install standalone Ansible roles, or whatever other resources the + AnsibleEntity might require. The second child uses `attributeWhenReady` to block until the first is ready, before + starting the AnsibleEntity to apply the desired playbook. + + + name: multi + location: + red1 + services: + - serviceType: brooklyn.entity.basic.SameServerEntity + name: Entities + brooklyn.children: + + - serviceType: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity + id: bootstrap + service.name: crond + playbook: bootstrap + playbook.yaml: | + --- + - hosts: localhost + tasks: + - shell: printf "[tomcat-servers]\nlocalhost ansible_connection=local\n" >> /etc/ansible/hosts + - file: path=/etc/ansible/playbooks state=directory mode=0755 + - get_url: url=https://github.com/ansible/ansible-examples/archive/master.zip dest=/tmp/master.zip mode=0440 + - command: unzip -o -d /etc/ansible/playbooks /tmp/master.zip + + - serviceType: org.apache.brooklyn.entity.stock.BasicApplication + start.latch: $brooklyn:entity("bootstrap").attributeWhenReady("service.isUp") + brooklyn.children: + - type: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity + name: test + service.name: tomcat + playbook: tomcat + playbook.yaml: | + --- + - hosts: localhost + - include: /etc/ansible/playbooks/ansible-examples-master/tomcat-standalone/site.yml + vars: + http_port: 8080 + https_port: 8443 + admin_username: admin + admin_password: secret + + +An alternative to the above is to use Ansible itself to do the waiting, as in the variant below, which uses AnsibleEntity +itself in the first SameServerEntity child, to install the required material. In the second child, which is simply an +AnsibleEntity rather than a BasicApplication, Ansible's `wait_for` operation is used as the first step in the playbook, +to block the remaining steps in its playbook until the first is complete. + + name: multi + location: + red1 + services: + - serviceType: brooklyn.entity.basic.SameServerEntity + name: Entities + brooklyn.children: + + - serviceType: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity + id: bootstrap + service.name: crond + playbook: bootstrap + playbook.yaml: | + --- + - hosts: localhost + tasks: + - command: rm -f /tmp/bootstrap.done + - shell: printf "[tomcat-servers]\nlocalhost ansible_connection=local\n" >> /etc/ansible/hosts + - file: path=/etc/ansible/playbooks state=directory mode=0755 + - get_url: url=https://github.com/ansible/ansible-examples/archive/master.zip dest=/tmp/master.zip mode=0440 + - command: unzip -o -d /etc/ansible/playbooks /tmp/master.zip + - file: path=/tmp/bootstrap.done state=touch + + - serviceType: org.apache.brooklyn.entity.cm.ansible.AnsibleEntity + name: test + service.name: tomcat + playbook: tomcat + playbook.yaml: | + --- + - tasks: + - wait_for: path=/tmp/bootstrap.done + include: /etc/ansible/playbooks/ansible-examples-master/tomcat-standalone/site.yml + vars: + http_port: 8080 + https_port: 8443 + admin_username: admin + admin_password: secret + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/ansible/index.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/ansible/index.md b/guide/blueprints/ansible/index.md new file mode 100644 index 0000000..a2376d1 --- /dev/null +++ b/guide/blueprints/ansible/index.md @@ -0,0 +1,16 @@ +--- +title: Ansible in YAML Blueprints +layout: website-normal +children: +- about-ansible.md +- creating-ansible-blueprints.md +--- + +This guide describes how Brooklyn entities can be created using the Ansible infrastructure management tool + ([ansible.com](http://ansible.com)). +At present Brooklyn provides basic support for Ansible, operating in a 'masterless' mode. +Comments on this support and suggestions for further development are welcome. + +This guide assumes you are familiar with the basics of [creating YAML blueprints](../). + +{% include list-children.html %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/blueprinting-tips.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/blueprinting-tips.md b/guide/blueprints/blueprinting-tips.md new file mode 100644 index 0000000..9712fef --- /dev/null +++ b/guide/blueprints/blueprinting-tips.md @@ -0,0 +1,183 @@ +--- +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. + + +## 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 +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 Bring Your Own Nodes (BYON) + +A [BYON location]({{ site.path.guide }}/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. + +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. + +These VMs should mirror the target environment as much as possible. + + +#### 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 Clocker + +Docker containers provide a convenient way to test blueprints (and also to run blueprints in +production!). + +The [Clocker project](http://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. + + +#### 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 (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 }}/blueprints/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. + +* 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. + +* 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. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/catalog/images/add-to-catalog.png ---------------------------------------------------------------------- diff --git a/guide/blueprints/catalog/images/add-to-catalog.png b/guide/blueprints/catalog/images/add-to-catalog.png new file mode 100644 index 0000000..0565e7e Binary files /dev/null and b/guide/blueprints/catalog/images/add-to-catalog.png differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/catalog/index.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/catalog/index.md b/guide/blueprints/catalog/index.md new file mode 100644 index 0000000..d4605b0 --- /dev/null +++ b/guide/blueprints/catalog/index.md @@ -0,0 +1,400 @@ +--- +title: Catalog +layout: website-normal +children: +- { section: General YAML Schema } +- { section: Catalog Metadata } +- { section: Catalog YAML Examples } +- { section: Templates and the Add-Application Wizard, title: Templates } +- { section: Adding to the Catalog, title: Adding and Deleting } +- { section: Versioning } +- { section: brooklyn-server-command-line-arguments, title: CLI Options } + +--- + +Apache Brooklyn provides a **catalog**, which is a persisted collection of versioned blueprints +and other resources. A set of blueprints is loaded from the `default.catalog.bom` in the Brooklyn +folder by default and additional ones can be added through the web console or CLI. Blueprints in +the catalog can be deployed directly, via the Brooklyn CLI or the web console, or referenced in +other blueprints using their `id`. + + +### Catalog Items YAML Syntax + +An item or items to be added to the catalog is defined by a YAML file, +specifying the catalog metadata for the items and the actual blueprint or resource definition. + + +#### General YAML Schema + +Catalog items can be defined using the general structure below: + +~~~ yaml +brooklyn.catalog: + <catalog-metadata> + items: + - <additional-catalog-metadata> + item: + <blueprint-or-resource-definition> + - <additional-catalog-metadata> + item: + <blueprint-or-resource-definition> +~~~ + +Alternatively, a single catalog item can be defined using the following general structure: + +~~~ yaml +brooklyn.catalog: + <catalog-metadata> + item: + <blueprint-or-resource-definition> +~~~ + +For example, the YAML below adds to the catalog a Tomcat entity with some additional default +configuration: + +~~~ yaml +brooklyn.catalog: + items: + - id: tomcat-server + version: "1.0.0" + itemType: entity + item: + type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server + brooklyn.config: + webapp.enabledProtocols: https + httpsSsl: + url: classpath://org/apache/brooklyn/entity/webapp/sample-java-keystore.jks + alias: myname + password: mypass +~~~ + + +#### Catalog Metadata + +Catalog metadata fields supply the additional information required in order to register an item in the catalog. +These fields can be supplied as `key: value` entries +where either the `<catalog-metadata>` or `<additional-catalog-metadata>` placeholders are, +with the latter overriding the former unless otherwise specified below. + +The following metadata is *required* for all items: + +- `id`: a human-friendly unique identifier for how this catalog item will be referenced from blueprints +- `version`: multiple versions of a blueprint can be installed and used simultaneously; + this field disambiguates between blueprints of the same `id`. + Note that this is typically *not* the version of the software being installed, + but rather the version of the blueprint. For more information on versioning, see below. + (Also note YAML treats numbers differently to Strings. Explicit quotes are recommended, to avoid + `1.10` being interpretted as the number `1.1`.) +- `itemType`: the type of the item being defined. The supported item types are: + - `entity` + - `template` + - `policy` + - `location` + +To reference a catalog item in another blueprint, simply reference its ID and optionally its version number. +For instance, if we've added an item with metadata `{ id: datastore, version: "1.0" }` (such as the example below), +we could refer to it in another blueprint with: + +~~~ yaml +services: +- type: datastore:1.0 +~~~ + +In addition to the above fields, exactly **one** of the following is also required: + +- `item`: the YAML for an entity, or policy, or location specification + (a map containing `type` and optional `brooklyn.config`). For a "template" item, it + should be a map containing `services` (i.e. the usual YAML format for a full application + blueprint). **Or** +- `items`: a list of catalog items, where each entry in the map follows the same schema as + the `brooklyn.catalog` value, and the keys in these map override any metadata specified as + a sibling of this `items` key (or, in the case of `brooklyn.libraries` they add to the list); + if there are references between items, then order is important: + `items` are processed in order, depth-first, and forward references are not supported. Entries + can be URL to another catalog file to include, inheriting the metadata from the current hierarchy. + Libraries defined so far in the metadata will be used to load classpath entries. For example: + +~~~ yaml +brooklyn.catalog: + brooklyn.libraries: + - http://some.server.or.other/path/my.jar + items: + - classpath://my-catalog-entries-inside-jar.bom + - some-property: value + include: classpath://more-catalog-entries-inside-jar.bom + - id: use-from-my-catalog + version: "1.0.0" + itemType: entity + item: + type: some-type-defined-in-my-catalog-entries + brooklyn.config: + some.config: "some value" +~~~ + +The following optional catalog metadata is supported: + +- `name`: a nicely formatted display name for the item, used when presenting it in a GUI. +- `description`: supplies an extended textual description for the item. +- `iconUrl`: points to an icon for the item, used when presenting it in a GUI. + The URL prefix `classpath` is supported but these URLs may *not* refer to resources in any OSGi + bundle in the `brooklyn.libraries` section (to prevent requiring all OSGi bundles to be loaded + at launch). Icons are instead typically installed either at the web server from which the OSGi + bundles or catalog items are supplied or in the `conf` folder of the Brooklyn distro. +- `scanJavaAnnotations` [experimental; deprecated]: if provided (as `true`), this will scan any + locally provided library URLs for types annotated `@Catalog` and extract metadata to include + them as catalog items. If no libraries are specified this will scan the default classpath. + This feature will likely be removed. + Also note that external OSGi dependencies are not supported + and other metadata (such as versions, etc) may not be applied. +- `brooklyn.libraries`: a list of pointers to OSGi bundles required for the catalog item. + This can be omitted if blueprints are pure YAML and everything required is included in the classpath and catalog. + Where custom Java code or bundled resources is needed, however, OSGi JARs supply + a convenient packaging format and a very powerful versioning format. + Libraries should be supplied in the form + `brooklyn.libraries: [ "http://...";, "http://..."; ]`, + or as + `brooklyn.libraries: [ { name: symbolic-name, version: "1.0", url: http://... }, ... ]` if `symbolic-name:1.0` + might already be installed from a different URL and you want to skip the download. + Note that these URLs should point at immutable OSGi bundles; + if the contents at any of these URLs changes, the behaviour of the blueprint may change + whenever a bundle is reloaded in a Brooklyn server, + and if entities have been deployed against that version, their behavior may change in subtle or potentially incompatible ways. + To avoid this situation, it is highly recommended to use OSGi version stamps as part of the URL. +- `include`: A URL to another catalog file to include, inheriting the meta from the current hierarchy. + Libraries defined so far in the meta will be used to load classpath entries. `include` must be used + when you have sibling properties. If it's the only property it may be skipped by having the URL as the + value - see `items` example above. + + +#### Catalog YAML Examples + +##### A Simple Example + +The following example installs the `RiakNode` entity, making it also available as an application template, +with a nice display name, description, and icon. +It can be referred in other blueprints to as `datastore:1.0`, +and its implementation will be the Java class `org.apache.brooklyn.entity.nosql.riak.RiakNode` included with Brooklyn. + +~~~ yaml +brooklyn.catalog: + id: datastore + version: "1.0" + itemType: template + iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png + name: Datastore (Riak) + description: Riak is an open-source NoSQL key-value data store. + item: + services: + - type: org.apache.brooklyn.entity.nosql.riak.RiakNode + name: Riak Node +~~~ + + +##### Multiple Items + +This YAML will install three items: + +~~~ yaml +brooklyn.catalog: + version: "1.1" + iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png + description: Riak is an open-source NoSQL key-value data store. + items: + - id: riak-node + itemType: entity + item: + type: org.apache.brooklyn.entity.nosql.riak.RiakNode + name: Riak Node + - id: riak-cluster + itemType: entity + item: + type: org.apache.brooklyn.entity.nosql.riak.RiakCluster + name: Riak Cluster + - id: datastore + name: Datastore (Riak Cluster) + itemType: template + item: + services: + - type: riak-cluster + brooklyn.config: + # the default size is 3 but this can be changed to suit your requirements + initial.size: 3 + provisioning.properties: + # you can also define machine specs + minRam: 8gb +~~~ + +The items this will add to the catalog are: + +- `riak-node`, as before, but with a different name +- `riak-cluster` as a convenience short name for the `org.apache.brooklyn.entity.nosql.riak.RiakCluster` class +- `datastore`, now pointing at the `riak-cluster` blueprint, in SoftLayer and with the given size and machine spec, + as the default implementation for anyone + requesting a `datastore` (and if installed atop the previous example, new references to `datastore` + will access this version because it is a higher number); + because it is a template, users will have the opportunity to edit the YAML (see below). + (This must be supplied after `riak-cluster`, because it refers to `riak-cluster`.) + + +#### Locations in the Catalog + +In addition to blueprints, locations can be added to the Apache Brooklyn catalog. The example below shows a location for the vagrant configuration used in the [getting started guide]({{ site.path.guide }}/start/blueprints.html), formatted as a catalog entry. + +~~~ yaml +brooklyn.catalog: + id: vagrant + version: "1.0" + itemType: location + name: Vagrant getting started location + item: + type: byon + brooklyn.config: + user: vagrant + password: vagrant + hosts: + - 10.10.10.101 + - 10.10.10.102 + - 10.10.10.103 + - 10.10.10.104 +~~~ + +Once this has been added to the catalog it can be used as a named location in yaml blueprints using: + +~~~ yaml +location: vagrant +~~~ + + +#### Legacy Syntax + +The following legacy and experimental syntax is also supported, but deprecated: + +~~~ yaml +<blueprint-definition> +brooklyn.catalog: + <catalog-metadata> +~~~ + +In this format, the `brooklyn.catalog` block is optional; +and an `id` in the `<blueprint-definition>` will be used to determine the catalog ID. +This is primarily supplied for OASIS CAMP 1.1 compatibility, +where the same YAML blueprint can be POSTed to the catalog endpoint to add to a catalog +or POSTed to the applications endpoint to deploy an instance. +(This syntax is discouraged as the latter usage, +POSTing to the applications endpoint, +will ignored the `brooklyn.catalog` information; +this means references to any `item` blocks in the `<catalog-metadata>` will not be resolved, +and any OSGi `brooklyn.libraries` defined there will not be loaded.) + + + +### Templates and the Add-Application Wizard + +A `template` is a full application. It consists of one or more entities inside an application +(though this is also composable: it can be used as part of another application). +When a `template` is added to the catalog, the blueprint will appear in the 'Create Application' dialog +as shown here: + +[](mysql-in-catalog.png) + + + +### Catalog Management + +The Catalog tab in the web console will show all versions of catalog items, +and allow you to add new items. + + +#### Adding to the Catalog + +On the UI the "add" button <img src="images/add-to-catalog.png" width="24" alt="add-to-catalog" /> at the top of the menu panel allows the +addition of new Applications to the catalog, via YAML, and of new Locations. + +In addition to the GUI, items can be added to the catalog via the REST API +with a `POST` of the YAML file to `/v1/catalog` endpoint. +To do this using `curl`: + +~~~ bash +curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/riak.catalog.bom +~~~ + +Or using the CLI: + +~~~ bash +br catalog add /path/to/riak.catalog.bom +~~~ + + + +#### Deleting from the Catalog + +On the UI, if an item is selected, a 'Delete' button in the detail panel can be used to delete it from the catalog. + +Using the REST API, you can delete a versioned item from the catalog using the corresponding endpoint. +For example, to delete the item with id `datastore` and version `1.0` with `curl`: + +~~~ bash +curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/applications/datastore/1.0 +~~~ + + +**Note:** Catalog items should not be deleted if there are running apps which were created using the same item. +During rebinding the catalog item is used to reconstruct the entity. + +If you have running apps which were created using the item you wish to delete, you should instead deprecate the catalog item. +Deprecated catalog items will not appear in the add application wizard, or in the catalog list but will still +be available to Brooklyn for rebinding. The option to display deprecated catalog items in the catalog list will be added +in a future release. + +Deprecation applies to a specific version of a catalog item, so the full +id including the version number is passed to the REST API as follows: + +~~~ bash +curl -u admin:password -X POST http://127.0.0.1:8081/v1/catalog/entities/MySQL:1.0/deprecated/true +~~~ + + +### Versioning + +Version numbers follow the OSGi convention. This can have a major, minor, micro and qualifier part. +For example, `1.0`. `1.0.1` or `1.0.1-20150101`. + +The combination of `id:version` strings must be unique across the catalog. +It is an error to deploy the same version of an existing item: +to update a blueprint, it is recommended to increase its version number; +alternatively in some cases it is permitted to delete an `id:version` instance +and then re-deploy. +If no version is specified, re-deploying will automatically +increment an internal version number for the catalog item. + +When referencing a blueprint, if a version number is not specified +the latest non-snapshot version will be loaded when an entity is instantiated. + + +### Brooklyn Server Command Line Arguments + +The command line arguments when launching `brooklyn` include several commands for working with the catalog. + +* `--catalogAdd <file.bom>` will add the catalog items in the `bom` file +* `--catalogReset` will reset the catalog to the initial state + (based on `brooklyn/default.catalog.bom` on the classpath, by default in a dist in the `conf/` directory) +* `--catalogInitial <file.bom>` will set the catalog items to use on first run, + on a catalog reset, or if persistence is off + +If `--catalogInitial` is not specified, the default initial catalog at `brooklyn/default.catalog.bom` will be used. +As `scanJavaAnnotations: true` is set in `default.catalog.bom`, Brooklyn will scan the classpath for catalog items, +which will be added to the catalog. +To launch Brooklyn without initializing the catalog, use `--catalogInitial classpath://brooklyn/empty.catalog.bom` + +If [persistence](../../ops/persistence/) is enabled, catalog additions will remain between runs. If items that were +previously added based on items in `brooklyn/default.catalog.bom` or `--catalogInitial` are +deleted, they will not be re-added on subsequent restarts of brooklyn. I.e. `--catalogInitial` is ignored +if persistence is enabled and persistent state has already been created. + +For more information on these commands, run `brooklyn help launch`. + + +<!-- +TODO: make test cases from the code snippets here, and when building the docs assert that they match test cases +--> http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/catalog/mysql-in-catalog-w700.png ---------------------------------------------------------------------- diff --git a/guide/blueprints/catalog/mysql-in-catalog-w700.png b/guide/blueprints/catalog/mysql-in-catalog-w700.png new file mode 100644 index 0000000..f370249 Binary files /dev/null and b/guide/blueprints/catalog/mysql-in-catalog-w700.png differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/catalog/mysql-in-catalog.png ---------------------------------------------------------------------- diff --git a/guide/blueprints/catalog/mysql-in-catalog.png b/guide/blueprints/catalog/mysql-in-catalog.png new file mode 100644 index 0000000..685455d Binary files /dev/null and b/guide/blueprints/catalog/mysql-in-catalog.png differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/chef/about-chef.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/about-chef.md b/guide/blueprints/chef/about-chef.md new file mode 100644 index 0000000..8f87d07 --- /dev/null +++ b/guide/blueprints/chef/about-chef.md @@ -0,0 +1,50 @@ +--- +title: About Chef +title_in_menu: About Chef +layout: website-normal +--- + +## What you need to know about Chef + +Chef works in two different modes, *server* and *solo*. *Server* is where the Chef client talks to a central server +to retrieve information about its roles, policies and cookbooks (where a cookbook defines how to install and +configure a particular piece of software). With *solo*, the client works in isolation, therefore its configuration +and cookbooks must be supplied by another means. + +Chef *client* is the Chef agent. This is a Ruby application which is installed on each and every managed host. When +invoked in server mode, it will contact the Chef server to check for updates to cookbooks and policy; it then "runs" +the recipes in its run lists, to converge the machine to a known state. In solo mode, it reads the locally-maintained +cookbooks and policies. The client may be run as a daemon that checks the server regularly, or it could merely be +run manually when required. + +The *policy* is a set of rules on the Chef server. A client starts with a set of *attributes*, which could be as +simple as its name and a recipe runlist, or which may involve a more complex set of attributes about how it is to be +configured. The client then augments this with auto-detected metadata - a tool called `ohai` is run that collects +detailed information about the host. Next, the policy on the server modifies these attributes - overriding some, +setting defaults for others - to produce a final set of attributes. It is these which are the input to the recipes. +Finally, the attributes are uploaded to the server where they are stored as metadata for the node, where they can be +inspected and modified by the system operator. + +Also of interest is `knife`, which is the workstation toolkit for Chef. Typically this would be installed on the +operation engineer's workstation, where it would be used to interact with the Chef server and clients. Of particular +interest to us is the *bootstrap* operation, which is used for setting up new Chef clients - given a virtual machine, +it will install the Chef client on it, configure it with enough information to find the Chef server and performs its +first run, and then kicks off the Chef client for the first time. + +There is often a preconception about how a Chef client is bootstrapped; mistakenly, there is the belief that the +`knife` tool configures the Chef server with information about the client, and the client finds out about itself from +the server. This is not the case - the bootstrap operation does not involve `knife` talking to the server. Instead, +`knife` packages up all of the required information and sends it to the client - the client will then introduce +itself to the server, passing on its configuration. + +This diagram summarises the interaction between Brooklyn, the new node, and the various Chef tools. Note that there +is no interaction between the Apache Brooklyn Server and the Chef Server. + +[](chef-call-flow.png) + +### How Brooklyn interacts with Chef + +Brooklyn understands both the *server* and *solo* modes of operation. Server mode utilises the `knife` toolkit, and +therefore `knife` must be installed onto the Apache Brooklyn server and configured appropriately. Solo mode does not have any +special requirements; when running in solo mode, Brooklyn will install and configure the Chef client over SSH, just +like it does most other kinds of entities. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/chef/advanced-chef-integration.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/advanced-chef-integration.md b/guide/blueprints/chef/advanced-chef-integration.md new file mode 100644 index 0000000..0d65286 --- /dev/null +++ b/guide/blueprints/chef/advanced-chef-integration.md @@ -0,0 +1,48 @@ +--- +title: Advanced Chef Integration +title_in_menu: Advanced Chef Integration +layout: website-normal +--- + +### Adding Sensors and Effectors + +Custom sensors and effectors can be added using an `entity.initializer` section in the YAML blueprint. + +One common pattern is to have sensors which extract information from Ohai. +Another common pattern is to install a monitoring agent as part of the run list, +configured to talk to a monitoring store, and then to add a sensor feed which reads data from that store. + +On the effector side, you can add SSH-based effectors in the usual way. +You can also describe additional chef converge targets following the pattern set down in +`ChefLifecycleEffectorTasks`, making use of conveniences in `ChefSoloTasks` and `ChefServerTasks`, +or provide effectors which invoke network API's of the systems under management +(for example to supply the common `executeScript` effector as on the standard `MySqlNode`). + + +### Next Steps: Simpifying sensors and effectors, transferring files, and configuring ports + +The Brooklyn-Chef integration is work in progress, with a few open issues we'd still like to add. +Much of the thinking for this is set forth in the [Google document](https://docs.google.com/a/cloudsoftcorp.com/document/d/18ZwzmncbJgJeQjnSvMapTWg6N526cvGMz5jaqdkxMf8) +indicated earlier. If you'd like to work with us to implement these, please let us know. + + +## Reference + +A general schema for the supported YAML is below: + +{% highlight yaml %} +- type: chef:cookbook_name + cookbook_urls: + cookbook_name: url://for/cookbook.tgz + dependency1: url://for/dependency1.tgz + launch_run_list: [ "cookbook_name::start" ] + launch_attributes: # map of arguments to set in the chef node + service_name: cookbook_service + pid_file: /var/run/cookbook.pid +{% endhighlight %} + +If you are interested in exploring the Java code for creating blueprints, +start with the `TypedToyMySqlEntiyChef` class, which essentially does what this tutorial has shown; +and then move on to the `DynamicToyMySqlEntiyChef` which starts to look at more sophisticated constructs. +(Familiarity with BASH and basic Java blueprints may be useful at that stage.) + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/chef/chef-call-flow.png ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/chef-call-flow.png b/guide/blueprints/chef/chef-call-flow.png new file mode 100644 index 0000000..d899de2 Binary files /dev/null and b/guide/blueprints/chef/chef-call-flow.png differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/chef/creating-blueprints.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/creating-blueprints.md b/guide/blueprints/chef/creating-blueprints.md new file mode 100644 index 0000000..8d30131 --- /dev/null +++ b/guide/blueprints/chef/creating-blueprints.md @@ -0,0 +1,105 @@ +--- +title: Creating Blueprints from Chef +title_in_menu: Creating Blueprints from Chef +layout: website-normal +--- + +In a nutshell, a new Chef-based entity can be defined as a service by specifying +`chef:cookbook_name` as the `service_type`, along with a collection of optional configuration. +An illustrative example is below: + +{% highlight yaml %} +{% readj example_yaml/mysql-chef-1.yaml %} +{% endhighlight %} + +*This works without any installation: try it now, copying-and-pasting to the Brooklyn console. +(Don't forget to add your preferred `location: some-cloud` to the spec.)* + +Notice, if you target `google-compute-engine` location, you may need to specify `bind_address: 0.0.0.0` for the `mysql` cookbook, as described [here](https://github.com/chef-cookbooks/mysql/blob/46dccac22d282a05ee6a401e10ae8f5f8114fd66/README.md#parameters). + +We'll now walk through the important constituent parts, +and then proceed to describing things which can be done to simplify the deployment. + + +### Cookbook Primary Name + +The first thing to note is the type definition: + + - type: chef:mysql + +This indicates that the Chef entity should be used (`org.apache.brooklyn.entity.chef.ChefEntity`) +to interpret and pass the configuration, +and that it should be parameterised with a `brooklyn.chef.cookbook.primary.name` of `mysql`. +This is the cookbook namespace used by default for determining what to install and run. + + +### Importing Cookbooks + +Next we specify which cookbooks are required and where they can be pulled from: + + cookbook_urls: + mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz + openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz + build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz + +Here, specific versions are being downloaded from the canonical github repository. +Any URL can be used, so long as it is resolvable on either the target machine or the +Brooklyn server; this includes `file:` and `classpath:` URLs. + +The archive can be ZIP or TAR or TGZ. + +The structure of the archive must be that a single folder is off the root, +and in that folder contains the usual Chef recipe and auxiliary files. +For example, the archive might contain `mysql-master/recipes/server.rb`. +Archives such as those above from github match this format. +The name of that folder does not matter, as often they contain version information. +When deployed, these will be renamed to match the short name (the key in the `cookbooks_url` map, +for instance `mysql` or `openssl`). + +If Chef server is configured (see below), this section can be omitted. + + +### Launch Run List and Attributes + +The next part is to specify the Chef run list and attributes to store when launching the entity: + + launch_run_list: + - mysql::server + + launch_attributes: + mysql: + server_root_password: p4ssw0rd + server_repl_password: p4ssw0rd + server_debian_password: p4ssw0rd + +For the `launch_run_list`, you can use either the YAML `- recipe` syntax or the JSON `[ "recipe" ]` syntax. + +The `launch_attributes` key takes a map which will be stored against the `node` object in Chef. +Thus in this example, the parameter `node['mysql']['server_root_password']` required by the mysql blueprint +is set as specified. + +You can of course set many other attributes in this manner, in addition to those that are required! + + +### Simple Monitoring + +The final section determines how Brooklyn confirms that the service is up. +Sophisticated solutions may install monitoring agents as part of the `launch_run_list`, +with Brooklyn configured to read monitoring information to confirm the launch was successful. +However for convenience, two common mechanisms are available out of the box: + + #service_name: mysqld + pid_file: /var/run/mysqld/mysqld.pid + +If `service_name` is supplied, Brooklyn will check the return code of the `status` command +run against that service, ensuring it is 0. (Note that this is not universally reliable, +although it is the same mechanism which Chef typically uses to test status when determining +whether to start a service. Some services, e.g. postgres, will return 0 even if the service +is not running.) + +If a `pid_file` is supplied, Brooklyn will check whether a process with the PID specified in that +file is running. This has been selected for mysql because it appears to be more portable: +the service name varies among OS's: it is `mysqld` on CentOS but `mysql` on Ubuntu! + + + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml b/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml new file mode 100644 index 0000000..bdac530 --- /dev/null +++ b/guide/blueprints/chef/example_yaml/mysql-chef-1.yaml @@ -0,0 +1,24 @@ +name: chef-mysql-sample +services: +- type: chef:mysql + + cookbook_urls: + # only needed for chef solo; URL can be local to brooklyn, or github, etc... + mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz + openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz + build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz + + launch_run_list: [ "mysql::server" ] + launch_attributes: + mysql: + # these attrs are required by the mysql cookbook under node['mysql'] + server_root_password: p4ssw0rd + server_repl_password: p4ssw0rd + server_debian_password: p4ssw0rd + # many others are attrs are supported by the cookbook and can be passed here... + + # how to determine if the process is running and how to kill it + # (supported options are `service_name` and `pid_file`; normally you should just pick one. + # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!) + #service_name: mysqld + pid_file: /var/run/mysqld/mysqld.pid http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml ---------------------------------------------------------------------- diff --git a/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml b/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml new file mode 100644 index 0000000..9e9de9b --- /dev/null +++ b/guide/blueprints/chef/example_yaml/mysql-chef-2.yaml @@ -0,0 +1,28 @@ +name: chef-mysql-sample +services: +- type: chef:mysql + id: db + + cookbook_urls: + # only needed for chef solo; URL can be local to brooklyn, or github, etc... + mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz + openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz + build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz + + launch_run_list: [ "mysql::server" ] + launch_attributes: + mysql: + # these attrs are required by the mysql cookbook under node['mysql'] + server_root_password: $brooklyn:entity("db").config("mysql.password") + server_repl_password: $brooklyn:entity("db").config("mysql.password") + server_debian_password: $brooklyn:entity("db").config("mysql.password") + # many others are attrs are supported by the cookbook and can be passed here... + + # how to determine if the process is running and how to kill it + # (supported options are `service_name` and `pid_file`; normally you should just pick one. + # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!) + #service_name: mysqld + pid_file: /var/run/mysqld/mysqld.pid + +brooklyn.config: + mysql.password: p4ssw0rd
