{"id":27402822,"url":"https://github.com/gregros/kubeq","last_synced_at":"2026-05-17T09:48:30.359Z","repository":{"id":286828019,"uuid":"938934655","full_name":"GregRos/kubeq","owner":"GregRos","description":"Irreponsibly powerful tool for querying your k8s cluster.","archived":false,"fork":false,"pushed_at":"2025-04-08T14:38:21.000Z","size":210,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-16T18:35:06.110Z","etag":null,"topics":["functional-programming","kubectl","kubernetes","library","package","poetry","python","tool"],"latest_commit_sha":null,"homepage":"","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/GregRos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-02-25T18:19:34.000Z","updated_at":"2025-05-06T13:09:23.000Z","dependencies_parsed_at":"2025-08-04T10:30:26.409Z","dependency_job_id":null,"html_url":"https://github.com/GregRos/kubeq","commit_stats":null,"previous_names":["gregros/kubeq"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GregRos/kubeq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregRos%2Fkubeq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregRos%2Fkubeq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregRos%2Fkubeq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregRos%2Fkubeq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GregRos","download_url":"https://codeload.github.com/GregRos/kubeq/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregRos%2Fkubeq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279020657,"owners_count":26086898,"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","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"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":["functional-programming","kubectl","kubernetes","library","package","poetry","python","tool"],"created_at":"2025-04-14T04:45:42.675Z","updated_at":"2025-10-14T19:37:38.905Z","avatar_url":"https://github.com/GregRos.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kubeq\n`kube` is a *diagnostic* tool for running queries on a k8s cluster across multiple resources types. It’s essentially a primitive but powerful query engine that runs locally.\n\nIt works by *reducing* its more complex query structure it into multiple simpler queries that the k8s API can digest, and then sending them all with a degree of parallelism.\n\nThis lets you answer such zany questions as:\n\n- What’s in that namespace?\n- What are all the flux resources in our cluster?\n- Are there any resources that aren’t in a ready state?\n\nKubeq can result in an ungodly amount of stress on your control plane. Modern kubernetes versions support rate limiting by default, so most likely kubeq will just fail, but it also comes with its own safety features just in case.\n\nYou might also have to disable them.\n# How it works\nKubeq uses queries that are very similar to what `kubectl get` supports, with a few exceptions:\n\n1. There are actually two queries — a *kind query* and a *resource query*.\n2. The *resource query* supports query operators for fields.\n3. You can also query annotations.\n4. It adds glob and regular expression operators to everything.\n\nFor example, here is how you can get a list of *all* Flux resources in your cluster that have a name starting with `the-awesome-` using the CLI:\n\n```bash\nkubeq get -k '*.fluxcd.io/*' -s 'name ~ the-awesome-*'\n```\n\nThis query will return all the resources with any kind and version, and a resource \ngroup that ends with `fluxcd.io`. \n\nUnder the hood, this query is processed as follows:\n\n1. First, we retrieve all the registered resources from the control plane or use a cache.\n2. We scan those resources to find matches for the glob under `-k`.\n3. For each resource, we send a query with no selectors, since k8s doesn’t support globs.\n4. We filter the results in memory based on the glob.\n5. We print the results.\n\n# Kind queries\nKind queries support just querying the resource kind identifier, which is the string that includes the kind, resource group, and version.\n\nThis is the string you get from `kubectl` that describes the resource you’re dealing with. Here are some examples:\n```\ngit.source.toolkit.fluxcd.io/v1\nkustomization.kustomize.config.k8s.io/v1beta1\n```\n\nYou can use globs and regular expressions. Globs are used by default, and you can enable regex by surrounding the entire kind query with `/.../`. You don’t need to escape `/` inside the regex. \n\nRegardless of what you use, you have to match **the entire kind**.\n\nUsing the CLI:\n\n```\n-k '*.fluxcd.io/*'\n-k '/.*\\.fluxcd.io/.*/'\n```\n# Selectors\nA selector narrows down the list of retrievable resources based on or more properties. Like `kubectl`, `kubeq` does not support disjunctions or unions. \n\nThis means that you can’t query resources based on something like:\n\n```\n🚫 NOT POSSIBLE 🚫\nfield1 = 1 OR field2 = 1\n```\n\nInstead, multiple selectors combine using `AND`, just like when using `kubectl`. However, you can also use the `in` operator to match one of several complete literals.\n\n```bash\n-s 'name in (name1, name2, name3)'\n```\n\nAs a general rule, it’s better to have **more selectors** than less, because it reduces the number of records that must be retrieved. The most performance intensive query is just:\n\n```bash\n😨 never do this!\nkubeq get -k '*' -s 'name ~ *'\n```\n\nWhich just retrieves **every single thing in the cluster**.\n\nThe properties you can use include the following:\n\n1. Labels.\n2. Annotations.\n3. Resource-specific fields.\n\nThe type of property is determined by a *property prefix* which includes:\n\n- Names of labels begin with `%`\n- Names of annotations begin with `^`\n\nIf a property doesn’t have a prefix, it’s considered a field. \n\nYou combine the property specifier with an operator. You can use one of the following operator structures:\n\n```\n%app = podinfo\n^annotation != something\nname in (one, two)\nname not in (one, two)\nname ~ gl?b\nname ~ /regex/\n```\n\n## Passing down\nkubeq will pass as much of your query as possible to the API, but a lot of things can’t be passed down. That includes:\n\n1. Query operators on fields\n2. Glob and regex matching.\n3. Any selector on annotations, which can’t normally be queried.\n\nWhen this happens, one of two things will happen:\n\n- The query will be split into two queries that when combined result in what you asked for.\n- The selector will be erased, which will cause the response to have extra results that need to be filtered out.\n\nThis means that a query that seems to have a lot of selectors might actually end up retrieving the entire cluster and sending hundreds of queries. There are some safety mechanisms in place, but it’s still a possibility.\n\nTo be clear, the strain on kubeq is less important than the strain this kind of thing puts on your control plane. \n\n## Combining selectors\nYou can combine multiple selectors on the command line using several `-s` flags, like this:\n\n```bash\nkubeq get -s '%app = thingy' -s '%whatever/hello-world = nope'\n```\n\nRemember, this **reduces** the number of results you’re going to get. You can even use several `-s` clauses on the same property if you want.\n\n```bash\nkubeq get -s 'name in (abba, arnold, zim, flouride)' -s 'name ~ a*'\n```\n\n# OOP API\nkubeq is written in Python, and it supports a Pythonic OOP query API, including lots of type hints to make sure you’re using it right.\n\nHere are some examples of it being used:\n\n```python\nfrom kubeq import KubeQ, SelectionFormula, Eq, Glob, In\nclient = KubeQ(context=\"minikube\")\nformula = SelectionFormula(\n\t{\n\t\tKind(\"version\"): Eq(\"v1\") | Eq(\"v2\"),\n\t\tKind(\"ident\"): Glob(\"P*\"),\n\t\tField(\"metadata.namespace\"): In(\"default\", \"kube-system\"),\n\t}\n)\nresults = await client.query(formula)\nfor r in results:\n\tprint(f\"- {r.metadata.name}\")\n\n```\n\n# 😨 Safety \nKubeq is a tool that can end up pulling your entire cluster — or more likely tripping internal rate limiting and crashing itself. \n\nSome disclaimers:\n- It only protects from individually large queries, not lots of people running queries at the same time.\n- Kubernetes rate limiting is also a thing and probably does a better job.\n\nThere are two fairly primitive mechanisms.\n1. A limit on the total number of queries\n2. A limit on the total number of resources seen\n\nThe default limits are 100 requests and 500 resources seen. They can be configured using:\n\n```\n--max-resources 500\n--max-requests 100\n```\n\nIf your query exceeds the values, partial results will still be retrieved, with a message that further data might be available.\n\nBesides these hard limits, there are extra mechanisms that affect query performance.\n\n```\n--reqs-per-minute 20\n--reqs-parallel 5\n```\n\nThese change number of requests per minute (completed or inflight) and number of parallel inflight requests.\n\n\n# Why is this?\nkubeq is an irresponsibly powerful tool for querying your k8s cluster. It arose from the need to answer one simple question:\n\n\u003e What the hell is in that namespace?\n\nKubernetes has a problem — while resources can be organized across many different hierarchies, its REST API allows you to query them across just one. Namely:\n\n```\ngroup → version → kind → namespace → name\n```\n\nNo tool or dashboard lets you go around this hierarchy. It’s basically set in stone.\n\nBut you often do want to look at collections of different types of resources. Namespaces serve one organizational tool for doing so. \n\nYou can create one, fill it with different resources, and then delete it — but there is no command that can tell you what the hell was in it.\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregros%2Fkubeq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgregros%2Fkubeq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregros%2Fkubeq/lists"}