kugl 0.3.0__tar.gz

kugl-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2023, 2024 by Jonathan Ross <jonross@alum.mit.edu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kugl-0.3.0/MANIFEST.in

@@ -0,0 +1 @@
+include kugl/builtins/kubernetes.yaml

kugl-0.3.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.1
+Name: kugl
+Version: 0.3.0
+Summary: Explore Kubernetes resources using SQLite
+Home-page: https://github.com/jonross/kugl
+Author: Jon Ross
+Author-email: kugl.devel@gmail.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: arrow<=1.3.0,>=1.0.1
+Requires-Dist: funcy<=1.18,>=1.13
+Requires-Dist: jmespath<=1.0,>=0.9.5
+Requires-Dist: pydantic<=2.9.2,>=2.0.2
+Requires-Dist: pyyaml<=6.0.2,>=5.3
+Requires-Dist: tabulate<=0.9.0,>=0.8.7
+
+
+    PyPI readme goes here.
+    
+    For documentation please visit the [GitHub repository](hgttps://github.com/jonross/kugl).
+    

kugl-0.3.0/README.md

@@ -0,0 +1,137 @@
+# Kugl
+
+Explore Kubernetes resources using SQLite.
+
+## Example
+
+Find the top users of a GPU pool, based on instance type and a team-specific pod label.
+
+With Kugl (and a little configuration)
+
+```shell
+kugl -a "select owner, sum(gpu_req), sum(cpu_req)
+         from pods join nodes on pods.node_name = nodes.name
+         where instance_type like 'g5.%large' and pods.phase in ('Running', 'Pending')
+         group by 1 order by 2 desc limit 10"
+```
+
+With `kubectl` and `jq`
+
+```shell
+kubectl get pods -o json --all-namespaces | 
+jq -r --argjson nodes "$(kubectl get nodes -o json | jq '[.items[] 
+        | select((.metadata.labels["node.kubernetes.io/instance-type"] // "") | test("g5.*large")) 
+        | .metadata.name]')" \
+  '[ .items[]
+    | select(.spec.nodeName as $node | $nodes | index($node))
+    | select(.status.phase == "Running" or .status.phase == "Pending")
+    | . as $pod | $pod.spec.containers[]
+    | select(.resources.requests["nvidia.com/gpu"] != null)
+    | {owner: $pod.metadata.labels["com.mycompany/job-owner"], 
+       gpu: .resources.requests["nvidia.com/gpu"], 
+       cpu: .resources.requests["cpu"]}
+  ] | group_by(.owner) 
+  | map({owner: .[0].owner, 
+         gpu: map(.gpu | tonumber) | add, 
+         cpu: map(.cpu | if test("m$") then (sub("m$"; "") | tonumber / 1000) else tonumber end) | add})
+  | sort_by(-.gpu) | .[:10] | .[]
+  | "\(.owner) \(.gpu) \(.cpu)"'
+```
+
+## Installing
+
+Kugl requires Python 3.9 or later, and kubectl.
+
+**This is an alpha release.**  Please expect bugs and backward-incompatible changes.
+
+If you don't mind Kugl cluttering your Python with its [dependencies](./reqs_public.txt):
+
+```shell
+pip install kugl
+```
+
+If you do mind, there's a Docker image; `mkdir ~/.kugl` and use this Bash alias.  (Sorry, this is an x86 image,
+I don't have multiarch working yet.)
+
+```shell
+kugl() {
+    docker run \
+        -v ~/.kube:/root/.kube \
+        -v ~/.kugl:/root/.kugl \
+        jonross/kugl:0.3.0 python3 -m kugl.main "$@"
+}
+```
+
+If neither of those suits you, it's easy to set up from source.  (This will build a virtualenv in the
+directory where you clone it.)
+
+```shell
+git clone https://github.com/jonross/kugl.git
+cd kugl
+make deps
+# put kugl's bin directory in your PATH
+PATH=${PATH}:$(pwd)/bin
+```
+
+### Test it
+
+Find the pods using the most memory:
+
+```shell
+kugl -a "select name, to_size(mem_req) from pods order by mem_req desc limit 15"
+```
+
+If this query is helpful, [save it](./docs-tmp/shortcuts.md), then you can run `kugl hi-mem`.
+
+Please also see the [recommended configuration](./docs-tmp/recommended.md).
+
+## How it works (important)
+
+Kugl is just a thin wrapper on Kubectl and SQLite.  It turns `SELECT ... FROM pods` into 
+`kubectl get pods -o json`, then maps fields from the response to columns
+in SQLite.  If you `JOIN` to other resource tables like `nodes` it calls `kubectl get`
+for those too.  If you need more columns or tables than are built in as of this release,
+there's a config file for that.
+
+Because Kugl always fetches all resources from a namespace (or everything, if 
+`-a/--all-namespaces` is used), it tries
+to ease Kubernetes API Server load by **caching responses for 
+two minutes**.  This is why it often prints "Data delayed up to ..." messages.
+
+Depending on your cluster activity, the cache can be a help or a hindrance.
+You can suppress the "delayed" messages with the `-r` / `--reckless` option, or
+always update data using the `-u` / `--update` option.  These behaviors, and
+the cache expiration time, can be set in the config file as well.
+
+In any case, please be mindful of stale data and server load.
+
+## Learn more
+
+* [Command-line syntax](./docs-tmp/syntax.md)
+* [Recommended configuration](./docs-tmp/recommended.md)
+* [Settings](./docs-tmp/settings.md)
+* [Built-in tables and functions](./docs-tmp/builtins.md)
+* [Configuring new columns and tables](./docs-tmp/extending.md)
+* [Troubleshooting and feedback](./docs-tmp/trouble.md)
+* [Beyond Kubernetes](./docs-tmp/beyond.md)
+* [License](./LICENSE)
+
+### Pronunciation
+
+Like "cudgel", so, a blunt instrument for convincing data to be row-shaped.
+
+Or "koo-jull", if you prefer something less combative.
+
+"Kugel" is a casserole with varying degrees of cultural significance, and sounds too much like "Google".
+
+### Rationale
+
+Kugl won't replace everyday use of `kubectl`; it's more for ad-hoc queries and reports, where the
+cognitive overhead of `kubectl | jq` is an obstacle.  In that context, full SQL support and user-defined
+tables are essential, and it is where Kugl hopes to go a step further than prior art.
+
+Some other implementations of SQL-on-Kubernetes:
+
+* [ksql](https://github.com/brendandburns/ksql) is built on Node.js and AlaSQL; last commit November 2016.
+* [kubeql](https://github.com/saracen/kubeql) is a SQL-like query language for Kubernetes; last commit October 2017.
+* [kube-query](https://github.com/aquasecurity/kube-query) is an [osquery](https://osquery.io/) extension; last commit July 2020.

kugl-0.3.0/kugl/api.py

@@ -0,0 +1,28 @@
+"""
+Imports usable by user-defined tables in Python (once we have those.)
+"""
+
+from kugl.impl.registry import Registry
+
+from kugl.util import (
+    fail,
+    parse_age,
+    parse_utc,
+    to_age,
+    to_utc,
+)
+
+
+def schema(name: str):
+    def wrap(cls):
+        Registry.get().add_schema(name, cls)
+        return cls
+    return wrap
+
+
+def table(**kwargs):
+    def wrap(cls):
+        Registry.get().add_table(cls, **kwargs)
+        return cls
+    return wrap
+

kugl-0.3.0/kugl/builtins/helpers.py

@@ -0,0 +1,156 @@
+"""
+Wrappers to make JSON returned by kubectl easier to work with.
+"""
+
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+import funcy as fn
+
+from kugl.util import parse_size, parse_cpu
+
+# What container name is considered the "main" container, if present
+MAIN_CONTAINERS = ["main", "notebook", "app"]
+
+
+@dataclass
+class Limits:
+    """
+    A class to hold CPU, GPU and memory resources. This is called "Limits" although it's used for both requests
+    and limits, so as not to confuse "resources" with Kubernetes resources in general.
+    """
+    cpu: Optional[float]
+    gpu: Optional[float]
+    mem: Optional[int]
+
+    def __add__(self, other):
+        if self.cpu is None and other.cpu is None:
+            cpu = None
+        else:
+            cpu = (self.cpu or 0) + (other.cpu or 0)
+        if self.gpu is None and other.gpu is None:
+            gpu = None
+        else:
+            gpu = (self.gpu or 0) + (other.gpu or 0)
+        if self.mem is None and other.mem is None:
+            mem = None
+        else:
+            mem = (self.mem or 0) + (other.mem or 0)
+        return Limits(cpu, gpu, mem)
+
+    def __radd__(self, other):
+        """Needed to support sum() -- handles 0 as a starting value"""
+        return self if other == 0 else self.__add__(other)
+
+    def as_tuple(self):
+        return (self.cpu, self.gpu, self.mem)
+
+    @classmethod
+    def extract(cls, obj):
+        """Extract a Limits object from a dictionary, or return an empty one if the dictionary is None.
+
+        :param obj: A dictionary with keys "cpu", "nvidia.com/gpu" and "memory" """
+        if obj is None:
+            return Limits(None, None, None)
+        cpu = parse_cpu(obj.get("cpu"))
+        gpu = parse_cpu(obj.get("nvidia.com/gpu"))
+        mem = parse_size(obj.get("memory"))
+        return Limits(cpu, gpu, mem)
+
+
+class ItemHelper:
+    """Some common code for wrappers on JSON for pods, nodes et cetera."""
+
+    def __init__(self, obj):
+        self.obj = obj
+        self.metadata = self.obj.get("metadata", {})
+        self.labels = self.metadata.get("labels", {})
+
+    def __getitem__(self, key):
+        """Return a key from the object; no default, will error if not present"""
+        return self.obj[key]
+
+    @property
+    def name(self):
+        """Return the name of the object from the metadata, or none if unavailable."""
+        return self.metadata.get("name") or self.obj.get("name")
+
+    @property
+    def namespace(self):
+        """Return the name of the object from the metadata, or none if unavailable."""
+        return self.metadata.get("namespace")
+
+    def label(self, name):
+        """Return one of the labels from the object, or None if it doesn't have that label."""
+        return self.labels.get(name)
+
+
+class Containerized:
+
+    @abstractmethod
+    def containers(self):
+        raise NotImplementedError()
+
+    def resources(self, tag):
+        return sum(Limits.extract(c.get("resources", {}).get(tag)) for c in self.containers)
+
+
+class PodHelper(ItemHelper, Containerized):
+
+    @property
+    def command(self):
+        return " ".join((self.main or {}).get("command", []))
+
+    @property
+    def is_daemon(self):
+        return any(ref.get("kind") == "DaemonSet" for ref in self.metadata.get("ownerReferences", []))
+
+    @property
+    def containers(self):
+        """Return the containers in the pod, if any, else an empty list."""
+        return self["spec"].get("containers", [])
+
+    @property
+    def main(self):
+        """Return the main container in the pod, if any, defined as the first container with a name
+        in MAIN_CONTAINERS.  If there are none of those, return the first one.
+        """
+        if not self.containers:
+            return None
+        main = fn.first(fn.filter(lambda c: c["name"] in MAIN_CONTAINERS, self.containers))
+        return main or self.containers[0]
+
+
+class JobHelper(ItemHelper, Containerized):
+
+    @property
+    def status(self):
+        status = self.obj.get("status", {})
+        if len(status) == 0:
+            return "Unknown"
+        # Per
+        # https://github.com/kubernetes-client/python/blob/master/kubernetes/docs/V1JobStatus.md
+        # and https://kubernetes.io/docs/concepts/workloads/controllers/job/
+        for c in status.get("conditions", []):
+            if c["status"] == "True":
+                if c["type"] == "Failed":
+                    # TODO use a separate column
+                    return c.get("reason") or "Failed"
+                if c["type"] == "Suspended":
+                    return "Suspended"
+                if c["type"] == "Complete":
+                    return "Complete"
+            if c["type"] == "FailureTarget":
+                return "Failed"
+            if c["type"] == "SuccessCriteriaMet":
+                return "Complete"
+        if status.get("active", 0) > 0:
+            return "Running"
+        return "Unknown"
+
+    @property
+    def containers(self):
+        """Return the containers in the job, if any, else an empty list."""
+        return self["spec"]["template"]["spec"].get("containers", [])
+

kugl-0.3.0/kugl/builtins/kubernetes.py

@@ -0,0 +1,220 @@
+"""
+Built-in table definitions for Kubernetes.
+
+NOTE: This is not a good example of how to write user-defined tables.
+FIXME: Remove references to non-API imports.
+FIXME: Don't use ArgumentParser in the API.
+"""
+import json
+from argparse import ArgumentParser
+from threading import Thread
+
+from .helpers import Limits, ItemHelper, PodHelper, JobHelper
+from kugl.api import schema, table, fail
+from kugl.util import parse_utc, run, WHITESPACE
+
+
+@schema("kubernetes")
+class KubernetesData:  # FIXME: this should be a resource type, not a schema
+
+    def add_cli_options(self, ap: ArgumentParser):
+        ap.add_argument("-a", "--all-namespaces", default=False, action="store_true")
+        ap.add_argument("-n", "--namespace", type=str)
+
+    def handle_cli_options(self, args):
+        if args.all_namespaces and args.namespace:
+            fail("Cannot use both -a/--all-namespaces and -n/--namespace")
+        self.set_namespace(args.all_namespaces, args.namespace)
+
+    def set_namespace(self, all_namespaces: bool, namespace: str):
+        if all_namespaces:
+            # FIXME: engine.py and testing.py still use this
+            self.ns = "__all"
+            self.all_ns = True
+        else:
+            self.ns = namespace or "default"
+            self.all_ns = False
+
+    def get_objects(self, kind: str, namespaced: bool)-> dict:
+        """Fetch resources from Kubernetes using kubectl.
+
+        :param kind: Kubernetes resource type e.g. "pods"
+        :return: JSON as output by "kubectl get {kind} -o json"
+        """
+        namespace_flag = ["--all-namespaces"] if self.ns else ["-n", self.ns]
+        if kind == "pods":
+            pod_statuses = {}
+            # Kick off a thread to get pod statuses
+            def _fetch():
+                _, output, _ = run(["kubectl", "get", "pods", *namespace_flag])
+                pod_statuses.update(self._pod_status_from_pod_list(output))
+            status_thread = Thread(target=_fetch, daemon=True)
+            status_thread.start()
+        if namespaced:
+            _, output, _= run(["kubectl", "get", kind, *namespace_flag, "-o", "json"])
+        else:
+            _, output, _ = run(["kubectl", "get", kind, "-o", "json"])
+        data = json.loads(output)
+        if kind == "pods":
+            # Add pod status to pods
+            status_thread.join()
+            def pod_with_updated_status(pod):
+                metadata = pod["metadata"]
+                status = pod_statuses.get(f"{metadata['namespace']}/{metadata['name']}")
+                if status:
+                    pod["kubectl_status"] = status
+                    return pod
+                return None
+            data["items"] = list(filter(None, map(pod_with_updated_status, data["items"])))
+        return data
+
+    def _pod_status_from_pod_list(self, output) -> dict[str, str]:
+        """
+        Convert the tabular output of 'kubectl get pods' to JSON.
+        :return: a dict mapping "namespace/name" to status
+        """
+        rows = [WHITESPACE.split(line.strip()) for line in output.strip().split("\n")]
+        if len(rows) < 2:
+            return {}
+        header, rows = rows[0], rows[1:]
+        name_index = header.index("NAME")
+        status_index = header.index("STATUS")
+        # It would be nice if 'kubectl get pods' printed the UID, but it doesn't, so use
+        # "namespace/name" as the key.  (Can't use a tuple since this has to be JSON-dumped.)
+        if self.all_ns:
+            namespace_index = header.index("NAMESPACE")
+            return {f"{row[namespace_index]}/{row[name_index]}": row[status_index] for row in rows}
+        else:
+            return {f"{self.ns}/{row[name_index]}": row[status_index] for row in rows}
+
+
+@table(schema="kubernetes", name="nodes", resource="nodes")
+class NodesTable:
+
+    @property
+    def schema(self):
+        return """
+            name TEXT,
+            uid TEXT,
+            cpu_alloc REAL,
+            gpu_alloc REAL,
+            mem_alloc INTEGER,
+            cpu_cap REAL,
+            gpu_cap REAL,
+            mem_cap INTEGER
+        """
+
+    def make_rows(self, context) -> list[tuple[dict, tuple]]:
+        for item in context.data["items"]:
+            node = ItemHelper(item)
+            yield item, (
+                node.name,
+                node.metadata.get("uid"),
+                *Limits.extract(node["status"]["allocatable"]).as_tuple(),
+                *Limits.extract(node["status"]["capacity"]).as_tuple(),
+            )
+
+
+@table(schema="kubernetes", name="pods", resource="pods")
+class PodsTable:
+
+    @property
+    def schema(self):
+        return """
+            name TEXT,
+            uid TEXT,
+            is_daemon INTEGER,
+            namespace TEXT,
+            node_name TEXT,
+            creation_ts INTEGER,
+            command TEXT,
+            phase TEXT,
+            status TEXT,
+            cpu_req REAL,
+            gpu_req REAL,
+            mem_req INTEGER,
+            cpu_lim REAL,
+            gpu_lim REAL,
+            mem_lim INTEGER
+        """
+
+    def make_rows(self, context) -> list[tuple[dict, tuple]]:
+        for item in context.data["items"]:
+            pod = PodHelper(item)
+            yield item, (
+                pod.name,
+                pod.metadata.get("uid"),
+                1 if pod.is_daemon else 0,
+                pod.namespace,
+                pod["spec"].get("nodeName"),
+                parse_utc(pod.metadata["creationTimestamp"]),
+                pod.command,
+                pod["status"]["phase"],
+                pod["kubectl_status"],
+                *pod.resources("requests").as_tuple(),
+                *pod.resources("limits").as_tuple(),
+            )
+
+
+@table(schema="kubernetes", name="jobs", resource="jobs")
+class JobsTable:
+
+    @property
+    def schema(self):
+        return """
+            name TEXT,
+            uid TEXT,
+            namespace TEXT,
+            status TEXT,
+            cpu_req REAL,
+            gpu_req REAL,
+            mem_req INTEGER,
+            cpu_lim REAL,
+            gpu_lim REAL,
+            mem_lim INTEGER
+        """
+
+    def make_rows(self, context) -> list[tuple[dict, tuple]]:
+        for item in context.data["items"]:
+            job = JobHelper(item)
+            yield item, (
+                job.name,
+                job.metadata.get("uid"),
+                job.namespace,
+                job.status,
+                *job.resources("requests").as_tuple(),
+                *job.resources("limits").as_tuple(),
+            )
+
+
+class LabelsTable:
+    """Base class for all built-in label tables; subclasses need only define UID_FIELD."""
+
+    @property
+    def schema(self):
+        return f"""
+            {self.UID_FIELD} TEXT,
+            key TEXT,
+            value TEXT
+        """
+
+    def make_rows(self, context) -> list[tuple[dict, tuple]]:
+        for item in context.data["items"]:
+            thing = ItemHelper(item)
+            for key, value in thing.labels.items():
+                yield item, (thing.metadata.get("uid"), key, value)
+
+
+@table(schema="kubernetes", name="node_labels", resource="nodes")
+class NodeLabelsTable(LabelsTable):
+    UID_FIELD = "node_uid"
+
+
+@table(schema="kubernetes", name="pod_labels", resource="pods")
+class PodLabelsTable(LabelsTable):
+    UID_FIELD = "pod_uid"
+
+
+@table(schema="kubernetes", name="job_labels", resource="jobs")
+class JobLabelsTable(LabelsTable):
+    UID_FIELD = "job_uid"

kugl-0.3.0/kugl/builtins/kubernetes.yaml

@@ -0,0 +1,27 @@
+
+resources:
+  - name: pods
+    namespaced: true
+  - name: pod_statuses
+    namespaced: true
+  - name: jobs
+    namespaced: true
+  - name: nodes
+    namespaced: false
+
+# node_taints builtin is defined here because it doesn't have any special column extraction
+# logic, and because it serves as a good unit test.
+
+create:
+  - table: node_taints
+    resource: nodes
+    row_source:
+      - items
+      - spec.taints
+    columns:
+      - name: node_uid
+        path: ^metadata.uid
+      - name: key
+        path: key
+      - name: effect
+        path: effect