{"id":19839932,"url":"https://github.com/fnzv/interlock","last_synced_at":"2025-05-01T19:30:30.878Z","repository":{"id":107777524,"uuid":"268075207","full_name":"fnzv/interlock","owner":"fnzv","description":"Interlock is a DNS failover and management tool based on Cloudflare API","archived":false,"fork":false,"pushed_at":"2020-06-03T21:21:17.000Z","size":299,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-06T17:05:41.647Z","etag":null,"topics":["cloudflare","dns","failover","metrics"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fnzv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2020-05-30T12:29:02.000Z","updated_at":"2023-07-30T19:01:01.000Z","dependencies_parsed_at":"2023-04-14T04:55:26.104Z","dependency_job_id":null,"html_url":"https://github.com/fnzv/interlock","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnzv%2Finterlock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnzv%2Finterlock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnzv%2Finterlock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnzv%2Finterlock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fnzv","download_url":"https://codeload.github.com/fnzv/interlock/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251932534,"owners_count":21667160,"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":["cloudflare","dns","failover","metrics"],"created_at":"2024-11-12T12:24:52.541Z","updated_at":"2025-05-01T19:30:30.873Z","avatar_url":"https://github.com/fnzv.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](imgs/interlock-scheme.png?raw=true)\n\nInterlock is a DNS failover and management tool based on Cloudflare APIs, the main goal of the project is to exclude CDN/site origins relying on HTTP Response codes or latency\n\nRelated blog post [here](https://sami.pw/blog/2020-05-30-automatic-failover-interlock)\n\nHere you can find some use-cases:\n- HA on Websites served by multiple datacenters (t.g. static sites, DR sites...)\n- Multi-CDN origins management\n- Measuring HTTP endpoints latency on InfluxDB\n\nSome example setups are briefly described below:\n- Public CI/CD scheduled container runs in order to remotely check that your origins are healthy (both latency and response)\n- Private CI/CD, in order to run locally and check service response e.g. (private services reachable via VPNs\\same LAN segment)\n- External backup failover in order to have at least one site responding when SHTF and you cannot change rapidly DNS (e.g. Maintenance page hostend on a third-party origin included in the conf responding on the same domain)\n- Node on your server LAN do measure latency in order to notify you if your site is getting slower (running on Dry Run = No CF records changes)\n\nBefore running in any production env be sure to understand the code underneath it (**Security notice**, you could **DELETE all** your DNS records if configured badly)\n\n## Demo\n[![asciicast ](https://asciinema.org/a/335086.png)](https://asciinema.org/a/335086)\n\nSample Grafana dashboard build with latency response data gathered via interlock\n\n![](imgs/interlock-grafana.png?raw=true)\n\n## Requirements\n- Cloudflare account (also free tier works)\n- Docker or GitlabCI or Golang\n\n\n## Setup variables\nBefore running the code you will require to securely set these ENV variables:\n- CF_API (**Mandatory** - You can generate a global API key from Cloudflare account settings)\n- CF_EMAIL (**Mandatory** - Your Cloudflare account email)\n- TGBOT_TOKEN  (Optional - Required only for Telegram Notifications , Create a TG Bot and use the bot token as a sender)\n- TGBOT_CHATID (Optional - Required only for Telegram Notifications , Your private TG chat id associated to your phone number)\n- INFLUXDB_PASSWORD (Optional - Required only for InfluxDB Metrics, other settings are inside interlock.conf)\n- DRYRUN (Optional - disables DNS changes)\n\nSecurity notice: Do not save ENV vars on public CI/CDs if not masked or are you sure about it and you know what are you doing \n\n## Configuration\nYou can find an example configuration here for interlock.conf\n```\nOrigins = [\n  \"example.org http://1.2.3.4\",\n  \"example.org http://1.2.3.5\",\n  \"example.com http://1.2.3.5\"\n]\nMaxLatency = 150\nInfluxdbHost = \"http://influxdb_host.example.org:8086\"\nInfluxdbDatabase = \"database_interlock\"\nInfluxdbUsername = \"influxdb_user\"\n```\n\nMaxLatency parameter is used to exclude origins based on http response latency\n\nInflux variables are used to send metrics to an InfluxDB\n\nWith this simple configuration the tool will check on every run if the sites under Origins are responding to the URIs specified, other than this pure HTTP response code check, latency will be measured (if MaxLatency \u003e 0).\n\n## Quick-start\n\nIn order to run interlock via Docker you will require to build your local image and run it with the following options:\n```\n# docker build -t interlock .\n# docker run  -e TGBOT_TOKEN -e TGBOT_CHATID -e CF_API -e CF_EMAIL -e INFLUXDB_PASSWORD interlock\n```\n\nTo run interlock under Golang you will require to download all imported code libraries and then execute the code (as always with ENV setup)\n```\n# go get .\n# go run interlockd.go\nChecking sami.pw on IP http://185.199.108.153...Sending metrics to influxdb  http://influxdbhost:8086\nLatency is OK  144\nOrigin OK...CF Record OK\n\nChecking sami.pw on IP http://185.199.109.153...Sending metrics to influxdb  http://influxdbhost:8086\nLatency is OK  36\nOrigin OK...CF Record OK\n\nChecking sa.mi.it on IP http://185.199.110.153...Sending metrics to influxdb  http://influxdbhost:8086\nLatency is OK  37\nOrigin OK...CF Record OK\n\nChecking sa.mi.it on IP http://185.199.111.153...Sending metrics to influxdb  http://influxdbhost:8086\nLatency is OK  37\nOrigin OK...CF Record OK\n```\n\n## Running as a k8s CronJob\n\nBefore running into the .yml code you will require an image of your configuration pushed into a private/public registry (e.g. Gitlab or DockerHub), once ready you can go on the next steps.\n\nIn order to run interlock on a k8s cluster you will require to use the same environment variables passed inside the .yml file, you can edit and run as the example below:\n```\n# kubectl apply -f k8s/interlock-deployment.yml\n# kubectl  get po | grep interlock # to check if pods created via CronJob are completed\ninterlockd-1590766200-przlb                        0/1     Completed   0          12m\ninterlockd-1590766500-d2hsw                        0/1     Completed   0          7m49s\ninterlockd-1590766800-dc4qp                        0/1     Completed   0          2m56s\n# kubectl  describe pods | grep interl -A3 -B4  # in order to troubleshoot image pull issues\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnzv%2Finterlock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffnzv%2Finterlock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnzv%2Finterlock/lists"}