Ansible role and module to make API calls to Elasticsearch using the official Python Elasticsearch Client.

It only needs to be installed on the host that the API calls are made from. For example, it can be installed on localhost and used to make calls to any Elasticsearch cluster.

It is recommended that all API calls are run only once, either by tagging them with run_once: true, or by running them from a single host. This ensures that Ansible does not make the same API call multiple times, which may cause unintended side effects.

• Access the full power and flexibility of the Elasticsearch APIs from Ansible playbooks
• Full support for all APIs, functions, and arguments in a simple and flexible syntax
• Install any available version of the Python Elasticsearch Client
• Choose not to install the client, if you are just making API calls

• API calls are not indempotent from Ansible's perspective. Every call is sent to Elasticsearch, whether or not changes are needed, and Elasticsearch handles it by its own rules. Elasticsearch may execute some API calls in an indempotent manner (e.g. not creating an index if it already exists), but it is impossible for Ansible to know whether a change has actually taken place.
• For that reason, all API calls are marked as changed: true, even if nothing has actually changed on the Elasticsearch cluster.

Operating System	Release	Status
centos	6
centos	7
debian	wheezy
debian	jessie
ubuntu	precise
ubuntu	trusty

Pip, to install the Python Elasticsearch Client. This role does not install pip; use your preferred role to install it on the host from which the API calls will be made.

• es_py_version: The version of the Python Elasticsearch Client to install, e.g. "1.5.0" (default: unspecified).
• es_py_state: The state of the Python Elasticsearch Client package, one of present, absent or latest (default: present).
• es_py_install: Whether or not to install the Python Elasticsearch Client (default: true). Set this to false if the client has already been installed, and you are just making API calls.

The Elasticsearch API is exposed as an Ansible module called elasticsearch_api, which provides access to all API functions defined in the Python Elasticsearch Client. All API calls follow a standard format, including the Elasticsearch hosts to connect to, the API and function to call, and any connection or function arguments.

See the API docs for full API documentation.

The list of Elasticsearch hosts to connect to. Reference

Required: no

Default: ["localhost:9200"]

Name of transport class to establish connection with. Reference

Required: no

Default: Urllib3HttpConnection

Choices:

• Connection
• Urllib3HttpConnection
• RequestsHttpConnection
• ThriftConnection
• MemcachedConnection

Dictionary of keyword arguments for the selected transport. See the API docs for the arguments that each transport type accepts.

Required: no

API to use, where the empty string refers to the main Elasticsearch API.

Required: no

Default: "" (refers to the main Elasticsearch API)

Choices:

• "" (empty string)
• cat
• cluster
• indices
• nodes
• snapshot

The API function to call.

Required: yes

A dictionary of keyword arguments for the specified function. See the API docs for the arguments tha each function accepts.

Required: no

---
# Install specific version of the Python Elasticsearch Client
- hosts: 127.0.0.1
  roles:
    - { role: elasticsearch_api, es_py_version: "1.4.0" }

# Install latest version of the Python Elasticsearch Client
- hosts: 127.0.0.1
  roles:
    - { role: elasticsearch_api, es_py_state: "latest" }

# Remove the Python Elasticsearch Client
- hosts: 127.0.0.1
  roles:
    - { role: elasticsearch_api, es_py_state: "absent" }

# Make API calls
# Assume the Python package has already been installed
- hosts: 127.0.0.1
  roles:
    - { role: elasticsearch_api, es_py_install: false }
  tasks:
    - name: Count number of documents on localhost
      elasticsearch_api:
        function: count

    - name: Specify hosts to connect to, and connection settings
      elasticsearch_api:
        hosts: ['es1.mydomain.com', 'es2.mydomain.com']
        transport_args:
          use_ssl: true
          verify_certs: true
          maxsize: 5
        function: count

    - name: Create an index with the specified settings and mapping
      elasticsearch_api:
        api: indices
        function: create
        function_args:
          index: my_index
          body: |
            {
              "settings": { "number_of_shards": 1 },
              "mappings": {
                "type1": {
                  "properties": {
                    "name": { "type": "string" },
                    "date": { "type": "date" },
                    "valid": { "type": "boolean" }
                  }
                }
              }
            }

    - name: Get status of indices with the indices API
      elasticsearch_api:
        api: indices
        function: status

MIT

Aloysius Lim (GitHub)