{"id":13820554,"url":"https://github.com/observatorium/thanos-receive-controller","last_synced_at":"2026-01-11T03:40:17.924Z","repository":{"id":35694087,"uuid":"192769308","full_name":"observatorium/thanos-receive-controller","owner":"observatorium","description":"Kubernetes controller to automatically configure Thanos receive hashrings","archived":false,"fork":false,"pushed_at":"2024-06-28T09:48:10.000Z","size":466,"stargazers_count":94,"open_issues_count":21,"forks_count":42,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-08-05T08:09:09.436Z","etag":null,"topics":["controller","kubernetes","prometheus","remote-write","thanos"],"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/observatorium.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":"2019-06-19T16:35:36.000Z","updated_at":"2024-07-29T13:07:28.000Z","dependencies_parsed_at":"2024-01-13T16:25:14.304Z","dependency_job_id":"5a1130f8-699d-4a97-886e-416fe421c58c","html_url":"https://github.com/observatorium/thanos-receive-controller","commit_stats":{"total_commits":129,"total_committers":28,"mean_commits":4.607142857142857,"dds":0.7596899224806202,"last_synced_commit":"7140e9476289b57b815692c3ec2dfd95b5fb4b6b"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/observatorium%2Fthanos-receive-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/observatorium%2Fthanos-receive-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/observatorium%2Fthanos-receive-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/observatorium%2Fthanos-receive-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/observatorium","download_url":"https://codeload.github.com/observatorium/thanos-receive-controller/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225423639,"owners_count":17472153,"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":["controller","kubernetes","prometheus","remote-write","thanos"],"created_at":"2024-08-04T08:01:05.230Z","updated_at":"2026-01-11T03:40:17.866Z","avatar_url":"https://github.com/observatorium.png","language":"Go","funding_links":[],"categories":["kubernetes"],"sub_categories":[],"readme":"# Thanos Receive Controller\n\nThe Thanos Receive Controller configures multiple hashrings of Thanos receivers running as StatefulSets on Kubernetes.  \nBased on an initial mapping of tenants to hashrings, the controller identifies the Pods in each hashring and generates a complete configuration file as a ConfigMap.\n\n[![Build Status](https://github.com/observatorium/thanos-receive-controller/actions/workflows/checks.yaml/badge.svg?branch=main)](https://github.com/observatorium/thanos-receive-controller/actions/workflows/checks.yaml)\n\n## Getting Started\n\nFirst, provide an initial mapping of tenants to hashrings in a ConfigMap, e.g.:\n\n```shell\ncat \u003c\u003c'EOF' | kubectl apply -f -\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: thanos-receive\n  labels:\n    app.kubernetes.io/name: thanos-receive\ndata:\n  hashrings.json: |\n    [\n        {\n            \"hashring\": \"hashring0\",\n            \"tenants\": [\"foo\", \"bar\"]\n        },\n        {\n            \"hashring\": \"hashring1\",\n            \"tenants\": [\"baz\"]\n        }\n    ]\nEOF\n```\n\nNext, deploy the controller, pointing it at the configuration file in the ConfigMap:\n\n```shell\ncat \u003c\u003c'EOF' | kubectl apply -f -\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: thanos-receive-controller\n  labels:\n    app.kubernetes.io/name: thanos-receive-controller\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app.kubernetes.io/name: thanos-receive-controller\n  template:\n    metadata:\n      labels:\n        app.kubernetes.io/name: thanos-receive-controller\n    spec:\n      containers:\n      - args:\n        - --configmap-name=thanos-receive\n        - --configmap-generated-name=thanos-receive-generated\n        - --file-name=hashrings.json\n        image: quay.io/observatorium/thanos-receive-controller\n        name: thanos-receive-controller\nEOF\n```\n\nFinally, deploy StatefulSets of Thanos receivers labeled with `controller.receive.thanos.io=thanos-receive-controller`.\nThe controller lists all of the StatefulSets with that label and matches the value of their `controller.receive.thanos.io/hashring` labels to the hashring names in the configuration file.\nThe endpoints for each hashring will be populated automatically by the controller and the complete configuration file will be placed in a ConfigMap named `thanos-receive-generated`.\nThis configuration should be consumed as a ConfigMap volume by the Thanos receivers.\n\n## About the `--allow-only-ready-replicas` flag\nBy default, upon a scale up, the controller adds all new receiver replicas into the hashring as soon as they are in a _running_ state.\nHowever, this means the new replicas will be receiving requests from other replicas in the hashring before they are ready to accept them.\nDue to the nature of how receiver works, it can take some time until receiver's storage is ready.\nDepending on your roll out strategy, you might see an increased failure rate in your hashring until enough replicas are in a ready state.\n\nAn alternative is to use the `--allow-only-ready-replicas`, which modifies this behavior.\nInstead, upon a scale-up, new replicas are added only after it is confirmed they are ready.\nThis means:\n- Old replicas keep operating with the old hashring, until all new replicas are ready. Once this is true, the hashring is updated to include all replicas in the stateful set\n- New replicas will initially come up with the old hashring configuration. This means they will serve only as a \"router\" and any requests that they receive will be forwarded to replicas in the old hashring. Once _all_ new receiver replicas are ready, the hashring will be updated to include both old and new replicas.\n\n\n## About the `--allow-dynamic-scaling` flag\nBy default, the controller does not react to voluntary/involuntary disruptions to receiver replicas in the StatefulSet.\nThis flag allows the user to enable this behavior.\nWhen enabled, the controller will react to voluntary/involuntary disruptions to receiver replicas in the StatefulSet.\nWhen a Pod is marked for termination, the controller will remove it from the hashring and the replica essentially becomes a \"router\" for the hashring.\nWhen a Pod is deleted, the controller will remove it from the hashring.\nWhen a Pod becomes unready, the controller will remove it from the hashring.\nThis behaviour can be considered for use alongside the [Ketama hashing algorithm](https://thanos.io/tip/components/receive.md/#ketama-recommended).\n\n## About the `--use-az-aware-hashring` flag\nBy default, the controller does not support az aware hashring introduced in Thanos v0.32+ (https://thanos.io/tip/components/receive.md/#az-aware-ketama-hashring-experimental),\nThis flag allows the user to enable this behaviour.\nWhen enabled, the controller will generate az aware hashring configuration based on the `--pod-az-annotation-key` flag, namely the value of the annotation key will be used as the az name for each pod.\nIf not specified, the statefulset name will be used as AZ field.\nNote that Thanos has be upgraded to v0.32+ to work with new hashring endpoint struct.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobservatorium%2Fthanos-receive-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobservatorium%2Fthanos-receive-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobservatorium%2Fthanos-receive-controller/lists"}