{"id":22998243,"url":"https://github.com/uswitch/heimdall","last_synced_at":"2025-07-26T16:37:35.040Z","repository":{"id":46602217,"uuid":"104201885","full_name":"uswitch/heimdall","owner":"uswitch","description":"Generate PrometheusRule CRDs from Ingress annotations and Go templates","archived":false,"fork":false,"pushed_at":"2023-05-03T13:06:58.000Z","size":22265,"stargazers_count":24,"open_issues_count":1,"forks_count":8,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-06-19T00:39:57.625Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uswitch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-20T10:37:11.000Z","updated_at":"2023-12-15T23:26:41.000Z","dependencies_parsed_at":"2024-06-19T00:27:11.036Z","dependency_job_id":"278da0d8-777a-47c7-9dec-c11f6ff6d229","html_url":"https://github.com/uswitch/heimdall","commit_stats":{"total_commits":106,"total_committers":12,"mean_commits":8.833333333333334,"dds":0.7452830188679245,"last_synced_commit":"0d8b6723d50d901ae346cc57f47dbdb6c4cc983c"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fheimdall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fheimdall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fheimdall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fheimdall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uswitch","download_url":"https://codeload.github.com/uswitch/heimdall/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229786999,"owners_count":18124014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-15T06:12:20.320Z","updated_at":"2024-12-15T06:12:20.964Z","avatar_url":"https://github.com/uswitch.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Heimdall\n\nHeimdall watches Ingresses in your Kubernetes cluster to create PrometheusRules\nbased off annotations and PrometheusRule templates.\n\nConfiguring PrometheusRules via annotations makes it easy for cluster users to\nset up relevant alerts for Ingresses with a single-line annotation. Cluster\noperators can configure Heimdall and other components to ensure cluster users\nhave a consistent set of PrometheusRules.\n\n## PrometheusRule Templates\n\nHeimdall needs templates for the PrometheusRules it will create. These are\nstandard [go template files](https://golang.org/pkg/text/template/). An example\ntemplate can be found [here](./kube/base/templates/). By default,\nHeimdall will look for a folder called `templates` to find these in. You can\noverride this with the `--templates` flag.\n\n## Example Annotations RVU uses\n\nWe do have some custom Prometheus Rules we use, which give you an idea on what alerts we create in an automated fashion.\nThese can be deleted, modified and new ones can be created by putting the templates in [this folder](./kube/base/templates/).\n\nYour Ingress / Deployment must have annotations in the form of:\n`com.uswitch.heimdall/\u003cprometheus-rule-name\u003e: \u003cthreshold\u003e`\n\nFor example:\n\n`com.uswitch.heimdall/5xx-rate: \"0.001\"`\n\nThis will create a PrometheusRule for an Ingress, based on the `5xx-rate.tmpl` template with a\nthreshold of `0.001`.\n\nAvailable annotations for Ingress:\n- `com.uswitch.heimdall/5xx-rate` - alerts if the 5XX rate goes above the given threshold for at least 1 minute\n\nAvailable annotations for Deployment:\n- `com.uswitch.heimdall/replicas-availability-deployment`- alerts if the given part of the total replicas are not running for 5 minutes. (0.1 would alert if 1 pod goes unavailable out of a total of 10 pods)\n\n## Running Heimdall locally\n\nOnce the kubernetes context is set to a local cluster, [skaffold](https://skaffold.dev/) + [kustomize](https://github.com/kubernetes-sigs/kustomize) can help deploying the local Heimdall version\nto the cluster. For that you might want to change the Container registry URL from quay to your own container registry.\nReferences are found in `/kube/base/deployment.yaml` \u0026 `/kube/overlays/skaffold/kustomization.yaml` \u0026 `skaffold.yaml`\n\nThe command to build and deploy the application is `skaffold dev`\n\nIf you'd like to generate a new `deployment.yaml` file for deploying purposes, you can run `kustomize build kube/base | tee -a deployment.yaml`.\n\n## Requirements\n\nHeimdall uses\n[PrometheusRules](https://github.com/coreos/prometheus-operator/blob/master/Documentation/design.md#prometheusrule)\n– custom resource definitions of [Prometheus\nOperator](https://github.com/coreos/prometheus-operator).\n\nPrometheusRule CRD must be added to the cluster prior to deploying Heimdall:\n\n`kubectl apply -f https://raw.githubusercontent.com/coreos/prometheus-operator/master/example/prometheus-operator-crd/prometheusrule.crd.yaml`\n\nYour monitoring pipeline would likely depend on Prometheus Operator to:\n\n- manage Prometheus StatefulSets\n- manage Alertmanager StatefulSets\n- watch PrometheusRule CRDs and create corresponding ConfigMaps\n- reload Prometheus instance when ConfigMap changes\n\n## Flags\n\n```\n--help                   Show context-sensitive help.\n--kubeconfig=KUBECONFIG  Path to kubeconfig.\n--namespace=\"\"           Namespace to monitor\n--debug                  Debug mode\n--templates=\"templates\"  Directory for the templates\n--sync-interval=1m       Synchronize list of Ingress resources this frequently\n```\n\n## Migration to v0.5+\n\nIn the past, Heimdall relied on its own Alerts type to manage Prometheus rules.  \nSince version v0.5 Heimdall no longer support custom Alerts type in favor of more widespread PrometheusRule CRD from the prometheus-operator project.  \nYou can find a simple script which accepts an Alerts YAML to stdin and prints a PrometheusRules YAML into stdout in contrib folder: [convert-alerts-to-promrules.py](./contrib/convert-alerts-to-promrules.py)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuswitch%2Fheimdall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuswitch%2Fheimdall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuswitch%2Fheimdall/lists"}