BigDataBoutique / docker-elastalert

Dockerized ElastAlert

Dockerized ElastAlert

ElastAlert by Yelp is a Python-based utility for enabling alerting for the Elastic Stack. This is an easy-to-use dockerized version of it, with focus on Kubernetes compatibility and flexibility.

Usage (Kubernetes)

Rules should be mounted to the container, and the preferred way of doing this is via a ConfigMap.

To create a ConfigMap containing the rules for the ElastAlert deployment, use the following on a folder rules/ containing the rules yaml files:

kubectl create configmap elastalert-rules --from-file=rules/ -o yaml

A typical Deployment of ElastAlert would then look like this:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: elastalert
  labels:
    app: elastalert
spec:
  replicas: 1
  selector:
    matchLabels:
      app: elastalert
  template:
    metadata:
      labels:
        app: elastalert
    spec:
      containers:
        - name: elastalert
          image: bigdataboutique/elastalert
          imagePullPolicy: IfNotPresent
          env:
            - name: ES_HOST
              value: "es-helm-master"
            - name: ES_PORT
              value: "9200"
            - name: ENV_NAME
              value: "test"
            - name: ELASTALERT_CONFIGS
              value: |
                # any configs that you need added to config.yaml
          volumeMounts:
            - name: rules
              mountPath: /app/rules
              readOnly: false
      volumes:
        - name: rules
          configMap:
            name: elastalert-rules
      restartPolicy: Always

When updating the rules you'd need to restart the ElastAlert pod:

kubectl delete configmap elastalert-rules
kubectl create configmap elastalert-rules --from-file=rules/ -o yaml
kubectl scale deployment/elastalert --replicas=0
kubectl scale deployment/elastalert --replicas=1

In order to enable quiet mode set the environment variable QUIET flag to true, eg

      containers:
        - name: elastalert
          image: bigdataboutique/elastalert
          env:
            - name: QUIET
              value: "true"

Usage (Docker)

On an instance with access to your Elasticsearch cluster:

a.

git clone https://github.com/BigDataBoutique/docker-elastalert

b. from the repository folder, edit config.yaml according to your requirements (you can either define the host and port here or leave them as parameters for the run command)

c. in the repository folder, create a rules folder and copy your rules there.

d. For an online run, use the following:

docker run -it --net=host  --mount type=bind,source="`pwd`/test-rules",target="/app/rules" --mount type=bind,source="`pwd`/config.yaml",target=/config.yaml -e ES_HOST=localhost -e ES_PORT=9200 -e ENV_NAME=bdbq --rm --name elastalert bigdataboutique/elastalert

replacing the host, port, amd env_name (see below). f. Once you've tested the online run works well, you can run in background mode:

docker run -d --net=host  --mount type=bind,source="`pwd`/test-rules",target="/app/rules" --mount type=bind,source="`pwd`/config.yaml",target=/config.yaml -e ES_HOST=localhost -e ES_PORT=9200 -e ENV_NAME=bdbq --name elastalert bigdataboutique/elastalert

you can then use docker stop elastalert and docker start elastalert when you want to do maintenance on rules (currently you must restart elastalert for changes to rules to take effect). Alternatively you can set up another folder for running an online session with the rules you want to test, using a different env_name in order not to touch the "production" indices.

Environment Variables

This container setup will do environment variable substitution in all rule files and config.yaml. Some environment variables are already defined and have to be set:

• ES_HOST and ES_PORT of the Elasticsearch being queried for events
• ENV_NAME is the environment name to run ElastAlert on, will be used for naming the ElastAlert backend indexes
• ELASTALERT_CONFIGS (optional), use this to append any configs you need for config.yaml
• TZ is the time zone for the alert. Default is TZ=UTC and we recommend keeping that. example:

-e TZ=Asia/Jerusalem

• TRACE with any value, creates a trace file at /app/trace.log in the docker. To use first touch query.log and in the docker command map it to the file within the docker. This is good for understanding what is the query generated by Elastalert. example:

  -e TRACE=true --mount type=bind,source="`pwd`/query.log",target="/app/query.log"