{"id":17132195,"url":"https://github.com/bitsofinfo/kubernetes-ingress-info","last_synced_at":"2026-05-04T03:37:51.123Z","repository":{"id":44549994,"uuid":"192225193","full_name":"bitsofinfo/kubernetes-ingress-info","owner":"bitsofinfo","description":"Simple REST endpoint to determine existence of Kubernetes Ingress \"host\" presence (or lack thereof) in a k8s cluster.","archived":false,"fork":false,"pushed_at":"2022-02-08T16:19:43.000Z","size":832,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T05:18:42.374Z","etag":null,"topics":["cloud","discovery","ingress","kubernetes","load-balancer","load-balancing"],"latest_commit_sha":null,"homepage":"https://bitsofinfo.wordpress.com/2019/07/12/determining-ingress-host-kubernetes-clusters/","language":"Python","has_issues":true,"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/bitsofinfo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-16T18:44:58.000Z","updated_at":"2024-11-14T16:45:18.000Z","dependencies_parsed_at":"2022-09-03T22:00:46.174Z","dependency_job_id":null,"html_url":"https://github.com/bitsofinfo/kubernetes-ingress-info","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/bitsofinfo/kubernetes-ingress-info","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fkubernetes-ingress-info","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fkubernetes-ingress-info/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fkubernetes-ingress-info/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fkubernetes-ingress-info/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitsofinfo","download_url":"https://codeload.github.com/bitsofinfo/kubernetes-ingress-info/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fkubernetes-ingress-info/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32593948,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"online","status_checked_at":"2026-05-04T02:00:06.625Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cloud","discovery","ingress","kubernetes","load-balancer","load-balancing"],"created_at":"2024-10-14T19:26:20.020Z","updated_at":"2026-05-04T03:37:51.086Z","avatar_url":"https://github.com/bitsofinfo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kubernetes-ingress-info\n\nThis project provides a simple REST service that can be deployed to any Kubernetes cluster\nthat reports whether or not a `host` exists in any `Ingress` deployed to that cluster.\n\nIts **important** that this API does **not** report on the *health* of any given `Ingress` `host`\nbut specifically whether or not ANY `Ingress` currently exists on the cluster where `kubernetes-ingress-info`\nis deployed, regardless of if its backend is actually up. It is intended to be a very lightweight and open\nendpoint to interrogate for this status.\n\nThis tool was specifically developed to serve as a endpoint for various cloud load-balancers\nand DNS services to be able to auto-detect *which* Kubernetes clusters are valid for a specific `host` FQDN.\nThis can aid in workload migration across various clusters or just enable workloads to be deployed to subsets\nof clusters out of many organizational clusters, while letting upstream DNS and or glsb based devices react\naccordingly as many of these platforms rely on simple HTTP 200 OK type of \"checks\".\n\n* [Use case](#usecase)\n* [Install/Setup](#req)\n* [Example](#example)\n* [API](#api)\n* [Caching](#cache)\n* [Usage](#usage)\n\n\n## \u003ca name=\"usecase\"\u003e\u003c/a\u003eUse case:\n\nThis tool was specifically developed to serve as a endpoint for various cloud load-balancers\nand DNS services to be able to auto-detect *which* Kubernetes clusters are valid for a specific `host` FQDN.\n\nLets say you have two apps available at **a.b.com** and **x.y.com** and you have 3 available Kubernetes\nit could potentially be deployed on, *clusterA*, *clusterB* and *clusterC*. Generally upstream from your cluster *LoadBalancers*\nyou will have another cloud load balancer device or you are just using some sort of DNS device to control what cluster *LoadBalancer* IPs are relevant for each application at any given time. So what you can do in this case is list all possible cluster IPs as possible targets for those FQDNs hostname, but enable/disable them based on calls to `kubernetes-ingress-info` which\nresides on all clusters. For this to work, you should ensure each possible target cluster `Ingress Controller` that is behind a `LoadBalancer` has `kubernetes-ingress-info` accessible via its own unique `Ingress`.\n\n![diag](/docs/diag1.png \"Diagram1\")\n\n## \u003ca id=\"req\"\u003e\u003c/a\u003eInstall/Setup\n\nHelm chart:  \nhttps://github.com/boarder981/k8s-ingress-info\n\nRun via Docker:  \nhttps://hub.docker.com/r/bitsofinfo/kubernetes-ingress-info\n\nOtherwise:\n\n**Python 3.6+**\n\n**Kubernetes version 1.19+**\n\nDependencies: See [Dockerfile](Dockerfile)\n\nWhen deploying to a Kubernetes cluster the `Pod` that `kubernetes-ingress-info` is\ndeployed as needs to run as a `serviceAccount` with (at a minimum) a binding to a\n`[Cluster]Role` with the following RBAC permissions:\n\n```\n...\nrules:\n- apiGroups: [\"networking.k8s.io\"]\n  resources: [\"ingresses\"]\n  verbs: [\"list\"]\n```\n\n\n\n## \u003ca name=\"example\"\u003e\u003c/a\u003eExample:\n\nThis example will install `kubernetes-ingress-info` onto a Kubernetes cluster.\nThe [example.yaml](examples/example.yaml) creates a `Namespace`, `ServiceAccount`\nwith RBAC bindings, a `Deployment`, `Service` and an `Ingress` bound to `host: kubernetes-ingress-info.local`.\n\nThe `ServiceAccount` has the ability to `list` all `ingresses` on a cluster. You can modify\nand install to your cluster however you see fit.\n\n```\nkubectl apply -f examples/example.yaml\n```\n\nOnce installed, you will need a `/etc/hosts` entry or DNS setup for `kubernetes-ingress-info.local` to\npoint to the `LoadBalancer` configured for whatever `IngressController` consumed the example `Ingress` in `example.yaml`\n\nLet's hit the root to get a list of all `Ingress` \"hosts\" on the cluster.\n```\ncurl http://kubernetes-ingress-info.local\n\n[\n  \"kubernetes-ingress-info.local\",\n  ....\n]\n```\n\nValidate the existence of a single `host`, will return a 200\n```\ncurl http://kubernetes-ingress-info.local/kubernetes-ingress-info.local\n\n{\n  \"info\": \"'kubernetes-ingress-info.local' found\"\n}\n```\n\nHow about one that does not exist? (returns a 404)\n```\ncurl http://kubernetes-ingress-info.local/non-existant-host.com\n\n{\n  \"error\": \"'non-existant-host.com' 404 not found\"\n}\n```\n\nCleanup:\n```\nkubectl delete -f examples/example.yaml\n```\n\n\n## \u003ca name=\"api\"\u003e\u003c/a\u003eAPI:\n\nThe API is as follows:\n\nGET all Ingress Hosts on the cluster:\n```\ncurl -X GET http[s]://[kubernetes-ingress-info]\n```\n\nGET a specific `host`. Returns 200 if `host` exists, or a 404 if non-existant\n```\ncurl -X GET http[s]://[kubernetes-ingress-info]/[host]\n```\n\nNote that if you startup `info.py` with the `--host-match-on-header \u003cheadername\u003e` value, the named HTTP request header\nwill be checked for a `host`. This `host` name will then be used if the `/\u003cpath\u003e` host is not found\n\nGET a specific `host` (via custom header). Returns 200 if `host` exists, or a 404 if non-existant\n```\ncurl -X GET http[s]://[kubernetes-ingress-info]/anything -H '\u003c--host-match-on-header header name\u003e: [host]'\n```\n\n## \u003ca name=\"cache\"\u003e\u003c/a\u003eCaching:\n\nIf you enable caching w/ `--enable-cache` the internal Ingress database that is constructed\nafter fetching all available `Ingress` from Kubernetes (and applying all specified selectors)\nis cached to disk. The cache structure is a single key that stores the entire dictionary to\nlocal disk. If running in a container this should have *minimal* storage requirements and\n*does not necessitate a dedicated volume*.\n\nWe currently use the https://github.com/grantjenks/python-diskcache library due to its `get` speed\nand active project activity.\n\n## \u003ca name=\"usage\"\u003e\u003c/a\u003eUsage:\n\n```\nbash-4.4$ python3 info.py -h\n\nusage: info.py [-h] [-r LOAD_CONFIG_MODE] [-i INCLUDE_LABEL_SELECTORS]\n               [-x EXCLUDE_LABEL_SELECTORS] [-n NAMESPACES]\n               [-m HOST_MATCH_ON_HEADER] [-p LISTEN_PORT] [-c]\n               [-e CACHE_TTL_SECONDS] [-d CACHE_DIR] [-l LOG_LEVEL]\n               [-b LOG_FILE]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -r LOAD_CONFIG_MODE, --load-config-mode LOAD_CONFIG_MODE\n                        How the target k8s cluster config will be loaded,\n                        'local' will leverage the current kubectl context from\n                        '~/.kube/config', while 'cluster' will talk direct to\n                        the cluster the process is executing in using the\n                        Pod's configured serviceAccount which needs read\n                        access to all objects of type Ingress. Default 'local'\n  -i INCLUDE_LABEL_SELECTORS, --include-label-selectors INCLUDE_LABEL_SELECTORS\n                        Optional comma delimited of Ingress\n                        label1=value,label2=value pairs that will be used to\n                        build the database of IngressInfo objects available to\n                        be fetched. If specified, ONLY Ingress objects having\n                        ALL specified labels will be retrieved. If not\n                        specified, ALL available Ingress objects will be\n                        retrieved from k8s. Excludes take precendence over\n                        includes.\n  -x EXCLUDE_LABEL_SELECTORS, --exclude-label-selectors EXCLUDE_LABEL_SELECTORS\n                        Optional comma delimited of Ingress\n                        label1=value,label2=value pairs that will be used to\n                        restrict the database of IngressInfo objects available\n                        to be fetched. If specified, ONLY Ingress objects NOT\n                        having ANY of the specified labels will be retrieved.\n                        If not specified, ALL available Ingress objects will\n                        be retrieved from k8s. Excludes take precendence over\n                        includes.\n  -n NAMESPACES, --namespace NAMESPACES\n                        Optional comma delimited of Namespaces to scope\n                        Ingress fetch within\n  -m HOST_MATCH_ON_HEADER, --host-match-on-header HOST_MATCH_ON_HEADER\n                        Optional name of HTTP Request header who's value will\n                        be inspected for an Ingress host match, should the\n                        default path based /[host] not find a match.\n  -p LISTEN_PORT, --listen-port LISTEN_PORT\n                        Port to listen on, default 8081\n  -c, --enable-cache    Optional, enabling caching (uses\n                        https://github.com/grantjenks/python-diskcache)\n  -e CACHE_TTL_SECONDS, --cache-ttl-seconds CACHE_TTL_SECONDS\n                        Optional, cache TTL in seconds\n  -d CACHE_DIR, --cache-dir CACHE_DIR\n                        Optional, cache dir, default /opt/kubernetes-ingress-\n                        info/cache\n  -l LOG_LEVEL, --log-level LOG_LEVEL\n                        log level, default DEBUG\n  -b LOG_FILE, --log-file LOG_FILE\n                        Path to log file, default None, STDOUT\n```                        \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsofinfo%2Fkubernetes-ingress-info","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitsofinfo%2Fkubernetes-ingress-info","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsofinfo%2Fkubernetes-ingress-info/lists"}