{"id":19889177,"url":"https://github.com/ernail/grafaml","last_synced_at":"2025-05-02T17:33:24.078Z","repository":{"id":183459908,"uuid":"667585200","full_name":"erNail/grafaml","owner":"erNail","description":"Create Grafana Dashboards from YAML using Helm Chart templating","archived":false,"fork":false,"pushed_at":"2024-07-29T01:28:23.000Z","size":510,"stargazers_count":10,"open_issues_count":5,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-12T18:09:18.516Z","etag":null,"topics":["grafana","helm","kubernetes","yaml"],"latest_commit_sha":null,"homepage":"","language":"Smarty","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/erNail.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2023-07-17T21:08:16.000Z","updated_at":"2024-06-24T14:21:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"9a0f45b8-c678-4aa0-bc36-9d9822006ad2","html_url":"https://github.com/erNail/grafaml","commit_stats":null,"previous_names":["ernail/grafaml"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erNail%2Fgrafaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erNail%2Fgrafaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erNail%2Fgrafaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erNail%2Fgrafaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erNail","download_url":"https://codeload.github.com/erNail/grafaml/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224324420,"owners_count":17292521,"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":["grafana","helm","kubernetes","yaml"],"created_at":"2024-11-12T18:09:21.584Z","updated_at":"2024-11-12T18:09:22.451Z","avatar_url":"https://github.com/erNail.png","language":"Smarty","funding_links":[],"categories":[],"sub_categories":[],"readme":"# grafaml\n\nCreate Grafana Dashboards from YAML using Helm Chart templating.\n\nThis YAML:\n\n```yaml\ntitle: \"Simple Dashboard\"\npanels:\n  columns: 2\n  panelHeight: 8\n  list:\n    - title: \"Prometheus Targets Up\"\n      type: \"stat\"\n      targets:\n        - expr: \"up\"\n\n    - title: \"Resource Usage in Percent\"\n      description: \"Memory and CPU Usage\"\n      type: \"stat\"\n      targets:\n        - expr: \"(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100\"\n          legendFormat: \"Memory Usage\"\n        - expr: \"sum by (instance, job)(avg by (mode, instance) (rate(node_cpu_seconds_total{mode!='idle'}[2m]))) * 100\"\n          legendFormat: \"CPU Usage\"\n\n    - title: \"Memory Usage in Percent over Time\"\n      type: \"timeseries\"\n      targets:\n        - expr: \"(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100\"\n\n    - title: \"CPU Usage in Percent over Time\"\n      type: \"timeseries\"\n      targets:\n        - expr: \"sum by (instance, job) (avg by (mode, instance) (rate(node_cpu_seconds_total{mode!='idle'}[2m])))\"\n```\n\nBecomes this dashboard:\n\n![Simple Dashboard](./example-dashboards/values-simple-dashboard.png)\n\n## Problems Grafaml Addresses\n\n1. **Grafana UI**: Creating and editing Dashboards in the Grafana UI can be a painstaking and slow process.\n\n2. **Grafana JSON Model**: Creating and editing Dashboards via the Grafana JSON model is complicated,\ndue to the complexity of the JSON model and the absolute positioning of panels.\n\n3. **Version Control**: Tracking dashboard changes in Git with the Grafan JSON model is inefficient.\nEven little changes to the dashboard can cause hundreds of lines to change.\n\n## Features\n\n**Create Dashboards from YAML**: Instead of using the Grafana UI or writing complex JSON models,\nyou can write simplified YAML files from which the dashboard JSON is generated.\nWith this, version control becomes efficient again.\n\n**Grid-Based Panel Positioning**: Instead of worrying about the absolute positioning of every single panel,\nGrafaml arranges panels based on their definition order in a grid with a flexible number of columns.\n\n**Kubernetes Deployment**: Grafaml is a Helm Chart.\nGrafana Dashboards can be deployed as ConfigMaps, which can optionally be discovered by the [Grafana Sidecar Container][1].\n\n## Limitations\n\n**Variable Positioning of Panels**: Panels are arranged in a grid based on their definition order.\nDue to this, it is not possible to have panels with variable width or positioning.\n\n## Getting started\n\n### Creating the dashboard YAML\n\nFirst we need to create a Helm Values file containing the definition of our dashboard.\nWe'll call the file `values-my-dashboard.json`.\nIt will define a very simple dashboard with only 2 panels:\n\n```yaml\ntitle: \"Simple Dashboard\"\npanels:\n  colums: 2\n  panelHeight: 8\n  list:\n    - title: \"Memory Usage in Percent over Time\"\n      type: \"timeseries\"\n      targets:\n        - expr: \"(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100\"\n    - title: \"CPU Usage in Percent over Time\"\n      type: \"timeseries\"\n      targets:\n        - expr: \"sum by (instance, job) (avg by (mode, instance) (rate(node_cpu_seconds_total{mode!='idle'}[2m])))\"\n```\n\nYou can find all possible configuration options in the [default `values.yaml`](./charts/grafaml/values.yaml)\nand in the [`README.md` of the Helm Chart`](./charts/grafaml/README.md).\n\nYou can find example Dashboards in the [`example-dashboards`](./example-dashboards/) directory.\n\nIn the next step, the `values-my-dashboard.json` will be merged with the default [default `values.yaml`](./charts/grafaml/values.yaml),\nfrom which the dashboard JSON will be generated.\n\n### Generating the dashboard JSON\n\nThis step is optional if you want to [deploy the dashboard in a Kubernetes Cluster](#deploying-the-dashboard-in-kubernetes).\n\nExecute this code in your Shell to create a `dashboard.json`:\n\n```shell\n# Adapt the variables to your needs\nname=\"my-dashboard\"\nvalues=\"./values-my-dashboard.yaml\"\nhelm template $name oci://registry-1.docker.io/ernail/grafaml --values $values --set onlyRenderDashboardJson=true | tail -n +3 \u003e dashboard.json\n```\n\n### Deploying the dashboard in Kubernetes\n\nExecute this code in your shell to deploy the dashboard as ConfigMap in Kubernetes:\n\n```shell\nname=\"my-dashboard\"\nvalues=\"./values-my-dashboard.yaml\"\nnamespace=\"my-namespace\"\nhelm upgrade $name oci://registry-1.docker.io/ernail/grafaml --install --create-namespace --namespace $namespace --values $values\n```\n\nIf you are using the [Grafana Sidecar Container][1], the dashboard should now be available in your Grafana.\n\n[1]: https://github.com/grafana/helm-charts/blob/main/charts/grafana/README.md#sidecar-for-dashboards\n\n## Usage\n\nThe basic usage of Grafaml is already explained in the [Getting Started](#getting-started) section.\nAny additional usage information is documented here.\n\n### Using Helmfile\n\n[Helmfile](https://github.com/helmfile/helmfile) is a declarative spec for deploying Helm Charts.\nIt can be used to simplify the commands for rendering and deploying the dashboards.\n\nIf you want to use Helmfile, here is an example `helmfile.yaml`:\n\n```yaml\nrepositories:\n  - name: \"ernail\"\n    url: \"registry-1.docker.io/ernail\"\n    oci: true\n\nreleases:\n  - name: \"my-dashboard\"\n    namespace: \"my-namespace\"\n    chart: \"ernail/grafaml\"\n    version: \"1.0.0\"\n    values:\n      - \"./values-my-dashboard.yaml\"\n      - onlyRenderDashboardJson: false\n```\n\nExecute this code in your Shell to create a `dashboard.json`:\n\n```shell\nhelmfile template --file ./helmfile.yaml --set onlyRenderDashboardJson=true | tail -n +3 \u003e dashboard.json\n```\n\nExecute this code in your shell to deploy the dashboard as ConfigMap in Kubernetes:\n\n```shell\nhelmfile apply --file ./helmfile.yaml\n```\n\n## Development\n\n### Testing\n\n```shell\nhelm unittest ./charts/grafaml\n```\n\n### Linting\n\n```shell\npip install -r requirements.txt\npre-commit run --all-files\nhelm lint ./charts/grafaml\nkube-linter lint ./charts/grafaml\n```\n\n### Templating\n\nUsing Helm:\n\n```shell\nhelm template grafaml ./charts/grafaml\n```\n\nUsing Helmfile:\n\n```shell\nhelmfile template --file ./charts/grafaml/helmfile.yaml\n```\n\n### Deploying\n\nUsing Helm:\n\n```shell\nhelm upgrade grafaml ./charts/grafaml --install --create-namespace --namespace grafaml\n```\n\nUsing Helmfile:\n\n```shell\nhelmfile apply --file ./charts/grafaml/helmfile.yaml\n```\n\n### Generating documentation\n\n```shell\nhelm-docs ./charts/grafaml/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fernail%2Fgrafaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fernail%2Fgrafaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fernail%2Fgrafaml/lists"}