diff --git a/README.md b/README.md index 7d8eb8be..aa187502 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ The use of a map ensures the Ansible playbook does not need to be updated to ref In addition to the es_config map, several other parameters are supported for additional functions e.g. script installation. These can be found in the role's defaults/main.yml file. -The following illustrates applying configuration parameters to an Elasticsearch instance. By default, Elasticsearch 2.3.4 is installed. +The following illustrates applying configuration parameters to an Elasticsearch instance. By default, Elasticsearch 2.4.3 is installed. ``` - name: Elasticsearch with custom configuration @@ -209,6 +209,99 @@ Then run it: ansible-playbook -i hosts ./your-playbook.yml ``` +### Installing X-Pack Features + +X-Pack features, such as Shield, are supported for Elasticsearch 2.4 only. This feature is currently experimental. To enable X-Pack set the parameter `es_enable_xpack` to true and list the required features in the parameter `es_xpack_features`. The following additional parameters allow X-Pack to be configured: + +* ```es_message_auth_file``` System Key field to allow message authentication. This file should be placed in the 'files' directory. +* ```es_role_mapping``` Role mappings file declared as yml as described [here](https://www.elastic.co/guide/en/shield/current/mapping-roles.html) + +``` +es_role_mapping: + power_user: + - "cn=admins,dc=example,dc=com" + user: + - "cn=users,dc=example,dc=com" + - "cn=admins,dc=example,dc=com" +``` + +* ```es_users``` - Users can be declared here as yml. Two sub keys 'native' and 'file' determine the realm under which realm the user is created. Beneath each of these keys users should be declared as yml entries. e.g. + +``` +es_users: + native: + kibana4_server: + password: changeMe + roles: + - kibana4_server + file: + es_admin: + password: changeMe + roles: + - admin + testUser: + password: changeMeAlso! + roles: + - power_user + - user +``` + + +* ```es_roles``` - Elasticsearch roles can be declared here as yml. Two sub keys 'native' and 'file' determine how the role is created i.e. either through a file or http(native) call. Beneath each key list the roles with appropriate permissions, using the file based format described [here] (https://www.elastic.co/guide/en/shield/current/_file_based_roles.html) e.g. + +``` +es_roles: + file: + admin: + cluster: + - all + indices: + - names: '*' + privileges: + - all + power_user: + cluster: + - monitor + indices: + - names: '*' + privileges: + - all + user: + indices: + - names: '*' + privileges: + - read + kibana4_server: + cluster: + - monitor + indices: + - names: '.kibana' + privileges: + - all + native: + logstash: + cluster: + - manage_index_templates + indices: + - names: 'logstash-*' + privileges: + - write + - delete + - create_index +``` + +* ```es_xpack_license``` - X-Pack license. The license should be declared as a json blob. Alternative use Ansible vault or copy the license to the target machine as part of a playbook and access via a lookup e.g. + +``` +es_xpack_license: "{{ lookup('file', '/tmp/license.json') }}" +``` + +X-Pack configuration parameters can be added to the elasticsearch.yml file using the normal `es_config` parameter. + +For a full example see [here](https://github.com/elastic/ansible-elasticsearch/blob/master/test/integration/xpack.yml) + + + ### Additional Configuration Additional parameters to es_config allow the customization of the Java and Elasticsearch versions, in addition to role behaviour. Options include: @@ -219,6 +312,8 @@ Following variables affect the versions installed: * ```es_version``` (e.g. "2.4.2"). * ```es_api_host``` The host name used for actions requiring HTTP e.g. installing templates. Defaults to "localhost". * ```es_api_port``` The port used for actions requiring HTTP e.g. installing templates. Defaults to 9200. +* ```es_api_basic_auth_username``` The Elasticsearch username for making admin changing actions. Used if Shield is enabled. Ensure this user is admin. +* ```es_api_basic_auth_password``` The password associated with the user declared in `es_api_basic_auth_username` * ```es_start_service``` (true (default) or false) * ```es_plugins_reinstall``` (true or false (default) ) * ```es_plugins``` an array of plugin definitions e.g.: @@ -239,7 +334,7 @@ es_java_opts: Earlier examples illustrate the installation of plugins for 2.x. The correct use of this parameter varies depending on the version of Elasticsearch being installed: - 2.x. - For officially supported plugins no version or source delimiter is required. The plugin script will determine the appropriate plugin version based on the target Elasticsearch version. - For community based plugins include the full path e.g. "lmenezes/elasticsearch-kopf" and the appropriate version for the target version of Elasticsearch. + For community based plugins include the full path e.g. "lmenezes/elasticsearch-kopf" and the appropriate version for the target version of Elasticsearch. This approach should NOT be used for X-Pack related plugins e.g. Shield. See X-Pack below for details here. If installing Marvel or Watcher, ensure the license plugin is also specified. Shield configuration is currently not supported but planned for later versions. @@ -288,7 +383,7 @@ To define proxy only for a particular plugin during its installation: * The role assumes the user/group exists on the server. The elasticsearch packages create the default elasticsearch user. If this needs to be changed, ensure the user exists. * The playbook relies on the inventory_name of each host to ensure its directories are unique * Changing an instance_name for a role application will result in the installation of a new component. The previous component will remain. -* KitchenCI has been used for testing. This is used to confirm images reach the correct state after a play is first applied. We currently test only the latest version of each major release i.e. 1.7.3 and 2.3.4 on +* KitchenCI has been used for testing. This is used to confirm images reach the correct state after a play is first applied. We currently test only the latest version of 2.x on all supported platforms. * The role aims to be idempotent. Running the role multiple times, with no changes, should result in no state change on the server. If the configuration is changed, these will be applied and Elasticsearch restarted where required. diff --git a/defaults/main.yml b/defaults/main.yml index 9e01f25a..dfa55da6 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -1,6 +1,6 @@ --- es_major_version: "2.x" -es_version: "2.3.4" +es_version: "2.4.3" es_version_lock: false es_use_repository: true es_apt_key: "https://packages.elasticsearch.org/GPG-KEY-elasticsearch" diff --git a/test/integration/config-2x/serverspec/default_spec.rb b/test/integration/config-2x/serverspec/default_spec.rb index f416eed2..c7d66859 100644 --- a/test/integration/config-2x/serverspec/default_spec.rb +++ b/test/integration/config-2x/serverspec/default_spec.rb @@ -1,6 +1,6 @@ require 'config_spec' describe 'Config Tests v 2.x' do - include_examples 'config::init', "2.3.4" + include_examples 'config::init', "2.4.3" end diff --git a/test/integration/multi-2x/serverspec/default_spec.rb b/test/integration/multi-2x/serverspec/default_spec.rb index 81637c4e..2772909c 100644 --- a/test/integration/multi-2x/serverspec/default_spec.rb +++ b/test/integration/multi-2x/serverspec/default_spec.rb @@ -2,7 +2,7 @@ describe 'Multi Tests v 2.x' do - include_examples 'multi::init', "2.3.4", ["kopf"] + include_examples 'multi::init', "2.4.3", ["kopf"] end diff --git a/test/integration/package-2x/serverspec/default_spec.rb b/test/integration/package-2x/serverspec/default_spec.rb index 417df476..b452119a 100644 --- a/test/integration/package-2x/serverspec/default_spec.rb +++ b/test/integration/package-2x/serverspec/default_spec.rb @@ -2,5 +2,5 @@ describe 'Package Tests v 2.x' do - include_examples 'package::init', "2.3.4", ["kopf"] + include_examples 'package::init', "2.4.3", ["kopf"] end \ No newline at end of file diff --git a/test/integration/standard-2x/serverspec/default_spec.rb b/test/integration/standard-2x/serverspec/default_spec.rb index 86033b3b..853d28dc 100644 --- a/test/integration/standard-2x/serverspec/default_spec.rb +++ b/test/integration/standard-2x/serverspec/default_spec.rb @@ -2,7 +2,7 @@ describe 'Standard Tests v 2.x' do - include_examples 'standard::init', "2.3.4" + include_examples 'standard::init', "2.4.3" end diff --git a/test/integration/xpack-2x/serverspec/default_spec.rb b/test/integration/xpack-2x/serverspec/default_spec.rb index e4ca2d87..e372a450 100644 --- a/test/integration/xpack-2x/serverspec/default_spec.rb +++ b/test/integration/xpack-2x/serverspec/default_spec.rb @@ -1,5 +1,5 @@ require 'xpack_spec' describe 'Xpack Tests v 2.x' do - include_examples 'xpack::init', "2.3.4" + include_examples 'xpack::init', "2.4.3" end