The autoheal repository is an OpenShift project written in Go that implements automated remediation for Kubernetes clusters by receiving alert notifications from Prometheus Alertmanager and executing Ansible playbooks to resolve underlying issues. The service bridges monitoring and infrastructure automation, enabling self-healing capabilities in cloud-native environments.
The core functionality centers on a configuration-driven architecture where users define healing rules in a YAML configuration file. These rules specify which Ansible playbooks should execute in response to specific alert patterns. The service matches incoming alerts against defined rules using label and annotation matching with regular expression support, then triggers corresponding AWX or Ansible Tower job templates. This design allows operators to automate responses to common cluster issues without manual intervention.
Configuration management is flexible and multi-layered. The primary configuration file can be specified via command line options, with sensible defaults pointing to autoheal.yml in the current directory. The service also accepts Kubernetes API configuration through the kubeconfig option, automatically detecting whether it runs inside or outside a cluster. For AWX connectivity, the configuration file defines the API address, optional HTTP proxy settings, and credentials that can be stored either as Kubernetes secrets or directly in the configuration for development environments. TLS certificate handling similarly supports both secret references and direct specification, with options for insecure connections disabled by default for production safety.
The healing rules section of the configuration contains the intelligence for automated remediation. Each rule specifies alert label and annotation patterns to match, the AWX job template to execute, and optional parameters like extra variables and host limits. The service processes all parameters as Go templates, allowing dynamic values derived from alert labels and annotations. This templating capability enables sophisticated scenarios where the specific remediation action adapts based on alert content, such as executing different playbooks for different services or targeting specific hosts based on alert instance labels.
To prevent healing storms from repeated alerts, the service implements throttling configuration with configurable intervals. Actions matching the same rule with identical template-processed field values are deduplicated within the specified interval, with the first execution proceeding and subsequent duplicates logged and ignored. The service also performs periodic job status checks against the AWX server to monitor active remediation jobs, with configurable check intervals defaulting to five minutes.
The repository includes comprehensive development support. Developers can run the service without a full OpenShift cluster by using example configuration files and simulating alerts with curl commands. A mock AWX server is provided for testing features that do not require actual Ansible Tower connectivity. The project includes automated tests, build scripts for binaries and RPM packages, and installation templates for deploying to OpenShift clusters.
According to GitGenius activity classification, the repository is actively maintained within the autoheal, container orchestration, and self-healing domains, with connections to related projects including openshift/hypershift, kubernetes/kubernetes, and microsoft/vscode through overlapping contributors. The project serves the broader DevOps and cloud-native ecosystem by automating fault detection and recovery, reducing manual operational burden in Kubernetes environments.
