{"id":19002301,"url":"https://github.com/linkerd/linkerd-failover","last_synced_at":"2025-08-09T20:24:33.436Z","repository":{"id":36978977,"uuid":"455328053","full_name":"linkerd/linkerd-failover","owner":"linkerd","description":"Linkerd Failover Operator","archived":false,"fork":false,"pushed_at":"2025-03-20T04:57:55.000Z","size":743,"stargazers_count":37,"open_issues_count":6,"forks_count":8,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-17T08:59:38.548Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linkerd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS.yml","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-02-03T21:04:21.000Z","updated_at":"2025-04-05T19:45:51.000Z","dependencies_parsed_at":"2024-04-19T05:40:25.868Z","dependency_job_id":"58be14c3-a3f1-4e40-b142-2e9e9d2bab65","html_url":"https://github.com/linkerd/linkerd-failover","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkerd%2Flinkerd-failover","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkerd%2Flinkerd-failover/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkerd%2Flinkerd-failover/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkerd%2Flinkerd-failover/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linkerd","download_url":"https://codeload.github.com/linkerd/linkerd-failover/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250291146,"owners_count":21406303,"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-11-08T18:14:34.608Z","updated_at":"2025-04-22T17:49:57.165Z","avatar_url":"https://github.com/linkerd.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# linkerd-failover\n\nLinkerd-failover is a Linkerd extension whose goal is to provide a failover\nmechanism so that a service that exists in multiple clusters may continue to\noperate as long as the service is available in any cluster.\n\nThe mechanism relies on Linkerd’s traffic-splitting functionality by providing\nan operator to alter the backend services' weights in real time depending on\ntheir readiness.\n\n**Note:** if you find issues in this extension, please file an issue against\nthe [main Linkerd2 repo](https://github.com/linkerd/linkerd2/issues).\n\n## Table of contents\n\n- [Issue Tracking](#issue-tracking)\n- [Requirements](#requirements)\n- [Configuration](#configuration)\n- [Installation](#installation)\n- [Example](#example)\n- [Implementation details](#implementation-details)\n  - [Failover criteria](#failover-criteria)\n  - [Failover logic](#failover-criteria)\n\n## Issue Tracking\n\nIssues are disabled in this repository since we track issues with this\nextension in the [main Linkerd2\nrepo](https://github.com/linkerd/linkerd2/issues). The rationale here is\nsimply that we've found over time that having issues scattered across multiple\nrepos makes it too easy to lose track of things.\n\n## Requirements\n\n- Linkerd `stable-2.11.2` or later\n- Linkerd-smi `v0.2.0` or later (required if using Linkerd `stable-2.12.0` or\n  later)\n\n## Configuration\n\nThe following Helm values are available:\n\n- `selector`: determines which `TrafficSplit` instances to consider for\n  failover. It defaults to `failover.linkerd.io/controlled-by={{.Release.Name}}`\n  (the value refers to the release name used in `helm install`).\n- `logLevel`, `logFormat`: for configuring the operator's logging.\n\n## Installation\n\nNote the SMI extension CRD is included in Linkerd 2.11.x so you can skip this\nstep for those versions. As of version `stable-2.12.0`, it's no longer included\nso you need to install it as described here.\n\nThe SMI extension and the operator are to be installed in the local cluster\n(where the clients consuming the service are located).\n\nLinkerd-smi installation:\n\n```console\nhelm repo add linkerd-smi https://linkerd.github.io/linkerd-smi\nhelm repo up\nhelm install linkerd-smi -n linkerd-smi --create-namespace linkerd-smi/linkerd-smi\n```\n\nLinkerd-failover installation:\n\n```console\n# For edge releases\nhelm repo add linkerd-edge https://helm.linkerd.io/edge\nhelm repo up\nhelm install linkerd-failover -n linkerd-failover --create-namespace --devel linkerd-edge/linkerd-failover\n\n# For stable releases\nhelm repo add linkerd https://helm.linkerd.io/stable\nhelm repo up\nhelm install linkerd-failover -n linkerd-failover --create-namespace linkerd/linkerd-failover\n```\n\n## Example\n\nThe following `TrafficSplit` serves as the initial state for a failover setup.\n\nClients should send requests to the apex service `sample-svc`. The primary\nservice that will serve these requests is declared through the\n`failover.linkerd.io/primary-service` annotation, `sample-svc` in this case. If\nthe `TrafficSplit` does not include this annotation, it will treat the first\nbackend as the primary service.\n\nWhen `sample-svc` starts failing, the weights will be switched over the other\nbackends.\n\nNote that the failover services can be located in the local cluster, or they can\npoint to mirror services backed by services in other clusters (through Linkerd's\nmulticluster functionality).\n\n```yaml\napiVersion: split.smi-spec.io/v1alpha2\nkind: TrafficSplit\nmetadata:\n    name: sample-svc\n    annotations:\n        failover.linkerd.io/primary-service: sample-svc\n    labels:\n        failover.linkerd.io/controlled-by: linkerd-failover\nspec:\n    service: sample-svc\n    backends:\n        - service: sample-svc\n          weight: 1\n        - service: sample-svc-central1\n          weight: 0\n        - service: sample-svc-east1\n          weight: 0\n        - service: sample-svc-east2\n          weight: 0\n        - service: sample-svc-asia1\n          weight: 0\n```\n\n## Implementation details\n\n### Failover criteria\n\nThe failover criteria is readiness failures on the targeted Pods. This is\ndirectly reflected on the Endpoints object associated with those Pods: only when\nPods are ready, does the `addresses` field of the relevant Endpoints get\npopulated.\n\n### Failover logic\n\nThe following describes the logic used to change the `TrafficSplit` weights:\n\n- Whenever the primary backend is ready, all the weight is set to it, setting\n  the weights for all the secondary backends to zero.\n- Whenever the primary backend is not ready, the following rules apply only if\n  there is at least one secondary backend that is ready:\n  - The primary backend’s weight is set to zero.\n  - The weight is distributed equally among all the secondary backends that\n    are ready.\n  - Whenever a secondary backend changes its readiness, the weight is\n    redistributed among all the secondary backends that are ready\n- Whenever both the primary and secondaries are unavailable, the connection will\n  fail at the client-side, as expected.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkerd%2Flinkerd-failover","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinkerd%2Flinkerd-failover","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkerd%2Flinkerd-failover/lists"}