ansible-role-elasticsearch/docs/ssl-tls-setup.md

# X-Pack Security SSL/TLS

The role allows configuring HTTP and transport layer SSL/TLS for the cluster. You will need to generate and provide your own PKCS12 or PEM encoded certificates as described in [Encrypting communications in Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.4/configuring-tls.html#configuring-tls).

By default this role will upload the certs to your elasticsearch servers. If you already copied the certs by your own way, set `es_ssl_upload` to `false` (default: `true`) 

If you don't want this role to add autogenerated SSL configuration to elasticsearch.yml set `es_enable_auto_ssl_configuration` to `false` (default: `true`).

The following should be configured to ensure a security-enabled cluster successfully forms:

* `es_enable_http_ssl`  Default `false`. Setting this to `true` will enable HTTP client SSL/TLS
* `es_enable_transport_ssl` - Default `false`. Setting this to `true` will enable transport layer SSL/TLS

When using a [PKCS12](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#security-http-pkcs12-files) keystore and truststore:

* `es_ssl_keystore`  path to your PKCS12 keystore (can be the same as `es_ssl_truststore`)
* `es_ssl_keystore_password`  set this if your keystore is protected with a password
* `es_ssl_truststore`  path to your PKCS12 keystore (can be the same as `es_ssl_keystore`)
* `es_ssl_truststore_password`  set this if your truststore is protected with a password

When using [PEM encoded](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#_pem_encoded_files_3) certificates:

* `es_ssl_key`  path to your SSL key
* `es_ssl_key_password`  set this if your SSL key is protected with a password
* `es_ssl_certificate`  the path to your SSL certificate

## Generating an SSL keystore

With a password:

```shell
$ bin/elasticsearch-certutil ca --out ./my-ca.p12 --pass "ca_password"
$ bin/elasticsearch-certutil cert --ca ./my-ca.p12 --ca-pass "ca_password" --out ./my-keystore.p12 --pass "keystore_password"
```

Without a password:

```shell
$ bin/elasticsearch-certutil ca --out ./my-ca.p12 --pass ""
$ bin/elasticsearch-certutil cert --ca ./my-ca.p12 --out ./my-keystore.p12 --pass ""
```

## Additional optional SSL/TLS configuration

* `es_enable_auto_ssl_configuration`  Default `true`. Whether this role should add automatically generated SSL config to elasticsearch.yml.
* `es_ssl_certificate_path`  Default `{{ es_conf_dir }}/certs`. The location where certificates should be stored on the ES node.
* `es_ssl_verification_mode` Default `certificate`. See [SSL verification_mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ssl-tls-settings) for options.
* `es_ssl_certificate_authority`  PEM encoded certificate file that should be trusted.
* `es_validate_certs`  Default `yes`. Determines if ansible should validate SSL certificates when performing actions over HTTPS. e.g. installing templates and managing native users.

## Example SSL/TLS configuration

```yaml
- name: Elasticsearch with SSL/TLS enabled
  hosts: localhost
  roles:
    - role: elastic.elasticsearch
  vars:
    es_config:
      node.name: "node1"
      cluster.name: "custom-cluster"
      discovery.seed_hosts: "localhost:9301"
      http.port: 9201
      transport.port: 9301
      node.data: false
      node.master: true
      bootstrap.memory_lock: true
      xpack.security.authc.realms.file.file1.order: 0
      xpack.security.authc.realms.native.native1.order: 1
    es_heap_size: 1g
    es_api_basic_auth_username: "elastic" # This is the default user created by the installation of elasticsearch
    es_api_basic_auth_password: "changeme" # This is the default password created by the installation of elasticsearch
    es_enable_http_ssl: true
    es_enable_transport_ssl: true
    es_ssl_keystore: "files/certs/my-keystore.p12"
    es_ssl_truststore: "files/certs/my-ca.p12"
    es_ssl_keystore_password: "keystore_password"
    es_ssl_truststore_password: "ca_password"
    es_validate_certs: no
```

## Changing the default password of elastic user

To change the default password of user elastic: 

* Add this line to your playbook:

```
vars:
  es_api_basic_auth_username: "elastic"
  es_api_basic_auth_password: "changeme"
  es_users:
    native:
      elastic:
        password: "<new password>"
```

* Deploy your playbook
* Update your playbook with:

```
vars:
  es_api_basic_auth_username: "elastic"
  es_api_basic_auth_password: "<new password>"
```