Additional docs, :package default

- Ensure :package is the default installation method everywhere, update docs to reflect. Fixes #389.
- Ensure defaults for :package and :tarball are clear; remove incorrect comment on resource. Fixes #391.
- Ensure actions are firing correctly when providers really do updates, so restarting is easier. Fixes #394.
- Drastically clarify elasticsearch_plugin docs, allow URL specifier for installs. Fixes #392.
- Re-comment the node role in the configure resource to be more plain. Fixes #393.
- Pass through default service notifications from elasticsearch_service to service. Fixes #392.

.kitchen.yml

@@ -35,28 +35,30 @@ platforms:
     - recipe[elasticsearch_test::fix_nss] # see recipe header
 
 suites:
-  - name: default # install by tarball
+  - name: tarball # install by tarball
     require_chef_omnibus: 12.5.1
     run_list:
       - recipe[java]
       - recipe[elasticsearch_test::default_with_plugins]
-
-  - name: package # install from package
-    require_chef_omnibus: 12.5.1
     attributes:
       elasticsearch:
-        install_type: package
+        install_type: tarball
 
+  - name: package # install from package
+    require_chef_omnibus: 12.5.1
     run_list:
       - recipe[java]
       - recipe[elasticsearch_test::default_with_plugins]
+    attributes:
+      elasticsearch:
+        install_type: package
 
-  - name: override_default # the override-everything use case
+  - name: override_tarball # the override-everything use case
     driver_config:
       require_chef_omnibus: 12.5.1
     run_list:
       - recipe[java]
-      - recipe[elasticsearch_test::default]
+      - recipe[elasticsearch_test::tarball]
 
   - name: override_package # the override-everything use case
     driver_config:

README.md

@@ -5,11 +5,14 @@ and supports Chef 12.5.1, 12.4.3, 12.3.0, 12.2.1, 12.1.2, and higher. It impleme
 CI as well as more modern testing with chefspec and test-kitchen. It no longer
 supports some of the more extraneous features such as discovery (use [chef search](https://docs.chef.io/chef_search.html) in your wrapper cookbook) or EBS
 device creation (use [the aws cookbook](https://github.com/chef-cookbooks/aws)).
+**Previous versions** of this cookbook may be found using the git tags on this repository.
 
-The previous version of this cookbook may be found in the [0.3.x branch](https://github.com/elastic/cookbook-elasticsearch/tree/0.3.x).
+## Pre-requisites
 
-**NOTE: This cookbook requires java, but does not provide it. Please install
-Java before using any recipe in this cookbook. We recommend [this one](https://github.com/agileorbit-cookbooks/java).**
+[Java Runtime](https://www.java.com/en/) - This cookbook requires java, but does not provide it. Please install
+Java before using any recipe in this cookbook. Please also note that Elasticsearch itself has specific minimum Java version requirements. We recommend [this cookbook](https://github.com/agileorbit-cookbooks/java) to install Java.
+
+[Elasticsearch](https://www.elastic.co/products/elasticsearch) - This cookbook has been upgraded to support Elasticsearch 2.0 and greater. While this cookbook still works with ES 1.7.x at the time of this writing, we expect to eventually **break compatibility in a minor release bump**. If you must have a cookbook that works with older versions of Elasticsearch, please test and then pin to a specific `major.minor` version and only leave the patch release to float.
 
 ## Attributes
 
@@ -18,9 +21,8 @@ of checksums for many different archives and package files of different
 elasticsearch versions. Both recipes and resources/providers here use those
 default values.
 
-Please take note that you may use `%s` in your URL and this cookbook will use
-sprintf/format to insert the version parameter as a string into your
-download_url.
+You may use `%s` in your URL and this cookbook will use sprintf/format to insert
+the version parameter as a string into your download_url.
 
 |Name|Default|Other values|
 |----|-------|------------|
@@ -45,13 +47,47 @@ options.
 
 ## Resources
 
-You should be aware that potentially all resources in this cookbook look each
-other up in the resource collection. By default, they will look for appropriate
-resources named 'default' or 'elasticsearch', as in the examples below. For
-example, if you use `elasticsearch_install 'default'`, `elasticsearch_config`
-will use the first resource to determine how you installed Elasticsearch. If you
-need to override this behavior, all resources accept `instance_name` as an
-additional parameter, to be used for matching.
+## Notifications and Service Restarts
+
+The resources provided in this cookbook **do not automatically restart**
+services when changes have occurred. This has been done to protect you from
+accidental data loss and service outages, as nodes might restart simultaneously
+or may not restart at all when bad configuration values are supplied.
+
+You **must** supply your desired notifications when using each resource if you
+want Chef to automatically restart services. Again, we don't recommend this.
+
+elasticsearch_service will pass through all of the standard `service` resource
+actions to the underlying service resource if you wish to notify it.
+
+### Resource names
+
+Many of the resources provided in this cookbook need to share configuration
+values. For example, the `elasticsearch_service` resource needs to know the path
+to the configuration file(s) generated by `elastcisearch_configure` and the path
+to the actual ES binary installed by `elasticsearch_install`. And they both need
+to know the appropriate system user and group defined by `elasticsearch_user`.
+
+Search order: In order to make this easy, all resources in this cookbook use the following
+search order to locate resources that apply to the same overall
+Elasticsearch setup:
+
+1. Resources that share the same resource name, e.g.:
+1. Resources that share the same value for `instance_name`
+1. Resources named `default`
+1. Resources named `elasticsearch`
+
+Examples of more complicated resource names are left to the reader, but here we
+present a typical example that should work in most cases:
+
+```
+elasticsearch_user 'default'
+elasticsearch_install 'default'
+elasticsearch_configure 'default'
+elasticsearch_service 'default'
+
+elasticsearch_plugin 'mobz/elasticsearch-head'
+```
 
 ### elasticsearch_user
 Actions: `:create`, `:remove`
@@ -225,21 +261,73 @@ even what version it is. So once we install a plugin to a directory, we
 generally assume that is the desired one and we don't touch it further.
 
 See https://github.com/elastic/cookbook-elasticsearch/issues/264 for more info.
+NB: You [may encounter issues on certain distros](http://blog.backslasher.net/java-ssl-crash.html) with NSS 3.16.1 and OpenJDK 7.x.
 
-When running a single instance per machine (VM, etc), it's typically
-sufficient to rely on the default value of `plugin_dir`:
+Officially supported or commercial plugins require just the plugin name:
 
 ```
-elasticsearch_plugin 'mobz/elasticsearch-head'
+elasticsearch_plugin 'analysis-icu' do
+  action :install
+end
+elasticsearch_plugin 'shield' do
+  action :install
+end
+```
+
+Plugins from GitHub require a URL of 'username/repository' or 'username/repository/version':
+
+```
+elasticsearch_plugin 'kopf' do
+  url 'lmenezes/elasticsearch-kopf'
+  action :install
+end
+
+elasticsearch_plugin 'kopf' do
+  url 'lmenezes/elasticsearch-kopf/1.5.7'
+  action :install
+end
+```
+
+Plugins from Maven Central or Sonatype require 'groupId/artifactId/version':
+```
+elasticsearch_plugin 'mapper-attachments' do
+  url 'org.elasticsearch/elasticsearch-mapper-attachments/2.6.0'
+  action :install
+end
+```
+
+Plugins can be installed from a custom URL or file location as follows:
+```
+elasticsearch_plugin 'mapper-attachments' do
+  url 'http://some.domain.name//my-plugin-1.0.0.zip'
+  action :install
+end
+
+elasticsearch_plugin 'mapper-attachments' do
+  url 'file:/path/to/my-plugin-1.0.0.zip'
+  action :install
+end
 ```
 
 To run multiple instances per machine, an explicit `plugin_dir` location
 has to be provided:
 
 ```
-elasticsearch_plugin 'mobz/elasticsearch-head'
+elasticsearch_plugin 'mobz/elasticsearch-head' do
+  plugin_dir '/usr/share/elasticsearch_foo/plugins'
+end
+```
+
+If for some reason, you want to name the resource something else, you may
+provide the plugin name using the `name` parameter:
+
+```
+elasticsearch_plugin 'xyzzy' do
+  name 'kopf'
+  url 'lmenezes/elasticsearch-kopf'
+  action :install
+end
 ```
-NB: You [may encounter issues on certain distros](http://blog.backslasher.net/java-ssl-crash.html) with NSS 3.16.1 and OpenJDK 7.x.
 
 ## Testing
 

attributes/default.rb

@@ -1,6 +1,6 @@
 # elasticsearch version & install type
 default['elasticsearch']['version'] = '2.0.0'
-default['elasticsearch']['install_type'] = :tarball
+default['elasticsearch']['install_type'] = :package
 
 # platform_family keyed download URLs
 default['elasticsearch']['download_urls']['debian'] = 'https://download.elasticsearch.org/elasticsearch/elasticsearch/elasticsearch-%s.deb'