Elasticsearch Role¶

This role manages the installation and configuration of Elasticsearch using rootless Podman containers. It includes optional TLS support and Elasticvue as a lightweight GUI interface.

Features¶

Rootless Podman deployment
Optional TLS/SSL encryption
Elasticvue GUI interface
Systemd integration using Quadlets
Configurable resource limits
X-Pack security features

Requirements¶

Podman 4.x or later
Systemd
User with sudo access
SELinux if running on RHEL/CentOS (role handles contexts)

Role Variables¶

Installation Options¶

elasticsearch_state: present  # Use 'absent' to remove
elasticsearch_force_reload: false
elasticsearch_delete_data: false  # Set to true to delete data during removal

Container Settings¶

elasticsearch_image: "docker.io/elasticsearch:8.12.1"
elasticsearch_elasticvue_image: "docker.io/cars10/elasticvue:latest"
elasticsearch_port: 9200
elasticsearch_gui_port: 8080

Security Settings¶

elasticsearch_enable_security: true
elasticsearch_password: "change_this_password"

TLS Configuration¶

elasticsearch_enable_tls: false
elasticsearch_tls_cert_file: ""  # Path to your certificate
elasticsearch_tls_key_file: ""   # Path to your private key
elasticsearch_tls_min_version: "TLSv1.2"
elasticsearch_tls_verify_client: "optional"

Resource Settings¶

elasticsearch_memory: "1g"  # JVM heap size

Example Playbooks¶

Basic Installation¶

- hosts: servers
  roles:
    - role: elasticsearch
      vars:
        elasticsearch_password: "secure_password"
        elasticsearch_memory: "2g"

With TLS Enabled¶

- hosts: servers
  roles:
    - role: elasticsearch
      vars:
        elasticsearch_password: "secure_password"
        elasticsearch_enable_tls: true
        elasticsearch_tls_cert_file: "/path/to/cert.pem"
        elasticsearch_tls_key_file: "/path/to/key.pem"

Removal with Data Cleanup¶

- hosts: servers
  roles:
    - role: elasticsearch
      vars:
        elasticsearch_state: absent
        elasticsearch_delete_data: true

Usage¶

Deployment¶

# Prepare system (one-time)
./manage-svc.sh elasticsearch prepare

# Deploy Elasticsearch
./manage-svc.sh elasticsearch deploy

# Verify deployment
./svc-exec.sh elasticsearch verify

Accessing Services¶

After deployment:

Elasticsearch API: http://localhost:9200
Elasticvue GUI: http://localhost:8080

Initial Setup¶

Get the cluster status:

curl -X GET "localhost:9200/_cluster/health?pretty" \
  -u elastic:${elasticsearch_password}

Access Elasticvue GUI:
Open http://localhost:8080 in your browser
Connect to http://localhost:9200
Use credentials: elastic / ${elasticsearch_password}

Service Management¶

# Check service status
systemctl --user status elasticsearch-pod

# View logs
podman logs elasticsearch-node
podman logs elasticsearch-gui

# Restart service
systemctl --user restart elasticsearch-pod

# Stop service
systemctl --user stop elasticsearch-pod

Security Considerations¶

Elasticvue Access¶

Elasticvue provides a convenient dashboard but has no built-in authentication. Security options:

1. Reverse Proxy Authentication¶

Set up Apache/nginx as a reverse proxy with authentication:

# Apache example
<Location "/elasticvue/">
    AuthType Basic
    AuthName "Restricted Access"
    AuthUserFile /etc/apache2/.htpasswd
    Require valid-user
    ProxyPass http://localhost:8080/
    ProxyPassReverse http://localhost:8080/
</Location>

2. Network Access Control¶

Bind strictly to localhost (default):

[Pod]
PublishPort=127.0.0.1:${ELASTICSEARCH_PORT}:9200
PublishPort=127.0.0.1:${ELASTICSEARCH_GUI_PORT}:8080

3. SSH Tunneling¶

Access through an SSH tunnel:

ssh -L 8080:localhost:8080 user@server

Best Practices¶

Never expose Elasticvue directly to the internet
Use HTTPS when accessing through a reverse proxy
Implement IP-based access restrictions where possible
Use API keys with limited permissions instead of the elastic superuser
Regularly audit and rotate API keys
Monitor access logs for unauthorized attempts
Change default passwords after installation
Configure firewall rules as needed

Resource Management¶

Memory Configuration¶

Elasticsearch requires proper memory settings:

# Container-level ulimits
ulimit:
  - "memlock=-1:-1"
  - "nofile=65535:65535"

# System-level limits
[Service]
LimitMEMLOCK=infinity
LimitNOFILE=65535

Both are needed because: 1. Systemd override ensures the user service has sufficient limits 2. Container limits ensure the specific container gets those limits

Elasticsearch needs these permissions for: - memlock: Prevents memory swapping (crucial for performance) - nofile: Allows many open file handles (ES opens many files)

System Requirements¶

Ensure vm.max_map_count is at least 262144:

sudo sysctl -w vm.max_map_count=262144

Make permanent:

echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

Troubleshooting¶

Container Won't Start¶

Check logs:
```
podman logs elasticsearch-node
```

Verify memory settings:

podman inspect elasticsearch-node | jq '.[0].HostConfig.Memory'

Check system requirements:
```
sysctl vm.max_map_count
```

Permission Denied Errors¶

On RHEL/CentOS, check SELinux contexts:

ls -lZ ~/elasticsearch-data
sudo restorecon -Rv ~/elasticsearch-data

Network Issues¶

Verify container network:

podman network inspect ct-net

Check DNS configuration in containers:

podman exec elasticsearch-node cat /etc/resolv.conf

Backup and Restore¶

Manual Backup¶

# Create backup directory
mkdir -p ~/elasticsearch-backups

# Stop Elasticsearch
systemctl --user stop elasticsearch-pod

# Backup data
tar czf ~/elasticsearch-backups/es-backup-$(date +%Y%m%d).tar.gz \
  ~/elasticsearch-data/

# Start Elasticsearch
systemctl --user start elasticsearch-pod

Restore¶

# Stop Elasticsearch
systemctl --user stop elasticsearch-pod

# Restore data
tar xzf ~/elasticsearch-backups/es-backup-YYYYMMDD.tar.gz -C ~/

# Start Elasticsearch
systemctl --user start elasticsearch-pod

Removal¶

Remove but Keep Data¶

./manage-svc.sh elasticsearch remove

Complete Removal¶

# Set delete flag in inventory or extra vars
./manage-svc.sh elasticsearch remove -e elasticsearch_delete_data=true

License¶

MIT

Author¶

Created by jackaltx and Claude.