{"id":20705749,"url":"https://github.com/sustainable-computing-io/susql-operator","last_synced_at":"2025-04-23T01:36:48.260Z","repository":{"id":203332935,"uuid":"709314412","full_name":"sustainable-computing-io/susql-operator","owner":"sustainable-computing-io","description":"a Kubernetes operator that aggregates energy data from tagged resources","archived":false,"fork":false,"pushed_at":"2024-06-07T09:36:53.000Z","size":307,"stargazers_count":6,"open_issues_count":32,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-06-11T16:16:17.565Z","etag":null,"topics":["energy","kepler","kubernetes","monitoring","openshift","operator","susql","sustainability"],"latest_commit_sha":null,"homepage":"http://susql.org","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sustainable-computing-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-24T13:22:26.000Z","updated_at":"2024-06-14T17:45:45.987Z","dependencies_parsed_at":null,"dependency_job_id":"a2302639-66e5-4d7e-a116-d264640499cb","html_url":"https://github.com/sustainable-computing-io/susql-operator","commit_stats":null,"previous_names":["sustainablecomputing/susql-operator","sustainable-computing-io/susql-operator"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sustainable-computing-io%2Fsusql-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sustainable-computing-io%2Fsusql-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sustainable-computing-io%2Fsusql-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sustainable-computing-io%2Fsusql-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sustainable-computing-io","download_url":"https://codeload.github.com/sustainable-computing-io/susql-operator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250354224,"owners_count":21416747,"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":["energy","kepler","kubernetes","monitoring","openshift","operator","susql","sustainability"],"created_at":"2024-11-17T01:19:35.199Z","updated_at":"2025-04-23T01:36:48.253Z","avatar_url":"https://github.com/sustainable-computing-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SusQL Operator\n\nSusQL is a Kubernetes operator that aggregates energy and estimated carbon dioxide emission data for pods tagged with SusQL specific labels. The energy measurements are obtained from [Kepler](https://sustainable-computing.io/) which should be deployed on the cluster before using SusQL. Click the picture below to watch the demo video.\n\n[![SusQL Demo](https://github.com/sustainable-computing-io/susql-operator/wiki/files/SusQL-Demo-2024-10-Thumbnail.png)](https://youtu.be/9CwuhOfVtjE)\n\n## Getting Started\n\nSusQL is an operator that can be deployed in a Kubernetes/OpenShift cluster. You can also use [kind](https://sigs.k8s.io/kind) or [minikube](https://minikube.sigs.k8s.io/) as a local cluster for testing, or run against a remote cluster.\n\n## Carbon Dioxide Emission Calculation\n\nBy default SusQL calculates carbon dioxide emission in grams of CO2 using a carbon intensity value from \n[US EPA](https://www.epa.gov/energy/greenhouse-gases-equivalencies-calculator-calculations-and-references).\nSusQL can be configured to use other static carbon intensity values or query carbon intensity values for a\ngiven location from web API's such as those provided by\nthe Green Software Foundation's [Carbon Aware SDK](https://github.com/Green-Software-Foundation/carbon-aware-sdk).\n\nDetailed information on configuration of CO2 emission calculation in SusQL is available in the [SusQL carbon\ncalculation documentation.](doc/carbon.md)\n\n## Prerequisites\n\nKepler is assumed to be installed in the cluster.\n\n## Installation\n\n- Follow these instructions for easy SusQL installation from the Red Hat Community Operator catalog on an OpenShift cluster.\n  - [Installation on OpenShift](doc/openshift-installation.md)\n\n- Follow these instructions to install the SusQL Operator from [OperatorHub.io](https://operatorhub.io) on a Kubernetes cluster including OpenShift.\n  - [Installation from OperatorHub.io](doc/operatorhub-installation.md)\n\n- Follow these instructions to install the SusQL Operator from a Helm chart on a Kubernetes cluster, including OpenShift.\n  - [Installation with Helm](doc/helm-installation.md)\n \n\n## Using SusQL\n\nTo begin using SusQL, a `LabelGroup` is used to specify the set of labels that the controller uses to identify pods that belong to the same energy aggregation. An example of a `LabelGroup` could be:\n\n```\napiVersion: susql.ibm.com/v1\nkind: LabelGroup\nmetadata:\n    name: labelgroup-name\n    namespace: default\nspec:\n    labels:\n        - my-label-1\n        - my-label-2\n```\n\nA pod that would be part of the ***group of pods*** belonging to the same energy aggregation would specify the `LabelGroup` labels as:\n\n```\napiVersion: v1\nkind: Pod\nmetadata:\n    name: pod-name\n    labels:\n        susql.label/1: my-label-1\n        susql.label/2: my-label-2\nspec:\n    containers:\n        - name: container\n          image: ubuntu\n          command: [\"sleep\"]\n          args: [\"infinity\"]\n```\n\nEnergy of the group of pods is exposed in two ways:\n\n* Through Prometheus at `http://prometheus-susql.openshift-kepler-operator.svc.cluster.local:9090` using the query `susql_total_energy_joules{susql_label_1=my-label-1,susql_label_2=my-label-2}`\n* From `status` of the `LabelGroup` CRD given as `labelgroup.status.totalEnergy`\n\n## Other Examples\n- A step by step explanation of how to aggregate a [GPU based Jupyter Notebook workload on OpenShift AI](doc/openshift-ai-example-notebook.md).\n\n\n## License\n\nCopyright 2023, 2024, 2025.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsustainable-computing-io%2Fsusql-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsustainable-computing-io%2Fsusql-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsustainable-computing-io%2Fsusql-operator/lists"}