mirror of
https://github.com/grafana/grafana.git
synced 2025-12-20 19:44:55 +08:00
Compare commits
11 Commits
zoltan/pos
...
release-12
| Author | SHA1 | Date | |
|---|---|---|---|
|
bb02902e47 | ||
|
20051fb1fc | ||
|
|
4c60d59676 | ||
|
18eeb4f21d | ||
|
597837995e | ||
|
047da1442e | ||
|
|
0898ec6045 | ||
|
e6826107e4 | ||
|
e1f5703052 | ||
|
8999e8e074 | ||
|
678ed88a7e |
4
.github/CODEOWNERS
vendored
4
.github/CODEOWNERS
vendored
@@ -41,12 +41,14 @@
|
||||
/docs/sources/ @irenerl24
|
||||
|
||||
/docs/sources/alerting/ @JohnnyK-Grafana
|
||||
/docs/sources/as-code/ @urbiz-grafana
|
||||
/docs/sources/developer-resources/ @urbiz-grafana
|
||||
/docs/sources/datasources/ @lwandz13
|
||||
/docs/sources/upgrade-guide/ @jtvdez
|
||||
/docs/sources/whatsnew/ @jtvdez
|
||||
|
||||
|
||||
/docs/sources/developers/plugins/ @grafana/plugins-platform-frontend @grafana/plugins-platform-backend
|
||||
/docs/sources/developer-resources/plugins/ @grafana/plugins-platform-frontend @grafana/plugins-platform-backend
|
||||
/docs/sources/visualizations/dashboards/ @imatwawana
|
||||
/docs/sources/visualizations/panels-visualizations/ @imatwawana
|
||||
|
||||
|
||||
1
.github/workflows/release-build.yml
vendored
1
.github/workflows/release-build.yml
vendored
@@ -212,6 +212,7 @@ jobs:
|
||||
run-id: ${{ github.run_id }}
|
||||
bucket-path: ${{ needs.setup.outputs.version }}_${{ github.run_id }}
|
||||
environment: prod
|
||||
runs-on: ubuntu-x64-small
|
||||
|
||||
publish-dockerhub:
|
||||
if: github.ref_name == 'main'
|
||||
|
||||
168
CHANGELOG.md
168
CHANGELOG.md
@@ -1,3 +1,171 @@
|
||||
<!-- 12.3.0 START -->
|
||||
|
||||
# 12.3.0 (2025-11-19)
|
||||
|
||||
### Features and enhancements
|
||||
|
||||
- **API Clients:** Add lazy hooks to clients [#113226](https://github.com/grafana/grafana/pull/113226), [@tomratcliffe](https://github.com/tomratcliffe)
|
||||
- **API clients:** Automatically set PATCH headers [#111879](https://github.com/grafana/grafana/pull/111879), [@Clarity-89](https://github.com/Clarity-89)
|
||||
- **API clients:** Extract into a package [#111810](https://github.com/grafana/grafana/pull/111810), [@Clarity-89](https://github.com/Clarity-89)
|
||||
- **API clients:** Extract into a package (Enterprise)
|
||||
- **API clients:** Update API clients to include all endpoints & add hooks [#113061](https://github.com/grafana/grafana/pull/113061), [@tomratcliffe](https://github.com/tomratcliffe)
|
||||
- **AccessControl:** Include hidden roles in service account role display [#112924](https://github.com/grafana/grafana/pull/112924), [@Jguer](https://github.com/Jguer)
|
||||
- **AccessControl:** Increase limit of LBAC for Datasources rules [#111560](https://github.com/grafana/grafana/pull/111560), [@Jguer](https://github.com/Jguer)
|
||||
- **Accessibility:** Wrap data source info onto 2 lines at small viewports [#113033](https://github.com/grafana/grafana/pull/113033), [@ashharrison90](https://github.com/ashharrison90)
|
||||
- **Alert Enrichment:** Add mutator to insert rule UID labels to allow for efficient use of labelSelector (Enterprise)
|
||||
- **Alerting:** Add enrichment components to rule view page (Enterprise)
|
||||
- **Alerting:** Add enrichment section to rule view page (Enterprise)
|
||||
- **Alerting:** Add jitter support for periodic alert state storage to reduce database load spikes [#111357](https://github.com/grafana/grafana/pull/111357), [@softho0n](https://github.com/softho0n)
|
||||
- **Alerting:** Add position-based matching for identical alert rules [#112407](https://github.com/grafana/grafana/pull/112407), [@konrad147](https://github.com/konrad147)
|
||||
- **Alerting:** Create alertingAlertRuleFormSchema in restrictedGrafanaApis [#112794](https://github.com/grafana/grafana/pull/112794), [@soniaAguilarPeiron](https://github.com/soniaAguilarPeiron)
|
||||
- **Alerting:** Display error message in central state history view [#111445](https://github.com/grafana/grafana/pull/111445), [@laurenashleigh](https://github.com/laurenashleigh)
|
||||
- **Alerting:** Enrichment per rule wip-2 (Enterprise)
|
||||
- **Alerting:** Hide metadata if grouping by folder [#113216](https://github.com/grafana/grafana/pull/113216), [@laurenashleigh](https://github.com/laurenashleigh)
|
||||
- **Alerting:** Improve template ai helper prompt and add some examples (Enterprise)
|
||||
- **Alerting:** Move enrichment tab between details and versions [#110886](https://github.com/grafana/grafana/pull/110886), [@laurenashleigh](https://github.com/laurenashleigh)
|
||||
- **Alerting:** Remove ai feedback button from alert form [#112713](https://github.com/grafana/grafana/pull/112713), [@soniaAguilarPeiron](https://github.com/soniaAguilarPeiron)
|
||||
- **Alerting:** Remove unused components [#111320](https://github.com/grafana/grafana/pull/111320), [@laurenashleigh](https://github.com/laurenashleigh)
|
||||
- **Alerting:** Remove useRulesSourcesWithRuler for SmartAlertTypeDetector [#111623](https://github.com/grafana/grafana/pull/111623), [@soniaAguilarPeiron](https://github.com/soniaAguilarPeiron)
|
||||
- **Alerting:** Surface remote AM silence creation errors properly [#112757](https://github.com/grafana/grafana/pull/112757), [@moustafab](https://github.com/moustafab)
|
||||
- **Alerting:** Triage [#110339](https://github.com/grafana/grafana/pull/110339), [@gillesdemey](https://github.com/gillesdemey)
|
||||
- **Alerting:** Triage rule details drawer [#112055](https://github.com/grafana/grafana/pull/112055), [@konrad147](https://github.com/konrad147)
|
||||
- **Alerting:** Update prompt examples for template AI Helper (Enterprise)
|
||||
- **Alerting:** Update width to instance details drawer in Triage page [#113209](https://github.com/grafana/grafana/pull/113209), [@soniaAguilarPeiron](https://github.com/soniaAguilarPeiron)
|
||||
- **Alerting:** Use new enrichment endpoints in FE (Enterprise)
|
||||
- **Alerting:** Use ruleUid as a prop instead of extracting it from the rule context (Enterprise)
|
||||
- **Analytics:** Aggregate daily summary in datasources analytics (Enterprise)
|
||||
- **Analytics:** Apply proper batching to Loki exports and add configurable settings (Enterprise)
|
||||
- **Annotations:** Exclude internal dashboard id when saved via UID [#111535](https://github.com/grafana/grafana/pull/111535), [@ryantxu](https://github.com/ryantxu)
|
||||
- **Azure:** Use SSO settings in plugin context [#112058](https://github.com/grafana/grafana/pull/112058), [@aangelisc](https://github.com/aangelisc)
|
||||
- **Buttons:** Active style for buttons [#111235](https://github.com/grafana/grafana/pull/111235), [@gtk-grafana](https://github.com/gtk-grafana)
|
||||
- **Caching:** Disable cache if datasource has oauthPassThru=true (Enterprise)
|
||||
- **Canvas:** Allow non-icon bg image fields [#112308](https://github.com/grafana/grafana/pull/112308), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **Chore:** Add logsdrilldown replace to apps/iam/go.mod [#112581](https://github.com/grafana/grafana/pull/112581), [@njvrzm](https://github.com/njvrzm)
|
||||
- **CloudWatch Logs:** Don't add console link to every field in the logs response [#112230](https://github.com/grafana/grafana/pull/112230), [@idastambuk](https://github.com/idastambuk)
|
||||
- **CloudWatch Logs:** Support Log Anomalies query type [#113067](https://github.com/grafana/grafana/pull/113067), [@idastambuk](https://github.com/idastambuk)
|
||||
- **CloudWatch:** Add syntax highlighting and autocomplete for logs diff command [#111207](https://github.com/grafana/grafana/pull/111207), [@kevinwcyu](https://github.com/kevinwcyu)
|
||||
- **CloudWatch:** Add tracking for logs anomalies [#113181](https://github.com/grafana/grafana/pull/113181), [@idastambuk](https://github.com/idastambuk)
|
||||
- **Dashboard Controls:** Add annotations to the dashboard controls menu [#112816](https://github.com/grafana/grafana/pull/112816), [@leventebalogh](https://github.com/leventebalogh)
|
||||
- **Dashboard Picker:** Update to use correct search + dashboards APIs [#112341](https://github.com/grafana/grafana/pull/112341), [@tomratcliffe](https://github.com/tomratcliffe)
|
||||
- **Dashboard:** Backend always set `metricEditorMode: 0` regardless `metricQueryType` and `expression` [#111613](https://github.com/grafana/grafana/pull/111613), [@ivanortegaalba](https://github.com/ivanortegaalba)
|
||||
- **Dashboards:** Add a new variable type called "Switch" [#111366](https://github.com/grafana/grafana/pull/111366), [@leventebalogh](https://github.com/leventebalogh)
|
||||
- **Dashboards:** Hide error notifications in kiosk mode on dashboards [#112390](https://github.com/grafana/grafana/pull/112390), [@ivanortegaalba](https://github.com/ivanortegaalba)
|
||||
- **Dynamic Dashboards:** Expand dashboards_init_dashboard_completed tracking info [#111102](https://github.com/grafana/grafana/pull/111102), [@idastambuk](https://github.com/idastambuk)
|
||||
- **ErrorBoundary:** Report specific boundary type to Faro [#112071](https://github.com/grafana/grafana/pull/112071), [@tskarhed](https://github.com/tskarhed)
|
||||
- **Explore:** Use compact mode only when targeting Tempo [#113037](https://github.com/grafana/grafana/pull/113037), [@ifrost](https://github.com/ifrost)
|
||||
- **FeatureToggles:** Remove deprecated experimental apiserver [#111617](https://github.com/grafana/grafana/pull/111617), [@ryantxu](https://github.com/ryantxu)
|
||||
- **Fields Selector:** Add component and integrate with Logs and Logs table visualization [#112534](https://github.com/grafana/grafana/pull/112534), [@matyax](https://github.com/matyax)
|
||||
- **Flame Graph:** Anchor exact match when clicking a table symbol in search [#111101](https://github.com/grafana/grafana/pull/111101), [@samarthbagga-meesho](https://github.com/samarthbagga-meesho)
|
||||
- **FlameGraph:** Improve prompt for open assistant to analyze flamegraph [#113071](https://github.com/grafana/grafana/pull/113071), [@simonswine](https://github.com/simonswine)
|
||||
- **FolderPicker:** Don't show expand button for empty folders and move search icon [#111872](https://github.com/grafana/grafana/pull/111872), [@aocenas](https://github.com/aocenas)
|
||||
- **FolderPicker:** Show parent folder when searching [#111026](https://github.com/grafana/grafana/pull/111026), [@aocenas](https://github.com/aocenas)
|
||||
- **Geomap:** Add a MapLibre style base layer [#109841](https://github.com/grafana/grafana/pull/109841), [@remogeissbuehler](https://github.com/remogeissbuehler)
|
||||
- **Geomap:** Move beta layers to GA [#113186](https://github.com/grafana/grafana/pull/113186), [@drew08t](https://github.com/drew08t)
|
||||
- **Go:** Update to 1.25.2 + golangci-lint v2.5.0 + golang.org/x/net v0.45.0 [#112149](https://github.com/grafana/grafana/pull/112149), [@macabu](https://github.com/macabu)
|
||||
- **Go:** Update to 1.25.3 [#112359](https://github.com/grafana/grafana/pull/112359), [@macabu](https://github.com/macabu)
|
||||
- **Grafana Advisor:** Prometheus Type Migration check [#110853](https://github.com/grafana/grafana/pull/110853), [@bossinc](https://github.com/bossinc)
|
||||
- **Grafana Data Source:** Add random walk configuration options [#113009](https://github.com/grafana/grafana/pull/113009), [@nmarrs](https://github.com/nmarrs)
|
||||
- **IAM:** Add uid column in team_member DB table [#112439](https://github.com/grafana/grafana/pull/112439), [@dmihai](https://github.com/dmihai)
|
||||
- **Jaeger:** Migrate API calls to gRPC endpoint [#113297](https://github.com/grafana/grafana/pull/113297), [@jcolladokuri](https://github.com/jcolladokuri)
|
||||
- **LBAC for data sources:** Provide user feedback of potential performance loss from LBAC rules (Enterprise)
|
||||
- **Library Panels:** Remove direct use of legacy search [#112231](https://github.com/grafana/grafana/pull/112231), [@tomratcliffe](https://github.com/tomratcliffe)
|
||||
- **Logs panel:** Respect selected fields for downloading logs [#111753](https://github.com/grafana/grafana/pull/111753), [@matyax](https://github.com/matyax)
|
||||
- **Nav:** Render menu items as `p` tags so truncation logic can work [#113248](https://github.com/grafana/grafana/pull/113248), [@tomratcliffe](https://github.com/tomratcliffe)
|
||||
- **Navigation:** Move Cost management and billing plugin to root [#111739](https://github.com/grafana/grafana/pull/111739), [@gubjanos](https://github.com/gubjanos)
|
||||
- **PanelTimeCompare:** Support saving time compare window [#113150](https://github.com/grafana/grafana/pull/113150), [@torkelo](https://github.com/torkelo)
|
||||
- **PanelTimeSettings:** Support panel time range settings changes from dashboard in view mode [#113027](https://github.com/grafana/grafana/pull/113027), [@torkelo](https://github.com/torkelo)
|
||||
- **Plugins:** Install Grafana Pathfinder behind a feature flag [#109909](https://github.com/grafana/grafana/pull/109909), [@Jayclifford345](https://github.com/Jayclifford345)
|
||||
- **PostgreSQL:** Support PGPASSFILE by making password optional [#108856](https://github.com/grafana/grafana/pull/108856), [@taraspos](https://github.com/taraspos)
|
||||
- **Provisioning:** Watch file system for changes [#112184](https://github.com/grafana/grafana/pull/112184), [@ryantxu](https://github.com/ryantxu)
|
||||
- **Reporting:** Add support for schema v2 dashboards (Enterprise)
|
||||
- **Reporting:** Wait for streaming to end before exporting CSVs (Enterprise)
|
||||
- **SQL Expressions:** Add Functions to Allow list [#113291](https://github.com/grafana/grafana/pull/113291), [@kylebrandt](https://github.com/kylebrandt)
|
||||
- **Snapshots:** Use appSubUrl for View all snapshots [#111652](https://github.com/grafana/grafana/pull/111652), [@Clarity-89](https://github.com/Clarity-89)
|
||||
- **Span Details:** Bring back span id to span details [#112411](https://github.com/grafana/grafana/pull/112411), [@ifrost](https://github.com/ifrost)
|
||||
- **Span Details:** Wrap label values [#112413](https://github.com/grafana/grafana/pull/112413), [@ifrost](https://github.com/ifrost)
|
||||
- **Stars:** Refactor StarsToolbarButton and unify nav update logic [#112582](https://github.com/grafana/grafana/pull/112582), [@tomratcliffe](https://github.com/tomratcliffe)
|
||||
- **Stat/BarGauge:** Border radius tweak [#112562](https://github.com/grafana/grafana/pull/112562), [@torkelo](https://github.com/torkelo)
|
||||
- **Table:** Add some error-case handling to ImageCell [#110461](https://github.com/grafana/grafana/pull/110461), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **Table:** Allow FieldType.other containing arrays to use Pills [#111205](https://github.com/grafana/grafana/pull/111205), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **Table:** Disable virtualization, hover overflow, and scrollbar width resizing on Safari 26 [#111834](https://github.com/grafana/grafana/pull/111834), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **Table:** Pill and JSON Cells should allow formatting [#111951](https://github.com/grafana/grafana/pull/111951), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **Table:** Support DataLinks and Actions in SparklineCell [#112244](https://github.com/grafana/grafana/pull/112244), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **Table:** Update ad-hoc filter to use name instead of displayName [#112815](https://github.com/grafana/grafana/pull/112815), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **Tempo:** Migrates tags and tag values to datasource backend CallResource requests (Enterprise)
|
||||
- **Theme:** Changes light theme canvas color a more white shade [#111318](https://github.com/grafana/grafana/pull/111318), [@torkelo](https://github.com/torkelo)
|
||||
- **Themes:** Update themes border radius [#111478](https://github.com/grafana/grafana/pull/111478), [@torkelo](https://github.com/torkelo)
|
||||
- **TimeComparison:** Automatically show/hide menu on hover [#112750](https://github.com/grafana/grafana/pull/112750), [@jesdavpet](https://github.com/jesdavpet)
|
||||
- **TimeSeries:** Allow custom time units on x-axis [#112913](https://github.com/grafana/grafana/pull/112913), [@leeoniya](https://github.com/leeoniya)
|
||||
- **Timeseries:** Numeric duration values could render as NaN (#73795) [#112076](https://github.com/grafana/grafana/pull/112076), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **Transformations:** Hide "Match all/any" conditions for less than two filters [#109754](https://github.com/grafana/grafana/pull/109754), [@sudoice](https://github.com/sudoice)
|
||||
- **UI Extensions:** Remove path validation from link extensions [#112259](https://github.com/grafana/grafana/pull/112259), [@leventebalogh](https://github.com/leventebalogh)
|
||||
|
||||
### Bug fixes
|
||||
|
||||
- **Access Control:** Fix the permission checks for saving/updating/deleting annotations [#112953](https://github.com/grafana/grafana/pull/112953), [@IevaVasiljeva](https://github.com/IevaVasiljeva)
|
||||
- **Accessibility:** Improve no-unreduced-motion rule and fix violations [#110304](https://github.com/grafana/grafana/pull/110304), [@tomratcliffe](https://github.com/tomratcliffe)
|
||||
- **Alerting Provisioning:** Don't error on recording rules without conditions [#109410](https://github.com/grafana/grafana/pull/109410), [@djpnicholls](https://github.com/djpnicholls)
|
||||
- **Alerting:** Clear outdated settings when switching contact point type [#111869](https://github.com/grafana/grafana/pull/111869), [@konrad147](https://github.com/konrad147)
|
||||
- **Alerting:** Fix enrichment tab to be rendered only for grafana alerting rules [#113030](https://github.com/grafana/grafana/pull/113030), [@soniaAguilarPeiron](https://github.com/soniaAguilarPeiron)
|
||||
- **Alerting:** Fix instances matching in notification policies [#112326](https://github.com/grafana/grafana/pull/112326), [@konrad147](https://github.com/konrad147)
|
||||
- **Alerting:** Fix threshold params [#111645](https://github.com/grafana/grafana/pull/111645), [@soniaAguilarPeiron](https://github.com/soniaAguilarPeiron)
|
||||
- **Alerting:** Fix unmarshalling of GettableStatus to include time intervals [#112602](https://github.com/grafana/grafana/pull/112602), [@yuri-tceretian](https://github.com/yuri-tceretian)
|
||||
- **Alerting:** Migrate `spec.title` and `spec.name` fieldSelectors [#111993](https://github.com/grafana/grafana/pull/111993), [@gillesdemey](https://github.com/gillesdemey)
|
||||
- **Alerting:** Normalize health when filtering rules [#113087](https://github.com/grafana/grafana/pull/113087), [@gillesdemey](https://github.com/gillesdemey)
|
||||
- **Alerting:** Prohibit receivers with empty name [#113064](https://github.com/grafana/grafana/pull/113064), [@yuri-tceretian](https://github.com/yuri-tceretian)
|
||||
- **Alerting:** Provisioning to fix contact point type on save [#112246](https://github.com/grafana/grafana/pull/112246), [@yuri-tceretian](https://github.com/yuri-tceretian)
|
||||
- **Alerting:** Remove \_\_grafana_origin when duplicating rule [#112396](https://github.com/grafana/grafana/pull/112396), [@soniaAguilarPeiron](https://github.com/soniaAguilarPeiron)
|
||||
- **AnnoList:** Fix annotations not loading when in a repeated row [#111540](https://github.com/grafana/grafana/pull/111540), [@joshhunt](https://github.com/joshhunt)
|
||||
- **Annotations:** Fix issue with transformation logic in scenes [#112288](https://github.com/grafana/grafana/pull/112288), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **Auth:** Fix render user OAuth passthrough [#111636](https://github.com/grafana/grafana/pull/111636), [@charandas](https://github.com/charandas)
|
||||
- **ComboBox:** Add loading state to dropdown and prefixIcon [#112967](https://github.com/grafana/grafana/pull/112967), [@tomratcliffe](https://github.com/tomratcliffe)
|
||||
- **Connections:** Fix connections home page on enterprise [#111751](https://github.com/grafana/grafana/pull/111751), [@oshirohugo](https://github.com/oshirohugo)
|
||||
- **Dashboard:** Fix editor specific permissions in /api [#113292](https://github.com/grafana/grafana/pull/113292), [@stephaniehingtgen](https://github.com/stephaniehingtgen)
|
||||
- **Dashboards:** Fix bug with anon users with editor permissions creating dashboards [#113260](https://github.com/grafana/grafana/pull/113260), [@stephaniehingtgen](https://github.com/stephaniehingtgen)
|
||||
- **Dashboards:** Fix missing Ctrl+O keyboard shortcut for crosshair toggle [#111310](https://github.com/grafana/grafana/pull/111310), [@ivanortegaalba](https://github.com/ivanortegaalba)
|
||||
- **Dashboards:** Fix moving to root folder [#111515](https://github.com/grafana/grafana/pull/111515), [@stephaniehingtgen](https://github.com/stephaniehingtgen)
|
||||
- **Dashboards:** Fix preload field not being persisted via /v1beta1 [#112475](https://github.com/grafana/grafana/pull/112475), [@ivanortegaalba](https://github.com/ivanortegaalba)
|
||||
- **Flame Graph:** Use suffix for values formatted with a short formatter [#110999](https://github.com/grafana/grafana/pull/110999), [@ifrost](https://github.com/ifrost)
|
||||
- **FlameGraph:** Ensure total is only counted once for recursive function calls [#111548](https://github.com/grafana/grafana/pull/111548), [@simonswine](https://github.com/simonswine)
|
||||
- **FolderPermissions:** Return 404 error when folder does not exist instead of 500 [#112919](https://github.com/grafana/grafana/pull/112919), [@Jguer](https://github.com/Jguer)
|
||||
- **FolderPicker:** Fix expand toggle also selecting folder [#111755](https://github.com/grafana/grafana/pull/111755), [@aocenas](https://github.com/aocenas)
|
||||
- **Graphite:** Fix legacy response unmarshalling [#112968](https://github.com/grafana/grafana/pull/112968), [@aangelisc](https://github.com/aangelisc)
|
||||
- **Histogram:** Properly handle sparse heatmap-cells frames [#112907](https://github.com/grafana/grafana/pull/112907), [@leeoniya](https://github.com/leeoniya)
|
||||
- **LDAP Authentication:** Fix URL to propagate username context as parameter [#111723](https://github.com/grafana/grafana/pull/111723), [@bradleypettit](https://github.com/bradleypettit)
|
||||
- **Node graph:** Fix context menu position after scrolling [#112374](https://github.com/grafana/grafana/pull/112374), [@adrapereira](https://github.com/adrapereira)
|
||||
- **Playlist:** Fix navigation issues with emoji-titled dashboards during dual-write migration [#111659](https://github.com/grafana/grafana/pull/111659), [@axelavargas](https://github.com/axelavargas)
|
||||
- **Plugin Details Page:** Fix tabs not loading on hard refresh [#112915](https://github.com/grafana/grafana/pull/112915), [@sunker](https://github.com/sunker)
|
||||
- **Plugin navigation:** Fix active nav item selection when there are more than 10 items in a group [#112886](https://github.com/grafana/grafana/pull/112886), [@aocenas](https://github.com/aocenas)
|
||||
- **Plugins:** Dependencies do not inherit parent URL for preinstall [#111762](https://github.com/grafana/grafana/pull/111762), [@wbrowne](https://github.com/wbrowne)
|
||||
- **Plugins:** Set isProvisioned for local plugins without remote counterpart [#111268](https://github.com/grafana/grafana/pull/111268), [@oshirohugo](https://github.com/oshirohugo)
|
||||
- **Prometheus:** Fix incremental querying logic for public dashboards [#111642](https://github.com/grafana/grafana/pull/111642), [@jcolladokuri](https://github.com/jcolladokuri)
|
||||
- **Prometheus:** Fix parsing logic of prometheus expressions to honor the order of binary operations [#112220](https://github.com/grafana/grafana/pull/112220), [@jcolladokuri](https://github.com/jcolladokuri)
|
||||
- **Security:** fix for CVE-2025-41115 in SCIM (System for Cross-domain Identity Management) (Enterprise)
|
||||
- **SoloPanel:** Fixes issue with solo route and scopes variable [#112769](https://github.com/grafana/grafana/pull/112769), [@torkelo](https://github.com/torkelo)
|
||||
- **Stars:** Fix starred state not being updated [#111936](https://github.com/grafana/grafana/pull/111936), [@Clarity-89](https://github.com/Clarity-89)
|
||||
- **Stat:** Fix math for percent change value heights when sparkline is not rendered [#112599](https://github.com/grafana/grafana/pull/112599), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **StateTimeline:** Fix color display in tooltip [#112878](https://github.com/grafana/grafana/pull/112878), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **Table:** Fix cell inspect for Sparkline and inferred JSON cells [#113059](https://github.com/grafana/grafana/pull/113059), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
- **TextPanel:** Fix `CodeEditor` not appearing properly [#111937](https://github.com/grafana/grafana/pull/111937), [@ashharrison90](https://github.com/ashharrison90)
|
||||
- **UnitPicker/Cascader:** Fixes type to search for unit feature [#112614](https://github.com/grafana/grafana/pull/112614), [@torkelo](https://github.com/torkelo)
|
||||
- **VizTooltip:** Better overflow handling on long series names [#112240](https://github.com/grafana/grafana/pull/112240), [@fastfrwrd](https://github.com/fastfrwrd)
|
||||
|
||||
### Breaking changes
|
||||
|
||||
- **Faro:** Update configuration with best practices [#112108](https://github.com/grafana/grafana/pull/112108), [@joshhunt](https://github.com/joshhunt)
|
||||
- **LibraryPanels:** Remove unique name constraints [#113077](https://github.com/grafana/grafana/pull/113077), [@ryantxu](https://github.com/ryantxu)
|
||||
- **RBAC:** Only write action sets [#112429](https://github.com/grafana/grafana/pull/112429), [@IevaVasiljeva](https://github.com/IevaVasiljeva)
|
||||
|
||||
### Plugin development fixes & changes
|
||||
|
||||
- **Checkbox:** Improve accessibility of the `indeterminate` state [#112388](https://github.com/grafana/grafana/pull/112388), [@ashharrison90](https://github.com/ashharrison90)
|
||||
- **Collapse:** Improve layout and deprecate `collapsible` prop [#113164](https://github.com/grafana/grafana/pull/113164), [@ashharrison90](https://github.com/ashharrison90)
|
||||
- **Docs:** Add storybook links to components [#113102](https://github.com/grafana/grafana/pull/113102), [@samsch](https://github.com/samsch)
|
||||
- **Modal:** Fix button focus being clipped [#112867](https://github.com/grafana/grafana/pull/112867), [@ashharrison90](https://github.com/ashharrison90)
|
||||
- **Slider:** Expose prop to control visibility of input [#113084](https://github.com/grafana/grafana/pull/113084), [@ashharrison90](https://github.com/ashharrison90)
|
||||
- **Slider:** Make `inputId` a required param and fix minor a11y violations [#112006](https://github.com/grafana/grafana/pull/112006), [@ashharrison90](https://github.com/ashharrison90)
|
||||
|
||||
<!-- 12.3.0 END -->
|
||||
<!-- 12.2.1 START -->
|
||||
|
||||
# 12.2.1 (2025-10-21)
|
||||
|
||||
@@ -138,6 +138,10 @@ The following list contains role-based access control actions.
|
||||
| `roles:read` | <ul><li>`roles:*`</li><li>`roles:uid:*`</li></ul> | List roles and read a specific role with its permissions. |
|
||||
| `roles:write` | <ul><li>`permissions:type:delegate`</li><ul> | Create or update a custom role. |
|
||||
| `roles:write` | <ul><li>`permissions:type:escalate`</li><ul> | Reset basic roles to their default permissions. |
|
||||
| `secret.securevalues:create` | <ul><li>`secret.securevalues:*`</li><li> | Create secure values. |
|
||||
| `secret.securevalues:read` | <ul><li>`secret.securevalues:*`</li><li> | Read and list secure values. |
|
||||
| `secret.securevalues:write` | <ul><li>`secret.securevalues:*`</li><li> | Update secure values. |
|
||||
| `secret.securevalues:delete` | <ul><li>`secret.securevalues:*`</li><li> | Delete secure values. |
|
||||
| `server.stats:read` | None | Read Grafana instance statistics. |
|
||||
| `server.usagestats.report:read` | None | View usage statistics report. |
|
||||
| `serviceaccounts:write` | <ul><li>`serviceaccounts:*`</li><ul> | Create Grafana service accounts. |
|
||||
|
||||
43
docs/sources/as-code/_index.md
Normal file
43
docs/sources/as-code/_index.md
Normal file
@@ -0,0 +1,43 @@
|
||||
---
|
||||
aliases:
|
||||
description: Deploy, configure and provision Grafana with as-code workflows.
|
||||
menuTitle: As code
|
||||
title: Deploy, configure and provision Grafana with as-code workflows
|
||||
hero:
|
||||
title: Configure and provision Grafana with as-code workflows
|
||||
level: 1
|
||||
width: 100
|
||||
height: 100
|
||||
description: Manage resources, including folders and dashboards, and configurations with as-code workflows.
|
||||
cards:
|
||||
items:
|
||||
- description: Using Observability as code, you can version, automate, and scale Grafana configurations, including dashboards and observability workflows.
|
||||
height: 24
|
||||
href: ./observability-as-code/
|
||||
title: Observability as code
|
||||
- description: Using Infrastructure as code, you can declaratively manage what Grafana resources to use.
|
||||
height: 24
|
||||
href: ./infrastructure-as-code/
|
||||
title: Infrastructure as code
|
||||
weight: 850
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/
|
||||
---
|
||||
|
||||
{{< docs/hero-simple key="hero" >}}
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
**Observability as code** lets you apply code management best practices to your observability resources. By representing Grafana resources as code, you can integrate them into existing infrastructure-as-code workflows and apply standard development practices. Instead of manually configuring dashboards or settings through the Grafana UI, you can:
|
||||
|
||||
- Write configurations in code: Define dashboards in JSON or other supported formats.
|
||||
- Sync your Grafana setup to GitHub: Track changes, collaborate, and roll back updates using Git and GitHub, or other remote sources.
|
||||
- Automate with CI/CD: Integrate Grafana directly into your development and deployment pipelines.
|
||||
- Standardize workflows: Ensure consistency across your teams by using repeatable, codified processes for managing Grafana resources.
|
||||
|
||||
In Grafana Cloud, you can use **Infrastructure as code** to declaratively create and manage dashboards via configuration files in source code, and incorporate them efficiently into your own use cases. This enables you to review code, reuse it, and create better workflows. Infrastructure as code tools include Terraform, Ansible, the Grafana Operator, and Grizzly.
|
||||
|
||||
## Explore
|
||||
|
||||
{{< card-grid key="cards" type="simple" >}}
|
||||
167
docs/sources/as-code/infrastructure-as-code/_index.md
Normal file
167
docs/sources/as-code/infrastructure-as-code/_index.md
Normal file
@@ -0,0 +1,167 @@
|
||||
---
|
||||
keywords:
|
||||
- Infrastructure as code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
menuTitle: Infrastructure as code
|
||||
title: Provision Grafana Cloud with infrastructure as code
|
||||
weight: 800
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/
|
||||
---
|
||||
|
||||
# Provision Grafana Cloud with infrastructure as code
|
||||
|
||||
With Grafana Cloud, you can create dashboards via configuration files in source code. This enables you to review code, reuse it, and create better workflows.
|
||||
|
||||
Via code, you can _declaratively_ manage _what_ Grafana resources to use.
|
||||
The as-code tools and tutorials that follow show you what do to, to declaratively manage Grafana resources, and incorporate them efficiently into your own use cases.
|
||||
|
||||
## Grafana Terraform provider
|
||||
|
||||
Grafana administrators can manage dashboards, alerts and collectors, add synthetic monitoring probes and checks, manage identity and access, and more using the [Terraform provider for Grafana](https://registry.terraform.io/providers/grafana/grafana/latest).
|
||||
|
||||
The following example shows a Terraform configuration for creating a dashboard:
|
||||
|
||||
```terraform
|
||||
resource "grafana_dashboard" "metrics" {
|
||||
config_json = jsonencode({
|
||||
title = "as-code dashboard"
|
||||
uid = "ascode"
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
This example dashboard only creates the dashboard and does not add any panels or rows.
|
||||
To get started, see the [Grafana Terraform provider guides](/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/) or refer to the [Terraform Grafana Provider documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
|
||||
|
||||
### Who is this recommended for?
|
||||
|
||||
Grafana Terraform provider is best suited for users who are already using Terraform for non-Grafana use cases.
|
||||
|
||||
To manage the entire Grafana ecosystem of resources on either Grafana Cloud or OSS deployments of Grafana, it’s best to use the Terraform Grafana provider because it supports the most Grafana resources compared to Grafana’s other as-code solutions.
|
||||
|
||||
For Grafana Fleet Management users, the Grafana Terraform provider is best used to preregister new collectors before they are operational or add remote attributes to collectors already registered with the service.
|
||||
|
||||
### Known limitations
|
||||
|
||||
Managing dashboards isn’t the simplest process—you have to work with long JSON files, which can become difficult to review and update, as well. Grafonnet can help with generating dashboard JSONs that can be used in Terraform, but Grafonnet requires knowing Jsonnet.
|
||||
|
||||
## Grafana Ansible collection
|
||||
|
||||
Resources for configuration management are available for Grafana through the [Ansible collection for Grafana](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/index.html#plugins-in-grafana-grafana). The Grafana Ansible collection can be used to manage a variety of resources, including folders, cloud stacks, and dashboards. You can programmatically manage resources on Grafana that aren’t currently part of the Grafana Ansible collection by writing Ansible playbooks that use the HTTP APIs to manage resources for Grafana.
|
||||
|
||||
The following example shows an Ansible configuration for creating a dashboard:
|
||||
|
||||
```yaml
|
||||
- name: dashboard as code
|
||||
grafana.grafana.dashboard:
|
||||
dashboard: { 'title': 'as-code dashboard', 'uid': 'ascode' }
|
||||
stack_slug: '{{ stack_slug }}'
|
||||
grafana_api_key: '{{ grafana_api_key }}'
|
||||
state: present
|
||||
```
|
||||
|
||||
This example dashboard creates only the dashboard and does not add any panels or rows.
|
||||
|
||||
To get started, see the [quickstart guides for the Grafana Ansible Collection](/docs/grafana-cloud/as-code/infrastructure-as-code/ansible/) or check out the [collections's documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/index.html#plugins-in-grafana-grafana).
|
||||
|
||||
### Who is this recommended for?
|
||||
|
||||
Like Terraform, the Grafana Ansible collection is best suited for people already using Ansible for non-Grafana use cases. The collection only works for Grafana Cloud right now, so it makes the most sense for Grafana Cloud customers who want to manage resources declaratively using Ansible.
|
||||
|
||||
### Known limitations
|
||||
|
||||
The Grafana Ansible collection only works for Grafana Cloud and only supports eight resources: API keys, cloud stacks, plugins, dashboards, folders, data sources, alert contact points, and notification policies. This can be a drawback if you want to manage the entire Grafana ecosystem as code with Ansible. As with Terraform, building dashboards is a challenging process.
|
||||
|
||||
## Grafana Operator
|
||||
|
||||
The Grafana Operator is a Kubernetes operator that can provision, manage, and operate Grafana instances and their associated resources within Kubernetes through Custom Resources. This Kubernetes-native tool eases the administration of Grafana, offering a declarative approach to managing dashboards, data sources, and folders. It also automatically syncs the Kubernetes Custom resources and the actual resources in the Grafana Instance. It supports leveraging Grafonnet for generating Grafana dashboard definitions for seamless dashboard configuration as code.
|
||||
|
||||
To get started, see the [quickstart guides for the Grafana Operator](/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/) or check out the [Grafana Operator's documentation](https://grafana.github.io/grafana-operator/).
|
||||
|
||||
A sample Kubernetes configuration for creating a dashboard using the Grafana operator looks like this:
|
||||
|
||||
```yaml
|
||||
apiVersion: integreatly.org/v1alpha1
|
||||
kind: GrafanaDashboard
|
||||
metadata:
|
||||
name: simple-dashboard
|
||||
labels:
|
||||
app: grafana
|
||||
spec:
|
||||
instanceSelector:
|
||||
matchLabels:
|
||||
dashboards: <Grafana-custom-resource-name>
|
||||
json: >
|
||||
{
|
||||
"title": "as-code dashboard",
|
||||
“uid” : “ascode”
|
||||
}
|
||||
```
|
||||
|
||||
### Who is this recommended for?
|
||||
|
||||
The Grafana Operator is particularly fitting for:
|
||||
|
||||
- Teams seeking integrated solutions to manage Grafana resources within the Kubernetes cluster ecosystem.
|
||||
- Teams employing a GitOps approach, allowing them to treat Grafana configurations as code, stored alongside application manifests for versioned and automated deployments.
|
||||
|
||||
### Known limitations
|
||||
|
||||
While the Grafana Operator simplifies many aspects of operating Grafana and its resources on Kubernetes, its current support is mainly focused on managing dashboards, folders, and data sources. Advanced features like alerting and plugins (only works for OSS) are not supported yet.
|
||||
|
||||
## Grafana Crossplane provider
|
||||
|
||||
[Grafana Crossplane provider](https://github.com/grafana/crossplane-provider-grafana) is built using Terrajet and provides support for all resources supported by the Grafana Terraform provider. It enables users to define Grafana resources as Kubernetes manifests and it also help users who build their GitOps pipelines around Kubernetes manifests using tools like ArgoCD.
|
||||
|
||||
To get started with the Grafana Crossplane provider, install Crossplane in the Kubernetes cluster and use this command to install the provider:
|
||||
|
||||
```shell
|
||||
kubectl crossplane install provider grafana/crossplane-provider-grafana:v0.1.0
|
||||
```
|
||||
|
||||
During installation of the provider, CRDs for all the resources supported by the Terraform provider are added to the cluster so users can begin defining their Grafana resources as Kubernetes custom resources. The Crossplane provider ensures that whatever is defined in the custom resource definitions is what is visible in Grafana UI. If any changes are made directly in the UI, the changes will be discarded when the provider resyncs. This helps ensure that whatever is defined declaratively in the cluster will be the source of truth for Grafana resources.
|
||||
|
||||
To get started, refer to the examples folder in the Grafana Crossplane repository.
|
||||
|
||||
The following example shows a Kubernetes custom resource definition for creating a dashboard:
|
||||
|
||||
```yaml
|
||||
apiVersion: grafana.jet.crossplane.io/v1alpha1
|
||||
kind: Dashboard
|
||||
metadata:
|
||||
name: as-code-dashboard
|
||||
spec:
|
||||
forProvider:
|
||||
configJson: |
|
||||
{
|
||||
"title": "as-code dashboard",
|
||||
"uid": "ascode"
|
||||
}
|
||||
providerConfigRef:
|
||||
name: grafana-crossplane-provider
|
||||
```
|
||||
|
||||
### Who is this recommended for?
|
||||
|
||||
The Grafana Crossplane provider is intended for existing Crossplane users looking to manage Grafana resources from within Kubernetes and as Kubernetes manifests for the GitOps pipelines.
|
||||
|
||||
### Known limitations
|
||||
|
||||
To use the Crossplane provider, you must have the Crossplane CLI and Crossplane installed in the Kubernetes cluster. Note that the Crossplane provider is in an alpha stage, so it has not reached a stable state yet.
|
||||
|
||||
## Grafana as code comparison
|
||||
|
||||
Most of the tools defined here can be used with one another.
|
||||
The following chart compares the properties and tools mentioned above.
|
||||
|
||||
| Property/Tool | Grafana Terraform Provider | Grafana Ansible Collection | Grafana Operator | Grizzly | Grafana Crossplane Provider |
|
||||
| -------------------------------------- | --------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
|
||||
| Grafana resources supported | All major Grafana resources | Grafana Cloud stack, plugins, API keys, dashboards, data sources, and folders | Dashboards, Datasources, Folders | Synthetic Monitoring checks, dashboards, data sources, folders, and Prometheus rules | All major Grafana resources |
|
||||
| Tool format | HCL/JSON | YAML | YAML | Jsonnet/YAML/JSON | YAML/JSON |
|
||||
| Follows Kubernetes-style manifests | | | ✓ | ✓ | ✓ |
|
||||
| Easy dashboard building process | | | ✓ | ✓ | |
|
||||
| Manage resources using Kubernetes | | | ✓ | | ✓ |
|
||||
| Retrieves Grafana resource information | ✓ | | | | |
|
||||
| Built-in resource sync process | | | ✓ | ✓ | ✓ |
|
||||
| Recommended for | Existing Terraform users | Existing Ansible users | Users looking to manage Grafana resources from within Kubernetes | Users looking to define Grafana resources in a Kubernetes-style YAML and users looking to get built-in workflow support and sync process | Users looking to manage Grafana resources from within Kubernetes |
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Ansible
|
||||
menuTitle: Ansible
|
||||
title: Grafana Ansible collection
|
||||
weight: 110
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/
|
||||
---
|
||||
|
||||
# Grafana Ansible collection
|
||||
|
||||
The [Grafana Ansible collection](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/) provides configuration management resources for Grafana. You can use it to manage resources such as dashboards, Cloud stacks, folders, and more.
|
||||
|
||||
The collection also houses the [Grafana Agent role](https://github.com/grafana/grafana-ansible-collection/tree/main/roles/grafana_agent) which can be used to deploy and manage Grafana Agent across various Linux machines.
|
||||
|
||||
{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
|
||||
|
||||
For resources currently not available in the Grafana Ansible collection, you can manage those resources on Grafana Cloud programmatically by writing Ansible playbooks that use the [Ansible's builtin uri module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/uri_module.html) to call the [HTTP APIs](/docs/grafana/latest/developers/http_api/) to manage resources for the Grafana Cloud portal, as well as those within a stack.
|
||||
|
||||
Use the following guides to get started using Ansible to manage your Grafana Cloud stack:
|
||||
|
||||
| Topic | Description |
|
||||
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [Create and manage a Grafana Cloud stack using Ansible](ansible-cloud-stack/) | Describes how to create a Grafana Cloud stack and add a data source and dashboard using [Ansible](https://www.ansible.com/). |
|
||||
| [Install Grafana Agent on a Linux host using Ansible](ansible-grafana-agent-linux/) | Describes how to install the Grafana Agent on a Linux node using Ansible and use it to push logs to Grafana Cloud. |
|
||||
| [Monitor multiple Linux hosts with Grafana Agent Role](ansible-multiple-agents/) | Describes how to use the Grafana Ansible collection to manage agents across multiple Linux hosts. |
|
||||
@@ -0,0 +1,259 @@
|
||||
---
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Ansible
|
||||
title: Create and manage a Grafana Cloud stack using Ansible
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/ansible-cloud-stack/
|
||||
---
|
||||
|
||||
# Create and manage a Grafana Cloud stack using Ansible
|
||||
|
||||
Learn how to add a data source, a dashboard, and a folder to a Grafana Cloud stack using Ansible collection for Grafana.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you begin, you should have the following available:
|
||||
|
||||
- A Grafana Cloud account.
|
||||
- [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/index.html) installed on your machine
|
||||
|
||||
## Create a Cloud stack
|
||||
|
||||
1. Create a Grafana Cloud Access Policy and get a token.
|
||||
You'll need this for the Ansible playbook to be able to create a Grafana Cloud stack.
|
||||
Refer to [Create a Grafana Cloud Access Policy](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies/).
|
||||
|
||||
1. Create an Ansible playbook file.
|
||||
|
||||
This Ansible playbook will create a Grafana Cloud stack by using the [Cloud stack module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/cloud_stack_module.html#ansible-collections-grafana-grafana-cloud-stack-module).
|
||||
|
||||
Create a file named `cloud-stack.yml` and add the following:
|
||||
|
||||
```yaml
|
||||
- name: Create Grafana Cloud stack
|
||||
connection: local
|
||||
hosts: localhost
|
||||
|
||||
vars:
|
||||
grafana_cloud_api_key: '<Your Cloud Access Policy token>'
|
||||
stack_name: '<stack-name>'
|
||||
org_name: '<org-name>'
|
||||
|
||||
tasks:
|
||||
- name: Create a Grafana Cloud stack
|
||||
grafana.grafana.cloud_stack:
|
||||
name: '{{ stack_name }}'
|
||||
stack_slug: '{{ stack_name }}'
|
||||
cloud_api_key: '{{ grafana_cloud_api_key }}'
|
||||
org_slug: '{{ org_name }}'
|
||||
delete_protection: true
|
||||
state: present
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<token>` with a token from the Cloud Access Policy you created in the Grafana Cloud portal.
|
||||
- `<stack-name>` with the name of your stack.
|
||||
- `<org-name>` with the name of the organization in Grafana Cloud.
|
||||
|
||||
## Create an API key in the Grafana stack
|
||||
|
||||
Create an API key in the Grafana stack.
|
||||
You'll need this key to configure Ansible to be able to create data source, folders, and dashboards.
|
||||
|
||||
1. Log into your Grafana Cloud instance.
|
||||
2. Click **Administration** and select **API keys**.
|
||||
3. Click **Add API key**.
|
||||
4. In **Key name**, enter a name for your API key.
|
||||
5. In **Role**, select **Admin** or **Editor** to associate the role with this API key.
|
||||
6. Click **Copy** to save it for later use.
|
||||
|
||||
## Add a data source
|
||||
|
||||
This guide uses the InfluxDB data source.
|
||||
The required arguments vary depending on the type of data source you select.
|
||||
|
||||
1. Create a file named `data-source.yml` and add the following:
|
||||
|
||||
```yaml
|
||||
- name: Add/Update data source
|
||||
connection: local
|
||||
hosts: localhost
|
||||
|
||||
vars:
|
||||
data_sources:
|
||||
[
|
||||
{
|
||||
name: '<data-source-name>',
|
||||
type: 'influxdb',
|
||||
url: '<data-source-url>',
|
||||
user: '<username>',
|
||||
secureJsonData: { password: '<password>' },
|
||||
database: '<db-name>',
|
||||
id: <id>,
|
||||
uid: '<uid>',
|
||||
access: 'proxy',
|
||||
},
|
||||
]
|
||||
|
||||
grafana_api_key: '<API-Key>'
|
||||
stack_name: '<stack-name>'
|
||||
|
||||
tasks:
|
||||
- name: Create/Update Data sources
|
||||
grafana.grafana.datasource:
|
||||
datasource: '{{ item }}'
|
||||
stack_slug: '{{ stack_name }}'
|
||||
grafana_api_key: '{{ grafana_api_key }}'
|
||||
state: present
|
||||
loop: '{{ data_sources }}'
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<data-source-name>` with the name of the data source to be added in Grafana.
|
||||
- `<data-source-url>` with URL of your data source.
|
||||
- `<username>` with the username for authenticating with your data source.
|
||||
- `<password>` with the password for authenticating with your data source.
|
||||
- `<db-name>` with name of your database.
|
||||
- `<id>` with the ID for your data source in Grafana.
|
||||
- `<uid>` wth the UID for your data source in Grafana.
|
||||
- `<stack-name>` with the name of your stack.
|
||||
- `<API-key>` with the [API key created in the Grafana instance](#create-an-api-key-in-the-grafana-stack).
|
||||
|
||||
## Add a folder
|
||||
|
||||
This Ansible playbook creates a folder in your Grafana instance by using the [Folder module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/folder_module.html#ansible-collections-grafana-grafana-folder-module).
|
||||
|
||||
1. Create a file named `folder.yml` and add the following:
|
||||
|
||||
```yaml
|
||||
- name: Add/Update Folders
|
||||
connection: local
|
||||
hosts: localhost
|
||||
|
||||
vars:
|
||||
folders: [{ title: '<folder-name>', uid: '<uid>' }]
|
||||
|
||||
stack_name: '<stack-name>'
|
||||
grafana_api_key: <API-key>
|
||||
|
||||
tasks:
|
||||
- name: Create/Update a Folder in Grafana
|
||||
grafana.grafana.folder:
|
||||
title: '{{ item.title }}'
|
||||
uid: '{{ item.uid }}'
|
||||
stack_slug: '{{ stack_name }}'
|
||||
grafana_api_key: '{{ grafana_api_key }}'
|
||||
state: present
|
||||
loop: '{{ folders }}'
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<folder-name>` with the name of the folder to be added in Grafana.
|
||||
- `<uid>` with the UID for your folder in Grafana.
|
||||
- `<stack-name>` with the name of your stack.
|
||||
- `<API-key>` with the [API key created in the Grafana instance](#create-an-api-key-in-the-grafana-stack).
|
||||
|
||||
## Add a dashboard to the folder
|
||||
|
||||
This Ansible playbook iterates through the dashboard JSON source code files in the folder referenced in `dashboards_path` and adds them in the Grafana instance by using the [Dashboard module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/dashboard_module.html#ansible-collections-grafana-grafana-dashboard-module).
|
||||
|
||||
1. Create a file named `dashboard.yml` and add the following:
|
||||
|
||||
```yaml
|
||||
- name: Add/Update Dashboards
|
||||
connection: local
|
||||
hosts: localhost
|
||||
|
||||
vars:
|
||||
dashboards_path: <path-to-dashboard-files> # Example "./dashboards"
|
||||
stack_name: "<stack-name>"
|
||||
grafana_api_key: <API-key>
|
||||
|
||||
tasks:
|
||||
- name: Find dashboard files
|
||||
find:
|
||||
paths: "{{ dashboards_path }}"
|
||||
file_type: file
|
||||
recurse: Yes
|
||||
patterns: "*.json"
|
||||
register: files_matched
|
||||
no_log: True
|
||||
|
||||
- name: Create list of dashboard file names
|
||||
set_fact:
|
||||
dashboard_file_names: "{{ dashboard_file_names | default ([]) + [item.path] }}"
|
||||
loop: "{{ files_matched.files }}"
|
||||
no_log: True
|
||||
|
||||
- name: Create/Update a dashboard
|
||||
grafana.grafana.dashboard:
|
||||
dashboard: "{{ lookup('ansible.builtin.file','{{ item }}' ) }}"
|
||||
stack_slug: "{{ stack_name }}"
|
||||
grafana_api_key: "{{ grafana_api_key }}"
|
||||
state: present
|
||||
loop: "{{ dashboard_file_names }}"
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<path-to-dashboard-files>` with the path to the folder containing dashboard JSON source code files.
|
||||
- `<stack-name>` with the name of your stack.
|
||||
- `<API-key>` with the [API key created in the Grafana instance](#create-an-api-key-in-the-grafana-stack).
|
||||
|
||||
## Run the Ansible playbooks
|
||||
|
||||
In a terminal, run the following commands from the directory where all of the Ansible playbooks are located.
|
||||
|
||||
1. To create the Grafana Cloud stack.
|
||||
|
||||
```shell
|
||||
ansible-playbook cloud-stack.yml
|
||||
```
|
||||
|
||||
1. To add a data source to the Grafana stack.
|
||||
|
||||
```shell
|
||||
ansible-playbook data-source.yml
|
||||
```
|
||||
|
||||
1. To add a folder to the Grafana stack
|
||||
|
||||
```shell
|
||||
ansible-playbook folder.yml
|
||||
```
|
||||
|
||||
1. To add a dashboard to the folder in your Grafana stack.
|
||||
|
||||
```shell
|
||||
ansible-playbook dashboard.yml
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
Once you run the Ansible playbooks, you should be able to verify the following:
|
||||
|
||||
- The new Grafana stack is created and visible in the Cloud Portal.
|
||||
|
||||
|
||||
|
||||
- A new data source (InfluxDB in this example) is visible in the Grafana stack.
|
||||
|
||||
|
||||
|
||||
- A new folder in Grafana.
|
||||
In the following image, a folder named `Demos` was added.
|
||||
|
||||
|
||||
|
||||
- A new dashboard in the Grafana stack.
|
||||
In the following image a dashboard named `InfluxDB Cloud Demos` was created inside the "Demos" folder.
|
||||
|
||||
|
||||
|
||||
## Summary
|
||||
|
||||
In this guide, you created a Grafana Cloud stack along with a data source, folder, and dashboard imported from a JSON file using Ansible.
|
||||
|
||||
To learn more about managing Grafana using Ansible, refer to the [Grafana Ansible collection](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/).
|
||||
@@ -0,0 +1,156 @@
|
||||
---
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Ansible
|
||||
title: Install Grafana Agent on a Linux host using Ansible
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/ansible-grafana-agent-linux/
|
||||
---
|
||||
|
||||
# Install Grafana Agent on a Linux host using Ansible
|
||||
|
||||
{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
|
||||
|
||||
This guide shows how to install Grafana Agent on a Linux host using [Ansible](https://www.ansible.com/) and to use it to push logs to Grafana Cloud.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you begin, you should have the following available:
|
||||
|
||||
- A Grafana Cloud account.
|
||||
- A Linux machine
|
||||
- Command line (terminal) access to that Linux machine with `unzip` binary installed
|
||||
- Account permissions sufficient to install and use Grafana Agent on the Linux machine
|
||||
- [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/index.html) installed on the Linux machine
|
||||
|
||||
## Choose your Grafana Agent installation method
|
||||
|
||||
This guide covers two methods for installing and configuring Grafana Agent using Ansible:
|
||||
|
||||
- Installing Grafana Agent in Flow mode
|
||||
- Installing Grafana Agent in static mode
|
||||
|
||||
Depending on your specific needs and the configuration of your environment, you may choose one method over the other for better compatibility or ease of setup.
|
||||
|
||||
<!-- vale Grafana.Spelling = NO -->
|
||||
|
||||
### Install Grafana Agent in flow mode using Ansible
|
||||
|
||||
This Ansible playbook installs Grafana Agent in Flow mode and also creates a systemd service to manage it.
|
||||
|
||||
It creates a user named `grafana-agent` on the Linux machine for running Grafana Agent.
|
||||
|
||||
1. Create a file named `grafana-agent.yml` and add the following:
|
||||
|
||||
```yaml
|
||||
- name: Install Grafana Agent Flow
|
||||
hosts: all
|
||||
become: true
|
||||
tasks:
|
||||
- name: Install Grafana Agent Flow
|
||||
ansible.builtin.include_role:
|
||||
name: grafana.grafana.grafana_agent
|
||||
vars:
|
||||
grafana_agent_mode: flow
|
||||
# Change config file on the host to .river
|
||||
grafana_agent_config_filename: config.river
|
||||
# Change config file to be copied
|
||||
grafana_agent_provisioned_config_file: '<path-to-config-file>'
|
||||
# Remove default flags
|
||||
grafana_agent_flags_extra:
|
||||
server.http.listen-addr: '0.0.0.0:12345'
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<path-to-config-file-on-localhost>` with the path to river configuration file on the Ansible Controller (Localhost).
|
||||
|
||||
### Install Grafana Agent in static mode using Ansible
|
||||
|
||||
This Ansible playbook installs Grafana Agent in static mode and also creates a systemd service to manage it.
|
||||
It creates a user named `grafana-agent` on the Linux machine for running Grafana Agent.
|
||||
|
||||
1. Create a file named `grafana-agent.yml` and add the following:
|
||||
|
||||
```yaml
|
||||
- name: Install Grafana Agent in static mode
|
||||
hosts: all
|
||||
become: true
|
||||
|
||||
vars:
|
||||
grafana_cloud_api_key: <Your Cloud Access Policy token>
|
||||
logs_username: <loki-username> # Example - 411478
|
||||
loki_url: <loki-push-url> # Example - https://logs-prod-017.grafana.net/loki/api/v1/push
|
||||
tasks:
|
||||
- name: Install Grafana Agent in static mode
|
||||
ansible.builtin.include_role:
|
||||
name: grafana_agent
|
||||
vars:
|
||||
grafana_agent_logs_config:
|
||||
configs:
|
||||
- clients:
|
||||
- basic_auth:
|
||||
password: '{{ grafana_cloud_api_key }}'
|
||||
username: '{{ logs_username }}'
|
||||
url: '{{ loki_url }}'
|
||||
name: default
|
||||
positions:
|
||||
filename: /tmp/positions.yaml
|
||||
scrape_configs:
|
||||
- job_name: integrations/node_exporter_direct_scrape
|
||||
static_configs:
|
||||
- targets:
|
||||
- localhost
|
||||
labels:
|
||||
instance: hostname
|
||||
__path__: /var/log/*.log
|
||||
job: integrations/node_exporter
|
||||
target_config:
|
||||
sync_period: 10s
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<Your Cloud Access Policy token>` with a token from the Cloud Access Policy you created in the Grafana Cloud portal.
|
||||
- `<loki-username>` with the Loki Username
|
||||
- `<loki-push-url>` with the push endpoint URL of Loki Instance
|
||||
|
||||
## Run the Ansible playbook on the Linux machine
|
||||
|
||||
In the Linux machine's terminal, run the following command from the directory where the Ansible playbook is located.
|
||||
|
||||
```shell
|
||||
ansible-playbook grafana-agent.yml
|
||||
```
|
||||
|
||||
## Validate
|
||||
|
||||
<!-- vale Grafana.ReferTo = NO -->
|
||||
|
||||
1. Grafana Agent service on the Linux machine should be `active` and `running`. You should see a similar output:
|
||||
<!-- vale Grafana.ReferTo = NO -->
|
||||
|
||||
```shell
|
||||
$ sudo systemctl status grafana-agent.service
|
||||
grafana-agent.service - Grafana Agent
|
||||
Loaded: loaded (/etc/systemd/system/grafana-agent.service; enabled; vendor preset: enabled)
|
||||
Active: active (running) since Wed 2022-07-20 09:56:15 UTC; 36s ago
|
||||
Main PID: 3176 (agent-linux-amd)
|
||||
Tasks: 8 (limit: 515)
|
||||
Memory: 92.5M
|
||||
CPU: 380ms
|
||||
CGroup: /system.slice/grafana-agent.service
|
||||
└─3176 /usr/local/bin/agent-linux-amd64 --config.file=/etc/grafana-cloud/agent-config.yaml
|
||||
```
|
||||
|
||||
1. In a Grafana Cloud stack, click **Explore** in the left-side menu.
|
||||
|
||||
1. At the top of the page, use the dropdown menu to select your Loki logs data source. In the Log Browser, run the query `{job="integrations/node_exporter"}`
|
||||
|
||||
|
||||
|
||||
## Summary
|
||||
|
||||
In this guide, you installed Grafana Agent on a Linux node using Ansible and used it to pushed logs to Grafana Cloud.
|
||||
|
||||
To learn more about the Grafana Ansible collection, refer to the [GitHub repository](https://github.com/grafana/grafana-ansible-collection) or its [documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/index.html).
|
||||
@@ -0,0 +1,207 @@
|
||||
---
|
||||
menuTitle: Monitor multiple Linux hosts with the grafana_agent role
|
||||
title: Monitor multiple Linux hosts with grafana_agent role
|
||||
weight: 300
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/ansible-multiple-agents/
|
||||
---
|
||||
|
||||
# Monitor multiple Linux hosts with the `grafana_agent` role
|
||||
|
||||
{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
|
||||
|
||||
Monitoring multiple Linux hosts can be difficult.
|
||||
To make it easier, you can use the `grafana_agent` role with the [Grafana Ansible collection](../).
|
||||
This guide shows how to use the `grafana_agent` Ansible role to deploy and manage Grafana Agent across multiple Linux hosts so you can monitor them using Grafana Cloud.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you begin, you should have:
|
||||
|
||||
- Linux hosts
|
||||
- SSH access to the Linux hosts
|
||||
- Account permissions sufficient to install and use Grafana Agent on the Linux hosts
|
||||
|
||||
## Install the Grafana Ansible collection
|
||||
|
||||
The [`grafana_agent` role](https://github.com/grafana/grafana-ansible-collection/tree/main/roles/grafana_agent) is available in the Grafana Ansible collection as of the 1.1.0 release.
|
||||
|
||||
To install the Grafana Ansible collection, run this command:
|
||||
|
||||
```
|
||||
ansible-galaxy collection install grafana.grafana
|
||||
```
|
||||
|
||||
## Create an Ansible inventory file
|
||||
|
||||
Next, you will set up your hosts and create an inventory file.
|
||||
|
||||
1. Create your hosts and add public SSH keys to them.
|
||||
|
||||
This example uses eight Linux hosts: two Ubuntu hosts, two CentOS hosts, two Fedora hosts, and two Debian hosts.
|
||||
|
||||
1. Create an Ansible inventory file.
|
||||
|
||||
The Ansible inventory, which resides in a file named `inventory`, looks similar to this:
|
||||
|
||||
```
|
||||
146.190.208.216 # hostname = ubuntu-01
|
||||
146.190.208.190 # hostname = ubuntu-02
|
||||
137.184.155.128 # hostname = centos-01
|
||||
146.190.216.129 # hostname = centos-02
|
||||
198.199.82.174 # hostname = debian-01
|
||||
198.199.77.93 # hostname = debian-02
|
||||
143.198.182.156 # hostname = fedora-01
|
||||
143.244.174.246 # hostname = fedora-02
|
||||
```
|
||||
|
||||
1. Create an `ansible.cfg` file within the same directory as `inventory`, with the following values:
|
||||
```
|
||||
[defaults]
|
||||
inventory = inventory # Path to the inventory file
|
||||
private_key_file = ~/.ssh/id_rsa # Path to my private SSH Key
|
||||
remote_user=root # username
|
||||
```
|
||||
{{< admonition type="note" >}}
|
||||
If you are copying the previously listed files, remove the comments (#).
|
||||
{{< /admonition >}}
|
||||
|
||||
## Use the `grafana_agent` Ansible role
|
||||
|
||||
Next you will create an Ansible playbook that calls the `grafana_agent` role from the `grafana.grafana` Ansible collection.
|
||||
|
||||
To use the `grafana_agent` Ansible role:
|
||||
|
||||
1. Create a file named `deploy-agent.yml` in the same directory as `ansible.cfg` and `inventory` and add the configuration below.
|
||||
|
||||
```yaml
|
||||
- name: Install Grafana Agent
|
||||
hosts: all
|
||||
become: true
|
||||
|
||||
vars:
|
||||
grafana_cloud_api_key: <Your Cloud Access Policy token>
|
||||
metrics_username: <prometheus-username> # Example - 825019
|
||||
logs_username: <loki-username> # Example - 411478
|
||||
prometheus_url: <prometheus-push-url> # Example - https://prometheus-us-central1.grafana.net/api/prom/push
|
||||
loki_url: <loki-push-url> # Example - https://logs-prod-017.grafana.net/loki/api/v1/push
|
||||
tasks:
|
||||
- name: Install Grafana Agent
|
||||
ansible.builtin.include_role:
|
||||
name: grafana.grafana.grafana_agent
|
||||
vars:
|
||||
grafana_agent_metrics_config:
|
||||
configs:
|
||||
- name: integrations
|
||||
remote_write:
|
||||
- basic_auth:
|
||||
password: '{{ grafana_cloud_api_key }}'
|
||||
username: '{{ metrics_username }}'
|
||||
url: '{{ prometheus_url }}'
|
||||
|
||||
global:
|
||||
scrape_interval: 60s
|
||||
wal_directory: /tmp/grafana-agent-wal
|
||||
grafana_agent_logs_config:
|
||||
configs:
|
||||
- name: default
|
||||
clients:
|
||||
- basic_auth:
|
||||
password: '{{ grafana_cloud_api_key }}'
|
||||
username: '{{ logs_username }}'
|
||||
url: '{{ loki_url }}'
|
||||
positions:
|
||||
filename: /tmp/positions.yaml
|
||||
target_config:
|
||||
sync_period: 10s
|
||||
scrape_configs:
|
||||
- job_name: varlogs
|
||||
static_configs:
|
||||
- targets: [localhost]
|
||||
labels:
|
||||
instance: ${HOSTNAME:-default}
|
||||
job: varlogs
|
||||
__path__: /var/log/*log
|
||||
grafana_agent_integrations_config:
|
||||
node_exporter:
|
||||
enabled: true
|
||||
instance: ${HOSTNAME:-default}
|
||||
prometheus_remote_write:
|
||||
- basic_auth:
|
||||
password: '{{ grafana_cloud_api_key }}'
|
||||
username: '{{ metrics_username }}'
|
||||
url: '{{ prometheus_url }}'
|
||||
grafana_agent_env_vars:
|
||||
HOSTNAME: '%H'
|
||||
```
|
||||
|
||||
The playbook calls the `grafana_agent` role from the `grafana.grafana` Ansible collection.
|
||||
|
||||
The Agent configuration in this playbook send metrics and logs from the Linux hosts to Grafana Cloud along with the hostname of each instance
|
||||
|
||||
Refer to the [Grafana Ansible documentation](https://github.com/grafana/grafana-ansible-collection/tree/main/roles/grafana_agent#role-variables) to understand the other variables you can pass to the `grafana_agent` role.
|
||||
|
||||
When deploying the Agent across multiple instances for monitoring them, It is essential that the Agent is able to auto-detect the hostname for ease in monitoring.
|
||||
Notice that the label `instance` has been set to the value `${HOSTNAME:-default}`, which is substituted by the value of the HOSTNAME environment variable in the Linux host.
|
||||
|
||||
To read more about the variable substitution, refer to the Grafana Agent [node_exporter_config](/docs/grafana-cloud/send-data/agent/static/configuration/integrations/node-exporter-config/) documentation.
|
||||
|
||||
1. To run the playbook, run this command:
|
||||
|
||||
```
|
||||
ansible-playbook deploy-agent.yml
|
||||
```
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
You can place the `deploy-agent.yml`, `ansible.cfg` and `inventory` files in different directories based on your needs.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Check that logs and metrics are being ingested into Grafana Cloud
|
||||
|
||||
Logs and metrics will soon be available in Grafana Cloud.
|
||||
To test this, use the Explore feature.
|
||||
Click the **Explore** icon (compass icon) in the vertical navigation bar.
|
||||
|
||||
### Check logs
|
||||
|
||||
To check logs:
|
||||
|
||||
1. Use the drop-down menu at the top of the page to select your Loki logs data source.
|
||||
|
||||
1. In the log browser, run the query `{instance="centos-01"}` where `centos-01` is the hostname of one of the Linux hosts.
|
||||
|
||||
If you see log lines (shown in the example below), logs are being received.
|
||||
|
||||
{{< figure alt="Grafana Explore showing a graph and log output from the preceding query" src="/static/assets/img/blog/ansible-to-manage-agent1.png" >}}
|
||||
|
||||
If no log lines appear, logs aren't being collected.
|
||||
|
||||
### Check metrics
|
||||
|
||||
To check metrics:
|
||||
|
||||
1. Use the drop-down menu at the top of the page to select your Prometheus data source.
|
||||
|
||||
1. Run the query `{instance="centos-01"}` where `centos-01` is the hostname of one of the Linux hosts.
|
||||
|
||||
If you see a metrics graph and table (shown in the example below), metrics are being received.
|
||||
|
||||
{{< figure alt="Grafana Explore showing a graph and metrics table output from the preceding query" src="/static/assets/img/blog/ansible-to-manage-agent2.png" >}}
|
||||
|
||||
If no metrics appear, metrics aren't being collected.
|
||||
|
||||
### View dashboards
|
||||
|
||||
Now that you have logs and metrics in Grafana, you can use dashboards to view them.
|
||||
Here's an example of one of the prebuilt dashboards included with the Linux integration in Grafana Cloud:
|
||||
|
||||
{{< figure alt="The Grafana Node Exporter integration dashboard showing panels of visualizations" src="/static/assets/img/blog/ansible-to-manage-agent3.png" >}}
|
||||
|
||||
Using the **Instance** drop-down in the dashboard, you can select from the hostnames where you deployed Grafana Agent and start monitoring them.
|
||||
|
||||
## Summary
|
||||
|
||||
The `grafana_agent` Ansible role makes it easy to deploy and manage Grafana Agent across multiple machines.
|
||||
This example showed Grafana Agent deployments across eight Linux hosts, but it's possible to monitor more hosts using the`grafana_agent` role.
|
||||
To add monitor more Linux hosts, update the `inventory` file and re-run the Ansible playbook.
|
||||
|
||||
To learn more about the Grafana Ansible collection, see its [GitHub repository](https://github.com/grafana/grafana-ansible-collection) or its [documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/index.html).
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Grafana Operator
|
||||
menuTitle: Grafana Operator
|
||||
title: Grafana Operator
|
||||
weight: 120
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/grafana-operator/
|
||||
---
|
||||
|
||||
# Grafana Operator
|
||||
|
||||
The [Grafana Operator](https://grafana.github.io/grafana-operator/) is a Kubernetes operator built to help you manage your Grafana instances and its resources in a Kubernetes environment. The Grafana Operator automatically syncs Kubernetes custom resources and actual resources in your Grafana instance, and allows you to install and manage local Grafana instances, dashboards and data sources in Kubernetes or OpenShift.
|
||||
|
||||
## Install the Grafana Operator
|
||||
|
||||
To install the Grafana Operator in your Kubernetes cluster, run the following command in your terminal:
|
||||
|
||||
```
|
||||
helm repo add grafana https://grafana.github.io/helm-charts
|
||||
helm upgrade -i grafana-operator grafana/grafana-operator
|
||||
```
|
||||
|
||||
For other installation methods, refer to the [Grafana Operator Installation](https://grafana.github.io/grafana-operator/docs/installation/) documentation.
|
||||
|
||||
## Use the Grafana Operator
|
||||
|
||||
Use the following guides to use the Grafana Operator to manage your Grafana instance:
|
||||
|
||||
- [Manage data sources, and dashboards with folders using the Grafana Operator](operator-dashboards-folders-datasources/) describes how to add a folders, data sources, and dashboards, using the [Grafana Operator](https://grafana.github.io/grafana-operator/).
|
||||
- [Manage Dashboards with GitOps Using ArgoCD](manage-dashboards-argocd/) describes how to create and manage dashboards using ArgoCD and [Grafana Operator](https://grafana.github.io/grafana-operator/).
|
||||
@@ -0,0 +1,299 @@
|
||||
---
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Grafana Operator
|
||||
- ArgoCD
|
||||
title: Manage Dashboards with GitOps Using ArgoCD
|
||||
weight: 110
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/grafana-operator/manage-dashboards-argocd/
|
||||
---
|
||||
|
||||
# Managing Grafana Dashboards with GitOps Using ArgoCD
|
||||
|
||||
This guide will walk you through setting up a continuous deployment pipeline using ArgoCD to synchronize your Grafana dashboards with a Git repository. We'll use the Grafana Dashboard Custom Resource provided by the Grafana Operator to manage dashboard configurations declaratively.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- An existing Grafana Cloud stack
|
||||
- A Kubernetes cluster with Grafana Operator installed, as shown in [Grafana Operator Installation](/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/#installing-the-grafana-operator).
|
||||
- ArgoCD installed on your Kubernetes cluster. Refer the [Installation Guide](https://argo-cd.readthedocs.io/en/stable/getting_started/).
|
||||
- Git repository to store your dashboard configurations.
|
||||
|
||||
## Set Up Your Git Repository
|
||||
|
||||
Within the repository, create a directory structure to organize your grafana and dashboard configurations. For this tutorial, lets create a folder named `grafana`.
|
||||
|
||||
## Grafana Operator Setup
|
||||
|
||||
The Grafana Operator allows us to authenticate with the Grafana instance using the Grafana Custom Resource (CR).
|
||||
|
||||
1. **Create the Grafana API Token Secret:**
|
||||
|
||||
Store the Grafana API Token in a secret with the following content in a file named `grafana-token.yml` in the `grafana` folder in your Git repo:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: grafana-cloud-credentials
|
||||
namespace: <grafana-operator-namespace>
|
||||
stringData:
|
||||
GRAFANA_CLOUD_INSTANCE_TOKEN: <Grafana-API-Key>
|
||||
type: Opaque
|
||||
```
|
||||
|
||||
Replace the following field values:
|
||||
|
||||
- `<Grafana-API-Key>` with API key from the Grafana instance. To create an API key, refer [Grafana API Key Documentation](/docs/grafana/latest/administration/api-keys/).
|
||||
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
|
||||
|
||||
2. **Configure the Grafana Custom Resource:**
|
||||
|
||||
Set up connection to your Grafana Cloud instance by creating a file named `grafana-cloud.yml` in the `grafana` folder in your Git repo with the following contents:
|
||||
|
||||
```yaml
|
||||
apiVersion: grafana.integreatly.org/v1beta1
|
||||
kind: Grafana
|
||||
metadata:
|
||||
name: <Grafana-cloud-stack-name>
|
||||
namespace: <grafana-operator-namespace>
|
||||
labels:
|
||||
dashboards: <Grafana-cloud-stack-name>
|
||||
spec:
|
||||
external:
|
||||
url: https://<Grafana-cloud-stack-name>.grafana.net/
|
||||
apiKey:
|
||||
name: grafana-cloud-credentials
|
||||
key: GRAFANA_CLOUD_INSTANCE_TOKEN
|
||||
```
|
||||
|
||||
Replace the following field values:
|
||||
|
||||
- `<Grafana-API-Key>` with API key from the Grafana instance.
|
||||
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
|
||||
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
|
||||
|
||||
## Add Dashboards to a Git repository
|
||||
|
||||
In your `grafana` directory, Create a sub-folder called `dashboards`. For this tutorial, we will create 3 seperate dashboards.
|
||||
|
||||
1. Under `dashboards` folder, Create a file named `simple-dashboard.yaml` with the following content for the first dashboard:
|
||||
|
||||
```yaml
|
||||
apiVersion: grafana.integreatly.org/v1beta1
|
||||
kind: GrafanaDashboard
|
||||
metadata:
|
||||
name: grafanadashboard-sample
|
||||
namespace: <grafana-operator-namespace>
|
||||
spec:
|
||||
resyncPeriod: 30s
|
||||
instanceSelector:
|
||||
matchLabels:
|
||||
dashboards: <Grafana-cloud-stack-name>
|
||||
json: >
|
||||
{
|
||||
"id": null,
|
||||
"title": "Simple Dashboard",
|
||||
"tags": [],
|
||||
"style": "dark",
|
||||
"timezone": "browser",
|
||||
"editable": true,
|
||||
"hideControls": false,
|
||||
"graphTooltip": 1,
|
||||
"panels": [],
|
||||
"time": {
|
||||
"from": "now-6h",
|
||||
"to": "now"
|
||||
},
|
||||
"timepicker": {
|
||||
"time_options": [],
|
||||
"refresh_intervals": []
|
||||
},
|
||||
"templating": {
|
||||
"list": []
|
||||
},
|
||||
"annotations": {
|
||||
"list": []
|
||||
},
|
||||
"refresh": "5s",
|
||||
"schemaVersion": 17,
|
||||
"version": 0,
|
||||
"links": []
|
||||
}
|
||||
```
|
||||
|
||||
Replace the following field values:
|
||||
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
|
||||
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
|
||||
|
||||
1. Under `dashboards` folder, Create a file named `dashboard-from-cm.yaml` with the following content for the second dashboard:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: dashboard-definition
|
||||
namespace: <grafana-operator-namespace>
|
||||
spec:
|
||||
resyncPeriod: 30s
|
||||
instanceSelector:
|
||||
matchLabels:
|
||||
dashboards: <Grafana-cloud-stack-name>
|
||||
json: >
|
||||
{
|
||||
"id": null,
|
||||
"title": "Simple Dashboard from ConfigMap",
|
||||
"tags": [],
|
||||
"style": "dark",
|
||||
"timezone": "browser",
|
||||
"editable": true,
|
||||
"hideControls": false,
|
||||
"graphTooltip": 1,
|
||||
"panels": [],
|
||||
"time": {
|
||||
"from": "now-6h",
|
||||
"to": "now"
|
||||
},
|
||||
"timepicker": {
|
||||
"time_options": [],
|
||||
"refresh_intervals": []
|
||||
},
|
||||
"templating": {
|
||||
"list": []
|
||||
},
|
||||
"annotations": {
|
||||
"list": []
|
||||
},
|
||||
"refresh": "5s",
|
||||
"schemaVersion": 17,
|
||||
"version": 0,
|
||||
"links": []
|
||||
}
|
||||
---
|
||||
apiVersion: grafana.integreatly.org/v1beta1
|
||||
kind: GrafanaDashboard
|
||||
metadata:
|
||||
name: grafanadashboard-from-configmap
|
||||
namespace: <grafana-operator-namespace>
|
||||
spec:
|
||||
instanceSelector:
|
||||
matchLabels:
|
||||
dashboards: <Grafana-cloud-stack-name>
|
||||
configMapRef:
|
||||
name: dashboard-definition
|
||||
key: json
|
||||
```
|
||||
|
||||
Replace the following field values:
|
||||
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
|
||||
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
|
||||
|
||||
1. Under `dashboards` folder, Create a file named `dashboard-from-id.yaml` with the following content for the third dashboard:
|
||||
|
||||
```yaml
|
||||
apiVersion: grafana.integreatly.org/v1beta1
|
||||
kind: GrafanaDashboard
|
||||
metadata:
|
||||
name: node-exporter-latest
|
||||
namespace: <grafana-operator-namespace>
|
||||
spec:
|
||||
instanceSelector:
|
||||
matchLabels:
|
||||
dashboards: <Grafana-cloud-stack-name>
|
||||
grafanaCom:
|
||||
id: 1860
|
||||
```
|
||||
|
||||
Replace the following field values:
|
||||
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
|
||||
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
|
||||
|
||||
## Configure Argo CD to Sync the Git Repository
|
||||
|
||||
Once all changes are committed to Git, Log in to the Argo CD user interface or use the CLI.
|
||||
|
||||
2. Create an Argo CD application to manage the synchronization:
|
||||
|
||||
**Using UI**:
|
||||
- Navigate to 'New App' and fill out the form with your Git repository details and the path to your `grafana` folder.
|
||||
- Make sure to tick mark directory Recurse.
|
||||
- Set the sync policy to `Automatic`.
|
||||
|
||||
**Using CLI**:
|
||||
- Prepare an application manifest named `argo-application.yaml` with the configuration pointing to your Git repository:
|
||||
|
||||
```yaml
|
||||
apiVersion: argoproj.io/v1alpha1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: Grafana
|
||||
namespace: <argocd-namespace>
|
||||
spec:
|
||||
destination:
|
||||
name: ''
|
||||
namespace: ''
|
||||
server: 'https://kubernetes.default.svc'
|
||||
source:
|
||||
path: <Path-to-grafana-folder>
|
||||
repoURL: '<Git-repo-url>'
|
||||
targetRevision: HEAD
|
||||
directory:
|
||||
recurse: true
|
||||
sources: []
|
||||
project: default
|
||||
syncPolicy:
|
||||
automated:
|
||||
prune: true
|
||||
selfHeal: true
|
||||
syncOptions:
|
||||
- CreateNamespace=true
|
||||
retry:
|
||||
limit: 2
|
||||
backoff:
|
||||
duration: 5s
|
||||
maxDuration: 3m0s
|
||||
factor: 2
|
||||
```
|
||||
|
||||
Replace the following field values:
|
||||
- `<Git-repo-url>` with the URL of your GIT Repository.
|
||||
- `<Path-to-grafana-folder>` with the path to the `grafana` folder.
|
||||
- `<argocd-namespace>` with the namespace where ArgoCD is deployed in Kubernetes Cluster.
|
||||
|
||||
- Create the application in Argo CD:
|
||||
|
||||
```shell
|
||||
kubectl apply -f argo-application.yaml
|
||||
```
|
||||
|
||||
## Verify Sync Status in Argo CD
|
||||
|
||||
1. Monitor the newly created Argo CD application, ensuring that it successfully syncs your dashboard configuration.
|
||||
|
||||
2. Visit the Argo CD dashboard and check the sync status. If it's successful, your Grafana dashboard should be up to date with the configuration from your Git repository.
|
||||
|
||||
## Updating the Dashboards
|
||||
|
||||
To update an existing dashboard:
|
||||
|
||||
1. Make changes to the dashboard JSON configuration in your Git repository.
|
||||
2. Commit and push the changes.
|
||||
3. Argo CD will detect the update and synchronize the changes to your Cutom Resource.
|
||||
4. Grafana Operator will then sync changes to the Grafana Instance.
|
||||
|
||||
## Validating the Grafana Dashboard Update
|
||||
|
||||
Log in to your Grafana dashboard and confirm that the changes have been applied. You should see the dashboard update reflected in the Grafana UI.
|
||||
|
||||
## Additional Tips
|
||||
|
||||
- You can also install the Grafana Operator's Helm Chart using ArgoCD to manage your setup with GitOps.
|
||||
- You can follow a similar setup for Grafana Dashboards and Folders.
|
||||
|
||||
## Conclusion
|
||||
|
||||
You've set up a GitOps workflow to manage Grafana dashboards using Argo CD and the Grafana Operator. Your dashboards are now version-controlled and can be consistently deployed across environments. This approach provides a reliable and auditable way to manage observability dashboards and scale your operations.
|
||||
|
||||
To learn more about managing Grafana using Grafana Operator, see the [Grafana Operator documentation](https://grafana.github.io/grafana-operator/docs/).
|
||||
@@ -0,0 +1,168 @@
|
||||
---
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Grafana Operator
|
||||
title: Manage folders, data sources, and dashboards using Grafana Operator
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/grafana-operator/operator-dashboards-folders-datasources/
|
||||
---
|
||||
|
||||
# Creating and managing folders, data sources, and dashboards using the Grafana Operator
|
||||
|
||||
Learn how to manage data sources, folders and dashboard, using Grafana Operator.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, you should have the following available:
|
||||
|
||||
- An existing Grafana Cloud stack.
|
||||
- Grafana Operator Installed in your Cluster, as shown in [Grafana Operator Installation](/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/#installing-the-grafana-operator).
|
||||
|
||||
## Grafana Operator Setup
|
||||
|
||||
The Grafana Operator allows us to authenticate with the Grafana instance using the Grafana Custom Resource (CR).
|
||||
|
||||
1. **Create the Grafana API Token Secret:**
|
||||
|
||||
Store the Grafana API Token in a secret with the following content in a file named `grafana-token.yml`:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: grafana-cloud-credentials
|
||||
namespace: <grafana-operator-namespace>
|
||||
stringData:
|
||||
GRAFANA_CLOUD_INSTANCE_TOKEN: <Grafana-API-Key>
|
||||
type: Opaque
|
||||
```
|
||||
|
||||
Replace the following field values:
|
||||
|
||||
- `<Grafana-API-Key>` with API key from the Grafana instance. To create an API key, refer [Grafana API Key Documentation](/docs/grafana/latest/administration/api-keys/).
|
||||
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
|
||||
|
||||
2. **Configure the Grafana Custom Resource:**
|
||||
|
||||
Set up connection to your Grafana Cloud instance by creating a file named `grafana-cloud.yml` with the following contents:
|
||||
|
||||
```yaml
|
||||
apiVersion: grafana.integreatly.org/v1beta1
|
||||
kind: Grafana
|
||||
metadata:
|
||||
name: <Grafana-cloud-stack-name>
|
||||
namespace: <grafana-operator-namespace>
|
||||
labels:
|
||||
dashboards: <Grafana-cloud-stack-name>
|
||||
spec:
|
||||
external:
|
||||
url: https://<Grafana-cloud-stack-name>.grafana.net/
|
||||
apiKey:
|
||||
name: grafana-cloud-credentials
|
||||
key: GRAFANA_CLOUD_INSTANCE_TOKEN
|
||||
```
|
||||
|
||||
Replace the following field values:
|
||||
|
||||
- `<Grafana-API-Key>` with API key from the Grafana instance.
|
||||
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
|
||||
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
|
||||
|
||||
## Add a data source
|
||||
|
||||
The following steps use the Prometheus data source. The required arguments vary depending on the data source you select.
|
||||
|
||||
1. **Create the Data Source Configuration:**
|
||||
|
||||
Save a new YAML file `datasource.yml` with the following content:
|
||||
|
||||
```yaml
|
||||
apiVersion: grafana.integreatly.org/v1beta1
|
||||
kind: GrafanaDatasource
|
||||
metadata:
|
||||
name: <data-source-name>
|
||||
namespace: <grafana-operator-namespace>
|
||||
spec:
|
||||
instanceSelector:
|
||||
matchLabels:
|
||||
dashboards: <Grafana-cloud-stack-name>
|
||||
allowCrossNamespaceImport: true
|
||||
datasource:
|
||||
access: proxy
|
||||
database: prometheus
|
||||
jsonData:
|
||||
timeInterval: 5s
|
||||
tlsSkipVerify: true
|
||||
name: <data-source-name>
|
||||
type: prometheus
|
||||
url: <data-source-url>
|
||||
```
|
||||
|
||||
Replace the following field values:
|
||||
|
||||
- `<data-source-name>` with the name of the data source to be added in Grafana.
|
||||
- `<data-source-url>` with URL of your data source.
|
||||
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
|
||||
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
|
||||
|
||||
## Add a dashboard to a folder
|
||||
|
||||
Use the following YAML definition to create a simple dashboard in the Grafana instance under a custom folder. If the folder defined under spec.folder fields doesnt not exist, The operator will create it before placing the dashboard inside the folder.
|
||||
|
||||
1. **Prepare the Dashboard Configuration File:**
|
||||
|
||||
In `dashboard.yml`, define the dashboard and assign it to a folder:
|
||||
|
||||
```yaml
|
||||
apiVersion: grafana.integreatly.org/v1beta1
|
||||
kind: GrafanaDashboard
|
||||
metadata:
|
||||
name: <folder-name>
|
||||
namespace: <grafana-operator-namespace>
|
||||
spec:
|
||||
instanceSelector:
|
||||
matchLabels:
|
||||
dashboards: <Grafana-cloud-stack-name>
|
||||
folder: "<folder-name>"
|
||||
json: >
|
||||
{
|
||||
"title": "as-code dashboard",
|
||||
“uid” : “ascode”
|
||||
}
|
||||
```
|
||||
|
||||
Replace the following field values:
|
||||
|
||||
- `<folder-name>` with the name of the folder in which you want the Dashboard to be created.
|
||||
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
|
||||
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
|
||||
|
||||
## Apply Kubernetes Manifests
|
||||
|
||||
In a terminal, run the following commands from the directory where all of the above Kubernetes YAML definitions are located.
|
||||
|
||||
1. Create Kubernetes Custom resources for all of the above configurations.
|
||||
|
||||
```shell
|
||||
kubectl apply -f grafana-token.yml grafana-cloud.yml datasource.yml dashboard.yml
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
Once you apply the configurations, you should be able to verify the following:
|
||||
|
||||
- A new data source is visible in Grafana. In the following image a datasource named `InfluxDB` was created.
|
||||
|
||||
|
||||
|
||||
- A new dashboard and folder in Grafana. In the following image a dashboard named `InfluxDB Cloud Demos` was created inside the `Demos` folder.
|
||||
|
||||
|
||||
|
||||
## Conclusion
|
||||
|
||||
In this guide, you created a data source, folder, and dashboard using the Grafana Operator.
|
||||
|
||||
To learn more about managing Grafana using Grafana Operator, see the [Grafana Operator documentation](https://grafana.github.io/grafana-operator/docs/).
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Grizzly
|
||||
- CLI
|
||||
menuTitle: Grizzly (deprecated)
|
||||
title: Grizzly
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/grizzly/
|
||||
aliases:
|
||||
- ../infrastructure-as-code/grizzly/dashboards-folders-datasources
|
||||
---
|
||||
|
||||
# Grizzly (deprecated)
|
||||
|
||||
{{< admonition type="warning" >}}
|
||||
Grizzly has been removed. It is no longer deployed, enhanced, or supported.
|
||||
|
||||
Use the [Grafana CLI](/docs/grafana/<GRAFANA_VERSION>/observability-as-code/grafana-cli/) instead.
|
||||
{{< /admonition >}}
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Terraform
|
||||
menuTitle: Terraform
|
||||
title: Grafana Terraform provider
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/
|
||||
---
|
||||
|
||||
# Grafana Terraform provider
|
||||
|
||||
The [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest) provisions configuration management resources for Grafana. You can use it to manage resources such as dashboards, data sources, plugins, folders, organizations or alert notification channels.
|
||||
|
||||
Use the following guides to get started using Terraform to manage your Grafana Cloud stack:
|
||||
|
||||
- [Creating and managing a Grafana Cloud stack using Terraform](terraform-cloud-stack/) describes how to create a Grafana Cloud stack and add a data source and dashboard using [Terraform](https://www.terraform.io/).
|
||||
- [Creating and managing dashboards using Terraform and GitHub Actions](dashboards-github-action/) describes how to create and manage multiple dashboards represented as JSON source code for Grafana using [Terraform](https://www.terraform.io/) and [GitHub Actions](https://github.com/features/actions).
|
||||
- [Managing IRM on Grafana Cloud using Terraform](terraform-oncall/) describes how to connect an integration to Grafana IRM, configure escalation policies, and add your on-call schedule using [Terraform](https://www.terraform.io/).
|
||||
- [Managing Fleet Management in Grafana Cloud using Terraform](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/terraform-fleet-management/) describes how to create collectors and pipelines in Grafana Fleet Management using [Terraform](https://www.terraform.io/).
|
||||
- [Managing Frontend Observability in Grafana Cloud using Terraform](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/terraform-frontend-observability/) describes how to manage resources in Frontend Observability using [Terraform](https://www.terraform.io/).
|
||||
- [Manage Cloud Provider Observability in Grafana Cloud using Terraform](terraform-cloud-provider-o11y/) describes how to manage Amazon CloudWatch and Microsoft Azure resources in Cloud Provider Observability using Terraform.
|
||||
- [Manage Knowledge Graph in Grafana Cloud using Terraform](terraform-knowledge-graph/) describes how to create and manage notification alerts, suppressed assertions, custom model rules, log configurations, and threshold configurations in Grafana Cloud Knowledge Graph using [Terraform](https://www.terraform.io/).
|
||||
- [Install plugins in Grafana Cloud using Terraform](terraform-plugins) describes how to install plugins in Grafana Cloud using [Terraform](https://www.terraform.io/).
|
||||
@@ -0,0 +1,250 @@
|
||||
---
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Terraform
|
||||
- GitHub Actions
|
||||
title: Creating and managing dashboards using Terraform and GitHub Actions
|
||||
weight: 110
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/dashboards-github-action/
|
||||
---
|
||||
|
||||
# Creating and managing dashboards using Terraform and GitHub Actions
|
||||
|
||||
Learn how to create and manage multiple dashboards represented as JSON source code for Grafana using [Terraform](https://www.terraform.io/) and [GitHub Actions](https://github.com/features/actions).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, you should have the following available:
|
||||
|
||||
- A Grafana Cloud account, as shown in [Get started](/docs/grafana-cloud/get-started/)
|
||||
- A [GitHub](https://github.com/) repository
|
||||
|
||||
## Add Dashboards to a GitHub repository
|
||||
|
||||
For this guide, we are adding dashboards for ElasticSearch, InfluxDB, and AWS EC2. You can use different dashboards according to your configured data sources.
|
||||
|
||||
1. In your GitHub repository, create a folder named `dashboards` in the root directory.
|
||||
|
||||
1. In the `dashboards` folder create three sub-folders. For this guide, we will create three sub-folders named `elasticsearch`, `influxdb`, and `aws`.
|
||||
|
||||
1. Add dashboard JSON source code to each of the three sub-folders.
|
||||
|
||||
## Terraform configuration for Grafana provider
|
||||
|
||||
This Terraform configuration configures the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when creating folders and dashboards in the Grafana instance.
|
||||
|
||||
1. Create a service account and token in the Grafana instance by following these steps:
|
||||
1. [Create a service account in Grafana](/docs/grafana-cloud/account-management/authentication-and-permissions/service-accounts/#create-a-service-account-in-grafana)
|
||||
1. [Add a token to a service account](/docs/grafana-cloud/account-management/authentication-and-permissions/service-accounts/#add-a-token-to-a-service-account-in-grafana)
|
||||
|
||||
1. Create a file named `main.tf` in the Git root directory and add the following code block:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
grafana = {
|
||||
source = "grafana/grafana"
|
||||
version = ">= 2.9.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "grafana" {
|
||||
alias = "cloud"
|
||||
|
||||
url = "<Grafana-instance-url>"
|
||||
auth = "<Grafana-Service-Account-token>"
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<Grafana-instance-url>` with the URL of your Grafana instance, for example `"https://my-stack.grafana.net/"`.
|
||||
- `<Grafana-Service-Account-token>` with a Service Account token from the Grafana instance.
|
||||
|
||||
## Terraform configuration for folders
|
||||
|
||||
This Terraform configuration creates three folders named `ElasticSearch`, `InfluxDB` and `AWS` in the Grafana instance using [grafana_folder (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/folder).
|
||||
|
||||
Create a file named `folders.tf` in the Git root directory and add the following code block:
|
||||
|
||||
```terraform
|
||||
resource "grafana_folder" "ElasticSearch" {
|
||||
provider = grafana.cloud
|
||||
|
||||
title = "ElasticSearch"
|
||||
}
|
||||
|
||||
resource "grafana_folder" "InfluxDB" {
|
||||
provider = grafana.cloud
|
||||
|
||||
title = "InfluxDB"
|
||||
}
|
||||
|
||||
resource "grafana_folder" "AWS" {
|
||||
provider = grafana.cloud
|
||||
|
||||
title = "AWS"
|
||||
}
|
||||
```
|
||||
|
||||
## Terraform configuration for dashboards
|
||||
|
||||
This Terraform configuration iterates through the Json files in the three folders (`elasticsearch`, `influxdb` and `aws`) you created in the GitHub repository and adds them to the respective folders in the Grafana instance using [grafana_dashboard (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/dashboard).
|
||||
|
||||
For example, the dashboard represented as JSON source code in the `elasticsearch` folder in the GitHub repository will be created in the `ElasticSearch` folder in the Grafana instance.
|
||||
|
||||
Create a file named `dashboards.tf` in the Git root directory and add the following code block:
|
||||
|
||||
```terraform
|
||||
resource "grafana_dashboard" "elasticsearch" {
|
||||
provider = grafana.cloud
|
||||
|
||||
for_each = fileset("${path.module}/dashboards/elasticsearch", "*.json")
|
||||
config_json = file("${path.module}/dashboards/elasticsearch/${each.key}")
|
||||
folder = grafana_folder.ElasticSearch.id
|
||||
}
|
||||
|
||||
resource "grafana_dashboard" "influxdb" {
|
||||
provider = grafana.cloud
|
||||
|
||||
for_each = fileset("${path.module}/dashboards/influxdb", "*.json")
|
||||
config_json = file("${path.module}/dashboards/influxdb/${each.key}")
|
||||
folder = grafana_folder.InfluxDB.id
|
||||
}
|
||||
|
||||
resource "grafana_dashboard" "aws" {
|
||||
provider = grafana.cloud
|
||||
|
||||
for_each = fileset("${path.module}/dashboards/aws", "*.json")
|
||||
config_json = file("${path.module}/dashboards/aws/${each.key}")
|
||||
folder = grafana_folder.AWS.id
|
||||
}
|
||||
```
|
||||
|
||||
## GitHub workflow for managing dashboards using Terraform
|
||||
|
||||
This GitHub workflow consists of the following steps:
|
||||
|
||||
- Using the [actions/checkout@v3](https://github.com/actions/checkout) action, The GitHub repository is checked out so that the GitHub workflow can access it.
|
||||
- The Terraform CLI is installed on the GitHub runner using the [hashicorp/setup-terraform@v1](https://github.com/hashicorp/setup-terraform) action.
|
||||
- `terraform init` is run as a bash command in the GitHub runner to initialize a working directory containing Terraform configuration files.
|
||||
- `terraform fmt -check` is run as a bash command in the GitHub runner to check if the Terraform configuration files are properly formatted. If the Terraform configuration files are not properly formatted, the workflow will fail at this step.
|
||||
- `terraform plan` is run as a bash command in the GitHub runner to preview the changes that Terraform will make.
|
||||
- Using [mshick/add-pr-comment@v1](https://github.com/mshick/add-pr-comment) action, the preview from Terraform plan is posted as a comment on the pull request. This helps in reviewing the changes that Terraform will make before the pull request is merged.
|
||||
- `terraform appy -auto-approve` is run as a bash command in the GitHub runner to apply the Terraform configuration files. `-auto-approve` flag is added to the command to skip interactive approval of plan before applying and make the workflow automated.
|
||||
This step is run only when changes are committed to `main` branch. When a pull request is merged, the merge action creates a commit to the `main` branch which triggers the `terraform apply -auto-approve` step to execute.
|
||||
|
||||
1. In your GitHub repository, create a folder named `.github` in the root directory .
|
||||
|
||||
1. In the `.github` folder create a sub-folder named `workflows`.
|
||||
|
||||
1. To add the GitHub workflow to your GitHub repository, create a file named `terraform.yml` in the `workflows` directory and add the following code block:
|
||||
|
||||
````yaml
|
||||
name: Terraform
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- 'main'
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
terraform:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
# Checkout the repository to the GitHub Actions runner
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
|
||||
# Install the latest version of Terraform CLI
|
||||
- name: Setup Terraform
|
||||
uses: hashicorp/setup-terraform@v1
|
||||
|
||||
# Initialize a new or existing Terraform working directory by creating initial files, loading any remote state, downloading modules, etc.
|
||||
- name: Terraform Init
|
||||
run: terraform init
|
||||
|
||||
# Checks that all Terraform configuration files adhere to a canonical format
|
||||
- name: Terraform Format
|
||||
run: terraform fmt -check
|
||||
|
||||
# Previews the changes that Terraform will make
|
||||
- name: Plan Terraform
|
||||
id: plan
|
||||
continue-on-error: true
|
||||
run: terraform plan -input=false -no-color
|
||||
|
||||
# Post the preview (terraform plan) from the previous step as a GitHub pull request comment
|
||||
- name: Post Plan to GitHub PR
|
||||
if: github.ref != 'refs/heads/main'
|
||||
uses: mshick/add-pr-comment@v1
|
||||
with:
|
||||
repo-token: ${{ secrets.GITHUB_TOKEN }}
|
||||
repo-token-user-login: 'github-actions[bot]'
|
||||
message: |
|
||||
Applying:
|
||||
|
||||
```
|
||||
${{ steps.plan.outputs.stdout }}
|
||||
```
|
||||
|
||||
# Applies the terraform configuration files when the branch is `main`
|
||||
- name: Apply Terraform
|
||||
if: github.ref == 'refs/heads/main'
|
||||
id: apply
|
||||
continue-on-error: true
|
||||
run: |
|
||||
terraform apply -auto-approve
|
||||
````
|
||||
|
||||
1. Commit the changes made to the `terraform.yml` in the previous step to the `main` branch in your GitHub repository. Once the changes are committed, The GitHub workflow you created should start to run automatically as the workflow we defined in the previous step runs when a pull request is created or when changes are committed to `main` branch.
|
||||
|
||||
## Managing the Terraform state
|
||||
|
||||
If you are not using a [Terraform backend](https://www.terraform.io/language/settings/backends/configuration) to store the `.tfstate` file, add the following code block to the end of the GitHub workflow file to make sure the Terraform state file is stored in Git.
|
||||
|
||||
```yaml
|
||||
- name: commit the terraform state
|
||||
if: github.ref == 'refs/heads/main'
|
||||
uses: stefanzweifel/git-auto-commit-action@v4
|
||||
with:
|
||||
commit_message: Updating Terraform state
|
||||
file_pattern: terraform.tfstate
|
||||
```
|
||||
|
||||
When you run `terraform apply`,Terraform automatically manages and updates the `terraform.tfstate` file to store state about your infrastructure and configuration.
|
||||
This step uses the [stefanzweifel/git-auto-commit-action@v4](https://github.com/stefanzweifel/git-auto-commit-action) action to auto-commit the `terraform.tfstate` file for changes made by the running the `terraform apply` step.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
The Terraform state file (terraform.tfstate) should not be stored in Git to avoid leakage of sensitive data. Instead, store Terraform state file using a remote backend like AWS S3 with proper RBAC. For more information, see [Terraform state](https://www.terraform.io/language/state).
|
||||
{{< /admonition >}}
|
||||
|
||||
## Validation
|
||||
|
||||
Once the GitHub workflow run is successful, you should be able to verify the following:
|
||||
|
||||
- `ElasticSearch`, `InfluxDB` and `AWS` folders are created in the Grafana instance.
|
||||
|
||||
|
||||
|
||||
- Dashboard represented as JSON source code from `elasticsearch` folder in GitHub are added under the `ElasticSearch` folder in the Grafana instance.
|
||||
|
||||
|
||||
|
||||
- Dashboard source code from the `influxdb` folder in GitHub is added under the `InfluxDB` folder in the Grafana instance.
|
||||
|
||||
|
||||
|
||||
- Dashboards from `aws` folder in GitHub are added under the `AWS` folder in the Grafana instance.
|
||||
|
||||
|
||||
|
||||
## Conclusion
|
||||
|
||||
In this guide, you created a GitHub workflow using Terraform to manage dashboard source code. Using this workflow, the dashboards in the Grafana instance will always be synchronized with the JSON source code files for dashboards in GitHub.
|
||||
|
||||
To learn more about managing Grafana Cloud using Terraform, see [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
|
||||
@@ -0,0 +1,115 @@
|
||||
---
|
||||
description: Learn how to manage Grafana Cloud Provider Observability resources in Grafana Cloud using Terraform
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Terraform
|
||||
- Cloud Provider Observability
|
||||
title: Manage Cloud Provider Observability in Grafana Cloud using Terraform
|
||||
weight: 210
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-cloud-provider-o11y/
|
||||
---
|
||||
|
||||
# Manage Cloud Provider Observability in Grafana Cloud using Terraform
|
||||
|
||||
Manage Cloud Provider Observability, including Amazon CloudWatch and Microsoft Azure resources, in Grafana Cloud using Terraform.
|
||||
For more information on Cloud Provider Observability, refer to the [Cloud Provider Observability](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/) documentation.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you begin, you should have the following available:
|
||||
|
||||
- A Grafana Cloud account
|
||||
- For more information on setting up a Grafana Cloud account, refer to [Get started](/docs/grafana-cloud/get-started/).
|
||||
- Terraform installed on your machine
|
||||
- For more information on how to install Terraform, refer to the [Terraform install documentation](https://developer.hashicorp.com/terraform/install).
|
||||
- Administrator permissions in your Grafana instance
|
||||
- For more information on assigning Grafana RBAC roles, refer to [Assign RBAC roles](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control/assign-rbac-roles/).
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Save all of the following Terraform configuration files in the same directory.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Configure authentication for the Grafana Provider
|
||||
|
||||
The Grafana Provider is a logical abstraction of an upstream API that you can use to interact with Grafana Cloud resources.
|
||||
You must configure it with the following information:
|
||||
|
||||
- A Grafana Cloud access policy token that includes the permissions the provider needs to access the Grafana Cloud Provider API.
|
||||
- A regional cloud provider API endpoint to establish which Grafana Cloud stack you are accessing.
|
||||
|
||||
To configure authentication for the Grafana Provider:
|
||||
|
||||
1. Create a Grafana Cloud access policy and token.
|
||||
- To create an access policy for your organization, refer to the [Create an access policy for a stack steps](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies/#create-an-access-policy-for-a-stack) and use the following scopes listed for the supported Amazon CloudWatch or Microsoft Azure resources:
|
||||
- Amazon CloudWatch
|
||||
- Metrics scrape or resource metadata scrape
|
||||
- `integration-management:read`
|
||||
- `integration-management:write`
|
||||
- `stacks:read`
|
||||
- Metric streams
|
||||
- `metrics:write`
|
||||
- ALB access logs, logs with Lambda, or logs with Amazon Data Firehose
|
||||
- `logs:write`
|
||||
- Microsoft Azure
|
||||
- Serverless metrics
|
||||
- `integration-management:read`
|
||||
- `integration-management:write`
|
||||
- `stacks:read`
|
||||
- Logs with Azure functions
|
||||
- `logs:write`
|
||||
|
||||
1. Obtain the regional Cloud Provider API endpoint.
|
||||
- To obtain the regional Cloud provider API endpoint, use your access policy token and the following command to return a list of all of the Grafana stacks you own, along with their respective Cloud Provider API hostnames:
|
||||
```bash
|
||||
curl -sH "Authorization: Bearer <Access Token from previous step>" "https://grafana.com/api/instances" | \
|
||||
jq '[.items[]|{stackName: .slug, clusterName:.clusterSlug, cloudProviderAPIURL: "https://cloud-provider-api-\(.clusterSlug).grafana.net"}]'
|
||||
```
|
||||
1. Create a file named `cloud-provider.tf` and add the following code block:
|
||||
|
||||
```tf
|
||||
terraform {
|
||||
required_providers {
|
||||
grafana = {
|
||||
source = "grafana/grafana"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "grafana" {
|
||||
cloud_api_url = "<CLOUD_PROVIDER_API_URL>"
|
||||
cloud_access_policy_token = "<CLOUD_ACCESS_POLICY_TOKEN>"
|
||||
}
|
||||
```
|
||||
|
||||
1. Create a `variables.tf` file and paste the `<CLOUD_ACCESS_POLICY_TOKEN>` and `<CLOUD_PROVIDER_API_URL` variables with your values.
|
||||
1. Run the following Terraform command:
|
||||
```tf
|
||||
terraform apply -var-file="variables.tf"
|
||||
```
|
||||
|
||||
## Configure your resources
|
||||
|
||||
To find instructions for configuring specific Amazon CloudWatch and Microsoft Azure resources in Cloud Provider Observability using Terraform, refer to the following documents:
|
||||
|
||||
- Amazon CloudWatch
|
||||
- [Metrics scrape](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/aws/cloudwatch-metrics/config-cw-metric-scrape/): Pull CloudWatch metrics from multiple regions for your AWS account, without needing to install Grafana Alloy.
|
||||
- [Metric streams](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/aws/cloudwatch-metrics/config-cw-metric-streams/#configure-metric-streams-with-terraform): Push metrics with CloudWatch metric streams using Amazon Data Firehose, providing real-time insights and scalability while simplifying configuration and reducing cost and manual effort.
|
||||
- [ALB access logs](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/aws/logs/cloudwatch-logs/config-alb-access-logs-lambda/#configure-with-terraform): Send application load balancer access logs from AWS to Grafana Cloud using a Lambda function.
|
||||
- [Logs with Lambda](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/aws/logs/cloudwatch-logs/config-cw-logs-lambda/#configure-with-terraform): Send logs to Grafana Cloud from multiple AWS services using a lambda-promtail function.
|
||||
- [Logs with Amazon Data Firehose](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/aws/logs/firehose-logs/config-firehose-logs/#configure-with-terraform): Send logs from AWS to Grafana Cloud with Amazon Data Firehose and minimal infrastructure.
|
||||
- Microsoft Azure
|
||||
- [Serverless metrics](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/azure/collect-azure-serverless/config-azure-metrics-serverless/): Monitor your Azure resources without the need to configure or deploy a collector by using Cloud Provider Observability.
|
||||
- [Logs with Azure functions](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/azure/config-azure-logs-azure-function/): Send Azure event logs to a Loki endpoint using an Azure function that subscribes to an Azure event hub.
|
||||
|
||||
## Grafana cloud provider resources
|
||||
|
||||
You can define the following Cloud Provider Observability resources and data sources using Terraform:
|
||||
|
||||
| Resource name | Description |
|
||||
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `grafana_cloud_provider_aws_account` | Represents an AWS IAM role that authorizes Grafana Cloud to pull Amazon CloudWatch metrics for a set of regions. Usually, there's one of these resources per configured AWS account. For a full reference of this resource, refer to [the Terraform Grafana Provider reference documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_provider_aws_account). |
|
||||
| `grafana_cloud_provider_aws_cloudwatch_scrape_job` | Represents a Grafana AWS scrape job. This configures Grafana to fetch a list of metrics/statistics for one or many AWS services, and for a given `grafana_cloud_provider_aws_account`. For a full reference of this resource, refer to [the Terraform Grafana Provider reference documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_provider_aws_cloudwatch_scrape_job) |
|
||||
| `grafana_cloud_provider_aws_resource_metadata_scrape_job` | Represents a Grafana AWS Resource Metadata scrape job. This resource configures Grafana to fetch resource metadata for one or multiple AWS services, for a given `grafana_cloud_provider_aws_account`. For a full reference of this resource, refer to [the Terraform Grafana Provider reference documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_provider_aws_resource_metadata_scrape_job) |
|
||||
| `grafana_cloud_provider_azure_credential` | A resource representing an Azure Service Principal credential used by Grafana Cloud to pull Azure Monitor metrics from one or more subscriptions. For a full reference of this resource, refer to [the Terraform Grafana Provider resource documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_provider_azure_credential). |
|
||||
@@ -0,0 +1,231 @@
|
||||
---
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Terraform
|
||||
title: Creating and managing a Grafana Cloud stack using Terraform
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-cloud-stack/
|
||||
---
|
||||
|
||||
# Creating and managing a Grafana Cloud stack using Terraform
|
||||
|
||||
Learn how to add a data source, a dashboard, and a folder to a Grafana Cloud stack using Terraform.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, you should have the following available:
|
||||
|
||||
- A Grafana Cloud account, as shown in [Get started](/docs/grafana-cloud/get-started/)
|
||||
- [Terraform](https://www.terraform.io/downloads) installed on your machine
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
All of the following Terraform configuration files should be saved in the same directory.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Create a Cloud stack
|
||||
|
||||
1. Create a Terraform configuration file.
|
||||
|
||||
This Terraform configuration will create a Grafana Cloud stack and a second token needed for your Grafana instance.
|
||||
|
||||
Create a file named `cloud-stack.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
grafana = {
|
||||
source = "grafana/grafana"
|
||||
version = ">= 2.9.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
// Step 1: Create a stack
|
||||
provider "grafana" {
|
||||
alias = "cloud"
|
||||
cloud_access_policy_token = "<cloud-access-token>"
|
||||
}
|
||||
|
||||
|
||||
resource "grafana_cloud_stack" "my_stack" {
|
||||
provider = grafana.cloud
|
||||
|
||||
name = "<stack-name>"
|
||||
slug = "<stack-name>"
|
||||
region_slug = "<region>" # Example "us","eu" etc
|
||||
delete_protection = true
|
||||
}
|
||||
|
||||
// Step 2: Create a service account and key for the stack
|
||||
resource "grafana_cloud_stack_service_account" "cloud_sa" {
|
||||
provider = grafana.cloud
|
||||
stack_slug = grafana_cloud_stack.my_stack.slug
|
||||
|
||||
name = "<service-account-name>"
|
||||
role = "Admin"
|
||||
is_disabled = false
|
||||
}
|
||||
|
||||
resource "grafana_cloud_stack_service_account_token" "cloud_sa" {
|
||||
provider = grafana.cloud
|
||||
stack_slug = grafana_cloud_stack.my_stack.slug
|
||||
|
||||
name = "terraform serviceaccount key"
|
||||
service_account_id = grafana_cloud_stack_service_account.cloud_sa.id
|
||||
}
|
||||
|
||||
// Step 3: Create resources within the stack
|
||||
provider "grafana" {
|
||||
alias = "my_stack"
|
||||
|
||||
url = grafana_cloud_stack.my_stack.url
|
||||
auth = grafana_cloud_stack_service_account_token.cloud_sa.key
|
||||
}
|
||||
resource "grafana_folder" "my_folder" {
|
||||
provider = grafana.my_stack
|
||||
|
||||
title = "Test Folder"
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<cloud-access-token>` with your Grafana Cloud Access Policy Token.
|
||||
To create a new one, refer [Grafana Cloud Access Policies](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/access-policies/)
|
||||
Add all stacks to the realms list.
|
||||
The scopes needed for the example are:
|
||||
- dashboards:read
|
||||
- orgs:read
|
||||
- stack-dashboards:read
|
||||
- stacks:read
|
||||
- dashboards:write
|
||||
- orgs:write
|
||||
- stack-dashboards:write
|
||||
- stacks:write
|
||||
- stack-service-accounts:write
|
||||
- dashboards:delete
|
||||
- stack-dashboards:delete
|
||||
- stacks:delete
|
||||
- `<stack-name>` with the name of your stack.
|
||||
- `<region>` with the region in which you want to create the stack. For example `us`, `eu`.
|
||||
- `<service-account-name>` with a name for the serviceaccount that will be created to use for operations within the stack/instance.
|
||||
|
||||
The first provider block, `grafana.cloud`, uses the Cloud Access Policy Token from the Cloud Portal and is referenced as a parameter when creating the Cloud stack and the token in the Grafana instance to provide the necessary authentication.
|
||||
|
||||
The second provider block, `grafana.my_stack`, is referenced as a parameter when creating resources inside the Grafana instance.
|
||||
|
||||
## Add a data source
|
||||
|
||||
This guide uses the InfluxDB data source. The required arguments for [grafana_data_source (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/data_source) vary depending on the type of data source you select.
|
||||
|
||||
1. Create a file named `datasource.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
resource "grafana_data_source" "<data-source-name>" {
|
||||
provider = grafana.my_stack
|
||||
|
||||
type = "influxdb"
|
||||
name = "<data-source-name>"
|
||||
url = "<data-source-url>"
|
||||
username = "<username>"
|
||||
password = "<password>"
|
||||
database_name = "<db-name>"
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<data-source-name>` with the name of the data source to be added in Grafana.
|
||||
- `<data-source-url>` with URL of your data source.
|
||||
- `<username>` with the username for authenticating with your data source.
|
||||
- `<password>` with password for authenticating with your data source.
|
||||
- `<db-name>` with name of your database.
|
||||
|
||||
## Add a folder
|
||||
|
||||
This Terraform configuration creates a folder in your Grafana instance using [grafana_folder (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/folder).
|
||||
|
||||
1. Create a file named `folder.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
resource "grafana_folder" "<folder-name>" {
|
||||
provider = grafana.my_stack
|
||||
|
||||
title = "<folder-name>"
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field value:
|
||||
- `<folder-name>` with a name for the folder.
|
||||
|
||||
## Add a dashboard to the folder
|
||||
|
||||
This Terraform configuration creates a dashboard inside the folder created above in your Grafana instance using [grafana_dashboard (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/dashboard).
|
||||
|
||||
1. Create a file named `dashboard.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
# Using a JSON file
|
||||
resource "grafana_dashboard" "dashboard" {
|
||||
provider = grafana.my_stack
|
||||
|
||||
config_json = file("<file-name>.json")
|
||||
folder = grafana_folder.<folder-name>.id
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field value:
|
||||
- `<file-name>` with the name of the JSON file that has the source code for the dashboard.
|
||||
|
||||
The dashboard is represented by its JSON source code and referenced in the `config_json` parameter.
|
||||
|
||||
## Apply the Terraform configuration
|
||||
|
||||
In a terminal, run the following commands from the directory where all of the configuration files are located.
|
||||
|
||||
1. Initialize a working directory containing Terraform configuration files.
|
||||
|
||||
```shell
|
||||
terraform init
|
||||
```
|
||||
|
||||
1. Preview the changes that Terraform will make.
|
||||
|
||||
```shell
|
||||
terraform plan
|
||||
```
|
||||
|
||||
1. Apply the configuration files.
|
||||
|
||||
```shell
|
||||
terraform apply
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
Once you apply the changes in the Terraform configurations, you should be able to verify the following:
|
||||
|
||||
- The new Grafana stack is created and visible in the Cloud Portal
|
||||
|
||||
|
||||
|
||||
- A service account key token is added in your Grafana instance. In the following image, the service account key token named "terraform serviceaccount key" was added by the [grafana_cloud_stack_service_account_token (Resource)](#create-a-cloud-stack).
|
||||
|
||||
|
||||
|
||||
- A new data source (InfluxDB in this example) is visible in the grafana instance.
|
||||
|
||||
|
||||
|
||||
- A new folder in Grafana. In the following image, a folder named "Demos" was added by the [grafana_folder (Resource)](./#add-a-folder).
|
||||
|
||||
|
||||
|
||||
- A new dashboard in the Grafana instance. In the following image a dashboard named "InfluxDB Cloud Demos" was created inside the "Demos" folder.
|
||||
|
||||
|
||||
|
||||
## Conclusion
|
||||
|
||||
In this guide, you created a Grafana Cloud stack along with a data source, folder, and dashboard imported from a JSON file using Terraform.
|
||||
|
||||
To learn more about managing Grafana Cloud using Terraform, see [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
|
||||
@@ -0,0 +1,384 @@
|
||||
---
|
||||
description: Learn how to create Grafana Fleet Management collectors and pipelines in Grafana Cloud using Terraform
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Terraform
|
||||
- Fleet Management
|
||||
- Alloy
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
title: Manage Fleet Management in Grafana Cloud using Terraform
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-fleet-management/
|
||||
---
|
||||
|
||||
# Manage Fleet Management in Grafana Cloud using Terraform
|
||||
|
||||
Learn how to create [Grafana Fleet Management](https://grafana.com/docs/grafana-cloud/send-data/fleet-management/) collectors and pipelines in Grafana Cloud using Terraform.
|
||||
This guide shows you how to create an access policy and a token for Fleet Management and [Grafana Alloy](https://grafana.com/docs/alloy/latest/), a collector with remote attributes, and a pipeline for profiling Alloy.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you begin, you should have the following available:
|
||||
|
||||
- A Grafana Cloud account, as shown in [Get started](https://grafana.com/docs/grafana-cloud/get-started/)
|
||||
- [Terraform](https://www.terraform.io/downloads) installed on your machine
|
||||
- [Alloy](https://grafana.com/docs/alloy/latest/set-up/install/) installed on your machine
|
||||
- Administrator permissions in your Grafana instance
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
All of the following Terraform configuration files should be saved in the same directory.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Configure a provider for Grafana Cloud
|
||||
|
||||
This Terraform configuration configures the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when interacting with the Cloud API.
|
||||
The [`grafana_cloud_stack` (Data Source)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/data-sources/cloud_stack) is used to retrieve the user ID and URL details of your instance.
|
||||
|
||||
1. Create a Grafana Cloud access policy and token.
|
||||
To create a new one, refer to [Grafana Cloud Access Policies](https://grafana.com/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/).
|
||||
Add your stack to the realms list.
|
||||
The scopes needed for the examples in this guide are:
|
||||
- `accesspolicies:read`
|
||||
- `accesspolicies:write`
|
||||
- `accesspolicies:delete`
|
||||
- `stacks:read`
|
||||
|
||||
1. Create a file named `cloud-provider.tf` and add the following code block:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
grafana = {
|
||||
source = "grafana/grafana"
|
||||
version = ">= 3.19.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "grafana" {
|
||||
alias = "cloud"
|
||||
|
||||
cloud_access_policy_token = "<CLOUD_ACCESS_POLICY_TOKEN>"
|
||||
}
|
||||
|
||||
data "grafana_cloud_stack" "stack" {
|
||||
provider = grafana.cloud
|
||||
|
||||
slug = "<STACK_SLUG>"
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<CLOUD_ACCESS_POLICY_TOKEN>` with the access policy token you created in the first step
|
||||
- `<STACK_SLUG>` with your stack slug, which is the subdomain where your Grafana Cloud instance is available: `https://<STACK_SLUG>.grafana.net`
|
||||
|
||||
## Create an access policy and token for Fleet Management
|
||||
|
||||
This Terraform configuration creates the following:
|
||||
|
||||
- An access policy named `fleet-management-policy` with `fleet-management:read` and `fleet-management:write` scopes, using [`grafana_cloud_access_policy` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy)
|
||||
- A token named `fleet-management-token`, using [`grafana_cloud_access_policy_token` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy_token)
|
||||
|
||||
1. Create a file named `fm-access-policy.tf` and add the following code block:
|
||||
|
||||
```terraform
|
||||
resource "grafana_cloud_access_policy" "fm_policy" {
|
||||
provider = grafana.cloud
|
||||
|
||||
name = "fleet-management-policy"
|
||||
region = data.grafana_cloud_stack.stack.region_slug
|
||||
|
||||
scopes = [
|
||||
"fleet-management:read",
|
||||
"fleet-management:write"
|
||||
]
|
||||
|
||||
realm {
|
||||
type = "stack"
|
||||
identifier = data.grafana_cloud_stack.stack.id
|
||||
}
|
||||
}
|
||||
|
||||
resource "grafana_cloud_access_policy_token" "fm_token" {
|
||||
provider = grafana.cloud
|
||||
|
||||
name = "fleet-management-token"
|
||||
region = grafana_cloud_access_policy.fm_policy.region
|
||||
access_policy_id = grafana_cloud_access_policy.fm_policy.policy_id
|
||||
}
|
||||
```
|
||||
|
||||
## Configure a provider for Fleet Management
|
||||
|
||||
This Terraform configuration configures the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when interacting with the Fleet Management API.
|
||||
|
||||
1. Create a file named `fm-provider.tf` and add the following code block:
|
||||
|
||||
```terraform
|
||||
locals {
|
||||
fm_id = data.grafana_cloud_stack.stack.fleet_management_user_id
|
||||
fm_token = grafana_cloud_access_policy_token.fm_token.token
|
||||
fm_url = data.grafana_cloud_stack.stack.fleet_management_url
|
||||
}
|
||||
|
||||
provider "grafana" {
|
||||
alias = "fm"
|
||||
|
||||
fleet_management_auth = "${local.fm_id}:${local.fm_token}"
|
||||
fleet_management_url = local.fm_url
|
||||
}
|
||||
```
|
||||
|
||||
## Create a Fleet Management collector
|
||||
|
||||
This Terraform configuration creates a collector with a remote attribute, using [`grafana_fleet_management_collector` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/fleet_management_collector).
|
||||
|
||||
This configuration only preregisters the collector.
|
||||
You must complete the [Run Alloy](#run-alloy) step for the collector to register with Fleet Management and be assigned remote attributes.
|
||||
|
||||
1. Create a file named `fm-collector.tf` and add the following code block:
|
||||
|
||||
```terraform
|
||||
resource "grafana_fleet_management_collector" "fm_collector" {
|
||||
provider = grafana.fm
|
||||
|
||||
id = "prod_collector"
|
||||
remote_attributes = {
|
||||
"env" = "PROD"
|
||||
}
|
||||
enabled = true
|
||||
}
|
||||
```
|
||||
|
||||
## Create a Fleet Management pipeline
|
||||
|
||||
This Terraform configuration creates a pipeline for Alloy profiling with a matcher for the collector declared in the previous step, using [`grafana_fleet_management_pipeline` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/fleet_management_pipeline).
|
||||
The pipeline writes the profiles to [Grafana Cloud Profiles](https://grafana.com/docs/grafana-cloud/monitor-applications/profiles/).
|
||||
|
||||
1. Create a file named `profiling.alloy.tftpl` and add the following content:
|
||||
|
||||
```alloy
|
||||
// This pipeline scrapes pprof Go profiles from Alloy and sends them to Pyroscope.
|
||||
//
|
||||
// It requires the following environment variables to be set where Alloy is running:
|
||||
// Required:
|
||||
// * GCLOUD_RW_API_KEY: The Grafana Cloud API key with write access to Pyroscope.
|
||||
// Optional:
|
||||
// * ALLOY_ADDRESS: The address Alloy listens on. Defaults to 127.0.0.1:12345.
|
||||
pyroscope.scrape "alloy" {
|
||||
targets = [
|
||||
{
|
||||
"__address__" = coalesce(
|
||||
sys.env("ALLOY_ADDRESS"),
|
||||
"127.0.0.1:12345",
|
||||
),
|
||||
"service_name" = "alloy",
|
||||
},
|
||||
]
|
||||
forward_to = [pyroscope.write.grafana_cloud.receiver]
|
||||
|
||||
profiling_config {
|
||||
profile.process_cpu {
|
||||
enabled = true
|
||||
}
|
||||
|
||||
profile.memory {
|
||||
enabled = true
|
||||
}
|
||||
|
||||
profile.mutex {
|
||||
enabled = true
|
||||
}
|
||||
|
||||
profile.block {
|
||||
enabled = true
|
||||
}
|
||||
|
||||
profile.goroutine {
|
||||
enabled = true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
pyroscope.write "grafana_cloud" {
|
||||
endpoint {
|
||||
url = "${profiles_url}"
|
||||
|
||||
basic_auth {
|
||||
username = "${profiles_id}"
|
||||
password = sys.env("GCLOUD_RW_API_KEY")
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. Create a file named `fm-pipeline.tf` and add the following code block:
|
||||
|
||||
```terraform
|
||||
locals {
|
||||
profiles_id = data.grafana_cloud_stack.stack.profiles_user_id
|
||||
profiles_url = data.grafana_cloud_stack.stack.profiles_url
|
||||
}
|
||||
|
||||
resource "grafana_fleet_management_pipeline" "pipeline" {
|
||||
provider = grafana.fm
|
||||
|
||||
name = "profiling"
|
||||
contents = templatefile(
|
||||
"profiling.alloy.tftpl",
|
||||
{
|
||||
profiles_id = local.profiles_id,
|
||||
profiles_url = local.profiles_url,
|
||||
},
|
||||
)
|
||||
matchers = [
|
||||
"env=\"PROD\""
|
||||
]
|
||||
enabled = true
|
||||
}
|
||||
```
|
||||
|
||||
## Create an access policy and token for Alloy
|
||||
|
||||
This Terraform configuration creates the following:
|
||||
|
||||
- An access policy named `alloy-policy` with `set:alloy-data-write` scope, using [`grafana_cloud_access_policy` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy)
|
||||
- A token named `alloy-token`, using [`grafana_cloud_access_policy_token` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy_token)
|
||||
|
||||
1. Create a file named `alloy-access-policy.tf` and add the following code block:
|
||||
|
||||
```terraform
|
||||
resource "grafana_cloud_access_policy" "alloy_policy" {
|
||||
provider = grafana.cloud
|
||||
|
||||
name = "alloy-policy"
|
||||
region = data.grafana_cloud_stack.stack.region_slug
|
||||
|
||||
scopes = [
|
||||
"set:alloy-data-write"
|
||||
]
|
||||
|
||||
realm {
|
||||
type = "stack"
|
||||
identifier = data.grafana_cloud_stack.stack.id
|
||||
}
|
||||
}
|
||||
|
||||
resource "grafana_cloud_access_policy_token" "alloy_token" {
|
||||
provider = grafana.cloud
|
||||
|
||||
name = "alloy-token"
|
||||
region = grafana_cloud_access_policy.alloy_policy.region
|
||||
access_policy_id = grafana_cloud_access_policy.alloy_policy.policy_id
|
||||
}
|
||||
|
||||
output "alloy_token" {
|
||||
value = grafana_cloud_access_policy_token.alloy_token.token
|
||||
sensitive = true
|
||||
}
|
||||
```
|
||||
|
||||
## Create a configuration file for Alloy
|
||||
|
||||
This Terraform configuration creates an Alloy configuration file with the [`remotecfg` block](https://grafana.com/docs/grafana-cloud/send-data/alloy/reference/config-blocks/remotecfg/) for Fleet Management, using [`local_file` (Resource)](https://registry.terraform.io/providers/hashicorp/local/latest/docs/resources/file).
|
||||
|
||||
1. Create a file named `config.alloy.tftpl` and add the following content:
|
||||
|
||||
```alloy
|
||||
remotecfg {
|
||||
id = "${collector_id}"
|
||||
url = "${fm_url}"
|
||||
poll_frequency = "60s"
|
||||
|
||||
basic_auth {
|
||||
username = "${fm_id}"
|
||||
password = sys.env("GCLOUD_RW_API_KEY")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. Create a file named `alloy-config.tf` and add the following code block:
|
||||
|
||||
```terraform
|
||||
resource "local_file" "alloy_config" {
|
||||
filename = "<ALLOY_CONFIG_PATH>"
|
||||
content = templatefile(
|
||||
"config.alloy.tftpl",
|
||||
{
|
||||
collector_id = "prod_collector",
|
||||
fm_id = local.fm_id,
|
||||
fm_url = local.fm_url,
|
||||
},
|
||||
)
|
||||
directory_permission = "0644"
|
||||
file_permission = "0644"
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<ALLOY_CONFIG_PATH>` with the path the Alloy configuration file should be written to, for example `config.alloy`
|
||||
|
||||
## Apply the Terraform configuration
|
||||
|
||||
In a terminal, run the following commands from the directory where all of the configuration files are located.
|
||||
|
||||
1. Initialize a working directory containing Terraform configuration files:
|
||||
|
||||
```shell
|
||||
terraform init
|
||||
```
|
||||
|
||||
1. Preview the Terraform changes:
|
||||
|
||||
```shell
|
||||
terraform plan
|
||||
```
|
||||
|
||||
1. Apply the configuration:
|
||||
|
||||
```shell
|
||||
terraform apply
|
||||
```
|
||||
|
||||
## Run Alloy
|
||||
|
||||
To learn how to start or restart Alloy, refer to [Run Grafana Alloy](https://grafana.com/docs/alloy/latest/set-up/run/).
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
The variable `GCLOUD_RW_API_KEY` must be set in the environment where Alloy is running for the remote configuration in this example to work.
|
||||
{{< /admonition >}}
|
||||
|
||||
1. Run the following command to view the Alloy token:
|
||||
|
||||
```shell
|
||||
terraform output -raw alloy_token
|
||||
```
|
||||
|
||||
1. Set the environment variable `GCLOUD_RW_API_KEY` to the value from the first step.
|
||||
1. Run Alloy.
|
||||
|
||||
## Validation
|
||||
|
||||
After you apply the changes in the Terraform configurations and run Alloy, you should be able to verify the following:
|
||||
|
||||
- A collector is added to the Fleet Management **Inventory tab**:
|
||||
|
||||
{{< figure alt="The Inventory screen in the Fleet Management interface in Grafana Cloud which shows that a new collector called `prod_collector` is registered with attribute `env=PROD`, has a healthy status, and was last modified a few seconds ago." src="/media/docs/fleet-management/screenshot-fleet-management-terraform-validate-collector.png" >}}
|
||||
|
||||
- A pipeline is added to the Fleet Management **Remote configuration tab**:
|
||||
|
||||
{{< figure alt="The Remote configuration screen in the Fleet Management interface in Grafana Cloud which shows that a new configuration pipeline called `profiling` is active and was last modified a few seconds ago." src="/media/docs/fleet-management/screenshot-fleet-management-terraform-validate-pipeline.png" >}}
|
||||
|
||||
- Alloy profiles are being exported to Grafana Cloud Profiles:
|
||||
|
||||
{{< figure alt="A dashboard in Grafana Cloud which shows Alloy profiling data, including graphs for CPU and memory." src="/media/docs/fleet-management/screenshot-fleet-management-terraform-validate-profiles.png" >}}
|
||||
|
||||
## Conclusion
|
||||
|
||||
In this guide, you created an access policy and a token for Fleet Management and Alloy, a collector with remote attributes, and a pipeline for profiling Alloy, all using Terraform.
|
||||
|
||||
To learn more about managing Grafana Cloud using Terraform, refer to [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
description: Learn how to manage Grafana Frontend Observability resources in Grafana Cloud using Terraform
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Terraform
|
||||
- Frontend Observability
|
||||
title: Manage Frontend Observability in Grafana Cloud with Terraform
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-frontend-observability/
|
||||
---
|
||||
|
||||
# Manage Frontend Observability in Grafana Cloud with Terraform
|
||||
|
||||
Learn how to use Terraform to manage [Grafana Frontend Observability](https://grafana.com/docs/grafana-cloud/frontend-observability/) resources, such as your applications.
|
||||
This guide shows you how to create an access policy and a token for Frontend Observability so that you can connect to the Frontend Observability API.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you begin, you should have the following available:
|
||||
|
||||
- A Grafana Cloud account, as shown in [Get started](https://grafana.com/docs/grafana-cloud/get-started/)
|
||||
- [Terraform](https://www.terraform.io/downloads) installed on your machine
|
||||
- Administrator permissions in your Grafana instance
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
All of the following Terraform configuration files should be saved in the same directory.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Configure a provider for Grafana Cloud
|
||||
|
||||
This Terraform configuration configures the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when interacting with the Cloud API.
|
||||
The [`grafana_cloud_stack` (Data Source)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/data-sources/cloud_stack) is used to retrieve the details of your instance.
|
||||
|
||||
1. Create a Grafana Cloud access policy and token.
|
||||
To create a new one, refer to [Grafana Cloud Access Policies](https://grafana.com/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/).
|
||||
Add your stack to the realms list.
|
||||
The scopes needed for the examples in this guide are:
|
||||
- `accesspolicies:read`
|
||||
- `accesspolicies:write`
|
||||
- `accesspolicies:delete`
|
||||
- `dashboards:read`
|
||||
- `dashboards:write`
|
||||
- `dashboards:delete`
|
||||
- `orgs:read`
|
||||
- `orgs:write`
|
||||
- `stacks:read`
|
||||
- `stacks:write`
|
||||
- `stacks:delete`
|
||||
- `stack-dashboards:read`
|
||||
- `stack-dashboards:write`
|
||||
- `stack-dashboards:delete`
|
||||
- `stack-service-accounts:write`
|
||||
|
||||
1. Create a file named `cloud-provider.tf` and add the following code block:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
grafana = {
|
||||
source = "grafana/grafana"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "grafana" {
|
||||
alias = "cloud"
|
||||
|
||||
cloud_access_policy_token = "<CLOUD_ACCESS_POLICY_TOKEN>"
|
||||
}
|
||||
|
||||
data "grafana_cloud_stack" "stack" {
|
||||
provider = grafana.cloud
|
||||
|
||||
slug = "<STACK_SLUG>"
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<CLOUD_ACCESS_POLICY_TOKEN>` with the access policy token you created in the first step
|
||||
- `<STACK_SLUG>` with your stack slug, which is the subdomain where your Grafana Cloud instance is available: `https://<STACK_SLUG>.grafana.net`
|
||||
|
||||
## Create an access policy and token for Frontend Observability
|
||||
|
||||
You must create a Terraform configuration with the following:
|
||||
|
||||
- An access policy with `frontend-observability:read`, `frontend-observability:write`, and `frontend-observability:delete` scopes, using [`grafana_cloud_access_policy` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy)
|
||||
- A token named `frontend_o11y_api_access_token`, using [`grafana_cloud_access_policy_token` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy_token)
|
||||
|
||||
## Configure the provider to use the Frontend Observability API
|
||||
|
||||
After you have created the token, you can configure the provider as follows:
|
||||
|
||||
```terraform
|
||||
provider "grafana" {
|
||||
frontend_o11y_api_access_token = "<access token from previous step>"
|
||||
}
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
In this guide, you created an access policy and a token for Frontend Observability using Terraform.
|
||||
|
||||
To learn more about managing Grafana Cloud using Terraform, refer to [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
cards:
|
||||
items:
|
||||
- description: Learn how to set up Terraform provider and configure your environment for managing Knowledge Graph resources.
|
||||
height: 24
|
||||
href: ./getting-started/
|
||||
title: Get started with Terraform
|
||||
- description: Configure notification alerts to manage how alerts are processed and routed in your Knowledge Graph.
|
||||
height: 24
|
||||
href: ./notification-alerts/
|
||||
title: Notification alerts
|
||||
- description: Define suppression rules to temporarily disable specific alerts during maintenance windows or testing.
|
||||
height: 24
|
||||
href: ./suppressed-assertions/
|
||||
title: Suppressed assertions
|
||||
- description: Create custom entity models and define how entities are discovered based on Prometheus queries.
|
||||
height: 24
|
||||
href: ./custom-model-rules/
|
||||
title: Custom model rules
|
||||
- description: Configure log data correlation with entities using data source mappings and filtering options.
|
||||
height: 24
|
||||
href: ./log-configurations/
|
||||
title: Log configurations
|
||||
- description: Set custom thresholds for request, resource, and health assertions to monitor your services.
|
||||
height: 24
|
||||
href: ./thresholds/
|
||||
title: Thresholds
|
||||
- description: Configure knowledge graph SLOs with entity-centric monitoring and RCA workbench integration for root cause analysis.
|
||||
height: 24
|
||||
href: ./knowledge-graph-slo/
|
||||
title: Knowledge graph SLOs
|
||||
title_class: pt-0 lh-1
|
||||
description: Manage Grafana Cloud Knowledge Graph using Terraform
|
||||
hero:
|
||||
description: Use Terraform to manage Grafana Cloud Knowledge Graph resources as code. Configure notification alerts, suppressed assertions, custom model rules, log configurations, and threshold configurations using infrastructure as code best practices.
|
||||
level: 1
|
||||
title: Manage Knowledge Graph using Terraform
|
||||
menuTitle: Manage Knowledge Graph in Grafana Cloud using Terraform
|
||||
title: Manage Knowledge Graph in Grafana Cloud using Terraform
|
||||
weight: 130
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Terraform
|
||||
- Knowledge Graph
|
||||
- Alert Configuration
|
||||
- Suppressed Assertions
|
||||
- Custom Model Rules
|
||||
- Log Configuration
|
||||
- Threshold Configuration
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/
|
||||
---
|
||||
|
||||
{{< docs/hero-simple key="hero" >}}
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Terraform enables you to manage [Grafana Cloud Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) resources using infrastructure as code. With Terraform, you can define, version control, and deploy Knowledge Graph configurations including alert rules, suppression policies, entity models, log correlations, and thresholds.
|
||||
|
||||
## Explore
|
||||
|
||||
{{< card-grid key="cards" type="simple" >}}
|
||||
|
||||
---
|
||||
|
||||
## Related resources
|
||||
|
||||
- [Grafana Terraform Provider Documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs)
|
||||
- [Knowledge Graph Documentation](/docs/grafana-cloud/knowledge-graph/)
|
||||
- [Terraform Best Practices](https://www.terraform.io/docs/cloud/guides/recommended-practices/index.html)
|
||||
@@ -0,0 +1,431 @@
|
||||
---
|
||||
description: Define custom entity models for Knowledge Graph using Terraform
|
||||
menuTitle: Custom model rules
|
||||
title: Create custom model rules using Terraform
|
||||
weight: 400
|
||||
keywords:
|
||||
- Terraform
|
||||
- Knowledge Graph
|
||||
- Custom Model Rules
|
||||
- Entity Models
|
||||
- Prometheus
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/custom-model-rules/
|
||||
---
|
||||
|
||||
# Create custom model rules using Terraform
|
||||
|
||||
Custom model rules in [Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) allow you to define how entities are discovered and modeled based on Prometheus queries. These rules enable you to create custom entity types, define their relationships, and specify how they should be enriched with additional data.
|
||||
|
||||
For information about managing entities and relations in the Knowledge Graph UI, refer to [Manage entities and relations](/docs/grafana-cloud/knowledge-graph/configure/manage-entities-relations/).
|
||||
|
||||
## Basic custom model rules
|
||||
|
||||
Create a file named `custom-model-rules.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
# Basic custom model rule for services
|
||||
resource "grafana_asserts_custom_model_rules" "basic_service" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "basic-service-model"
|
||||
|
||||
rules {
|
||||
entity {
|
||||
type = "Service"
|
||||
name = "service"
|
||||
|
||||
defined_by {
|
||||
query = "up{job!=''}"
|
||||
label_values = {
|
||||
service = "job"
|
||||
}
|
||||
literals = {
|
||||
_source = "up_query"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Advanced service model with scope and lookup
|
||||
|
||||
Define service entities with environment scoping and relationship mappings:
|
||||
|
||||
```terraform
|
||||
# Advanced service model with environment scoping
|
||||
resource "grafana_asserts_custom_model_rules" "advanced_service" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "advanced-service-model"
|
||||
|
||||
rules {
|
||||
entity {
|
||||
type = "Service"
|
||||
name = "workload | service | job"
|
||||
|
||||
scope = {
|
||||
namespace = "namespace"
|
||||
env = "asserts_env"
|
||||
site = "asserts_site"
|
||||
}
|
||||
|
||||
lookup = {
|
||||
workload = "workload | deployment | statefulset | daemonset | replicaset"
|
||||
service = "service"
|
||||
job = "job"
|
||||
proxy_job = "job"
|
||||
}
|
||||
|
||||
defined_by {
|
||||
query = "up{job!='', asserts_env!=''}"
|
||||
label_values = {
|
||||
service = "service"
|
||||
job = "job"
|
||||
workload = "workload"
|
||||
namespace = "namespace"
|
||||
}
|
||||
literals = {
|
||||
_source = "up_with_workload"
|
||||
}
|
||||
}
|
||||
|
||||
defined_by {
|
||||
query = "up{job='maintenance'}"
|
||||
disabled = true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Multi-entity model configuration
|
||||
|
||||
Define multiple entity types in a single configuration:
|
||||
|
||||
```terraform
|
||||
# Multiple entity types in a single model
|
||||
resource "grafana_asserts_custom_model_rules" "multi_entity" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "kubernetes-entities"
|
||||
|
||||
rules {
|
||||
# Service entity
|
||||
entity {
|
||||
type = "Service"
|
||||
name = "service"
|
||||
|
||||
scope = {
|
||||
namespace = "namespace"
|
||||
cluster = "cluster"
|
||||
}
|
||||
|
||||
defined_by {
|
||||
query = "up{service!=''}"
|
||||
label_values = {
|
||||
service = "service"
|
||||
namespace = "namespace"
|
||||
cluster = "cluster"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Pod entity
|
||||
entity {
|
||||
type = "Pod"
|
||||
name = "Pod"
|
||||
|
||||
scope = {
|
||||
namespace = "namespace"
|
||||
cluster = "cluster"
|
||||
}
|
||||
|
||||
lookup = {
|
||||
service = "service"
|
||||
workload = "workload"
|
||||
}
|
||||
|
||||
defined_by {
|
||||
query = "kube_pod_info{pod!=''}"
|
||||
label_values = {
|
||||
Pod = "pod"
|
||||
namespace = "namespace"
|
||||
cluster = "cluster"
|
||||
service = "service"
|
||||
}
|
||||
literals = {
|
||||
_entity_type = "Pod"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Namespace entity
|
||||
entity {
|
||||
type = "Namespace"
|
||||
name = "namespace"
|
||||
|
||||
scope = {
|
||||
cluster = "cluster"
|
||||
}
|
||||
|
||||
defined_by {
|
||||
query = "kube_namespace_status_phase{namespace!=''}"
|
||||
label_values = {
|
||||
namespace = "namespace"
|
||||
cluster = "cluster"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Complex entity with enrichment
|
||||
|
||||
Create service entities with multiple data sources and enrichment:
|
||||
|
||||
```terraform
|
||||
# Service entity with enrichment from multiple sources
|
||||
resource "grafana_asserts_custom_model_rules" "enriched_service" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "enriched-service-model"
|
||||
|
||||
rules {
|
||||
entity {
|
||||
type = "Service"
|
||||
name = "service"
|
||||
|
||||
enriched_by = [
|
||||
"prometheus_metrics",
|
||||
"kubernetes_metadata",
|
||||
"application_logs"
|
||||
]
|
||||
|
||||
scope = {
|
||||
environment = "asserts_env"
|
||||
region = "asserts_site"
|
||||
team = "team"
|
||||
}
|
||||
|
||||
lookup = {
|
||||
deployment = "workload"
|
||||
Pod = "pod"
|
||||
container = "container"
|
||||
}
|
||||
|
||||
# Primary definition from service up metrics
|
||||
defined_by {
|
||||
query = "up{service!='', asserts_env!=''}"
|
||||
label_values = {
|
||||
service = "service"
|
||||
environment = "asserts_env"
|
||||
region = "asserts_site"
|
||||
team = "team"
|
||||
}
|
||||
literals = {
|
||||
_primary_source = "service_up"
|
||||
}
|
||||
}
|
||||
|
||||
# Secondary definition from application metrics
|
||||
defined_by {
|
||||
query = "http_requests_total{service!=''}"
|
||||
label_values = {
|
||||
service = "service"
|
||||
environment = "environment"
|
||||
version = "version"
|
||||
}
|
||||
literals = {
|
||||
_secondary_source = "http_metrics"
|
||||
}
|
||||
}
|
||||
|
||||
# Disabled definition for testing
|
||||
defined_by {
|
||||
query = "test_metric{service!=''}"
|
||||
disabled = true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Database and infrastructure entities
|
||||
|
||||
Define database and infrastructure entity models:
|
||||
|
||||
```terraform
|
||||
# Database and infrastructure entity models
|
||||
resource "grafana_asserts_custom_model_rules" "infrastructure" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "infrastructure-entities"
|
||||
|
||||
rules {
|
||||
# Database entity
|
||||
entity {
|
||||
type = "Database"
|
||||
name = "database_instance"
|
||||
|
||||
scope = {
|
||||
environment = "env"
|
||||
region = "region"
|
||||
}
|
||||
|
||||
lookup = {
|
||||
host = "instance"
|
||||
port = "port"
|
||||
db_name = "database"
|
||||
}
|
||||
|
||||
defined_by {
|
||||
query = "mysql_up{instance!=''}"
|
||||
label_values = {
|
||||
database_instance = "instance"
|
||||
database = "database"
|
||||
env = "environment"
|
||||
region = "region"
|
||||
}
|
||||
literals = {
|
||||
_db_type = "mysql"
|
||||
}
|
||||
metric_value = "1"
|
||||
}
|
||||
|
||||
defined_by {
|
||||
query = "postgres_up{instance!=''}"
|
||||
label_values = {
|
||||
database_instance = "instance"
|
||||
database = "datname"
|
||||
env = "environment"
|
||||
}
|
||||
literals = {
|
||||
_db_type = "postgresql"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Load balancer entity
|
||||
entity {
|
||||
type = "LoadBalancer"
|
||||
name = "lb_instance"
|
||||
|
||||
scope = {
|
||||
environment = "env"
|
||||
}
|
||||
|
||||
defined_by {
|
||||
query = "haproxy_up{proxy!=''}"
|
||||
label_values = {
|
||||
lb_instance = "instance"
|
||||
proxy = "proxy"
|
||||
env = "environment"
|
||||
}
|
||||
literals = {
|
||||
_lb_type = "haproxy"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Resource reference
|
||||
|
||||
### `grafana_asserts_custom_model_rules`
|
||||
|
||||
Manage Knowledge Graph custom model rules through the Grafana API. This resource allows you to define custom entity models based on Prometheus queries with advanced mapping and enrichment capabilities.
|
||||
|
||||
#### Arguments
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `name` | `string` | Yes | The name of the custom model rules. This field is immutable and forces recreation if changed. |
|
||||
| `rules` | `list(object)` | Yes | The rules configuration containing entity definitions. Refer to [rules block](#rules-block) for details. |
|
||||
|
||||
#### Rules block
|
||||
|
||||
Each `rules` block supports the following:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| -------- | -------------- | -------- | ------------------------------------------------------------------------------- |
|
||||
| `entity` | `list(object)` | Yes | List of entity definitions. Refer to [entity block](#entity-block) for details. |
|
||||
|
||||
#### Entity block
|
||||
|
||||
Each `entity` block supports the following:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `type` | `string` | Yes | The type of the entity (for example, Service, Pod, Namespace). |
|
||||
| `name` | `string` | Yes | The name pattern for the entity. Can include pipe-separated alternatives. |
|
||||
| `defined_by` | `list(object)` | Yes | List of queries that define this entity. Refer to [`defined_by` block](#defined_by-block) for details. |
|
||||
| `disabled` | `bool` | No | Whether this entity is disabled. Defaults to `false`. |
|
||||
| `enriched_by` | `list(string)` | No | List of enrichment sources for the entity. |
|
||||
| `lookup` | `map(string)` | No | Lookup mappings for the entity to relate different label names. |
|
||||
| `scope` | `map(string)` | No | Scope labels that define the boundaries of this entity type. |
|
||||
|
||||
#### `defined_by` block
|
||||
|
||||
Each `defined_by` block supports the following:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| -------------- | ------------- | -------- | ------------------------------------------------------------------------- |
|
||||
| `query` | `string` | Yes | The Prometheus query that defines this entity. |
|
||||
| `disabled` | `bool` | No | Whether this query is disabled. Defaults to `false`. |
|
||||
| `label_values` | `map(string)` | No | Label value mappings for extracting entity attributes from query results. |
|
||||
| `literals` | `map(string)` | No | Literal value mappings for adding static attributes to entities. |
|
||||
| `metric_value` | `string` | No | Metric value to use from the query result. |
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
When `disabled = true` is set for a `defined_by` query, only the `query` field is used for matching. All other fields in the block are ignored.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Best practices
|
||||
|
||||
### Entity models
|
||||
|
||||
- Design your entity models to reflect your actual infrastructure and application architecture
|
||||
- Use descriptive names for custom model rules that indicate their purpose and scope
|
||||
- Start with basic entity definitions and gradually add complexity as needed
|
||||
- Define clear entity scopes using the `scope` parameter to organize entities by environment, region, or team
|
||||
|
||||
### Query design and performance
|
||||
|
||||
- Write efficient Prometheus queries that don't overload your monitoring system
|
||||
- Test your Prometheus queries independently before using them in model rules
|
||||
- Use specific label filters to reduce the scope of your queries where possible
|
||||
- Consider the cardinality implications of your entity definitions
|
||||
- Use the `disabled` flag to temporarily disable problematic queries during debugging
|
||||
|
||||
### Relationships and enrichment
|
||||
|
||||
- Use `lookup` mappings to establish relationships between different entity types
|
||||
- Leverage `enriched_by` to specify additional data sources for entity enrichment
|
||||
- Map Prometheus labels to entity attributes using clear and descriptive names
|
||||
- Use meaningful `literals` to add static metadata that helps with entity identification
|
||||
|
||||
### Label and attribute management
|
||||
|
||||
- Establish consistent labeling conventions across your infrastructure
|
||||
- Use `label_values` to extract dynamic attributes from your metrics
|
||||
- Document the meaning and expected values of custom literals
|
||||
- Ensure label names match across different entity definitions for proper relationship discovery
|
||||
|
||||
## Validation
|
||||
|
||||
After applying the Terraform configuration, verify that:
|
||||
|
||||
- Custom model rules are applied in your Knowledge Graph instance
|
||||
- Entities are being discovered according to your defined queries
|
||||
- Entity relationships and enrichment are working as expected
|
||||
- Entity graphs display the correct entity types and connections
|
||||
- Queries perform well without causing excessive load
|
||||
|
||||
## Related documentation
|
||||
|
||||
- [Manage entities and relations in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/manage-entities-relations/)
|
||||
- [Get started with Terraform for Knowledge Graph](../getting-started/)
|
||||
- [Knowledge graph basics](/docs/grafana-cloud/knowledge-graph/knowledge-graph-basics/)
|
||||
@@ -0,0 +1,140 @@
|
||||
---
|
||||
description: Learn how to configure Terraform to manage Knowledge Graph resources
|
||||
menuTitle: Get started
|
||||
title: Get started with Terraform for Knowledge Graph
|
||||
weight: 100
|
||||
keywords:
|
||||
- Terraform
|
||||
- Knowledge Graph
|
||||
- Provider Setup
|
||||
- Getting Started
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/getting-started/
|
||||
---
|
||||
|
||||
# Get started with Terraform for Knowledge Graph
|
||||
|
||||
Learn how to configure Terraform to manage [Grafana Cloud Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) resources. This guide walks you through setting up the Grafana Terraform provider and preparing your environment.
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you begin, ensure you have the following:
|
||||
|
||||
- A Grafana Cloud account, as shown in [Get started](/docs/grafana-cloud/get-started/)
|
||||
- [Terraform](https://www.terraform.io/downloads) installed on your machine
|
||||
- Administrator permissions in your Grafana instance
|
||||
- [Knowledge Graph enabled](/docs/grafana-cloud/knowledge-graph/get-started/) in your Grafana Cloud stack
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
All Terraform configuration files should be saved in the same directory.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Configure the Grafana provider
|
||||
|
||||
This Terraform configuration sets up the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when managing knowledge graph resources.
|
||||
|
||||
You can reuse a similar setup to the one described in [Creating and managing a Grafana Cloud stack using Terraform](/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/terraform-cloud-stack/) to set up a service account and a token.
|
||||
|
||||
### Steps
|
||||
|
||||
1. Create a Service account and token in Grafana.
|
||||
|
||||
To create a new one, refer to [Service account tokens](/docs/grafana/latest/administration/service-accounts/#service-account-tokens).
|
||||
|
||||
1. Create a file named `main.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
grafana = {
|
||||
source = "grafana/grafana"
|
||||
version = ">= 2.9.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "grafana" {
|
||||
alias = "asserts"
|
||||
|
||||
url = "<Stack-URL>"
|
||||
auth = "<Service-account-token>"
|
||||
stack_id = "<Stack-ID>"
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<Stack-URL>` with the URL of your Grafana stack (for example, `https://my-stack.grafana.net/`)
|
||||
- `<Service-account-token>` with the service account token that you created
|
||||
- `<Stack-ID>` with your Grafana Cloud stack ID
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
The `stack_id` parameter is required for Knowledge Graph resources to identify the stack where the resources belong.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Apply Terraform configurations
|
||||
|
||||
After creating your Terraform configuration files, apply them using the following commands:
|
||||
|
||||
1. Initialize a working directory containing Terraform configuration files:
|
||||
|
||||
```shell
|
||||
terraform init
|
||||
```
|
||||
|
||||
1. Preview the changes that Terraform makes:
|
||||
|
||||
```shell
|
||||
terraform plan
|
||||
```
|
||||
|
||||
1. Apply the configuration files:
|
||||
|
||||
```shell
|
||||
terraform apply
|
||||
```
|
||||
|
||||
## Verify your setup
|
||||
|
||||
After applying the configuration, verify your setup by checking that:
|
||||
|
||||
- Terraform can authenticate with your Grafana Cloud stack
|
||||
- The provider is properly configured with the correct stack ID
|
||||
- No errors appear in the Terraform output
|
||||
|
||||
## Best practices
|
||||
|
||||
When managing Knowledge Graph resources with Terraform, consider the following best practices:
|
||||
|
||||
### Name conventions
|
||||
|
||||
- Use descriptive names that clearly indicate the purpose of each resource
|
||||
- Follow a consistent naming pattern across your organization
|
||||
- Include environment or team identifiers in names when appropriate
|
||||
|
||||
### Version control
|
||||
|
||||
- Store your Terraform configurations in version control (Git)
|
||||
- Use separate directories or workspaces for different environments
|
||||
- Document changes in commit messages
|
||||
|
||||
### State management
|
||||
|
||||
- Use remote state backends for team collaboration
|
||||
- Enable state locking to prevent concurrent modifications
|
||||
- Regularly back up your Terraform state files
|
||||
|
||||
### Security
|
||||
|
||||
- Never commit service account tokens or sensitive data to version control
|
||||
- Use environment variables or secret management tools for credentials
|
||||
- Rotate service account tokens regularly
|
||||
|
||||
## Next steps
|
||||
|
||||
Now that you have configured the Terraform provider, you can start managing knowledge graph resources:
|
||||
|
||||
- [Configure notification alerts](../notification-alerts/)
|
||||
- [Define suppressed assertions](../suppressed-assertions/)
|
||||
- [Create custom model rules](../custom-model-rules/)
|
||||
- [Set up log configurations](../log-configurations/)
|
||||
- [Configure thresholds](../thresholds/)
|
||||
- [Configure knowledge graph SLOs](../knowledge-graph-slo/)
|
||||
@@ -0,0 +1,696 @@
|
||||
---
|
||||
description: Learn how to configure knowledge graph SLOs in Grafana using Terraform for entity-centric monitoring and root cause analysis
|
||||
menuTitle: Knowledge graph SLOs
|
||||
title: Configure knowledge graph SLOs using Terraform
|
||||
weight: 650
|
||||
keywords:
|
||||
- Terraform
|
||||
- Knowledge graph
|
||||
- SLO
|
||||
- Service Level Objectives
|
||||
- RCA workbench
|
||||
---
|
||||
|
||||
# Configure knowledge graph SLOs using Terraform
|
||||
|
||||
Service level objectives (SLOs) in the [knowledge graph](/docs/grafana-cloud/knowledge-graph/) provide entity-centric service level monitoring with integrated root cause analysis capabilities. By using the `grafana_slo_provenance` label with the value `asserts`, you can create SLOs that display the "asserts" badge in the UI and enable the **Open RCA workbench** button for seamless troubleshooting.
|
||||
|
||||
For details about creating and managing SLOs in the knowledge graph UI, refer to [Create and manage the knowledge graph SLOs](/docs/grafana-cloud/knowledge-graph/configure/manage-slos/).
|
||||
|
||||
## Overview
|
||||
|
||||
Knowledge graph SLOs extend standard Grafana SLOs with entity-centric monitoring and root cause analysis features:
|
||||
|
||||
- **Entity-centric monitoring:** SLOs are tied to specific services, applications, or infrastructure entities tracked by the knowledge graph
|
||||
- **RCA workbench integration:** The **Open RCA workbench** button enables deep-linking to pre-filtered troubleshooting views
|
||||
- **Knowledge graph provenance badge:** SLOs display an "asserts" badge instead of "provisioned" in the UI
|
||||
- **Search expressions:** Define custom search expressions to filter entities in RCA workbench when troubleshooting an SLO breach
|
||||
|
||||
## Before you begin
|
||||
|
||||
To create a knowledge graph SLO using Terraform, you need to:
|
||||
|
||||
- Configure the knowledge graph and have metrics flowing into Grafana Cloud
|
||||
- [Set up Terraform for the knowledge Graph](../getting-started/)
|
||||
- Possess knowledge of and have experience with defining SLOs, SLIs, SLAs, and error budgets
|
||||
- Have an understanding of PromQL
|
||||
|
||||
## Create a basic knowledge graph SLO
|
||||
|
||||
Create a file named `kg-slo.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
# Basic knowledge graph SLO with entity-centric monitoring
|
||||
resource "grafana_slo" "kg_example" {
|
||||
name = "API Service Availability"
|
||||
description = "SLO managed by knowledge graph for entity-centric monitoring and RCA"
|
||||
|
||||
query {
|
||||
freeform {
|
||||
query = "sum(rate(http_requests_total{code!~\"5..\"}[$__rate_interval])) / sum(rate(http_requests_total[$__rate_interval]))"
|
||||
}
|
||||
type = "freeform"
|
||||
}
|
||||
|
||||
objectives {
|
||||
value = 0.995
|
||||
window = "30d"
|
||||
}
|
||||
|
||||
destination_datasource {
|
||||
uid = "grafanacloud-prom"
|
||||
}
|
||||
|
||||
# Knowledge graph integration labels
|
||||
# The grafana_slo_provenance label triggers knowledge graph-specific behavior:
|
||||
# - Displays "asserts" badge instead of "provisioned"
|
||||
# - Shows "Open RCA workbench" button in the SLO UI
|
||||
# - Enables correlation with knowledge graph entity-centric monitoring
|
||||
label {
|
||||
key = "grafana_slo_provenance"
|
||||
value = "asserts"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "service_name"
|
||||
value = "api-service"
|
||||
}
|
||||
|
||||
# Search expression for RCA workbench
|
||||
# This enables the "Open RCA workbench" button to deep-link with pre-filtered context
|
||||
search_expression = "service=api-service"
|
||||
|
||||
alerting {
|
||||
fastburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "SLO Burn Rate Very High"
|
||||
}
|
||||
annotation {
|
||||
key = "description"
|
||||
value = "Error budget is burning too fast"
|
||||
}
|
||||
}
|
||||
slowburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "SLO Burn Rate High"
|
||||
}
|
||||
annotation {
|
||||
key = "description"
|
||||
value = "Error budget is burning too fast"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configure an SLO with multiple entity labels
|
||||
|
||||
Configure SLOs with multiple entity labels for fine-grained filtering in RCA workbench:
|
||||
|
||||
```terraform
|
||||
# Knowledge graph SLO with comprehensive entity labels
|
||||
resource "grafana_slo" "payment_service" {
|
||||
name = "Payment Service Latency SLO"
|
||||
description = "Latency SLO for payment processing with team and environment context"
|
||||
|
||||
query {
|
||||
freeform {
|
||||
query = "histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket{service=\"payment\"}[$__rate_interval])) by (le)) < 0.5"
|
||||
}
|
||||
type = "freeform"
|
||||
}
|
||||
|
||||
objectives {
|
||||
value = 0.99
|
||||
window = "7d"
|
||||
}
|
||||
|
||||
destination_datasource {
|
||||
uid = "grafanacloud-prom"
|
||||
}
|
||||
|
||||
# Knowledge graph provenance - required for RCA workbench integration
|
||||
label {
|
||||
key = "grafana_slo_provenance"
|
||||
value = "asserts"
|
||||
}
|
||||
|
||||
# Service identification
|
||||
label {
|
||||
key = "service_name"
|
||||
value = "payment-service"
|
||||
}
|
||||
|
||||
# Team ownership
|
||||
label {
|
||||
key = "team_name"
|
||||
value = "payments-team"
|
||||
}
|
||||
|
||||
# Environment
|
||||
label {
|
||||
key = "environment"
|
||||
value = "production"
|
||||
}
|
||||
|
||||
# Business unit
|
||||
label {
|
||||
key = "business_unit"
|
||||
value = "fintech"
|
||||
}
|
||||
|
||||
# Search expression with multiple filters
|
||||
search_expression = "service=payment-service AND environment=production"
|
||||
|
||||
alerting {
|
||||
fastburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "Payment Latency Critical"
|
||||
}
|
||||
annotation {
|
||||
key = "description"
|
||||
value = "Payment service P99 latency exceeding SLO - immediate attention required"
|
||||
}
|
||||
annotation {
|
||||
key = "runbook_url"
|
||||
value = "https://docs.example.com/runbooks/payment-latency"
|
||||
}
|
||||
}
|
||||
slowburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "Payment Latency Warning"
|
||||
}
|
||||
annotation {
|
||||
key = "description"
|
||||
value = "Payment service experiencing elevated latency"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configure a Kubernetes service SLO
|
||||
|
||||
Configure knowledge graph SLOs for Kubernetes services with Pod and namespace context:
|
||||
|
||||
```terraform
|
||||
# Knowledge graph SLO for Kubernetes service
|
||||
resource "grafana_slo" "k8s_frontend" {
|
||||
name = "Frontend Service Availability"
|
||||
description = "Availability SLO for frontend service in Kubernetes"
|
||||
|
||||
query {
|
||||
freeform {
|
||||
query = "sum(rate(http_requests_total{namespace=\"frontend\",code!~\"5..\"}[$__rate_interval])) / sum(rate(http_requests_total{namespace=\"frontend\"}[$__rate_interval]))"
|
||||
}
|
||||
type = "freeform"
|
||||
}
|
||||
|
||||
objectives {
|
||||
value = 0.999
|
||||
window = "30d"
|
||||
}
|
||||
|
||||
destination_datasource {
|
||||
uid = "grafanacloud-prom"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "grafana_slo_provenance"
|
||||
value = "asserts"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "service_name"
|
||||
value = "frontend"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "namespace"
|
||||
value = "frontend"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "cluster"
|
||||
value = "prod-us-west-2"
|
||||
}
|
||||
|
||||
# Search expression targeting Kubernetes entities
|
||||
search_expression = "namespace=frontend AND cluster=prod-us-west-2"
|
||||
|
||||
alerting {
|
||||
fastburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "Frontend Service Critical"
|
||||
}
|
||||
annotation {
|
||||
key = "description"
|
||||
value = "Frontend service availability below SLO"
|
||||
}
|
||||
annotation {
|
||||
key = "severity"
|
||||
value = "critical"
|
||||
}
|
||||
}
|
||||
slowburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "Frontend Service Degraded"
|
||||
}
|
||||
annotation {
|
||||
key = "description"
|
||||
value = "Frontend service showing signs of degradation"
|
||||
}
|
||||
annotation {
|
||||
key = "severity"
|
||||
value = "warning"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configure an API endpoint-specific SLO
|
||||
|
||||
Configure knowledge graph SLOs for specific API endpoints with request context:
|
||||
|
||||
```terraform
|
||||
# Knowledge graph SLO for critical API endpoint
|
||||
resource "grafana_slo" "checkout_api" {
|
||||
name = "Checkout API Availability"
|
||||
description = "Availability SLO for /api/checkout endpoint"
|
||||
|
||||
query {
|
||||
freeform {
|
||||
query = "sum(rate(http_requests_total{path=\"/api/checkout\",code!~\"5..\"}[$__rate_interval])) / sum(rate(http_requests_total{path=\"/api/checkout\"}[$__rate_interval]))"
|
||||
}
|
||||
type = "freeform"
|
||||
}
|
||||
|
||||
objectives {
|
||||
value = 0.9999
|
||||
window = "30d"
|
||||
}
|
||||
|
||||
destination_datasource {
|
||||
uid = "grafanacloud-prom"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "grafana_slo_provenance"
|
||||
value = "asserts"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "service_name"
|
||||
value = "checkout-service"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "endpoint"
|
||||
value = "/api/checkout"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "criticality"
|
||||
value = "high"
|
||||
}
|
||||
|
||||
# Search expression with endpoint context
|
||||
search_expression = "service=checkout-service AND path=/api/checkout"
|
||||
|
||||
alerting {
|
||||
fastburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "Checkout API Critical Failure"
|
||||
}
|
||||
annotation {
|
||||
key = "description"
|
||||
value = "Checkout API experiencing high error rates - revenue impact"
|
||||
}
|
||||
annotation {
|
||||
key = "severity"
|
||||
value = "critical"
|
||||
}
|
||||
annotation {
|
||||
key = "alert_priority"
|
||||
value = "P0"
|
||||
}
|
||||
}
|
||||
slowburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "Checkout API Degradation"
|
||||
}
|
||||
annotation {
|
||||
key = "description"
|
||||
value = "Checkout API showing elevated error rates"
|
||||
}
|
||||
annotation {
|
||||
key = "severity"
|
||||
value = "warning"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configure a multi-environment SLO
|
||||
|
||||
Manage knowledge graph SLOs across multiple environments using Terraform workspaces or modules:
|
||||
|
||||
```terraform
|
||||
# Variable for environment-specific configuration
|
||||
variable "environment" {
|
||||
description = "Environment name"
|
||||
type = string
|
||||
}
|
||||
|
||||
variable "slo_target" {
|
||||
description = "SLO target percentage"
|
||||
type = number
|
||||
}
|
||||
|
||||
# Environment-aware knowledge graph SLO
|
||||
resource "grafana_slo" "api_service" {
|
||||
name = "${var.environment} - API Service Availability"
|
||||
description = "API service availability SLO for ${var.environment} environment"
|
||||
|
||||
query {
|
||||
freeform {
|
||||
query = "sum(rate(http_requests_total{environment=\"${var.environment}\",code!~\"5..\"}[$__rate_interval])) / sum(rate(http_requests_total{environment=\"${var.environment}\"}[$__rate_interval]))"
|
||||
}
|
||||
type = "freeform"
|
||||
}
|
||||
|
||||
objectives {
|
||||
value = var.slo_target
|
||||
window = "30d"
|
||||
}
|
||||
|
||||
destination_datasource {
|
||||
uid = "grafanacloud-prom"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "grafana_slo_provenance"
|
||||
value = "asserts"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "service_name"
|
||||
value = "api-service"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "environment"
|
||||
value = var.environment
|
||||
}
|
||||
|
||||
search_expression = "service=api-service AND environment=${var.environment}"
|
||||
|
||||
alerting {
|
||||
fastburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "${var.environment} API Critical"
|
||||
}
|
||||
annotation {
|
||||
key = "description"
|
||||
value = "API service in ${var.environment} experiencing critical errors"
|
||||
}
|
||||
}
|
||||
slowburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "${var.environment} API Warning"
|
||||
}
|
||||
annotation {
|
||||
key = "description"
|
||||
value = "API service in ${var.environment} showing elevated errors"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Resource reference
|
||||
|
||||
### `grafana_slo` with knowledge graph provenance
|
||||
|
||||
When creating knowledge graph-managed SLOs, the `grafana_slo` resource requires the `grafana_slo_provenance` label set to `asserts` to enable RCA workbench integration.
|
||||
|
||||
#### Required knowledge graph configuration
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ------------------------------ | -------- | ----------- | -------------------------------------------------------------------------------------------------- |
|
||||
| `grafana_slo_provenance` label | `string` | Yes | Must be set to `asserts` to enable knowledge graph-specific features and RCA workbench integration |
|
||||
| `search_expression` | `string` | Recommended | Search expression for filtering entities in RCA workbench |
|
||||
|
||||
#### Key arguments for knowledge graph SLOs
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ------------------------ | -------------- | -------- | ----------------------------------------------------------------- |
|
||||
| `name` | `string` | Yes | The name of the SLO |
|
||||
| `description` | `string` | No | Description of the SLO purpose and scope |
|
||||
| `query` | `object` | Yes | Query configuration defining how SLO is calculated |
|
||||
| `objectives` | `object` | Yes | Target objectives including value and time window |
|
||||
| `destination_datasource` | `object` | Yes | Destination data source for SLO metrics |
|
||||
| `label` | `list(object)` | Yes | Labels for the SLO, must include `grafana_slo_provenance=asserts` |
|
||||
| `search_expression` | `string` | No | Search expression for RCA workbench filtering |
|
||||
| `alerting` | `object` | No | Alerting configuration for fast burn and slow burn alerts |
|
||||
|
||||
#### Query block
|
||||
|
||||
The `query` block supports the following:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ---------- | -------- | -------- | --------------------------------------------------------- |
|
||||
| `type` | `string` | Yes | Query type, typically `freeform` for knowledge graph SLOs |
|
||||
| `freeform` | `object` | Yes | Freeform query configuration |
|
||||
|
||||
The `freeform` block supports:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ------- | -------- | -------- | -------------------------------- |
|
||||
| `query` | `string` | Yes | PromQL query for SLO calculation |
|
||||
|
||||
#### Objectives block
|
||||
|
||||
The `objectives` block supports the following:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| -------- | -------- | -------- | --------------------------------------------------- |
|
||||
| `value` | `number` | Yes | Target SLO value (for example, 0.995 for 99.5%) |
|
||||
| `window` | `string` | Yes | Time window for SLO evaluation (for example, "30d") |
|
||||
|
||||
#### Label block
|
||||
|
||||
Each `label` block supports the following:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ------- | -------- | -------- | ----------- |
|
||||
| `key` | `string` | Yes | Label key |
|
||||
| `value` | `string` | Yes | Label value |
|
||||
|
||||
**Required label for knowledge graph SLOs:**
|
||||
|
||||
- `grafana_slo_provenance` = `asserts` (enables knowledge graph features)
|
||||
|
||||
**Recommended labels for entity tracking:**
|
||||
|
||||
- `service_name` - Name of the service
|
||||
- `team_name` - Team responsible for the service
|
||||
- `environment` - Environment (prod, staging, development)
|
||||
- `namespace` - Kubernetes namespace
|
||||
- `cluster` - Kubernetes cluster name
|
||||
|
||||
<!-- vale Grafana.Gerunds = NO -->
|
||||
|
||||
#### Alerting block
|
||||
|
||||
The `alerting` block supports the following:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ---------- | -------- | -------- | ---------------------------------- |
|
||||
| `fastburn` | `object` | No | Fast burn rate alert configuration |
|
||||
| `slowburn` | `object` | No | Slow burn rate alert configuration |
|
||||
|
||||
Each alert block (`fastburn`, `slowburn`) supports:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ------------ | -------------- | -------- | ------------------------------- |
|
||||
| `annotation` | `list(object)` | No | Annotations to add to the alert |
|
||||
|
||||
Each `annotation` block supports:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ------- | -------- | -------- | ---------------- |
|
||||
| `key` | `string` | Yes | Annotation key |
|
||||
| `value` | `string` | Yes | Annotation value |
|
||||
|
||||
Common annotation keys:
|
||||
|
||||
- `name` - Alert name
|
||||
- `description` - Alert description
|
||||
- `severity` - Alert severity level
|
||||
- `runbook_url` - Link to runbook documentation
|
||||
<!-- vale Grafana.Gerunds = YES -->
|
||||
|
||||
#### Example
|
||||
|
||||
```terraform
|
||||
resource "grafana_slo" "kg_example" {
|
||||
name = "My Service SLO"
|
||||
description = "SLO with knowledge graph RCA integration"
|
||||
|
||||
query {
|
||||
freeform {
|
||||
query = "sum(rate(http_requests_total{code!~\"5..\"}[$__rate_interval])) / sum(rate(http_requests_total[$__rate_interval]))"
|
||||
}
|
||||
type = "freeform"
|
||||
}
|
||||
|
||||
objectives {
|
||||
value = 0.995
|
||||
window = "30d"
|
||||
}
|
||||
|
||||
destination_datasource {
|
||||
uid = "grafanacloud-prom"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "grafana_slo_provenance"
|
||||
value = "asserts"
|
||||
}
|
||||
|
||||
label {
|
||||
key = "service_name"
|
||||
value = "my-service"
|
||||
}
|
||||
|
||||
search_expression = "service=my-service"
|
||||
|
||||
alerting {
|
||||
fastburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "SLO Fast Burn"
|
||||
}
|
||||
}
|
||||
slowburn {
|
||||
annotation {
|
||||
key = "name"
|
||||
value = "SLO Slow Burn"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best practices
|
||||
|
||||
Follow these best practices when setting knowledge graph SLOs.
|
||||
|
||||
### Use the knowledge graph provenance label
|
||||
|
||||
- Always include the `grafana_slo_provenance` label with value `asserts` for knowledge graph-managed SLOs
|
||||
- This label enables the "asserts" badge in the UI instead of "provisioned"
|
||||
- It also enables the **Open RCA workbench** button for troubleshooting SLO breaches
|
||||
|
||||
### Define search expressions
|
||||
|
||||
- Define meaningful search expressions that filter relevant entities in RCA workbench
|
||||
- The search expression defines which entities populate RCA workbench when you troubleshoot an SLO breach
|
||||
- Use entity attributes like service name, environment, namespace, and cluster
|
||||
- Combine multiple filters with `AND` operators for precise filtering
|
||||
- Test search expressions in RCA workbench before codifying them in Terraform
|
||||
|
||||
### Add entity labels
|
||||
|
||||
- Add descriptive labels to track service ownership, environment, and criticality
|
||||
- Use consistent label naming conventions across all SLOs
|
||||
- Include team names to enable quick identification of ownership
|
||||
- Tag critical business services with appropriate labels
|
||||
|
||||
### Set SLO targets
|
||||
|
||||
- Set realistic SLO targets based on service requirements and capabilities
|
||||
- Use higher targets (0.999+) for critical user-facing services
|
||||
- Consider different targets for different environments (production vs staging)
|
||||
- Review and adjust targets based on actual service performance
|
||||
|
||||
### Add alert annotations
|
||||
|
||||
- Add comprehensive descriptions to help on-call engineers understand the alert
|
||||
- Include runbook URLs in annotations for quick access to troubleshooting guides
|
||||
- Set appropriate severity levels (critical, warning) based on business impact
|
||||
- Customize alert names to clearly identify the affected service and issue
|
||||
|
||||
### Configure queries
|
||||
|
||||
- Use PromQL queries that accurately represent service health
|
||||
- Exclude expected error codes, such as 404, from error calculations when appropriate
|
||||
- Leverage rate intervals with `$__rate_interval` for dynamic time range support
|
||||
- Test queries in Grafana before adding them to Terraform configurations
|
||||
|
||||
### Set compliance windows
|
||||
|
||||
- Use 30-day windows for production SLOs to align with monthly reporting
|
||||
- Consider shorter windows (7d) for development or testing environments
|
||||
- Ensure compliance windows align with business requirements and error budget policies
|
||||
|
||||
## Verify the configuration
|
||||
|
||||
After applying the Terraform configuration, verify that:
|
||||
|
||||
- SLOs are created in your Grafana Cloud stack
|
||||
- SLOs appear in **Observability > SLO** with the "asserts" badge
|
||||
- The **Open RCA workbench** button is visible when you expand **Objective** for an SLO
|
||||
- You can select a time range in the **Error Budget Burndown** panel and click **Open in RCA workbench**
|
||||
- Search expressions correctly filter entities in RCA workbench
|
||||
- Fast burn and slow burn alerts are configured with appropriate thresholds
|
||||
- Labels are correctly applied and visible in the SLO details
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Follow these troubleshooting steps if you experience issues setting knowledge graph SLOs.
|
||||
|
||||
### SLO shows "provisioned" instead of "asserts" badge
|
||||
|
||||
Ensure the `grafana_slo_provenance` label is set to `asserts`:
|
||||
|
||||
```terraform
|
||||
label {
|
||||
key = "grafana_slo_provenance"
|
||||
value = "asserts"
|
||||
}
|
||||
```
|
||||
|
||||
### Open RCA workbench button not appearing
|
||||
|
||||
- Verify the `search_expression` field is populated
|
||||
- The **Open RCA workbench** button appears after you have added a search expression in the **RCA workbench Context** section
|
||||
- Ensure the search expression uses valid entity attributes
|
||||
- Check that the knowledge graph is properly configured and receiving data
|
||||
|
||||
### Alerts not triggering
|
||||
|
||||
- Verify the PromQL query returns valid results in Grafana
|
||||
- Check that the destination data source is correctly configured
|
||||
- Ensure alerting blocks are properly defined with annotations
|
||||
|
||||
## Related documentation
|
||||
|
||||
- [Create and manage knowledge graph SLOs](/docs/grafana-cloud/knowledge-graph/configure/manage-slos/)
|
||||
- [Troubleshoot an SLO breach with the knowledge graph](/docs/grafana-cloud/knowledge-graph/troubleshoot-infra-apps/slos/)
|
||||
- [Get started with Terraform for the knowledge graph](../getting-started/)
|
||||
- [Introduction to Grafana SLO](/docs/grafana-cloud/alerting-and-irm/slo/introduction/)
|
||||
- [Configure notifications in the knowledge graph](/docs/grafana-cloud/knowledge-graph/configure/notifications/)
|
||||
@@ -0,0 +1,290 @@
|
||||
---
|
||||
description: Configure log correlation for Knowledge Graph using Terraform
|
||||
menuTitle: Log configurations
|
||||
title: Configure log correlation using Terraform
|
||||
weight: 500
|
||||
keywords:
|
||||
- Terraform
|
||||
- Knowledge Graph
|
||||
- Log Configuration
|
||||
- Log Correlation
|
||||
- Loki
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/log-configurations/
|
||||
---
|
||||
|
||||
# Configure log correlation using Terraform
|
||||
|
||||
Log configurations in [Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) allow you to define how log data is queried and correlated with entities. You can specify data sources, entity matching rules, label mappings, and filtering options for spans and traces.
|
||||
|
||||
For information about configuring log correlation in the Knowledge Graph UI, refer to [Configure logs correlation](/docs/grafana-cloud/knowledge-graph/configure/logs-correlation/).
|
||||
|
||||
## Basic log configuration
|
||||
|
||||
Create a file named `log-configs.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
# Basic log configuration for services
|
||||
resource "grafana_asserts_log_config" "production" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "production"
|
||||
priority = 1000
|
||||
default_config = false
|
||||
data_source_uid = "grafanacloud-logs"
|
||||
error_label = "error"
|
||||
|
||||
match {
|
||||
property = "asserts_entity_type"
|
||||
op = "EQUALS"
|
||||
values = ["Service"]
|
||||
}
|
||||
|
||||
match {
|
||||
property = "environment"
|
||||
op = "EQUALS"
|
||||
values = ["production", "staging"]
|
||||
}
|
||||
|
||||
entity_property_to_log_label_mapping = {
|
||||
"otel_namespace" = "service_namespace"
|
||||
"otel_service" = "service_name"
|
||||
"environment" = "env"
|
||||
"site" = "region"
|
||||
}
|
||||
|
||||
filter_by_span_id = true
|
||||
filter_by_trace_id = true
|
||||
}
|
||||
```
|
||||
|
||||
## Log configuration with multiple match rules
|
||||
|
||||
Configure log correlation with multiple entity matching criteria:
|
||||
|
||||
```terraform
|
||||
# Development environment log configuration
|
||||
resource "grafana_asserts_log_config" "development" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "development"
|
||||
priority = 2000
|
||||
default_config = true
|
||||
data_source_uid = "elasticsearch-dev"
|
||||
error_label = "error"
|
||||
|
||||
match {
|
||||
property = "asserts_entity_type"
|
||||
op = "EQUALS"
|
||||
values = ["Service"]
|
||||
}
|
||||
|
||||
match {
|
||||
property = "environment"
|
||||
op = "EQUALS"
|
||||
values = ["development", "testing"]
|
||||
}
|
||||
|
||||
match {
|
||||
property = "site"
|
||||
op = "EQUALS"
|
||||
values = ["us-east-1"]
|
||||
}
|
||||
|
||||
match {
|
||||
property = "service"
|
||||
op = "EQUALS"
|
||||
values = ["api"]
|
||||
}
|
||||
|
||||
entity_property_to_log_label_mapping = {
|
||||
"otel_namespace" = "service_namespace"
|
||||
"otel_service" = "service_name"
|
||||
"environment" = "env"
|
||||
"site" = "region"
|
||||
"service" = "app"
|
||||
}
|
||||
|
||||
filter_by_span_id = true
|
||||
filter_by_trace_id = true
|
||||
}
|
||||
```
|
||||
|
||||
## Minimal log configuration
|
||||
|
||||
Create a minimal configuration for all entities:
|
||||
|
||||
```terraform
|
||||
# Minimal configuration for all entities
|
||||
resource "grafana_asserts_log_config" "minimal" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "minimal"
|
||||
priority = 3000
|
||||
default_config = false
|
||||
data_source_uid = "loki-minimal"
|
||||
|
||||
match {
|
||||
property = "asserts_entity_type"
|
||||
op = "IS_NOT_NULL"
|
||||
values = []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Advanced log configuration with complex match rules
|
||||
|
||||
Configure logs with multiple operations and advanced match rules:
|
||||
|
||||
```terraform
|
||||
# Advanced configuration with multiple operations
|
||||
resource "grafana_asserts_log_config" "advanced" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "advanced"
|
||||
priority = 1500
|
||||
default_config = false
|
||||
data_source_uid = "loki-advanced"
|
||||
error_label = "level"
|
||||
|
||||
match {
|
||||
property = "service_type"
|
||||
op = "CONTAINS"
|
||||
values = ["web", "api"]
|
||||
}
|
||||
|
||||
match {
|
||||
property = "environment"
|
||||
op = "NOT_EQUALS"
|
||||
values = ["test"]
|
||||
}
|
||||
|
||||
match {
|
||||
property = "team"
|
||||
op = "IS_NOT_NULL"
|
||||
values = []
|
||||
}
|
||||
|
||||
entity_property_to_log_label_mapping = {
|
||||
"service_type" = "type"
|
||||
"team" = "owner"
|
||||
"environment" = "env"
|
||||
"version" = "app_version"
|
||||
}
|
||||
|
||||
filter_by_span_id = true
|
||||
filter_by_trace_id = false
|
||||
}
|
||||
```
|
||||
|
||||
## Resource reference
|
||||
|
||||
### `grafana_asserts_log_config`
|
||||
|
||||
Manage Knowledge Graph log configurations through the Grafana API.
|
||||
|
||||
#### Arguments
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| -------------------------------------- | -------------- | -------- | -------------------------------------------------------------------------------------------- |
|
||||
| `name` | `string` | Yes | The name of the log configuration. This field is immutable and forces recreation if changed. |
|
||||
| `priority` | `number` | Yes | Priority of the log configuration. Higher priority configurations are evaluated first. |
|
||||
| `default_config` | `bool` | Yes | Whether this is the default configuration. Default configurations cannot be deleted. |
|
||||
| `data_source_uid` | `string` | Yes | DataSource UID to be queried (for example, a Loki instance). |
|
||||
| `match` | `list(object)` | No | List of match rules for entity properties. Refer to [match block](#match-block) for details. |
|
||||
| `error_label` | `string` | No | Label name used to identify error logs. |
|
||||
| `entity_property_to_log_label_mapping` | `map(string)` | No | Mapping of entity properties to log labels for correlation. |
|
||||
| `filter_by_span_id` | `bool` | No | Whether to filter logs by span ID for distributed tracing correlation. |
|
||||
| `filter_by_trace_id` | `bool` | No | Whether to filter logs by trace ID for distributed tracing correlation. |
|
||||
|
||||
#### Match block
|
||||
|
||||
Each `match` block supports the following:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ---------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `property` | `string` | Yes | Entity property to match against. |
|
||||
| `op` | `string` | Yes | Operation to use for matching. One of: `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `DOES_NOT_CONTAIN`, `IS_NULL`, `IS_NOT_NULL`. |
|
||||
| `values` | `list(string)` | Yes | Values to match against. Can be empty for `IS_NULL` and `IS_NOT_NULL` operations. |
|
||||
|
||||
#### Example
|
||||
|
||||
```terraform
|
||||
resource "grafana_asserts_log_config" "example" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "example-logs"
|
||||
priority = 1000
|
||||
default_config = false
|
||||
data_source_uid = "loki-prod"
|
||||
error_label = "level"
|
||||
|
||||
match {
|
||||
property = "asserts_entity_type"
|
||||
op = "EQUALS"
|
||||
values = ["Service", "Pod"]
|
||||
}
|
||||
|
||||
entity_property_to_log_label_mapping = {
|
||||
"service" = "app"
|
||||
"namespace" = "k8s_namespace"
|
||||
"environment" = "env"
|
||||
}
|
||||
|
||||
filter_by_span_id = true
|
||||
filter_by_trace_id = true
|
||||
}
|
||||
```
|
||||
|
||||
## Best practices
|
||||
|
||||
### Priority management
|
||||
|
||||
- Assign lower priority numbers to more specific configurations
|
||||
- Higher priority configurations are evaluated first
|
||||
- Use consistent priority ranges for different configuration types
|
||||
- Document the reasoning behind priority assignments
|
||||
|
||||
### Data source configuration
|
||||
|
||||
- Ensure the data source UID matches your actual Loki or log aggregation system
|
||||
- Test data source connectivity before applying configurations
|
||||
- Use descriptive names for log configurations to indicate their purpose
|
||||
- Consider using separate data sources for different environments
|
||||
|
||||
### Label map strategy
|
||||
|
||||
- Map entity properties consistently across all log configurations
|
||||
- Use meaningful log label names that match your logging standards
|
||||
- Document the mapping relationships in configuration comments
|
||||
- Verify that mapped labels exist in your log data
|
||||
|
||||
### Match rules design
|
||||
|
||||
- Start with broad match rules and refine based on needs
|
||||
- Use specific property names that exist in your entity model
|
||||
- Test match rules with sample data before deploying
|
||||
- Combine multiple match rules for precise entity targeting
|
||||
|
||||
### Distributed trace integration
|
||||
|
||||
- Enable `filter_by_span_id` and `filter_by_trace_id` when using OpenTelemetry
|
||||
- Ensure your logs contain the appropriate trace and span ID labels
|
||||
- Use consistent label names for trace IDs across your logging infrastructure
|
||||
- Test trace correlation to verify it works as expected
|
||||
|
||||
## Validation
|
||||
|
||||
After applying the Terraform configuration, verify that:
|
||||
|
||||
- Log configurations are created in your Knowledge Graph instance
|
||||
- Configurations appear in the Knowledge Graph UI under **Observability > Configuration > Logs**
|
||||
- Log correlation works when drilling down from entities
|
||||
- Label mappings correctly translate entity properties to log labels
|
||||
- Match rules properly filter entities
|
||||
- Trace and span ID filtering works for distributed tracing
|
||||
|
||||
## Related documentation
|
||||
|
||||
- [Configure logs correlation in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/logs-correlation/)
|
||||
- [Get started with Terraform for Knowledge Graph](../getting-started/)
|
||||
- [Loki documentation](/docs/loki/latest/)
|
||||
@@ -0,0 +1,224 @@
|
||||
---
|
||||
description: Configure notification alerts for Knowledge Graph using Terraform
|
||||
menuTitle: Notification alerts
|
||||
title: Configure notification alerts using Terraform
|
||||
weight: 200
|
||||
keywords:
|
||||
- Terraform
|
||||
- Knowledge Graph
|
||||
- Notification Alerts
|
||||
- Alert Configuration
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/notification-alerts/
|
||||
---
|
||||
|
||||
# Configure notification alerts using Terraform
|
||||
|
||||
Notification alerts configurations in [Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) allow you to manage how alerts are processed and routed. You can specify match labels to filter alerts, add custom labels, set duration requirements, and control silencing.
|
||||
|
||||
For information about configuring notification alerts in the Knowledge Graph UI, refer to [Configure notifications](/docs/grafana-cloud/knowledge-graph/configure/notifications/).
|
||||
|
||||
## Basic notification alerts configuration
|
||||
|
||||
Create a file named `alert-configs.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
# Basic alert configuration with silencing
|
||||
resource "grafana_asserts_notification_alerts_config" "prometheus_remote_storage_failures" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "PrometheusRemoteStorageFailures"
|
||||
|
||||
match_labels = {
|
||||
alertname = "PrometheusRemoteStorageFailures"
|
||||
alertgroup = "prometheus.alerts"
|
||||
asserts_env = "prod"
|
||||
}
|
||||
|
||||
silenced = true
|
||||
}
|
||||
|
||||
# High severity alert with specific job and context matching
|
||||
resource "grafana_asserts_notification_alerts_config" "error_buildup_notify" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "ErrorBuildupNotify"
|
||||
|
||||
match_labels = {
|
||||
alertname = "ErrorBuildup"
|
||||
job = "acai"
|
||||
asserts_request_type = "inbound"
|
||||
asserts_request_context = "/auth"
|
||||
}
|
||||
|
||||
silenced = false
|
||||
}
|
||||
```
|
||||
|
||||
## Notification alerts with additional labels and duration
|
||||
|
||||
Configure alerts with custom labels and timing requirements:
|
||||
|
||||
```terraform
|
||||
# Alert with additional labels and custom duration
|
||||
resource "grafana_asserts_notification_alerts_config" "payment_test_alert" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "PaymentTestAlert"
|
||||
|
||||
match_labels = {
|
||||
alertname = "PaymentTestAlert"
|
||||
additional_labels = "asserts_severity=~\"critical\""
|
||||
alertgroup = "alex-k8s-integration-test.alerts"
|
||||
}
|
||||
|
||||
alert_labels = {
|
||||
testing = "onetwothree"
|
||||
}
|
||||
|
||||
duration = "5m"
|
||||
silenced = false
|
||||
}
|
||||
```
|
||||
|
||||
## Latency and performance notification alerts
|
||||
|
||||
Monitor and alert on latency and performance issues:
|
||||
|
||||
```terraform
|
||||
# Latency alert for shipping service
|
||||
resource "grafana_asserts_notification_alerts_config" "high_shipping_latency" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "high shipping latency"
|
||||
|
||||
match_labels = {
|
||||
alertname = "LatencyP99ErrorBuildup"
|
||||
job = "shipping"
|
||||
asserts_request_type = "inbound"
|
||||
}
|
||||
|
||||
silenced = false
|
||||
}
|
||||
|
||||
# CPU throttling alert with warning severity
|
||||
resource "grafana_asserts_notification_alerts_config" "cpu_throttling_sustained" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "CPUThrottlingSustained"
|
||||
|
||||
match_labels = {
|
||||
alertname = "CPUThrottlingSustained"
|
||||
additional_labels = "asserts_severity=~\"warning\""
|
||||
}
|
||||
|
||||
silenced = true
|
||||
}
|
||||
```
|
||||
|
||||
## Infrastructure and service notification alerts
|
||||
|
||||
Configure alerts for infrastructure components and services:
|
||||
|
||||
```terraform
|
||||
# Ingress error rate alert
|
||||
resource "grafana_asserts_notification_alerts_config" "ingress_error" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "ingress error"
|
||||
|
||||
match_labels = {
|
||||
alertname = "ErrorRatioBreach"
|
||||
job = "ingress-nginx-controller-metrics"
|
||||
asserts_request_type = "inbound"
|
||||
}
|
||||
|
||||
silenced = false
|
||||
}
|
||||
|
||||
# MySQL Galera cluster alert
|
||||
resource "grafana_asserts_notification_alerts_config" "mysql_galera_not_ready" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "MySQLGaleraNotReady"
|
||||
|
||||
match_labels = {
|
||||
alertname = "MySQLGaleraNotReady"
|
||||
}
|
||||
|
||||
silenced = false
|
||||
}
|
||||
```
|
||||
|
||||
## Resource reference
|
||||
|
||||
### `grafana_asserts_notification_alerts_config`
|
||||
|
||||
Manage Knowledge Graph notification alerts configurations through the Grafana API.
|
||||
|
||||
#### Arguments
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| -------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `name` | `string` | Yes | The name of the notification alerts configuration. This field is immutable and forces recreation if changed. |
|
||||
| `match_labels` | `map(string)` | No | Labels to match for this notification alerts configuration. Used to filter which alerts this configuration applies to. |
|
||||
| `alert_labels` | `map(string)` | No | Labels to add to alerts generated by this notification alerts configuration. |
|
||||
| `duration` | `string` | No | Duration for which the condition must be true before firing (for example, '5m', '30s'). Maps to 'for' in Knowledge Graph API. |
|
||||
| `silenced` | `bool` | No | Whether this notification alerts configuration is silenced. Defaults to `false`. |
|
||||
|
||||
#### Example
|
||||
|
||||
```terraform
|
||||
resource "grafana_asserts_notification_alerts_config" "example" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "ExampleAlert"
|
||||
|
||||
match_labels = {
|
||||
alertname = "HighCPUUsage"
|
||||
job = "monitoring"
|
||||
}
|
||||
|
||||
alert_labels = {
|
||||
severity = "warning"
|
||||
team = "platform"
|
||||
}
|
||||
|
||||
duration = "5m"
|
||||
silenced = false
|
||||
}
|
||||
```
|
||||
|
||||
## Best practices
|
||||
|
||||
### Label management
|
||||
|
||||
- Use specific and meaningful labels in `match_labels` to ensure precise alert filtering
|
||||
- Leverage existing label conventions from your monitoring setup
|
||||
- Consider using `asserts_env` and `asserts_site` labels for multi-environment setups
|
||||
|
||||
### Silence strategy
|
||||
|
||||
- Use the `silenced` parameter for temporary suppression rather than deleting notification alerts configurations
|
||||
- Document the reason for silencing in your Terraform configuration comments
|
||||
- Regularly review silenced configurations to ensure they're still needed
|
||||
|
||||
### Duration configuration
|
||||
|
||||
- Set appropriate duration values based on your alerting requirements
|
||||
- Consider the nature of the monitored condition when choosing duration
|
||||
- Use consistent duration formats across similar alert types
|
||||
|
||||
## Validation
|
||||
|
||||
After applying the Terraform configuration, verify that:
|
||||
|
||||
- Notification alerts configurations are created in your Knowledge Graph instance
|
||||
- Configurations appear in the Knowledge Graph UI under **Observability > Rules > Notify**
|
||||
- Match labels correctly filter the intended alerts
|
||||
- Custom labels are properly applied to generated alerts
|
||||
|
||||
## Related documentation
|
||||
|
||||
- [Configure notifications in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/notifications/)
|
||||
- [Get started with Terraform for Knowledge Graph](../getting-started/)
|
||||
- [Configure alerts in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/alerts/)
|
||||
@@ -0,0 +1,308 @@
|
||||
---
|
||||
description: Configure suppressed assertions for Knowledge Graph using Terraform
|
||||
menuTitle: Suppressed assertions
|
||||
title: Configure suppressed assertions using Terraform
|
||||
weight: 300
|
||||
keywords:
|
||||
- Terraform
|
||||
- Knowledge Graph
|
||||
- Suppressed Assertions
|
||||
- Alert Suppression
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/suppressed-assertions/
|
||||
---
|
||||
|
||||
# Configure suppressed assertions using Terraform
|
||||
|
||||
Suppressed assertions configurations allow you to disable specific alerts or assertions based on label matching in [Knowledge Graph](/docs/grafana-cloud/knowledge-graph/). This is useful for maintenance windows, test environments, or when you want to temporarily suppress certain types of alerts.
|
||||
|
||||
For information about suppressing insights in the Knowledge Graph UI, refer to [Suppress insights](/docs/grafana-cloud/knowledge-graph/troubleshoot-infra-apps/suppress-insights/).
|
||||
|
||||
## Basic suppressed assertions configuration
|
||||
|
||||
Create a file named `suppressed-assertions.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
# Basic suppressed alert configuration for maintenance
|
||||
resource "grafana_asserts_suppressed_assertions_config" "maintenance_window" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "MaintenanceWindow"
|
||||
|
||||
match_labels = {
|
||||
service = "api-service"
|
||||
maintenance = "true"
|
||||
}
|
||||
}
|
||||
|
||||
# Suppress specific alertname during deployment
|
||||
resource "grafana_asserts_suppressed_assertions_config" "deployment_suppression" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "DeploymentSuppression"
|
||||
|
||||
match_labels = {
|
||||
alertname = "HighLatency"
|
||||
job = "web-service"
|
||||
env = "staging"
|
||||
}
|
||||
}
|
||||
|
||||
# Suppress alerts for specific test environment
|
||||
resource "grafana_asserts_suppressed_assertions_config" "test_environment_suppression" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "TestEnvironmentSuppression"
|
||||
|
||||
match_labels = {
|
||||
alertgroup = "test.alerts"
|
||||
environment = "test"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Service-specific suppression configurations
|
||||
|
||||
Suppress alerts for specific services during maintenance or operational activities:
|
||||
|
||||
```terraform
|
||||
# Suppress alerts for specific services during maintenance
|
||||
resource "grafana_asserts_suppressed_assertions_config" "api_service_maintenance" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "APIServiceMaintenance"
|
||||
|
||||
match_labels = {
|
||||
service = "api-gateway"
|
||||
job = "api-gateway"
|
||||
maintenance = "scheduled"
|
||||
}
|
||||
}
|
||||
|
||||
# Suppress database alerts during backup operations
|
||||
resource "grafana_asserts_suppressed_assertions_config" "database_backup" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "DatabaseBackupSuppression"
|
||||
|
||||
match_labels = {
|
||||
service = "postgresql"
|
||||
job = "postgres-exporter"
|
||||
backup_mode = "active"
|
||||
}
|
||||
}
|
||||
|
||||
# Suppress monitoring system alerts during updates
|
||||
resource "grafana_asserts_suppressed_assertions_config" "monitoring_update" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "MonitoringSystemUpdate"
|
||||
|
||||
match_labels = {
|
||||
service = "prometheus"
|
||||
job = "prometheus"
|
||||
update = "in_progress"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Environment and team-based suppression
|
||||
|
||||
Create suppression rules based on environment or team:
|
||||
|
||||
```terraform
|
||||
# Suppress all alerts for development environment
|
||||
resource "grafana_asserts_suppressed_assertions_config" "dev_environment" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "DevelopmentEnvironmentSuppression"
|
||||
|
||||
match_labels = {
|
||||
environment = "development"
|
||||
team = "platform"
|
||||
}
|
||||
}
|
||||
|
||||
# Suppress alerts for specific team during their maintenance window
|
||||
resource "grafana_asserts_suppressed_assertions_config" "team_maintenance" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "TeamMaintenanceWindow"
|
||||
|
||||
match_labels = {
|
||||
team = "backend"
|
||||
maintenance = "team_scheduled"
|
||||
timezone = "UTC"
|
||||
}
|
||||
}
|
||||
|
||||
# Suppress alerts for staging environment during testing
|
||||
resource "grafana_asserts_suppressed_assertions_config" "staging_testing" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "StagingTestingSuppression"
|
||||
|
||||
match_labels = {
|
||||
environment = "staging"
|
||||
testing = "automated"
|
||||
job = "integration-tests"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Alert type and severity-based suppression
|
||||
|
||||
Suppress alerts based on their type or severity:
|
||||
|
||||
```terraform
|
||||
# Suppress low severity alerts during business hours
|
||||
resource "grafana_asserts_suppressed_assertions_config" "low_severity_business_hours" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "LowSeverityBusinessHours"
|
||||
|
||||
match_labels = {
|
||||
severity = "warning"
|
||||
timezone = "business_hours"
|
||||
}
|
||||
}
|
||||
|
||||
# Suppress specific alert types during known issues
|
||||
resource "grafana_asserts_suppressed_assertions_config" "known_issue_suppression" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "KnownIssueSuppression"
|
||||
|
||||
match_labels = {
|
||||
alertname = "HighMemoryUsage"
|
||||
service = "legacy-service"
|
||||
issue_id = "LEG-123"
|
||||
}
|
||||
}
|
||||
|
||||
# Suppress infrastructure alerts during planned maintenance
|
||||
resource "grafana_asserts_suppressed_assertions_config" "infrastructure_maintenance" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "InfrastructureMaintenance"
|
||||
|
||||
match_labels = {
|
||||
alertgroup = "infrastructure.alerts"
|
||||
maintenance_type = "planned"
|
||||
affected_services = "all"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Complex multi-label suppression
|
||||
|
||||
Define complex suppression rules with multiple labels:
|
||||
|
||||
```terraform
|
||||
# Complex suppression for multi-service deployments
|
||||
resource "grafana_asserts_suppressed_assertions_config" "multi_service_deployment" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "MultiServiceDeploymentSuppression"
|
||||
|
||||
match_labels = {
|
||||
deployment_id = "deploy-2024-01-15"
|
||||
services = "api,worker,frontend"
|
||||
environment = "production"
|
||||
deployment_type = "blue_green"
|
||||
}
|
||||
}
|
||||
|
||||
# Suppress alerts for specific cluster during maintenance
|
||||
resource "grafana_asserts_suppressed_assertions_config" "cluster_maintenance" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "ClusterMaintenanceSuppression"
|
||||
|
||||
match_labels = {
|
||||
cluster = "production-cluster-1"
|
||||
maintenance = "cluster_upgrade"
|
||||
affected_nodes = "all"
|
||||
estimated_duration = "2h"
|
||||
}
|
||||
}
|
||||
|
||||
# Suppress alerts for specific region during network issues
|
||||
resource "grafana_asserts_suppressed_assertions_config" "regional_network_issue" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "RegionalNetworkIssueSuppression"
|
||||
|
||||
match_labels = {
|
||||
region = "us-west-2"
|
||||
issue_type = "network"
|
||||
affected_services = "external_dependencies"
|
||||
incident_id = "NET-456"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Resource reference
|
||||
|
||||
### `grafana_asserts_suppressed_assertions_config`
|
||||
|
||||
Manage Knowledge Graph suppressed assertions configurations through the Grafana API.
|
||||
|
||||
#### Arguments
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| -------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
|
||||
| `name` | `string` | Yes | The name of the suppressed assertions configuration. This field is immutable and forces recreation if changed. |
|
||||
| `match_labels` | `map(string)` | No | Labels to match for this suppressed assertions configuration. Used to determine which alerts should be suppressed. |
|
||||
|
||||
#### Example
|
||||
|
||||
```terraform
|
||||
resource "grafana_asserts_suppressed_assertions_config" "example" {
|
||||
provider = grafana.asserts
|
||||
|
||||
name = "ExampleSuppression"
|
||||
|
||||
match_labels = {
|
||||
alertname = "TestAlert"
|
||||
env = "development"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best practices
|
||||
|
||||
### Suppression strategy
|
||||
|
||||
- Use suppression rules for temporary situations rather than permanent solutions
|
||||
- Document the reason for suppression in your Terraform configuration comments
|
||||
- Set expiration dates or reminders to review suppression rules
|
||||
- Prefer fixing alert thresholds over suppressing recurring false positives
|
||||
|
||||
### Label match rules
|
||||
|
||||
- Be specific with match labels to avoid suppressing unintended alerts
|
||||
- Test suppression rules in non-production environments first
|
||||
- Use descriptive names that indicate the purpose and scope of the suppression
|
||||
- Include relevant context in labels (for example, incident IDs, maintenance windows)
|
||||
|
||||
### Lifecycle management
|
||||
|
||||
- Regularly review active suppression rules to ensure they're still needed
|
||||
- Remove or update suppression rules after maintenance windows or deployments
|
||||
- Use version control to track when suppression rules were added and why
|
||||
- Consider using time-based automation to enable or disable suppression rules
|
||||
|
||||
## Validation
|
||||
|
||||
After applying the Terraform configuration, verify that:
|
||||
|
||||
- Suppressed assertions configurations are active in your Knowledge Graph instance
|
||||
- Configurations appear in the Knowledge Graph UI under **Observability > Rules > Suppress**
|
||||
- Matching alerts are properly suppressed
|
||||
- Suppression rules don't affect unintended alerts
|
||||
|
||||
## Related documentation
|
||||
|
||||
- [Suppress insights in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/troubleshoot-infra-apps/suppress-insights/)
|
||||
- [Get started with Terraform for Knowledge Graph](../getting-started/)
|
||||
- [Configure notifications](/docs/grafana-cloud/knowledge-graph/configure/notifications/)
|
||||
@@ -0,0 +1,355 @@
|
||||
---
|
||||
description: Configure thresholds for Knowledge Graph using Terraform
|
||||
menuTitle: Thresholds
|
||||
title: Configure thresholds using Terraform
|
||||
weight: 600
|
||||
keywords:
|
||||
- Terraform
|
||||
- Knowledge Graph
|
||||
- Thresholds
|
||||
- Request Thresholds
|
||||
- Resource Thresholds
|
||||
- Health Thresholds
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/thresholds/
|
||||
---
|
||||
|
||||
# Configure thresholds using Terraform
|
||||
|
||||
Threshold configurations in [Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) allow you to define custom thresholds for request, resource, and health assertions. These configurations help you set specific limits and conditions for monitoring your services and infrastructure.
|
||||
|
||||
For information about managing thresholds in the Knowledge Graph UI, refer to [Manage thresholds](/docs/grafana-cloud/knowledge-graph/configure/manage-thresholds/).
|
||||
|
||||
## Basic threshold configuration
|
||||
|
||||
Create a file named `thresholds.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
# Basic threshold configuration with all three types
|
||||
resource "grafana_asserts_thresholds" "basic" {
|
||||
provider = grafana.asserts
|
||||
|
||||
request_thresholds = [{
|
||||
entity_name = "payment-service"
|
||||
assertion_name = "ErrorRatioBreach"
|
||||
request_type = "inbound"
|
||||
request_context = "/charge"
|
||||
value = 0.01
|
||||
}]
|
||||
|
||||
resource_thresholds = [{
|
||||
assertion_name = "Saturation"
|
||||
resource_type = "container"
|
||||
container_name = "worker"
|
||||
source = "metrics"
|
||||
severity = "warning"
|
||||
value = 75
|
||||
}]
|
||||
|
||||
health_thresholds = [{
|
||||
assertion_name = "ServiceDown"
|
||||
expression = "up < 1"
|
||||
entity_type = "Service"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
## Request threshold configurations
|
||||
|
||||
Configure thresholds for different service request types and contexts:
|
||||
|
||||
```terraform
|
||||
# Multiple request thresholds for different services
|
||||
resource "grafana_asserts_thresholds" "request_thresholds" {
|
||||
provider = grafana.asserts
|
||||
|
||||
request_thresholds = [
|
||||
{
|
||||
entity_name = "api-service"
|
||||
assertion_name = "ErrorRatioBreach"
|
||||
request_type = "inbound"
|
||||
request_context = "/api/v1/users"
|
||||
value = 0.02
|
||||
},
|
||||
{
|
||||
entity_name = "api-service"
|
||||
assertion_name = "LatencyP99ErrorBuildup"
|
||||
request_type = "inbound"
|
||||
request_context = "/api/v1/orders"
|
||||
value = 500
|
||||
},
|
||||
{
|
||||
entity_name = "payment-gateway"
|
||||
assertion_name = "RequestRateAnomaly"
|
||||
request_type = "outbound"
|
||||
request_context = "/payment/process"
|
||||
value = 1000
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Resource threshold configurations
|
||||
|
||||
Define resource thresholds for different severity levels:
|
||||
|
||||
```terraform
|
||||
# Resource thresholds for different severity levels
|
||||
resource "grafana_asserts_thresholds" "resource_thresholds" {
|
||||
provider = grafana.asserts
|
||||
|
||||
resource_thresholds = [
|
||||
{
|
||||
assertion_name = "Saturation"
|
||||
resource_type = "container"
|
||||
container_name = "web-server"
|
||||
source = "metrics"
|
||||
severity = "warning"
|
||||
value = 75
|
||||
},
|
||||
{
|
||||
assertion_name = "Saturation"
|
||||
resource_type = "container"
|
||||
container_name = "web-server"
|
||||
source = "metrics"
|
||||
severity = "critical"
|
||||
value = 90
|
||||
},
|
||||
{
|
||||
assertion_name = "ResourceRateBreach"
|
||||
resource_type = "Pod"
|
||||
container_name = "database"
|
||||
source = "logs"
|
||||
severity = "warning"
|
||||
value = 80
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Health threshold configurations
|
||||
|
||||
Configure health checks with Prometheus expressions:
|
||||
|
||||
```terraform
|
||||
# Health thresholds with Prometheus expressions
|
||||
resource "grafana_asserts_thresholds" "health_thresholds" {
|
||||
provider = grafana.asserts
|
||||
|
||||
health_thresholds = [
|
||||
{
|
||||
assertion_name = "ServiceDown"
|
||||
expression = "up{job=\"api-service\"} < 1"
|
||||
entity_type = "Service"
|
||||
},
|
||||
{
|
||||
assertion_name = "HighMemoryUsage"
|
||||
expression = "memory_usage_percent > 85"
|
||||
entity_type = "Service"
|
||||
},
|
||||
{
|
||||
assertion_name = "DatabaseConnectivity"
|
||||
expression = "db_connection_pool_active / db_connection_pool_max > 0.9"
|
||||
entity_type = "Service"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Comprehensive threshold configuration
|
||||
|
||||
Define comprehensive thresholds for production environments:
|
||||
|
||||
```terraform
|
||||
# Production environment with comprehensive thresholds
|
||||
resource "grafana_asserts_thresholds" "production" {
|
||||
provider = grafana.asserts
|
||||
|
||||
request_thresholds = [
|
||||
{
|
||||
entity_name = "frontend"
|
||||
assertion_name = "ErrorRatioBreach"
|
||||
request_type = "inbound"
|
||||
request_context = "/"
|
||||
value = 0.005
|
||||
},
|
||||
{
|
||||
entity_name = "backend-api"
|
||||
assertion_name = "LatencyP99ErrorBuildup"
|
||||
request_type = "inbound"
|
||||
request_context = "/api"
|
||||
value = 200
|
||||
}
|
||||
]
|
||||
|
||||
resource_thresholds = [
|
||||
{
|
||||
assertion_name = "Saturation"
|
||||
resource_type = "container"
|
||||
container_name = "frontend"
|
||||
source = "metrics"
|
||||
severity = "warning"
|
||||
value = 70
|
||||
},
|
||||
{
|
||||
assertion_name = "Saturation"
|
||||
resource_type = "container"
|
||||
container_name = "backend-api"
|
||||
source = "metrics"
|
||||
severity = "critical"
|
||||
value = 85
|
||||
}
|
||||
]
|
||||
|
||||
health_thresholds = [
|
||||
{
|
||||
assertion_name = "ServiceDown"
|
||||
expression = "up < 1"
|
||||
entity_type = "Service"
|
||||
},
|
||||
{
|
||||
assertion_name = "NodeDown"
|
||||
expression = "up{job=\"node-exporter\"} < 1"
|
||||
entity_type = "Service"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Resource reference
|
||||
|
||||
### `grafana_asserts_thresholds`
|
||||
|
||||
Manage Knowledge Graph threshold configurations through the Grafana API. This resource allows you to define custom thresholds for request, resource, and health assertions.
|
||||
|
||||
#### Arguments
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| --------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `request_thresholds` | `list(object)` | No | List of request threshold configurations. Refer to [request thresholds block](#request-thresholds-block) for details. |
|
||||
| `resource_thresholds` | `list(object)` | No | List of resource threshold configurations. Refer to [resource thresholds block](#resource-thresholds-block) for details. |
|
||||
| `health_thresholds` | `list(object)` | No | List of health threshold configurations. Refer to [health thresholds block](#health-thresholds-block) for details. |
|
||||
|
||||
#### Request thresholds block
|
||||
|
||||
Each `request_thresholds` block supports the following:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ----------------- | -------- | -------- | ------------------------------------------------------ |
|
||||
| `entity_name` | `string` | Yes | The name of the entity to apply the threshold to. |
|
||||
| `assertion_name` | `string` | Yes | The name of the assertion to configure. |
|
||||
| `request_type` | `string` | Yes | The type of request (inbound, outbound). |
|
||||
| `request_context` | `string` | Yes | The request context or path to apply the threshold to. |
|
||||
| `value` | `number` | Yes | The threshold value. |
|
||||
|
||||
#### Resource thresholds block
|
||||
|
||||
Each `resource_thresholds` block supports the following:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ---------------- | -------- | -------- | ---------------------------------------------------- |
|
||||
| `assertion_name` | `string` | Yes | The name of the assertion to configure. |
|
||||
| `resource_type` | `string` | Yes | The type of resource (container, Pod, node). |
|
||||
| `container_name` | `string` | Yes | The name of the container to apply the threshold to. |
|
||||
| `source` | `string` | Yes | The source of the metrics (metrics, logs). |
|
||||
| `severity` | `string` | Yes | The severity level (warning, critical). |
|
||||
| `value` | `number` | Yes | The threshold value. |
|
||||
|
||||
#### Health thresholds block
|
||||
|
||||
Each `health_thresholds` block supports the following:
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
| ---------------- | -------- | -------- | ------------------------------------------------------------------------------------ |
|
||||
| `assertion_name` | `string` | Yes | The name of the assertion to configure. |
|
||||
| `expression` | `string` | Yes | The Prometheus expression for the health check. |
|
||||
| `entity_type` | `string` | Yes | Entity type for the health threshold (for example, Service, Pod, Namespace, Volume). |
|
||||
| `alert_category` | `string` | No | Optional alert category label for the health threshold. |
|
||||
|
||||
#### Example
|
||||
|
||||
```terraform
|
||||
resource "grafana_asserts_thresholds" "example" {
|
||||
provider = grafana.asserts
|
||||
|
||||
request_thresholds = [{
|
||||
entity_name = "api-service"
|
||||
assertion_name = "ErrorRatioBreach"
|
||||
request_type = "inbound"
|
||||
request_context = "/api/v1/users"
|
||||
value = 0.02
|
||||
}]
|
||||
|
||||
resource_thresholds = [{
|
||||
assertion_name = "Saturation"
|
||||
resource_type = "container"
|
||||
container_name = "web-server"
|
||||
source = "metrics"
|
||||
severity = "warning"
|
||||
value = 75
|
||||
}]
|
||||
|
||||
health_thresholds = [{
|
||||
assertion_name = "ServiceDown"
|
||||
expression = "up{job=\"api-service\"} < 1"
|
||||
entity_type = "Service"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
## Best practices
|
||||
|
||||
### Threshold configuration management
|
||||
|
||||
- Set appropriate threshold values based on your service level objectives (SLOs)
|
||||
- Use different severity levels (warning, critical) to create escalation paths
|
||||
- Test threshold configurations in non-production environments first
|
||||
- Monitor threshold effectiveness and adjust values based on actual performance data
|
||||
|
||||
### Request threshold best practices
|
||||
|
||||
- Configure request thresholds for critical user-facing endpoints
|
||||
- Set different thresholds for different request types (inbound vs outbound)
|
||||
- Consider request context when setting thresholds for specific API paths
|
||||
- Use error ratio thresholds to catch service degradation early
|
||||
- Review historical performance data to set realistic threshold values
|
||||
|
||||
### Resource threshold best practices
|
||||
|
||||
- Set resource thresholds based on your infrastructure capacity
|
||||
- Use container-specific thresholds for microservices architectures
|
||||
- Configure both warning and critical thresholds for gradual escalation
|
||||
- Monitor resource utilization patterns to set realistic threshold values
|
||||
- Consider seasonal or periodic patterns in resource usage
|
||||
|
||||
### Health threshold best practices
|
||||
|
||||
- Use Prometheus expressions that accurately reflect service health
|
||||
- Test health check expressions independently before applying them
|
||||
- Set up health thresholds for critical dependencies and external services
|
||||
- Use composite expressions for complex health checks
|
||||
- Ensure expressions perform efficiently without causing excessive load
|
||||
|
||||
### Value selection guidelines
|
||||
|
||||
- Start conservative and adjust based on real-world performance
|
||||
- Use percentages (0-1 range) for ratio-based metrics
|
||||
- Use milliseconds for latency thresholds
|
||||
- Document the reasoning behind specific threshold values
|
||||
- Review and update thresholds regularly based on system evolution
|
||||
|
||||
## Validation
|
||||
|
||||
After applying the Terraform configuration, verify that:
|
||||
|
||||
- Threshold configurations are applied in your Knowledge Graph instance
|
||||
- Configurations appear in the Knowledge Graph UI under **Observability > Rules > Threshold**
|
||||
- Request thresholds correctly identify breaches for specified services
|
||||
- Resource thresholds trigger at appropriate severity levels
|
||||
- Health thresholds accurately reflect service status
|
||||
- Threshold values align with your SLO commitments
|
||||
|
||||
## Related documentation
|
||||
|
||||
- [Manage thresholds in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/manage-thresholds/)
|
||||
- [Get started with Terraform for Knowledge Graph](../getting-started/)
|
||||
- [Configure alerts in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/alerts/)
|
||||
@@ -0,0 +1,357 @@
|
||||
---
|
||||
description: Learn how to create Grafana IRM integrations, escalation policies, and on-call schedules in Grafana Cloud using Terraform
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Terraform
|
||||
- Grafana Cloud IRM
|
||||
- OnCall
|
||||
title: Manage Grafana IRM in Grafana Cloud using Terraform
|
||||
weight: 120
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-oncall/
|
||||
---
|
||||
|
||||
# Manage Grafana IRM in Grafana Cloud using Terraform
|
||||
|
||||
Learn how to use Terraform to manage [Grafana IRM](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/) resources.
|
||||
This guide shows you how to connect an integration, configure escalation policies, and add on-call schedules using Terraform.
|
||||
|
||||
To illustrate the use of IRM across multiple teams, this guide features examples with two teams: `Devs` and `SREs`.
|
||||
Additionally, it includes the necessary steps to configure Slack for IRM.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Grafana IRM supports Terraform-based configuration for a limited set of resources, primarily those related to OnCall functionality.
|
||||
These resources use the `grafana_oncall_` naming convention in Terraform. Additional IRM components are not yet configurable via Terraform.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you begin, you should have the following:
|
||||
|
||||
- A Grafana Cloud account, as shown in [Get started](https://grafana.com/docs/grafana-cloud/get-started/)
|
||||
- [Terraform](https://www.terraform.io/downloads) installed on your machine
|
||||
- Administrator permissions in your Grafana instance
|
||||
- (Optional) Administrator permissions in your Slack workspace, if you plan to integrate Slack with Grafana IRM
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
All of the following Terraform configuration files should be saved in the same directory.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Connect Slack to Grafana IRM
|
||||
|
||||
Before including Slack settings in your Terraform setup, you must first configure the Slack integration with Grafana IRM.
|
||||
|
||||
To connect your Slack workspace to Grafana IRM, refer to the [Slack integration for Grafana IRM](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/configure/integrations/irm-slack/) documentation.
|
||||
|
||||
## Configure the Grafana provider
|
||||
|
||||
This Terraform configuration sets up the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when managing resources for Grafana IRM.
|
||||
|
||||
You can reuse a similar setup to the one described in [Creating and managing a Grafana Cloud stack using Terraform](../terraform-cloud-stack/) to set up a service account and a token.
|
||||
|
||||
1. Create a Service account and token in Grafana. To create a new one, refer to [Service account tokens](https://grafana.com/docs/grafana/latest/administration/service-accounts/#service-account-tokens).
|
||||
|
||||
1. Create a file named `main.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
grafana = {
|
||||
source = "grafana/grafana"
|
||||
version = ">= 3.15.3"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "grafana" {
|
||||
alias = "oncall"
|
||||
|
||||
url = "<Stack-URL>"
|
||||
auth = "<Service-account-token>"
|
||||
oncall_url = "<OnCall-URL>"
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<Stack-URL>` with the URL of your Grafana stack
|
||||
- `<Service-account-token>` with the service account token that you created
|
||||
- `<OnCall-URL>` with the API URL found on the **Admin & API** tab of the IRM **Settings** page
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
If the service account has the right permissions, this provider setup also allows you to manage other Grafana resources.
|
||||
{{< /admonition >}}
|
||||
|
||||
### Authentication via OnCall API tokens (deprecated)
|
||||
|
||||
OnCall API tokens are being deprecated.
|
||||
While existing tokens will continue to work, we recommend using
|
||||
[Grafana Cloud service account tokens](https://grafana.com/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/service-accounts/) for all new API authentication.
|
||||
|
||||
{{< collapse title="Authentication via OnCall API tokens" >}}
|
||||
To use an existing OnCall API token:
|
||||
|
||||
1. Log into your Grafana Cloud instance
|
||||
1. Select **Alerts & IRM** > **IRM**
|
||||
1. Click **Settings**, and then select **Admin & API**
|
||||
1. Locate the **Grafana IRM API** section
|
||||
1. View, copy or revoke existing **OnCall API tokens**
|
||||
|
||||
1. Create a file named `main.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
grafana = {
|
||||
source = "grafana/grafana"
|
||||
version = ">= 2.9.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "grafana" {
|
||||
alias = "oncall"
|
||||
|
||||
oncall_access_token = "<OnCall-API-Token>"
|
||||
oncall_url = "<OnCall-URL>"
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<OnCall-API-Token>` with your existing OnCall API Token
|
||||
- `<OnCall-URL>` with the API URL found on the **Admin & API** tab of the IRM **Settings** page
|
||||
{{< /collapse >}}
|
||||
|
||||
## Add on-call schedules
|
||||
|
||||
This Terraform configuration sets up two on-call schedules, `SREs` and `Devs`, using the [`grafana_oncall_schedule` resource](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/oncall_schedule) to define the schedules within Grafana IRM.
|
||||
Additionally, this configuration includes Slack channels to receive notifications for the on-call schedules of each team.
|
||||
|
||||
To learn more about managing on-call schedules, refer to the [On-call schedules documentation](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/manage/on-call-schedules/).
|
||||
|
||||
1. Create two new calendars in your calendar service, one for `Devs` and one for `SREs`
|
||||
|
||||
1. Locate and save the secret iCal URLs.
|
||||
For example, in a Google calendar, these URLs can be found in **Settings > Settings for my calendars > Integrate calendar**
|
||||
|
||||
1. Create a file named `schedule.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
# Name of the Slack channel to notify about on-call schedules for Devs
|
||||
data "grafana_oncall_slack_channel" "Devs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
name = "<Devs-channel-name>"
|
||||
}
|
||||
|
||||
# Name of the Slack channel to notify about on-call schedules for SREs
|
||||
data "grafana_oncall_slack_channel" "SREs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
name = "<SREs-channel-name>"
|
||||
}
|
||||
|
||||
resource "grafana_oncall_schedule" "schedule_Devs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
name = "Devs"
|
||||
type = "ical"
|
||||
ical_url_primary = "<secret-iCal-URL-for-devs-calendar>"
|
||||
slack {
|
||||
channel_id = data.grafana_oncall_slack_channel.Devs.slack_id
|
||||
}
|
||||
}
|
||||
|
||||
resource "grafana_oncall_schedule" "schedule_SREs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
name = "SREs"
|
||||
type = "ical"
|
||||
ical_url_primary = "<secret-iCal-URL-for-SREs-calendar>"
|
||||
slack {
|
||||
channel_id = data.grafana_oncall_slack_channel.SREs.slack_id
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. Replace the following field values:
|
||||
- `<Devs-channel-name>` with name of the Slack channel to notify about on-call schedules for `Devs`
|
||||
- `<SREs-channel-name>` with name of the Slack channel to notify about on-call schedules for `SREs`
|
||||
- `<secret-iCal-URL-for-devs-calendar>` with the secret iCal URL created in the first step for `Devs` Calendar
|
||||
- `<secret-iCal-URL-for-SREs-calendar>` with the secret iCal URL created in the first step for `SREs` Calendar
|
||||
|
||||
## Add escalation chains
|
||||
|
||||
This Terraform configuration creates two escalation chains named `SREs` and `Devs` in Grafana IRM using the [`grafana_oncall_escalation_chain` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/oncall_escalation_chain).
|
||||
The configuration also adds the following three steps to each escalation chain using the [`grafana_oncall_escalation` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/oncall_escalation):
|
||||
|
||||
- Notify users from on-call schedule
|
||||
- Wait for 5 minutes
|
||||
- Notify default Slack channel
|
||||
|
||||
1. Create a file named `escalation-devs.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
resource "grafana_oncall_escalation_chain" "Devs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
name = "Devs"
|
||||
}
|
||||
|
||||
// Notify users from on-call schedule
|
||||
resource "grafana_oncall_escalation" "notify_schedule_step_Devs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
escalation_chain_id = grafana_oncall_escalation_chain.Devs.id
|
||||
type = "notify_on_call_from_schedule"
|
||||
notify_on_call_from_schedule = grafana_oncall_schedule.schedule_Devs.id
|
||||
position = 0
|
||||
}
|
||||
|
||||
// Wait step for 5 Minutes
|
||||
resource "grafana_oncall_escalation" "wait_step_Devs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
escalation_chain_id = grafana_oncall_escalation_chain.Devs.id
|
||||
type = "wait"
|
||||
duration = 300
|
||||
position = 1
|
||||
}
|
||||
|
||||
// Notify default Slack channel step
|
||||
resource "grafana_oncall_escalation" "notify_step_Devs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
escalation_chain_id = grafana_oncall_escalation_chain.Devs.id
|
||||
type = "notify_whole_channel"
|
||||
important = true
|
||||
position = 2
|
||||
}
|
||||
```
|
||||
|
||||
2. Create a file named `escalation-sre.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
resource "grafana_oncall_escalation_chain" "SREs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
name = "SREs"
|
||||
}
|
||||
|
||||
// Notify users from on-call schedule
|
||||
resource "grafana_oncall_escalation" "notify_schedule_step_SREs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
escalation_chain_id = grafana_oncall_escalation_chain.SREs.id
|
||||
type = "notify_on_call_from_schedule"
|
||||
notify_on_call_from_schedule = grafana_oncall_schedule.schedule_SREs.id
|
||||
position = 0
|
||||
}
|
||||
|
||||
// Wait step for 5 Minutes
|
||||
resource "grafana_oncall_escalation" "wait_step_SREs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
escalation_chain_id = grafana_oncall_escalation_chain.SREs.id
|
||||
type = "wait"
|
||||
duration = 300
|
||||
position = 1
|
||||
}
|
||||
|
||||
// Notify default Slack channel step
|
||||
resource "grafana_oncall_escalation" "notify_step_SREs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
escalation_chain_id = grafana_oncall_escalation_chain.SREs.id
|
||||
type = "notify_whole_channel"
|
||||
important = true
|
||||
position = 2
|
||||
}
|
||||
```
|
||||
|
||||
## Connect an integration to Grafana IRM
|
||||
|
||||
This Terraform configuration connects Alertmanager to Grafana IRM using the [`grafana_oncall_integration` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/oncall_integration).
|
||||
It also adds the `Devs` escalation chain as the default route for alerts.
|
||||
|
||||
1. Create a file named `integrations.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
resource "grafana_oncall_integration" "AlertManager" {
|
||||
provider = grafana.oncall
|
||||
|
||||
name = "AlertManager"
|
||||
type = "alertmanager"
|
||||
default_route {
|
||||
escalation_chain_id = grafana_oncall_escalation_chain.Devs.id
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. To configure Alertmanager, refer to [Alertmanager integration for Grafana OnCall](https://grafana.com/docs/grafana-cloud/alerting-and-irm/oncall/integrations/alertmanager/)
|
||||
|
||||
## Set up a route to configure escalation behavior for alert group notifications
|
||||
|
||||
This Terraform configuration sets up a route to the Alertmanager integration using the `grafana_oncall_route` (Resource).
|
||||
This route ensures that notifications for alerts with `\"namespace\" *: *\"ops-.*\"` in the payload are escalated to the `SREs` escalation chain.
|
||||
|
||||
Create a file named `routes.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
resource "grafana_oncall_route" "route_SREs" {
|
||||
provider = grafana.oncall
|
||||
|
||||
integration_id = grafana_oncall_integration.AlertManager.id
|
||||
escalation_chain_id = grafana_oncall_escalation_chain.SREs.id
|
||||
routing_regex = "\"namespace\" *: *\"ops-.*\""
|
||||
position = 0
|
||||
}
|
||||
```
|
||||
|
||||
## Apply the Terraform configuration
|
||||
|
||||
In a terminal, run the following commands from the directory where all of the configuration files are located.
|
||||
|
||||
1. Initialize a working directory containing Terraform configuration files.
|
||||
|
||||
```shell
|
||||
terraform init
|
||||
```
|
||||
|
||||
1. Preview the changes that Terraform will make.
|
||||
|
||||
```shell
|
||||
terraform plan
|
||||
```
|
||||
|
||||
1. Apply the configuration files.
|
||||
|
||||
```shell
|
||||
terraform apply
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
After you apply the changes in the Terraform configurations, you can verify the following:
|
||||
|
||||
- Two new Schedules named `Devs` and `SREs` are created in Grafana IRM:
|
||||
|
||||
|
||||
|
||||
- New Escalation chain named `SREs` is created in Grafana IRM:
|
||||
|
||||
|
||||
|
||||
- New Escalation chain named `Devs` is created in Grafana IRM:
|
||||
|
||||
|
||||
|
||||
- The Alertmanager integration is added and configured with escalation policies:
|
||||
|
||||
|
||||
|
||||
## Conclusion
|
||||
|
||||
In this guide, you learned how to use Terraform to manage Grafana IRM by connecting an integration, configuring escalation policies, and setting up on-call schedules.
|
||||
|
||||
To learn more about managing Grafana Cloud using Terraform, refer to [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
description: Learn how to install plugins in Grafana Cloud using Terraform
|
||||
keywords:
|
||||
- Infrastructure as Code
|
||||
- Quickstart
|
||||
- Grafana Cloud
|
||||
- Terraform
|
||||
- Plugins
|
||||
title: Install plugins in Grafana Cloud using Terraform
|
||||
weight: 300
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-plugins/
|
||||
---
|
||||
|
||||
# Install plugins in Grafana Cloud using Terraform
|
||||
|
||||
This guide shows you how to install plugins in Grafana Cloud using Terraform. For more information about Grafana plugins see [Find and use Grafana plugins](/docs/grafana-cloud/introduction/find-and-use-plugins/).
|
||||
|
||||
## Before you begin
|
||||
|
||||
Before you begin, you should have the following available:
|
||||
|
||||
- A Grafana Cloud account; for more information on setting up a Grafana Cloud account, refer to [Get started](https://grafana.com/docs/grafana-cloud/get-started/).
|
||||
- Terraform installed on your machine; for more information on how to install Terraform, refer to the [Terraform install documentation](https://developer.hashicorp.com/terraform/install).
|
||||
- Administrator permissions in your Grafana instance; for more information on assigning Grafana RBAC roles, refer to [Assign RBAC roles](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control/assign-rbac-roles/).
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
All of the following Terraform configuration files should be saved in the same directory.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Configure the Grafana provider
|
||||
|
||||
Use this Terraform configuration to set up the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide the authentication required to manage plugin resources.
|
||||
|
||||
1. Create a service account and token in Grafana. For more information on creating a service account and token, refer to [Service account tokens](https://grafana.com/docs/grafana/latest/administration/service-accounts/#service-account-tokens). You can also refer to [Creating and managing a Grafana Cloud stack using Terraform](../terraform-cloud-stack/) to set up a service account and a token.
|
||||
|
||||
1. Make sure that the token has the following permissions:
|
||||
|
||||
- `stack-plugins:read`
|
||||
- `stack-plugins:write`
|
||||
- `stack-plugins:delete`
|
||||
|
||||
Next, create a file named `main.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
grafana = {
|
||||
source = "grafana/grafana"
|
||||
version = ">= 4.5.3"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "grafana" {
|
||||
cloud_api_url = "<Stack-URL>"
|
||||
cloud_access_policy_token = "<Service-account-token>"
|
||||
}
|
||||
```
|
||||
|
||||
Replace the following field values:
|
||||
|
||||
- `Stack-URL` with the URL of your Grafana stack, for example `https://my-stack.grafana.net/`
|
||||
- `Service-account-token` with the service account token that you created
|
||||
|
||||
## Create new plugin resource
|
||||
|
||||
Create a file named `plugins.tf` and add the following:
|
||||
|
||||
```terraform
|
||||
resource "grafana_cloud_plugin_installation" "grafana-clock-panel" {
|
||||
stack_slug = "<Your-Stack-Slug>"
|
||||
slug = "grafana-clock-panel"
|
||||
version = "latest"
|
||||
}
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
In this guide, you learned how to install a plugin in Grafana Cloud using Terraform.
|
||||
|
||||
To learn more about plugin installation, refer to [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_plugin_installation).
|
||||
92
docs/sources/as-code/observability-as-code/_index.md
Normal file
92
docs/sources/as-code/observability-as-code/_index.md
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
description: Overview of Observability as code including description, key features, and explanation of benefits.
|
||||
keywords:
|
||||
- observability
|
||||
- configuration
|
||||
- as code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Observability as code
|
||||
weight: 100
|
||||
cards:
|
||||
items:
|
||||
- title: Grafana CLI
|
||||
height: 24
|
||||
href: ./grafana-cli/
|
||||
description: Grafana CLI (`grafanactl`) is a command-line tool designed to simplify interaction with Grafana instances using the new REST APIs. You can authenticate, manage multiple environments, and perform administrative tasks from the terminal. It's suitable for CI/CD pipelines, local development, or free-form tasks.
|
||||
- title: Foundation SDK
|
||||
height: 24
|
||||
href: ./foundation-sdk/
|
||||
description: The Grafana Foundation SDK is a set of tools, types, and libraries that let you define Grafana dashboards and resources using familiar programming languages like Go, TypeScript, Python, Java, and PHP. Use it in conjunction with `grafanactl` to push your programmatically generated resources.
|
||||
- title: JSON schema v2
|
||||
height: 24
|
||||
href: ./schema-v2/
|
||||
description: Grafana dashboards are represented as JSON objects that store metadata, panels, variables, and settings. Observability as Code works with all versions of the JSON model, and it's fully compatible with version 2.
|
||||
- title: Git Sync (private preview)
|
||||
height: 24
|
||||
href: ./provision-resources/intro-git-sync/
|
||||
description: Git Sync lets you store your dashboard files in a GitHub repository and synchronize those changes with your Grafana instance, enabling version control, branching, and pull requests directly from Grafana.
|
||||
- title: File provisioning (private preview)
|
||||
height: 24
|
||||
href: ./provision-resources/
|
||||
description: File provisioning in Grafana lets you include resources, including folders and dashboard JSON files, that are stored in a local file system.
|
||||
title_class: pt-0 lh-1
|
||||
hero:
|
||||
title: Observability as Code
|
||||
description: Using Observability as Code, you can version, automate, and scale Grafana configurations, including dashboards and observability workflows.
|
||||
height: 110
|
||||
level: 1
|
||||
width: 110
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/
|
||||
aliases:
|
||||
- ../observability-as-code/ # /docs/grafana/next/observability-as-code/
|
||||
- ../observability-as-code/get-started/
|
||||
refs:
|
||||
infra-as-code:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/as-code/infrastructure-as-code/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/as-code/infrastructure-as-code/
|
||||
---
|
||||
|
||||
{{< docs/hero-simple key="hero" >}}
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Grafana provides a suite of tools for **Observability as code** to help you manage your Grafana resources programmatically and at scale. This approach lets you define dashboards, data sources, and other configurations in code, enabling version control, automated testing, and reliable deployments through CI/CD pipelines. You can apply code management best practices to your observability resources, and integrate them into existing infrastructure-as-code workflows.
|
||||
|
||||
Historically, managing Grafana as code involved various community and Grafana Labs tools, but lacked a single, cohesive story. Grafana 12 introduces foundational improvements, including new versioned APIs and official tooling, to provide a clearer path forward:
|
||||
|
||||
- This approach requires handling HTTP requests and responses but provides complete control over resource management.
|
||||
- `grafanactl`, Git Sync, and the Foundation SDK are all built on top of these APIs.
|
||||
- To understand Dashboard Schemas accepted by the APIs, refer to the [JSON models documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/).
|
||||
|
||||
## Explore
|
||||
|
||||
{{< card-grid key="cards" type="simple" >}}
|
||||
|
||||
## Additional Observability as code tools
|
||||
|
||||
If you're already using established [Infrastructure as code](ref:infra-as-code) or other configuration management tools, Grafana offers integrations to manage resources within your existing workflows.
|
||||
|
||||
- [Terraform](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/)
|
||||
- Use the Grafana Terraform provider to manage dashboards, alerts, and more.
|
||||
- Understand how to define and deploy resources using HCL/JSON configurations.
|
||||
- [Ansible](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/ansible/)
|
||||
- Learn to use the Grafana Ansible collection to manage Grafana Cloud resources, including folders and cloud stacks.
|
||||
- Write playbooks to automate resource provisioning through the Grafana API.
|
||||
- [Grafana Operator](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/)
|
||||
- Utilize Kubernetes-native management with the Grafana Operator.
|
||||
- Manage dashboards, folders, and data sources via Kubernetes Custom Resources.
|
||||
- Integrate with GitOps workflows for seamless version control and deployment.
|
||||
- [Crossplane](https://github.com/grafana/crossplane-provider-grafana) lets you manage Grafana resources using Kubernetes manifests with the Grafana Crossplane provider.
|
||||
- [Grafonnet](https://github.com/grafana/grafonnet) is a Jsonnet library for generating Grafana dashboard JSON definitions programmatically.
|
||||
@@ -10,6 +10,9 @@ labels:
|
||||
- oss
|
||||
title: Foundation SDK
|
||||
weight: 250
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/foundation-sdk/
|
||||
aliases:
|
||||
- ../../observability-as-code/foundation-sdk/ # /docs/grafana/next/observability-as-code/foundation-sdk/
|
||||
---
|
||||
|
||||
# Get started with the Grafana Foundation SDK
|
||||
@@ -181,7 +184,7 @@ After you've defined your dashboard as code, build the final dashboard represent
|
||||
With the JSON payload, you can:
|
||||
|
||||
- **Manually import:** Paste into Grafana’s dashboard import feature.
|
||||
- **Automate:** Use [Grafana’s API](../../developers/http_api/) or the [Grafana CLI](../grafana-cli/) to programmatically upload the dashboard JSON.
|
||||
- **Automate:** Use [Grafana's API](/docs/grafana/<GRAFANA_VERSION>/developer-resources/api-reference/http-api/) or the [Grafana CLI](../grafana-cli/) to programmatically upload the dashboard JSON.
|
||||
|
||||
## Concepts
|
||||
|
||||
@@ -12,6 +12,9 @@ labels:
|
||||
- oss
|
||||
title: Automate dashboard provisioning with CI/CD
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/foundation-sdk/dashboard-automation/
|
||||
aliases:
|
||||
- ../../../observability-as-code/foundation-sdk/dashboard-automation/ # /docs/grafana/next/observability-as-code/foundation-sdk/dashboard-automation/
|
||||
---
|
||||
|
||||
# Automate dashboard provisioning with CI/CD
|
||||
@@ -30,7 +30,7 @@ cards:
|
||||
title: Manage resources with Grafana CLI
|
||||
title_class: pt-0 lh-1
|
||||
hero:
|
||||
description: Grafana CLI (`grafanactl`) is a command-line tool designed to simplify interaction with Grafana instances. It enables users to authenticate, manage multiple environments, and perform administrative tasks through Grafana’s REST API, all from the terminal. Whether you're automating workflows in CI/CD pipelines or switching between staging and production environments, Grafana CLI provides a flexible and scriptable way to manage your Grafana setup efficiently.
|
||||
description: Grafana CLI (`grafanactl`) is a command-line tool designed to simplify interaction with Grafana instances. It enables users to authenticate, manage multiple environments, and perform administrative tasks through Grafana’s REST API, all from the terminal. Whether you're automating workflows in CI/CD pipelines or switching between staging and production environments, Grafana CLI provides a flexible and scriptable way to manage your Grafana setup efficiently. `grafanactl` works across all environments for Grafana OSS, Enterprise, and Cloud.
|
||||
height: 110
|
||||
level: 1
|
||||
title: Grafana CLI
|
||||
@@ -38,6 +38,9 @@ hero:
|
||||
title: Introduction to Grafana CLI
|
||||
menuTitle: Grafana CLI
|
||||
weight: 130
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/
|
||||
aliases:
|
||||
- ../../observability-as-code/grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/
|
||||
---
|
||||
|
||||
{{< docs/hero-simple key="hero" >}}
|
||||
@@ -13,12 +13,15 @@ labels:
|
||||
- oss
|
||||
title: Manage resources with Grafana CLI
|
||||
weight: 300
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/grafanacli-workflows/
|
||||
aliases:
|
||||
- ../../../observability-as-code/grafana-cli/grafanacli-workflows/ # /docs/grafana/next/observability-as-code/grafana-cli/grafanacli-workflows/
|
||||
---
|
||||
|
||||
# Manage resources with Grafana CLI
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
`grafanactl` is under active development. Command-line flags and subcommands described here may change. This document outlines the target workflows the tool is expected to support.
|
||||
`grafanactl` is under active development. Command-line flags and subcommands described here may change. This document outlines the target workflows the tool is expected to support. You can find a full list of supported commands [in this page](https://grafana.github.io/grafanactl/reference/cli/grafanactl/).
|
||||
{{< /admonition >}}
|
||||
|
||||
## Migrate resources between environments
|
||||
@@ -14,6 +14,9 @@ labels:
|
||||
- oss
|
||||
title: Install Grafana CLI
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/install-grafana-cli/
|
||||
aliases:
|
||||
- ../../../observability-as-code/grafana-cli/install-grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/install-grafana-cli/
|
||||
---
|
||||
|
||||
# Install Grafana CLI
|
||||
@@ -13,6 +13,9 @@ labels:
|
||||
- oss
|
||||
title: Set up Grafana CLI
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/set-up-grafana-cli/
|
||||
aliases:
|
||||
- ../../../observability-as-code/grafana-cli/set-up-grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/set-up-grafana-cli/
|
||||
---
|
||||
|
||||
# Set up Grafana CLI
|
||||
@@ -14,6 +14,9 @@ labels:
|
||||
title: Provision resources and sync dashboards
|
||||
menuTitle: Provision resources
|
||||
weight: 300
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/
|
||||
aliases:
|
||||
- ../../observability-as-code/provision-resources/ # /docs/grafana/next/observability-as-code/provision-resources/
|
||||
---
|
||||
|
||||
# Provision resources and sync dashboards
|
||||
@@ -22,7 +25,7 @@ weight: 300
|
||||
|
||||
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud. Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided. You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9).
|
||||
|
||||
Git Sync and local file provisioning are [experimental features](https://grafana.com/docs/release-life-cycle/) introduced in Grafana v12 for open source and Enterprise editions. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.
|
||||
Git Sync and local file provisioning are [experimental features](https://grafana.com/docs/release-life-cycle/) introduced in Grafana v12 for open source and Enterprise editions available in [nightly releases](https://grafana.com/grafana/download/nightly). Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
@@ -11,6 +11,9 @@ labels:
|
||||
- oss
|
||||
title: Set up file provisioning
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/file-path-setup/
|
||||
aliases:
|
||||
- ../../../observability-as-code/provision-resources/file-path-setup/ # /docs/grafana/next/observability-as-code/provision-resources/file-path-setup/
|
||||
---
|
||||
|
||||
# Set up file provisioning
|
||||
@@ -40,8 +43,7 @@ To set up file sync with local with local files, you need to:
|
||||
Local file provisioning using **Administration** > **Provisioning** will eventually replace the traditional methods Grafana has used for referencing local file systems for dashboard files.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
For production system, we recommend using the `folderFromFilesStructure` capability instead of **Administration** > **Provisioning** to include dashboards from a local file system in your Grafana instance.
|
||||
Refer to [Provision Grafana](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#provision-folders-structure-from-filesystem-to-grafana) for more information.
|
||||
For production systems, use the `folderFromFilesStructure` capability instead of **Administration** > **Provisioning** to include dashboards from a local file system in your Grafana instance. Refer to [Provision Grafana](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#provision-folders-structure-from-filesystem-to-grafana) for more information.
|
||||
{{< /admonition >}}
|
||||
|
||||
### Limitations
|
||||
@@ -125,6 +127,18 @@ The set up process verifies the path and provides an error message if a problem
|
||||
|
||||
### Choose what to synchronize
|
||||
|
||||
#### Synchronization limitations
|
||||
|
||||
Full instance sync is not available in Grafana Cloud.
|
||||
|
||||
In Grafana OSS/Enterprise:
|
||||
|
||||
- If you try to perform a full instance sync with resources that contain alerts or panels, the connection will be blocked.
|
||||
- You won't be able to create new alerts or library panels after setup is completed.
|
||||
- If you opted for full instance sync and want to use alerts and library panels, you'll have to delete the provisioned repository and connect again with folder sync.
|
||||
|
||||
#### Set up synchronization
|
||||
|
||||
Choose to either sync your entire organization resources with external storage, or to sync certain resources to a new Grafana folder (with up to 10 connections).
|
||||
|
||||
- Choose **Sync all resources with external storage** if you want to sync and manage your entire Grafana instance through external storage. With this option, all of your dashboards are synced to that one repository. You can only have one provisioned connection with this selection, and you won't have the option of setting up additional repositories to connect to.
|
||||
@@ -11,6 +11,9 @@ labels:
|
||||
- oss
|
||||
title: Set up Git Sync
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/git-sync-setup/
|
||||
aliases:
|
||||
- ../../../observability-as-code/provision-resources/git-sync-setup/ # /docs/grafana/next/observability-as-code/provision-resources/git-sync-setup/
|
||||
---
|
||||
|
||||
# Set up Git Sync
|
||||
@@ -61,6 +64,8 @@ Refer to [Known limitations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
### Requirements
|
||||
|
||||
To set up Git Sync, you need:
|
||||
|
||||
- Administration rights in your Grafana organization.
|
||||
@@ -128,34 +133,37 @@ To connect your GitHub repository, follow these steps:
|
||||
|
||||
### Choose what to synchronize
|
||||
|
||||
In this step you can decide which elements to synchronize. Keep in mind the available options depend on the status of your Grafana instance.
|
||||
|
||||
- If the instance contains resources in an incompatible data format, you'll have to migrate all the data using instance sync. Folder sync won't be supported.
|
||||
- If there is already another connection using folder sync, instance sync won't be offered.
|
||||
|
||||
#### Synchronization limitations
|
||||
|
||||
Git Sync only supports dashboards and folders. Alerts, panels, and other resources are not supported yet.
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Git Sync only works with specific folders for the moment. Full-instance sync is not currently supported. Refer to [Supported resources](/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync#supported-resources) for more details about which resources you can sync.
|
||||
Refer to [Known limitations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync#known-limitations/) before using Git Sync. Refer to [Supported resources](/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync#supported-resources) for details about which resources you can sync.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
In this step you can decide which elements to synchronize. Keep in mind the available options depend on the status of your GitHub repository. The first time you connect Grafana with a GitHub repository, you need to synchronize with external storage. If you are syncing with a new or empty repository, you won't have an option to migrate dashboards.
|
||||
Full instance sync is not available in Grafana Cloud.
|
||||
|
||||
1. Choose to either sync your entire organization resources with external storage, or to sync certain resources to a new Grafana folder (with up to 10 connections).
|
||||
In Grafana OSS/Enterprise:
|
||||
|
||||
- If you try to perform a full instance sync with resources that contain alerts or panels, Git Sync will block the connection.
|
||||
- You won't be able to create new alerts or library panels after the setup is completed.
|
||||
- If you opted for full instance sync and want to use alerts and library panels, you'll have to delete the synced repository and connect again with folder sync.
|
||||
|
||||
#### Set up synchronization
|
||||
|
||||
To set up synchronization, choose to either sync your entire organization resources with external storage, or to sync certain resources to a new Grafana folder (with up to 10 connections).
|
||||
|
||||
- Choose **Sync all resources with external storage** if you want to sync and manage your entire Grafana instance through external storage. With this option, all of your dashboards are synced to that one repository. You can only have one provisioned connection with this selection, and you won't have the option of setting up additional repositories to connect to.
|
||||
|
||||
- Choose **Sync external storage to new Grafana folder** to sync external resources into a new folder without affecting the rest of your instance. You can repeat this process for up to 10 connections.
|
||||
|
||||
1. Enter a **Display name** for the repository connection. Resources stored in this connection appear under the chosen display name in the Grafana UI.
|
||||
1. Click **Synchronize** to continue.
|
||||
|
||||
<!-- ### Synchronize with external storage
|
||||
|
||||
{{< admonition type="note">}}
|
||||
During the synchronization process, your dashboards will be temporarily unavailable.
|
||||
No data or configuration will be lost.
|
||||
However, no one will be able to create, edit, or delete resources during this process.
|
||||
In the last step, the resources will disappear and will reappear and be managed through external storage.
|
||||
{{< /admonition >}}
|
||||
|
||||
1. Select **History** to include commits for each historical value in the synchronized data.
|
||||
1. Select **Begin synchronization** to continue. -->
|
||||
Next, enter a **Display name** for the repository connection. Resources stored in this connection appear under the chosen display name in the Grafana UI. Click **Synchronize** to continue.
|
||||
|
||||
### Choose additional settings
|
||||
|
||||
@@ -163,7 +171,6 @@ Finally, you can set up how often your configured storage is polled for updates.
|
||||
|
||||
1. For **Update instance interval (seconds)**, enter how often you want the instance to pull updates from GitHub. The default value is 60 seconds.
|
||||
1. Optional: Select **Read only** to ensure resources can't be modified in Grafana.
|
||||
<!-- No workflow option listed in the UI. 1. For **Workflows**, select the GitHub workflows that you want to allow to run in the repository. Both **Branch** and **Write** are selected by default. -->
|
||||
1. Optional: If you have the Grafana Image Renderer plugin configured, you can **Enable dashboards previews in pull requests**. If image rendering is not available, then you can't select this option. For more information, refer to the [Image Renderer service](https://github.com/grafana/grafana-image-renderer).
|
||||
1. Select **Finish** to proceed.
|
||||
|
||||
@@ -179,23 +186,11 @@ You can extend Git Sync by getting instant updates and pull requests using webho
|
||||
|
||||
### Set up webhooks for realtime notification and pull request integration
|
||||
|
||||
When connecting to a GitHub repository, Git Sync use webhooks to enable real-time updates from GitHub public repositories or enable the pull request integration.
|
||||
Without webhooks, the polling interval is set in the final configuration screen (default is 60 seconds).
|
||||
Your Grafana instance must be exposed to the public internet.
|
||||
You can do this via port forwarding and DNS, a tool such as `ngrok`, or any other method you prefer.
|
||||
When connecting to a GitHub repository, Git Sync uses webhooks to enable real-time updates from GitHub public repositories or enable pull request integrations. Without webhooks, the polling interval is set in the final configuration screen, and the default is 60 seconds. If you use local storage, then Git Sync only provides periodic pulling.
|
||||
|
||||
The permissions set in your GitHub access token provide the authorization for this communication.
|
||||
You can set up webhooks with whichever service or tooling you prefer. You can use Cloudflare Tunnels with a Cloudflare-managed domain, port-forwarding and DNS options, or a tool such as `ngrok`.
|
||||
|
||||
If you use local storage, then Git Sync only provides periodic pulling.
|
||||
|
||||
<!-- Grafana Cloud support not available yet
|
||||
{{< admonition type="note" >}}
|
||||
Webhooks are automatically available for Grafana Cloud users.
|
||||
{{< /admonition >}}
|
||||
-->
|
||||
|
||||
Set up webhooks with whichever service or tooling you prefer.
|
||||
For example, you can use Cloudflare Tunnels with a Cloudflare-managed domain, port-forwarding and DNS options, or a tool such as `ngrok`.
|
||||
To set up webhooks you need to expose your Grafana instance to the public Internet. You can do this via port forwarding and DNS, a tool such as `ngrok`, or any other method you prefer. The permissions set in your GitHub access token provide the authorization for this communication.
|
||||
|
||||
After you have the public URL, you can add it to your Grafana configuration file:
|
||||
|
||||
@@ -204,23 +199,22 @@ After you have the public URL, you can add it to your Grafana configuration file
|
||||
root_url = https://PUBLIC_DOMAIN.HERE
|
||||
```
|
||||
|
||||
You can check the configured webhooks in the **View** link for your GitHub repository from **Administration** > **Provisioning**.
|
||||
To check the configured webhooks, go to **Administration** > **Provisioning** and click the **View** link for your GitHub repository.
|
||||
|
||||
#### Necessary paths
|
||||
#### Expose necessary paths only
|
||||
|
||||
If your security setup does not permit publicly exposing the Grafana instance, you can either choose to allowlist the GitHub IP addresses, or expose only the necessary paths.
|
||||
If your security setup does not permit publicly exposing the Grafana instance, you can either choose to `allowlist` the GitHub IP addresses, or expose only the necessary paths.
|
||||
|
||||
The necessary paths required to be exposed are (RegExp):
|
||||
The necessary paths required to be exposed are, in RegExp:
|
||||
|
||||
- `/apis/provisioning\.grafana\.app/v0(alpha1)?/namespaces/[^/]+/repositories/[^/]+/(webhook|render/.*)$`
|
||||
<!-- TODO: Path for the blob storage for image rendering? @ryantxu would know this best. -->
|
||||
|
||||
### Set up image rendering for dashboard previews
|
||||
|
||||
By setting up image rendering, you can add visual previews of dashboard updates directly in pull requests.
|
||||
Image rendering also requires webhooks.
|
||||
Set up image rendering to add visual previews of dashboard updates directly in pull requests. Image rendering also requires webhooks.
|
||||
|
||||
You can enable this capability by installing the Grafana Image Renderer in your Grafana instance. For more information and installation instructions, refer to the [Image Renderer service](https://github.com/grafana/grafana-image-renderer).
|
||||
To enable this capability, install the Grafana Image Renderer in your Grafana instance. For more information and installation instructions, refer to the [Image Renderer service](https://github.com/grafana/grafana-image-renderer).
|
||||
|
||||
## Modify configurations after set up is complete
|
||||
|
||||
@@ -10,8 +10,17 @@ labels:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
refs:
|
||||
roles-and-permissions:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/account-management/authentication-and-permissions/cloud-roles/
|
||||
title: Git Sync
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/intro-git-sync/
|
||||
aliases:
|
||||
- ../../../observability-as-code/provision-resources/intro-git-sync/ # /docs/grafana/next/observability-as-code/provision-resources/intro-git-sync/
|
||||
---
|
||||
|
||||
# Introduction to Git Sync
|
||||
@@ -63,14 +72,36 @@ With Git Sync, you can make changes to the files in the provisioned folder in Gi
|
||||
|
||||
## Known limitations
|
||||
|
||||
Git Sync is under development and the following limitations apply:
|
||||
{{< admonition type="caution" >}}
|
||||
|
||||
Refer to [Requirements](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/git-sync-setup#requirements/) to learn what you need to use Git Sync.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
**Git Sync is under development and the following limitations apply.**
|
||||
|
||||
**Synced resources**
|
||||
|
||||
- You can only sync dashboards and folders. Refer to [Supported resources](#supported-resources) for more information.
|
||||
- If you're using Git Sync in Grafana OSS and Grafana Enterprise, some resources might be in an incompatible data format and can't be synced.
|
||||
- You can only authenticate in GitHub using your Personal Access Token token.
|
||||
- Support for native Git, Git app, and other providers, such as GitLab or Bitbucket, is on the roadmap.
|
||||
- If you're using Git Sync in Grafana OSS and Grafana Enterprise, some resources might be in an incompatible data format and won't be synced.
|
||||
- Full-instance sync is not available in Grafana Cloud and has limitations in Grafana OSS and Grafana Enterprise. Refer to [Choose what to synchronize](../git-sync-setup/#choose-what-to-synchronize) for more details.
|
||||
- When migrating to full instance sync, during the synchronization process your resources will be temporarily unavailable. No one will be able to create, edit, or delete resources during this process.
|
||||
- If you want to manage existing resources with Git Sync, you need to save them as JSON files and commit them to the synced repository. Open a PR to import, copy, move, or save a dashboard.
|
||||
- Restoring resources from the UI is currently not possible. As an alternative, you can restore dashboards directly in your GitHub repository by raising a PR, and they will be updated in Grafana.
|
||||
|
||||
**Authentication**
|
||||
|
||||
- You can only authenticate in GitHub using your Personal Access Token token.
|
||||
|
||||
**Permission management**
|
||||
|
||||
- You cannot modify the permissions of a provisioned folder after you've synced it.
|
||||
- Default permissions are: Admin = Admin, Editor = Editor, and Viewer = Viewer. Refer to [Roles and permissions](ref:roles-and-permissions) for more information.
|
||||
|
||||
**Compatibility**
|
||||
|
||||
- Support for native Git, Git app, and other providers, such as GitLab or Bitbucket, is on the roadmap.
|
||||
|
||||
## Supported resources
|
||||
|
||||
Git Sync only supports dashboards and folders. Alerts, panels, and other resources are not supported yet.
|
||||
@@ -86,9 +117,9 @@ A resource can be:
|
||||
| **Supported** | The resource can be managed with Git Sync. | The resource is supported but has compatibility issues. It **cannot** be managed with Git Sync. |
|
||||
| **Unsupported** | The resource is **not** supported and **cannot** be managed with Git Sync. | Not applicable. |
|
||||
|
||||
### Instance states
|
||||
### Git Sync instance states
|
||||
|
||||
An instance can be in one of the following states:
|
||||
An instance can be in one of the following Git Sync states:
|
||||
|
||||
- **Unprovisioned**: None of the instance's resources are being managed by Git Sync.
|
||||
- **Partially provisioned**: Some of the resources are controlled by Git Sync.
|
||||
@@ -11,6 +11,9 @@ labels:
|
||||
- oss
|
||||
title: Work with provisioned dashboards
|
||||
weight: 300
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/provisioned-dashboards/
|
||||
aliases:
|
||||
- ../../../observability-as-code/provision-resources/provisioned-dashboards/ # /docs/grafana/next/observability-as-code/provision-resources/provisioned-dashboards/
|
||||
---
|
||||
|
||||
# Work with provisioned dashboards
|
||||
@@ -14,6 +14,9 @@ labels:
|
||||
title: Manage provisioned repositories with Git Sync
|
||||
menuTitle: Manage repositories with Git Sync
|
||||
weight: 400
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/use-git-sync/
|
||||
aliases:
|
||||
- ../../../observability-as-code/provision-resources/use-git-sync/ # /docs/grafana/next/observability-as-code/provision-resources/use-git-sync/
|
||||
---
|
||||
|
||||
# Manage provisioned repositories with Git Sync
|
||||
@@ -14,6 +14,9 @@ labels:
|
||||
- oss
|
||||
title: JSON schema v2
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/
|
||||
aliases:
|
||||
- ../../observability-as-code/schema-v2/ # /docs/grafana/next/observability-as-code/schema-v2/
|
||||
---
|
||||
|
||||
# Dashboard JSON schema v2
|
||||
@@ -17,6 +17,9 @@ labels:
|
||||
menuTitle: annotations schema
|
||||
title: annotations
|
||||
weight: 100
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/annotations-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/annotations-schema/ # /docs/grafana/next/observability-as-code/schema-v2/annotations-schema/
|
||||
---
|
||||
|
||||
# `annotations`
|
||||
@@ -17,6 +17,9 @@ labels:
|
||||
menuTitle: layout schema
|
||||
title: layout
|
||||
weight: 400
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/layout-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/layout-schema/ # /docs/grafana/next/observability-as-code/schema-v2/layout-schema/
|
||||
---
|
||||
|
||||
# `layout`
|
||||
@@ -17,6 +17,9 @@ labels:
|
||||
menuTitle: LibraryPanelKind schema
|
||||
title: LibraryPanelKind
|
||||
weight: 300
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/librarypanel-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/librarypanel-schema/ # /docs/grafana/next/observability-as-code/schema-v2/librarypanel-schema/
|
||||
---
|
||||
|
||||
# `LibraryPanelKind`
|
||||
@@ -17,6 +17,9 @@ labels:
|
||||
menuTitle: links schema
|
||||
title: links
|
||||
weight: 500
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/links-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/links-schema/ # /docs/grafana/next/observability-as-code/schema-v2/links-schema/
|
||||
---
|
||||
|
||||
# `links`
|
||||
@@ -17,6 +17,9 @@ labels:
|
||||
menuTitle: PanelKind schema
|
||||
title: PanelKind
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/panel-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/panel-schema/ # /docs/grafana/next/observability-as-code/schema-v2/panel-schema/
|
||||
---
|
||||
|
||||
# `PanelKind`
|
||||
@@ -17,6 +17,9 @@ labels:
|
||||
menuTitle: timesettings schema
|
||||
title: timesettings
|
||||
weight: 600
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/timesettings-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/timesettings-schema/ # /docs/grafana/next/observability-as-code/schema-v2/timesettings-schema/
|
||||
---
|
||||
|
||||
# `timeSettings`
|
||||
@@ -17,6 +17,9 @@ labels:
|
||||
menuTitle: variables schema
|
||||
title: variables
|
||||
weight: 700
|
||||
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/variables-schema/
|
||||
aliases:
|
||||
- ../../../observability-as-code/schema-v2/variables-schema/ # /docs/grafana/next/observability-as-code/schema-v2/variables-schema/
|
||||
---
|
||||
|
||||
# `variables`
|
||||
44
docs/sources/developer-resources/_index.md
Normal file
44
docs/sources/developer-resources/_index.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
description: Provides developer-oriented content.
|
||||
menuTitle: Developer resources
|
||||
title: Developer resources
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
weight: 900
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/
|
||||
---
|
||||
|
||||
# Developer resources
|
||||
|
||||
This section of the documentation contains additional resources for developers and contributors.
|
||||
|
||||
## Contribute to Grafana
|
||||
|
||||
Refer to the [Contribute to Grafana](https://grafana.com/docs/grafana-cloud/developer-resources/contribute) guide to learn the various ways you can contribute to Grafana. Read the [Grafana Labs Software Grant and Contributor License Agreement](https://grafana.com/docs/grafana-cloud/developer-resources/cla) before making any contribution.
|
||||
|
||||
## Grafana developer portal
|
||||
|
||||
Go to the [Grafana developer portal](https://grafana.com/developers) to access the following documentation:
|
||||
|
||||
- [Grafana plugin development tools](https://grafana.com/developers/plugin-tools)
|
||||
- [Grafana data model](https://grafana.com/developers/dataplane)
|
||||
- [Grafana React components library](https://developers.grafana.com)
|
||||
- [Grafana Scenes library](https://grafana.com/developers/scenes)
|
||||
|
||||
## API reference guides
|
||||
|
||||
Learn about the following Grafana APIs:
|
||||
|
||||
- [HTTP API](./api-reference/http-api/)
|
||||
- [Cloud API](./api-reference/cloud-api/)
|
||||
- [Tracing API](./api-reference/tracing-api/)
|
||||
|
||||
## Other resources
|
||||
|
||||
You might also find the following resources to be helpful:
|
||||
|
||||
- [Grafana Tutorials:](https://grafana.com/tutorials/) Step-by-step guides that help you make the most of Grafana.
|
||||
- [Grafana Community Forums:](https://community.grafana.com) Get technical support for open source Grafana, Loki, and Tempo.
|
||||
2101
docs/sources/developer-resources/api-reference/cloud-api.md
Normal file
2101
docs/sources/developer-resources/api-reference/cloud-api.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -1,8 +1,10 @@
|
||||
---
|
||||
aliases:
|
||||
- ../http_api/
|
||||
- ../overview/
|
||||
canonical: /docs/grafana/latest/developers/http_api/
|
||||
- ../../http_api/ # /docs/grafana/next/http_api/
|
||||
- ../../overview/ # /docs/grafana/next/overview/
|
||||
- ../../../developers/http_api/ # /docs/grafana/developers/http_api/
|
||||
- ../../developers/http_api/ # /docs/grafana/next/developers/http_api/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/
|
||||
description: Grafana HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -14,14 +16,14 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: HTTP API
|
||||
weight: 100
|
||||
---
|
||||
|
||||
# HTTP API reference
|
||||
# Grafana HTTP API reference
|
||||
|
||||
The Grafana backend exposes an HTTP API, which is the same API that's used by the frontend to do everything from saving
|
||||
dashboards, creating users, and updating data sources.
|
||||
Every Grafana instance exposes an HTTP API, which is the same API used by the Grafana frontend to manage resources like saving dashboards, creating users, updating data sources, deleting alerts, and more. You can use the HTTP API to programmatically access or manage resources from your Grafana instance running in Grafana Cloud. Below is the list of existing [HTTP APIs](#http-apis).
|
||||
|
||||
HTTP API details are [specified](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/public/api-merged.json) using OpenAPI v2.
|
||||
|
||||
@@ -29,10 +31,22 @@ There is also an [OpenAPI v3 specification](https://editor.swagger.io/?url=https
|
||||
|
||||
Users can browser and try out both via the Swagger UI editor (served by the Grafana server) by navigating to `/swagger-ui`.
|
||||
|
||||
## Authenticate API requests
|
||||
{{< admonition type="note" >}}
|
||||
|
||||
If you need to manage or access other resources from your [Grafana Cloud Stack](/docs/grafana-cloud/account-management/cloud-stacks/), refer to the [Grafana Cloud API](../cloud-api/) instead.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
## Authenticate HTTP API requests
|
||||
|
||||
### Grafana OSS
|
||||
|
||||
{{< docs/shared lookup="developers/authentication.md" source="grafana" version="<GRAFANA_VERSION>" >}}
|
||||
|
||||
### Grafana Cloud
|
||||
|
||||
{{< docs/shared source="grafana-cloud" lookup="/developer-resources/authentication.md" version="" >}}
|
||||
|
||||
## X-Grafana-Org-Id Header
|
||||
|
||||
**X-Grafana-Org-Id** is an optional property that specifies the organization to which the action is applied. If it is not set, the created key belongs to the current context org. Use this header in all requests except those regarding admin.
|
||||
@@ -75,10 +89,6 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
- [Team API](team/)
|
||||
- [User API](user/)
|
||||
|
||||
## Deprecated HTTP APIs
|
||||
|
||||
- [Authentication API](auth/)
|
||||
|
||||
## Grafana Enterprise HTTP APIs
|
||||
|
||||
Grafana Enterprise includes all of the Grafana OSS APIs as well as the following APIs:
|
||||
@@ -88,4 +98,9 @@ Grafana Enterprise includes all of the Grafana OSS APIs as well as the following
|
||||
- [Query and resource caching API](query_and_resource_caching/)
|
||||
- [Reporting API](reporting/)
|
||||
- [Role-based access control API](access_control/)
|
||||
- [Secrets Management API](secrets_management/)
|
||||
- [Team sync API](team_sync/)
|
||||
|
||||
## Deprecated HTTP APIs
|
||||
|
||||
- [Authentication API](authentication/)
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/access_control/
|
||||
- ../../http_api/accesscontrol/
|
||||
canonical: /docs/grafana/latest/developers/http_api/access_control/
|
||||
- ../../../http_api/access_control/ # /docs/grafana/next/http_api/access_control/
|
||||
- ../../../http_api/accesscontrol/ # /docs/grafana/next/http_api/accesscontrol/
|
||||
- ../../../developers/http_api/access_control/ # /docs/grafana/next/developers/http_api/access_control/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/access_control/
|
||||
description: ''
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -16,6 +17,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: RBAC HTTP API
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/admin/
|
||||
canonical: /docs/grafana/latest/developers/http_api/admin/
|
||||
- ../../../http_api/admin/ # /docs/grafana/next/http_api/admin/
|
||||
- ../../../developers/http_api/admin/ # /docs/grafana/next/developers/http_api/admin/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/admin/
|
||||
description: Grafana Admin HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -28,7 +29,7 @@ To use these API endpoints you have to use Basic authentication and the Grafana
|
||||
The `admin` user that Grafana is provisioned with by default has permissions to use these API endpoints.
|
||||
{{< /admonition >}}
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](../../../administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
## Fetch settings
|
||||
|
||||
@@ -371,7 +372,7 @@ Content-Type: application/json
|
||||
}
|
||||
```
|
||||
|
||||
Note that `OrgId` is an optional parameter that can be used to assign a new user to a different organization when [auto_assign_org](../../../setup-grafana/configure-grafana/#auto-assign-org) is set to `true`.
|
||||
Note that `OrgId` is an optional parameter that can be used to assign a new user to a different organization when [auto_assign_org](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#auto-assign-org) is set to `true`.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
@@ -694,7 +695,7 @@ Content-Type: application/json
|
||||
|
||||
`POST /api/admin/encryption/rotate-data-keys`
|
||||
|
||||
[Rotates](../../../setup-grafana/configure-security/configure-database-encryption/#rotate-data-keys) data encryption keys.
|
||||
[Rotates](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#rotate-data-keys) data encryption keys.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
@@ -715,7 +716,7 @@ Content-Type: application/json
|
||||
|
||||
`POST /api/admin/encryption/reencrypt-data-keys`
|
||||
|
||||
[Re-encrypts](../../../setup-grafana/configure-security/configure-database-encryption/#re-encrypt-data-keys) data encryption keys.
|
||||
[Re-encrypts](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#re-encrypt-data-keys) data encryption keys.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
@@ -736,7 +737,7 @@ Content-Type: application/json
|
||||
|
||||
`POST /api/admin/encryption/reencrypt-secrets`
|
||||
|
||||
[Re-encrypts](../../../setup-grafana/configure-security/configure-database-encryption/#re-encrypt-secrets) secrets.
|
||||
[Re-encrypts](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#re-encrypt-secrets) secrets.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
@@ -757,7 +758,7 @@ Content-Type: application/json
|
||||
|
||||
`POST /api/admin/encryption/rollback-secrets`
|
||||
|
||||
[Rolls back](../../../setup-grafana/configure-security/configure-database-encryption/#roll-back-secrets) secrets.
|
||||
[Rolls back](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#roll-back-secrets) secrets.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/alerting_provisioning/
|
||||
canonical: /docs/grafana/latest/developers/http_api/alerting_provisioning/
|
||||
- ../../../http_api/alerting_provisioning/ # /docs/grafana/next/http_api/alerting_provisioning/
|
||||
- ../../../developers/http_api/alerting_provisioning/ # /docs/grafana/next/developers/http_api/alerting_provisioning/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/alerting_provisioning/
|
||||
description: Grafana Alerts HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/annotations/
|
||||
canonical: /docs/grafana/latest/developers/http_api/annotations/
|
||||
- ../../../http_api/annotations/ # /docs/grafana/next/http_api/annotations/
|
||||
- ../../../developers/http_api/annotations/ # /docs/grafana/next/developers/http_api/annotations/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/annotations/
|
||||
description: Grafana Annotations HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -15,6 +16,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Annotations HTTP API
|
||||
---
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/new_api_structure/
|
||||
- ../../http_api/new_api_structure/
|
||||
canonical: /docs/grafana/latest/developers/http_api/new_api_structure/
|
||||
- ../../../http_api/new_api_structure/ # /docs/grafana/next/http_api/new_api_structure/
|
||||
- ../../../developers/http_api/apis/ # /docs/grafana/next/developers/http_api/apis/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/apis/
|
||||
description: ''
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,6 +13,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: New API Structure
|
||||
---
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/authentication/
|
||||
description: 'You can authenticate HTTP API requests using basic authentication or a service account token.'
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- role-based-access-control
|
||||
- acl
|
||||
- enterprise
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Authentication options for the HTTP API
|
||||
menuTitle: Authentication
|
||||
weight: 01
|
||||
aliases:
|
||||
- ../../../developers/http_api/authentication/ # /docs/grafana/next/developers/http_api/authentication/
|
||||
---
|
||||
|
||||
# Authentication
|
||||
|
||||
## Authentication options for the HTTP API for Grafana OSS
|
||||
|
||||
{{< docs/shared lookup="developers/authentication.md" source="grafana" version="<GRAFANA_VERSION>" >}}
|
||||
|
||||
## Authentication options for the HTTP API in Grafana Cloud
|
||||
|
||||
{{< docs/shared source="grafana-cloud" lookup="/developer-resources/authentication.md" version="" >}}
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/correlations/
|
||||
canonical: /docs/grafana/latest/developers/http_api/correlations/
|
||||
- ../../../http_api/correlations/ # /docs/grafana/next/http_api/correlations/
|
||||
- ../../../developers/http_api/correlations/ # /docs/grafana/next/developers/http_api/correlations/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/correlations/
|
||||
description: Grafana Correlations HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -14,6 +15,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Correlations HTTP API '
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/dashboard/
|
||||
canonical: /docs/grafana/latest/developers/http_api/dashboard/
|
||||
- ../../../http_api/dashboard/ # /docs/grafana/next/http_api/dashboard/
|
||||
- ../../../developers/http_api/dashboard/ # /docs/grafana/next/developers/http_api/dashboard/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/dashboard/
|
||||
description: Grafana Dashboard HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,6 +14,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Dashboard HTTP API
|
||||
---
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/dashboard_permissions/
|
||||
- ../../http_api/dashboardpermissions/
|
||||
canonical: /docs/grafana/latest/developers/http_api/dashboard_permissions/
|
||||
- ../../../http_api/dashboard_permissions/ # /docs/grafana/next/http_api/dashboard_permissions/
|
||||
- ../../../http_api/dashboardpermissions/ # /docs/grafana/next/http_api/dashboardpermissions/
|
||||
- ../../../developers/http_api/dashboard_permissions/ # /docs/grafana/next/developers/http_api/dashboard_permissions/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/dashboard_permissions/
|
||||
description: Grafana Dashboard Permissions HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -17,6 +18,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Dashboard Permissions HTTP API
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/dashboard_public/
|
||||
canonical: /docs/grafana/latest/developers/http_api/dashboard_public/
|
||||
- ../../../http_api/dashboard_public/ # /docs/grafana/next/http_api/dashboard_public/
|
||||
- ../../../developers/http_api/dashboard_public/ # /docs/grafana/next/developers/http_api/dashboard_public/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/dashboard_public/
|
||||
description: Grafana Shared Dashboards HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,6 +14,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Shared Dashboards HTTP API
|
||||
refs:
|
||||
role-based-access-control-permissions:
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/dashboard_versions/
|
||||
- ../../http_api/dashboardversions/
|
||||
canonical: /docs/grafana/latest/developers/http_api/dashboard_versions/
|
||||
- ../../../http_api/dashboard_versions/ # /docs/grafana/next/http_api/dashboard_versions/
|
||||
- ../../../http_api/dashboardversions/ # /docs/grafana/next/http_api/dashboardversions/
|
||||
- ../../../developers/http_api/dashboard_versions/ # /docs/grafana/next/developers/http_api/dashboard_versions/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/dashboard_versions/
|
||||
description: Grafana Dashboard Versions HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -15,6 +16,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Dashboard Versions HTTP API '
|
||||
---
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/data_source/
|
||||
- ../../http_api/datasource/
|
||||
canonical: /docs/grafana/latest/developers/http_api/data_source/
|
||||
- ../../../http_api/data_source/ # /docs/grafana/next/http_api/data_source/
|
||||
- ../../../http_api/datasource/ # /docs/grafana/next/http_api/datasource/
|
||||
- ../../../developers/http_api/data_source/ # /docs/grafana/next/developers/http_api/data_source/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/data_source/
|
||||
description: Grafana Data source HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -14,6 +15,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Data source HTTP API
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/datasource_lbac_rules/
|
||||
canonical: /docs/grafana/latest/developers/http_api/datasource_lbac_rules/
|
||||
- ../../../http_api/datasource_lbac_rules/ # /docs/grafana/next/http_api/datasource_lbac_rules/
|
||||
- ../../../developers/http_api/datasource_lbac_rules/ # /docs/grafana/next/developers/http_api/datasource_lbac_rules/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/datasource_lbac_rules/
|
||||
description: Data Source LBAC rules API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/datasource_permissions/
|
||||
- ../../http_api/datasourcepermissions/
|
||||
canonical: /docs/grafana/latest/developers/http_api/datasource_permissions/
|
||||
- ../../../http_api/datasource_permissions/ # /docs/grafana/next/http_api/datasource_permissions/
|
||||
- ../../../http_api/datasourcepermissions/ # /docs/grafana/next/http_api/datasourcepermissions/
|
||||
- ../../../developers/http_api/datasource_permissions/ # /docs/grafana/next/developers/http_api/datasource_permissions/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/datasource_permissions/
|
||||
description: Data Source Permissions API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -18,6 +19,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Datasource Permissions HTTP API
|
||||
---
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../developers/http_api/examples/ # /docs/grafana/next/developers/http_api/examples/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/examples/
|
||||
keywords:
|
||||
- grafana
|
||||
- tutorials
|
||||
- API
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: 'HTTP API examples'
|
||||
menuTitle: 'Examples'
|
||||
weight: 02
|
||||
---
|
||||
|
||||
# HTTP API examples
|
||||
|
||||
{{< section >}}
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/create-api-tokens-for-org/ # /docs/grafana/<GRAFANA_VERSION>/http_api/create-api-tokens-for-org/
|
||||
- ../../../tutorials/api_org_token_howto/ # /docs/grafana/<GRAFANA_VERSION>/tutorials/api_org_token_howto/
|
||||
canonical: /docs/grafana/latest/developers/http_api/examples/create-api-tokens-for-org/
|
||||
- ../../../../http_api/create-api-tokens-for-org/ # /docs/grafana/next/http_api/create-api-tokens-for-org/
|
||||
- ../../../../tutorials/api_org_token_howto/ # /docs/grafana/next/tutorials/api_org_token_howto/
|
||||
- ../../../../developers/http_api/examples/create-api-tokens-for-org/ # /docs/grafana/next/developers/http_api/examples/create-api-tokens-for-org/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/examples/create-api-tokens-for-org/
|
||||
keywords:
|
||||
- grafana
|
||||
- tutorials
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/curl-examples/ # /docs/grafana/<GRAFANA_VERSION>/http_api/curl-examples/
|
||||
- ../../http_api/curl-examples/ # /docs/grafana/<GRAFANA_VERSION>/developers/http_api/curl-examples/
|
||||
canonical: /docs/grafana/latest/developers/http_api/examples/curl-examples/
|
||||
- ../../../../http_api/curl-examples/ # /docs/grafana/next/http_api/curl-examples/
|
||||
- ../../../../developers/http_api/curl-examples/ # /docs/grafana/next/developers/http_api/curl-examples/
|
||||
- ../../../../developers/http_api/examples/curl-examples/ # /docs/grafana/next/developers/http_api/examples/curl-examples/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/examples/curl-examples/
|
||||
description: cURL examples
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/folder/
|
||||
canonical: /docs/grafana/latest/developers/http_api/folder/
|
||||
- ../../../http_api/folder/ # /docs/grafana/next/http_api/folder/
|
||||
- ../../../developers/http_api/folder/ # /docs/grafana/next/developers/http_api/folder/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/folder/
|
||||
description: Grafana Folder HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,13 +14,14 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Folder HTTP API
|
||||
refs:
|
||||
apis:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/developers/http_api/apis/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/developer-resources/api-reference/http-api/apis/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/developer-resources/api-reference/http-api/apis/
|
||||
destination: ./apis/
|
||||
alerting:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/alerting
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/folder_dashboard_search/
|
||||
canonical: /docs/grafana/latest/developers/http_api/folder_dashboard_search/
|
||||
- ../../../http_api/folder_dashboard_search/ # /docs/grafana/next/http_api/folder_dashboard_search/
|
||||
- ../../../developers/http_api/folder_dashboard_search/ # /docs/grafana/next/developers/http_api/folder_dashboard_search/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/folder_dashboard_search/
|
||||
description: Grafana Folder/Dashboard Search HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -15,6 +16,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Folder/Dashboard Search HTTP API
|
||||
---
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/dashboardpermissions/
|
||||
- ../../http_api/folder_permissions/
|
||||
canonical: /docs/grafana/latest/developers/http_api/folder_permissions/
|
||||
- ../../../http_api/dashboardpermissions/ # /docs/grafana/next/http_api/dashboardpermissions/
|
||||
- ../../../http_api/folder_permissions/ # /docs/grafana/next/http_api/folder_permissions/
|
||||
- ../../../developers/http_api/folder_permissions/ # /docs/grafana/next/developers/http_api/folder_permissions/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/folder_permissions/
|
||||
description: Grafana Folder Permissions HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -17,6 +18,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Folder Permissions HTTP API
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/library_element/
|
||||
canonical: /docs/grafana/latest/developers/http_api/library_element/
|
||||
- ../../../http_api/library_element/ # /docs/grafana/next/http_api/library_element/
|
||||
- ../../../developers/http_api/library_element/ # /docs/grafana/next/developers/http_api/library_element/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/library_element/
|
||||
description: Grafana Library Element HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,6 +14,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Library Element HTTP API '
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/licensing/
|
||||
canonical: /docs/grafana/latest/developers/http_api/licensing/
|
||||
- ../../../http_api/licensing/ # /docs/grafana/next/http_api/licensing/
|
||||
- ../../../developers/http_api/licensing/ # /docs/grafana/next/developers/http_api/licensing/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/licensing/
|
||||
description: Enterprise Licensing HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/org/
|
||||
- ../../http_api/organization/
|
||||
canonical: /docs/grafana/latest/developers/http_api/org/
|
||||
- ../../../http_api/org/ # /docs/grafana/next/http_api/org/
|
||||
- ../../../http_api/organization/ # /docs/grafana/next/http_api/organization/
|
||||
- ../../../developers/http_api/org/ # /docs/grafana/next/developers/http_api/org/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/org/
|
||||
description: Grafana Organization HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/other/
|
||||
canonical: /docs/grafana/latest/developers/http_api/other/
|
||||
- ../../../http_api/other/ # /docs/grafana/next/http_api/other/
|
||||
- ../../../developers/http_api/other/ # /docs/grafana/next/developers/http_api/other/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/other/
|
||||
description: Grafana Other HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/playlist/
|
||||
canonical: /docs/grafana/latest/developers/http_api/playlist/
|
||||
- ../../../http_api/playlist/ # /docs/grafana/next/http_api/playlist/
|
||||
- ../../../developers/http_api/playlist/ # /docs/grafana/next/developers/http_api/playlist/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/playlist/
|
||||
description: Playlist Admin HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,6 +14,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Playlist HTTP API '
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/preferences/
|
||||
canonical: /docs/grafana/latest/developers/http_api/preferences/
|
||||
- ../../../http_api/preferences/ # /docs/grafana/next/http_api/preferences/
|
||||
- ../../../developers/http_api/preferences/ # /docs/grafana/next/developers/http_api/preferences/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/preferences/
|
||||
description: Grafana HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,6 +14,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Preferences API'
|
||||
---
|
||||
|
||||
@@ -1,9 +1,10 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/query_caching/
|
||||
- ../../http_api/resource_caching/
|
||||
- ../../http_api/caching/
|
||||
canonical: /docs/grafana/latest/developers/http_api/query_and_resource_caching/
|
||||
- ../../../http_api/query_caching/ # /docs/grafana/next/http_api/query_caching/
|
||||
- ../../../http_api/resource_caching/ # /docs/grafana/next/http_api/resource_caching/
|
||||
- ../../../http_api/caching/ # /docs/grafana/next/http_api/caching/
|
||||
- ../../../developers/http_api/query_and_resource_caching/ # /docs/grafana/next/developers/http_api/query_and_resource_caching/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/query_and_resource_caching/
|
||||
description: Grafana Enterprise Query and Resource Caching HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -18,6 +19,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Query and Resource Caching HTTP API
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/query_history/
|
||||
canonical: /docs/grafana/latest/developers/http_api/query_history/
|
||||
- ../../../http_api/query_history/ # /docs/grafana/next/http_api/query_history/
|
||||
- ../../../developers/http_api/query_history/ # /docs/grafana/next/developers/http_api/query_history/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/query_history/
|
||||
description: Grafana Query History HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,6 +14,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Query History HTTP API '
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/reporting/
|
||||
canonical: /docs/grafana/latest/developers/http_api/reporting/
|
||||
- ../../../http_api/reporting/ # /docs/grafana/next/http_api/reporting/
|
||||
- ../../../developers/http_api/reporting/ # /docs/grafana/next/developers/http_api/reporting/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/reporting/
|
||||
description: Grafana Enterprise APIs
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -12,6 +13,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Reporting API
|
||||
---
|
||||
|
||||
@@ -0,0 +1,401 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/secrets_management/ # /docs/grafana/next/http_api/secrets_management/
|
||||
- ../../../developers/http_api/secrets_management/ # /docs/grafana/next/developers/http_api/secrets_management/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/secrets_management/
|
||||
description: Grafana Secrets Management HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- secrets
|
||||
- enterprise
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- cloud
|
||||
title: Secrets Management HTTP API
|
||||
refs:
|
||||
api-overview:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/developers/http_api/apis/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/developer-resources/api-reference/http-api/apis/
|
||||
rbac-permissions:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/custom-role-actions-scopes/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control/custom-role-actions-scopes/
|
||||
---
|
||||
|
||||
# Secrets Management API
|
||||
|
||||
> If you are running Grafana Enterprise, you need to have specific permissions for some endpoints . Refer to [Role-based access control permissions](ref:rbac-permissions) for more information.
|
||||
|
||||
> To view more about the new API structure, refer to [API overview](ref:api-overview).
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
The API is currently in [public preview](https://grafana.com/docs/release-life-cycle/#public-preview) and might be subject to changes.
|
||||
{{< /admonition >}}
|
||||
|
||||
The Grafana Secrets Management API allows you to manage secrets that are used by other services and applications within your Grafana instance.
|
||||
|
||||
### Decrypters
|
||||
|
||||
The decrypters field is an allowlist that lets the secure value know which services and apps can decrypt the secret value.
|
||||
|
||||
Currently available decrypters:
|
||||
|
||||
- `synthetic-monitoring` (for Synthetic Monitoring checks)
|
||||
- `provisioning.grafana.app` (for GitSync/Provisioning)
|
||||
|
||||
## Create a secure value
|
||||
|
||||
`POST /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues`
|
||||
|
||||
Creates a new secure value.
|
||||
|
||||
**URL parameters**
|
||||
|
||||
- `namespace`: To read more about which namespace to use, see the [API overview](ref:api-overview).
|
||||
|
||||
**Request body**
|
||||
|
||||
- `metadata.name`: The Grafana unique identifier. If you do not want to provide this, set `metadata.generateName` instead to the prefix you would like for the randomly generated uid (can't be an empty string).
|
||||
- `spec.description`: Short description that explains the purpose of this secure value. Required. Up to 25 characters long.
|
||||
- `spec.value`: The secret value to store. Required. Up to 24576 bytes long.
|
||||
- `spec.decrypters`: List of services allowed to decrypt this secure value. Up to 64 items, see note in [decrypters](#decrypters) for a list of supported values.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#secrets-management-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| ---------------------------- | ----------------------------------------- |
|
||||
| `secret.securevalues:create` | <ul><li>`secret.securevalues:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example create request**:
|
||||
|
||||
```http
|
||||
POST /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 201 Created
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 343
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **201** – Created
|
||||
- **400** – Errors (invalid JSON, missing or invalid fields, etc)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **409** – Conflict (secure value with the same name already exists)
|
||||
|
||||
{{< admonition type="note">}}
|
||||
The `spec.value` field is never returned by API endpoints. Users cannot not decrypt secrets.
|
||||
{{< /admonition >}}
|
||||
|
||||
## List secure values
|
||||
|
||||
`GET /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues`
|
||||
|
||||
List all secure values in a namespace.
|
||||
|
||||
**URL parameters**
|
||||
|
||||
- `namespace`: To read more about which namespace to use, see the [API overview](ref:api-overview).
|
||||
|
||||
**Query parameters**
|
||||
|
||||
- `labelSelector`: Filter secure values by labels.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#secrets-management-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| ---------------------------- | ----------------------------------------- |
|
||||
| `secret.securevalues:read` | <ul><li>`secret.securevalues:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example list request**:
|
||||
|
||||
```http
|
||||
GET /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 383
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
|
||||
## Get a secure value
|
||||
|
||||
`GET /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues/:name`
|
||||
|
||||
Get the details of a specific secure value. It will not return the secret value.
|
||||
|
||||
**URL parameters**
|
||||
|
||||
- `namespace`: To read more about which namespace to use, see the [API overview](ref:api-overview).
|
||||
- `name`: The name of the secure value.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#secrets-management-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| ---------------------------- | ----------------------------------------- |
|
||||
| `secret.securevalues:read` | <ul><li>`secret.securevalues:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example get request**:
|
||||
|
||||
```http
|
||||
GET /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues/api-key HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 294
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Not found
|
||||
|
||||
## Update a secure value
|
||||
|
||||
`PUT /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues/:name`
|
||||
|
||||
Replace an existing secure value with a new specification.
|
||||
|
||||
**URL parameters**
|
||||
|
||||
- `namespace`: To read more about which namespace to use, see the [API overview](ref:api-overview).
|
||||
- `name`: The name of the secure value.
|
||||
|
||||
**Request body**
|
||||
|
||||
- `spec.description`: Short description that explains the purpose of this secure value. Required. Up to 25 characters long.
|
||||
- `spec.value`: The secret value to store. Required. Up to 24576 bytes long.
|
||||
- `spec.decrypters`: List of services allowed to decrypt this secure value. Up to 64 items, see note in [decrypters](#decrypters) for a list of supported values.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#secrets-management-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| --------------------------- | ----------------------------------------- |
|
||||
| `secret.securevalues:write` | <ul><li>`secret.securevalues:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example update request**:
|
||||
|
||||
```http
|
||||
PUT /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues/api-key HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 282
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – OK
|
||||
- **400** – Errors (invalid JSON, missing or invalid fields, etc)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Not found
|
||||
|
||||
## Delete a secure value
|
||||
|
||||
`DELETE /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues/:name`
|
||||
|
||||
Permanently delete a secure value. This also deletes the underlying stored secret value.
|
||||
|
||||
**URL parameters**
|
||||
|
||||
- `namespace`: To read more about the namespace to use, see the [API overview](ref:api-overview).
|
||||
- `name`: The name of the secure value.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#secrets-management-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| ---------------------------- | ----------------------------------------- |
|
||||
| `secret.securevalues:delete` | <ul><li>`secret.securevalues:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example delete request**:
|
||||
|
||||
```http
|
||||
DELETE /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues/api-key HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 65
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Not found
|
||||
"name": "api-key"
|
||||
},
|
||||
"spec": {
|
||||
"description": "External API Key",
|
||||
"value": "new-value-12345",
|
||||
"decrypters": ["synthetic-monitoring"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 282
|
||||
|
||||
{
|
||||
"apiVersion": "secret.grafana.app/v1beta1",
|
||||
"kind": "SecureValue",
|
||||
"metadata": {
|
||||
"name": "api-key",
|
||||
"namespace": "default",
|
||||
"uid": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
|
||||
"creationTimestamp": "2024-01-15T10:35:00Z"
|
||||
},
|
||||
"spec": {
|
||||
"description": "External API Key",
|
||||
"decrypters": ["synthetic-monitoring"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – OK
|
||||
- **400** – Errors (invalid JSON, missing or invalid fields, etc)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Not found
|
||||
|
||||
## Delete a secure value
|
||||
|
||||
`DELETE /apis/secret.grafana.app/v1beta1/namespaces/:namespace/securevalues/:name`
|
||||
|
||||
Permanently delete a secure value. This also deletes the underlying stored secret value.
|
||||
|
||||
**URL parameters**
|
||||
|
||||
- `namespace`: To read more about the namespace to use, see the [API overview](ref:api-overview).
|
||||
- `name`: The name of the secure value.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#secrets-management-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| ---------------------------- | ----------------------------------------- |
|
||||
| `secret.securevalues:delete` | <ul><li>`secret.securevalues:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example delete request**:
|
||||
|
||||
```http
|
||||
DELETE /apis/secret.grafana.app/v1beta1/namespaces/default/securevalues/api-key HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 65
|
||||
|
||||
{
|
||||
"apiVersion": "v1",
|
||||
"kind": "Status",
|
||||
"status": "Success",
|
||||
"code": 200
|
||||
}
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Not found
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/serviceaccount/
|
||||
canonical: /docs/grafana/latest/developers/http_api/serviceaccount/
|
||||
- ../../../http_api/serviceaccount/ # /docs/grafana/next/http_api/serviceaccount/
|
||||
- ../../../developers/http_api/serviceaccount/ # /docs/grafana/next/developers/http_api/serviceaccount/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/serviceaccount/
|
||||
description: Grafana service account HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,6 +14,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Service account HTTP API
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/short_url/
|
||||
canonical: /docs/grafana/latest/developers/http_api/short_url/
|
||||
- ../../../http_api/short_url/ # /docs/grafana/next/http_api/short_url/
|
||||
- ../../../developers/http_api/short_url/ # /docs/grafana/next/developers/http_api/short_url/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/
|
||||
description: Grafana Short URL HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,6 +14,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Short URL HTTP API '
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/snapshot/
|
||||
canonical: /docs/grafana/latest/developers/http_api/snapshot/
|
||||
- ../../../http_api/snapshot/ # /docs/grafana/next/http_api/snapshot/
|
||||
- ../../../developers/http_api/snapshot/ # /docs/grafana/next/developers/http_api/snapshot/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/snapshot/
|
||||
description: Grafana HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,6 +14,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Snapshot API'
|
||||
---
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/sso-settings/
|
||||
- ../../http_api/ssosettings/
|
||||
canonical: /docs/grafana/latest/developers/http_api/sso-settings/
|
||||
- ../../../http_api/sso-settings/ # /docs/grafana/next/http_api/sso-settings/
|
||||
- ../../../http_api/ssosettings/ # /docs/grafana/next/http_api/ssosettings/
|
||||
- ../../../developers/http_api/sso-settings/ # /docs/grafana/next/developers/http_api/sso-settings/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/sso-settings/
|
||||
description: Grafana SSO Settings API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -15,6 +16,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: SSO Settings API
|
||||
---
|
||||
|
||||
@@ -25,7 +27,7 @@ title: SSO Settings API
|
||||
The API can be used to create, update, delete, get, and list SSO Settings for OAuth2 and SAML.
|
||||
|
||||
The settings managed by this API are stored in the database and override
|
||||
[settings from other sources](../../../setup-grafana/configure-access/configure-authentication/)
|
||||
[settings from other sources](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/)
|
||||
(arguments, environment variables, settings file, etc).
|
||||
Therefore, every time settings for a specific provider are removed or reset to the default settings at runtime,
|
||||
the settings are inherited from the other sources in the reverse order of precedence
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/team/
|
||||
canonical: /docs/grafana/latest/developers/http_api/team/
|
||||
- ../../../http_api/team/ # /docs/grafana/next/http_api/team/
|
||||
- ../../../developers/http_api/team/ # /docs/grafana/next/developers/http_api/team/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/team/
|
||||
description: Grafana Team HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -15,6 +16,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Team HTTP API
|
||||
---
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/external_group_sync/
|
||||
- ./external_group_sync/
|
||||
canonical: /docs/grafana/latest/developers/http_api/team_sync/
|
||||
- ../../../http_api/external_group_sync/ # /docs/grafana/next/http_api/external_group_sync/
|
||||
- ../../../developers/http_api/external_group_sync/ # /docs/grafana/next/developers/http_api/external_group_sync/
|
||||
- ../../../developers/http_api/team_sync/ # /docs/grafana/next/developers/http_api/team_sync/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/team_sync/
|
||||
description: Grafana Team Sync HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -18,6 +19,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Team Sync HTTP API
|
||||
---
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/user/
|
||||
canonical: /docs/grafana/latest/developers/http_api/user/
|
||||
- ../../../http_api/user/ # /docs/grafana/next/http_api/user/
|
||||
- ../../../developers/http_api/user/ # /docs/grafana/next/developers/http_api/user/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/user/
|
||||
description: Grafana User HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
@@ -13,6 +14,7 @@ labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: User HTTP API
|
||||
refs:
|
||||
role-based-access-control-permissions:
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
description: This topic includes links to Grafana Cloud tracing API documentation.
|
||||
keywords:
|
||||
- Grafana
|
||||
- Cloud
|
||||
- trace
|
||||
- tracing
|
||||
- API
|
||||
menuTitle: Tracing API reference
|
||||
title: Grafana Cloud tracing API reference
|
||||
weight: 200
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/tracing-api/
|
||||
---
|
||||
|
||||
# Grafana Cloud tracing API reference
|
||||
|
||||
Consult the following tracing API reference resources as necessary:
|
||||
|
||||
- [Tempo HTTP API](/docs/tempo/latest/api_docs/)
|
||||
- [Push spans with HTTP: Example using HTTP API](/docs/tempo/latest/api_docs/pushing-spans-with-http/)
|
||||
- [Metrics summary API (experimental)](/docs/grafana-cloud/send-data/traces/metrics-summary-api/)
|
||||
- [Grafana Enterprise Traces Admin API](/docs/enterprise-traces/latest/admin-api/)
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
aliases:
|
||||
- ../project/cla/
|
||||
- ../project/cla/ # /docs/grafana/next/project/cla/
|
||||
- /docs/contributing/cla.html/
|
||||
- ../developers/cla/ # /docs/grafana/next/developers/cla/
|
||||
description: Contributor License Agreement (CLA)
|
||||
labels:
|
||||
products:
|
||||
@@ -9,6 +10,7 @@ labels:
|
||||
- oss
|
||||
title: Contributor License Agreement (CLA)
|
||||
weight: 400
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/cla/
|
||||
---
|
||||
|
||||
# Grafana Labs Software Grant and Contributor License Agreement ("Agreement")
|
||||
@@ -10,6 +10,9 @@ labels:
|
||||
- oss
|
||||
title: Contribute to Grafana
|
||||
weight: 300
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/contribute/
|
||||
aliases:
|
||||
- ../developers/contribute/ # /docs/grafana/next/developers/contribute/
|
||||
---
|
||||
|
||||
# Contribute to Grafana
|
||||
@@ -20,7 +23,7 @@ This page lists resources for developers who want to contribute to the Grafana s
|
||||
|
||||
Choose how you want to contribute to Grafana, from code to plugins to community support.
|
||||
|
||||
### Contribute Code to Grafana
|
||||
### Contribute code to Grafana
|
||||
|
||||
- [Contributing to Grafana](https://github.com/grafana/grafana/blob/main/CONTRIBUTING.md) introduces the contribution process and community resources.
|
||||
- [Developer guide](https://github.com/grafana/grafana/blob/main/contribute/developer-guide.md) shows how to set up your environment and run Grafana in development.
|
||||
@@ -41,7 +44,7 @@ Choose how you want to contribute to Grafana, from code to plugins to community
|
||||
- Help with [issue triage](https://github.com/grafana/grafana/blob/main/contribute/triage-issues.md) by reviewing, labeling, and clarifying open issues.
|
||||
- Report security vulnerabilities following our [security policy](https://github.com/grafana/grafana/security/policy).
|
||||
|
||||
## Choose the right channel
|
||||
## Communicate with Grafana
|
||||
|
||||
Use the right place to ask questions, report problems, and propose changes.
|
||||
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
aliases:
|
||||
- plugins/developing/
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Developers
|
||||
weight: 190
|
||||
---
|
||||
|
||||
# Developers
|
||||
|
||||
Go to the [Grafana developer portal](/developers) to access the following documentation:
|
||||
|
||||
- [Grafana plugin development](/developers/plugin-tools)
|
||||
- [Grafana design system](https://developers.grafana.com)
|
||||
- [Grafana Scenes](/developers/scenes)
|
||||
- [Grafana data plane](/developers/dataplane)
|
||||
|
||||
This section of our documentation contains additional resources:
|
||||
|
||||
{{< section >}}
|
||||
|
||||
You might also find the following resources to be helpful:
|
||||
|
||||
- [Grafana Tutorials:](https://grafana.com/tutorials/) Step-by-step guides that help you make the most of Grafana.
|
||||
- [Grafana Community Forums:](https://community.grafana.com) Get technical support for open source Grafana, Loki, and Tempo.
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
canonical: https://grafana.com/docs/grafana/latest/developers/http_api/authentication/
|
||||
description: 'You can authenticate HTTP API requests using basic authentication or a service account token.'
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- role-based-access-control
|
||||
- acl
|
||||
- enterprise
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Authentication options for the HTTP API
|
||||
menuTitle: Authentication
|
||||
weight: 01
|
||||
---
|
||||
|
||||
# Authentication options for the HTTP API
|
||||
|
||||
{{< docs/shared lookup="developers/authentication.md" source="grafana" version="<GRAFANA_VERSION>" >}}
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
canonical: https://grafana.com/docs/grafana/latest/developers/http_api/examples/
|
||||
keywords:
|
||||
- grafana
|
||||
- tutorials
|
||||
- API
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: 'HTTP API examples'
|
||||
menuTitle: 'Examples'
|
||||
weight: 02
|
||||
---
|
||||
|
||||
# HTTP API examples
|
||||
|
||||
{{< section >}}
|
||||
@@ -1,113 +0,0 @@
|
||||
---
|
||||
description: Overview of Observability as Code including description, key features, and explanation of benefits.
|
||||
keywords:
|
||||
- observability
|
||||
- configuration
|
||||
- as code
|
||||
- dashboards
|
||||
- git integration
|
||||
- git sync
|
||||
- github
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Observability as Code
|
||||
weight: 100
|
||||
cards:
|
||||
items:
|
||||
- title: Get started
|
||||
height: 24
|
||||
href: ./get-started/
|
||||
description: Learn about how you can use Observability as Code.
|
||||
- title: Grafana CLI
|
||||
height: 24
|
||||
href: ./grafana-cli/
|
||||
description: Grafana CLI (`grafanactl`) is a command-line tool designed to simplify interaction with Grafana instances. You can authenticate, manage multiple environments, and perform administrative tasks through Grafana’s REST API, all from the terminal.
|
||||
- title: JSON schema v2
|
||||
height: 24
|
||||
href: ./schema-v2/
|
||||
description: Grafana dashboards are represented as JSON objects that store metadata, panels, variables, and settings. Observability as Code works with all versions of the JSON model, and it's fully compatible with version 2.
|
||||
- title: Foundation SDK
|
||||
height: 24
|
||||
href: ./foundation-sdk/
|
||||
description: The Grafana Foundation SDK is a set of tools, types, and libraries that let you define Grafana dashboards and resources using strongly typed code.
|
||||
- title: Git Sync (private preview)
|
||||
height: 24
|
||||
href: ./provision-resources/intro-git-sync/
|
||||
description: Git Sync is an experimental feature that lets you store your dashboard files in a GitHub repository and synchronize those changes with your Grafana instance.
|
||||
- title: File provisioning (private preview)
|
||||
height: 24
|
||||
href: ./provision-resources/
|
||||
description: File provisioning in Grafana lets you include resources, including folders and dashboard JSON files, that are stored in a local file system.
|
||||
title_class: pt-0 lh-1
|
||||
hero:
|
||||
title: Observability as Code
|
||||
description: Using Observability as Code, you can version, automate, and scale Grafana configurations, including dashboards and observability workflows.
|
||||
height: 110
|
||||
level: 1
|
||||
width: 110
|
||||
---
|
||||
|
||||
{{< docs/hero-simple key="hero" >}}
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Observability as Code lets you apply code management best practices to your observability resources.
|
||||
By representing Grafana resources as code, you can integrate them into existing infrastructure-as-code workflows and apply standard development practices.
|
||||
|
||||
Observability as Code provides more control over configuration. Instead of manually configuring dashboards or settings through the Grafana UI, you can:
|
||||
|
||||
- Write configurations in code: Define dashboards in JSON or other supported formats.
|
||||
- Sync your Grafana setup to GitHub: Track changes, collaborate, and roll back updates using Git and GitHub, or other remote sources.
|
||||
- Automate with CI/CD: Integrate Grafana directly into your development and deployment pipelines.
|
||||
- Standardize workflows: Ensure consistency across your teams by using repeatable, codified processes for managing Grafana resources.
|
||||
|
||||
## Explore
|
||||
|
||||
{{< card-grid key="cards" type="simple" >}}
|
||||
|
||||
<!-- Hiding this part of the doc because the rest of the docs aren't released yet
|
||||
|
||||
## Key features
|
||||
|
||||
At this time, Observability as Code lets you configure dashboards in static files rather than using the UI.
|
||||
The number of resources covered by this approach will expand over time.
|
||||
|
||||
### App Platform: A unified foundation
|
||||
|
||||
The [App Platform](https://github.com/grafana/grafana-app-sdk) is the backbone of Observability as Code. It provides consistent APIs for managing Grafana resources like dashboards, data sources, and service-level objectives (SLOs). With the App Platform, you gain:
|
||||
|
||||
- A stable and predictable API for integrating Grafana into your systems.
|
||||
- Support for cloud-native workflows, making it easier to build and scale observability solutions.
|
||||
- The ability to manage Grafana resources programmatically.
|
||||
- Backwards compatibility with earlier versions of Grafana APIs, so older applications still work.
|
||||
|
||||
### Git integration
|
||||
|
||||
Version control is at the heart of Observability as Code. By integrating Grafana with Git, you can:
|
||||
|
||||
- Store your dashboards in a Git repository.
|
||||
- Automatically deploy changes through CI/CD pipelines.
|
||||
- Track who made changes, when they were made, and why.
|
||||
|
||||
### Enhanced dashboard management
|
||||
|
||||
Dashboards are central to Grafana’s value, and Observability as Code introduces improvements to make them easier to work with:
|
||||
|
||||
- **Ready for Schema v2:** An experimental dashboard schema that simplifies dashboards definition, separating properties for better clarity and making configurations more intuitive.
|
||||
- **New layout options:** Flexible layouts, including a new responsive grid layout that allow for more dynamic and responsive panel layouts.
|
||||
- **Improved metadata management:** Add descriptions, tags, and other metadata to better organize and understand your dashboards.
|
||||
|
||||
### Tooling and integrations
|
||||
|
||||
Observability as Code comes with tools to make your workflows seamless:
|
||||
|
||||
- Examples and best practices for integrating Grafana with tools like Terraform, Kubernetes, and GitHub Actions.
|
||||
- The Foundation SDK provides a set of libraries for getting started quickly configuring and manipulating Grafana resources.
|
||||
- A command line tool for configuring your dashboards programmatically.
|
||||
- Documentation, videos, and SDKs to help you get started quickly.
|
||||
-->
|
||||
@@ -1,85 +0,0 @@
|
||||
---
|
||||
description: Get started with Observability as Code by exploring the documentation, libraries, and tools available for as-code practices.
|
||||
keywords:
|
||||
- configuration
|
||||
- as code
|
||||
- as-code
|
||||
- dashboards
|
||||
- Git Sync
|
||||
- Git
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Get started with Observability as Code
|
||||
weight: 100
|
||||
---
|
||||
|
||||
# Get started with Observability as Code
|
||||
|
||||
Grafana provides a suite of tools for **Observability as Code** to help you manage your Grafana resources programmatically and at scale. This approach lets you define dashboards, data sources, and other configurations in code, enabling version control, automated testing, and reliable deployments through CI/CD pipelines.
|
||||
|
||||
Historically, managing Grafana as code involved various community and Grafana Labs tools, but lacked a single, cohesive story. Grafana 12 introduces foundational improvements, including new versioned APIs and official tooling, to provide a clearer path forward.
|
||||
|
||||
## Grafana CLI (`grafanactl`)
|
||||
|
||||
Use the official command-line tool, `grafanactl`, to interact with your Grafana instances and manage resources via the new APIs.
|
||||
|
||||
- It's the recommended tool for automation and direct API interaction, suitable for CI/CD pipelines and local development or free-form tasks. It supports pulling/pushing configurations from remote instances, validating configurations, and more.
|
||||
- `grafanactl` works across all environments for Grafana OSS, Enterprise, and Cloud.
|
||||
|
||||
Refer to the [Grafana CLI (`grafanactl`)](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/grafana-cli) documentation for more information.
|
||||
|
||||
## Git Sync
|
||||
|
||||
For an integrated, UI-driven Git workflow focused on dashboards, explore Git Sync.
|
||||
|
||||
- Connect folders or entire Grafana instances directly to a GitHub repository to synchronize dashboard definitions, enabling version control, branching, and pull requests directly from Grafana.
|
||||
- Git Sync offers a simple, out-of-the-box approach for managing dashboards as code.
|
||||
{{< admonition type="note" >}}
|
||||
Git Sync is available in **private preview** for Grafana Cloud, and it's an **experimental feature** in Grafana 12, available in Grafana OSS and Enterprise [nightly releases](https://grafana.com/grafana/download/nightly).
|
||||
{{< /admonition >}}
|
||||
|
||||
Refer to the [Git Sync documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync/) to learn more.
|
||||
|
||||
## Direct API usage
|
||||
|
||||
For maximum flexibility, advanced use cases, or building custom tooling, you can interact directly with the underlying versioned APIs.
|
||||
|
||||
- This approach requires handling HTTP requests and responses but provides complete control over resource management.
|
||||
- `grafanactl`, Git Sync, and the Foundation SDK are all built on top of these APIs.
|
||||
- To understand Dashboard Schemas accepted by the APIs, refer to the [JSON models documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/).
|
||||
|
||||
Refer to the [Grafana APIs](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/developers/http_api/apis/) documentation for more information.
|
||||
|
||||
## Foundation SDK
|
||||
|
||||
To programmatically define your Grafana resources (like dashboards or alerts) using familiar programming languages, use Foundation SDK.
|
||||
|
||||
- Define resources using strongly typed builders in languages like Go, TypeScript, Python, Java, and PHP.
|
||||
- Avoid crafting complex JSON manually and integrate resource generation into your existing development workflows.
|
||||
- Catch errors at compile time and easily integrate resource generation into your CI/CD pipelines.
|
||||
- Use in conjunction with `grafanactl` to push your programmatically generated resources.
|
||||
|
||||
Refer to the [Foundation SDK](../foundation-sdk) documentation for more information.
|
||||
|
||||
## Additional Observability as Code tools
|
||||
|
||||
If you're already using established Infrastructure as Code or other configuration management tools, Grafana offers integrations to manage resources within your existing workflows.
|
||||
|
||||
- [Terraform](https://grafana.com/docs/grafana-cloud/developer-resources/infrastructure-as-code/terraform/)
|
||||
- Use the Grafana Terraform provider to manage dashboards, alerts, and more.
|
||||
- Understand how to define and deploy resources using HCL/JSON configurations.
|
||||
|
||||
- [Ansible](https://grafana.com/docs/grafana-cloud/developer-resources/infrastructure-as-code/ansible/)
|
||||
- Learn to use the Grafana Ansible collection to manage Grafana Cloud resources, including folders and cloud stacks.
|
||||
- Write playbooks to automate resource provisioning through the Grafana API.
|
||||
|
||||
- [Grafana Operator](https://grafana.com/docs/grafana-cloud/developer-resources/infrastructure-as-code/grafana-operator/)
|
||||
- Utilize Kubernetes-native management with the Grafana Operator.
|
||||
- Manage dashboards, folders, and data sources via Kubernetes Custom Resources.
|
||||
- Integrate with GitOps workflows for seamless version control and deployment.
|
||||
|
||||
- [Crossplane](https://github.com/grafana/crossplane-provider-grafana) lets you manage Grafana resources using Kubernetes manifests with the Grafana Crossplane provider.
|
||||
- [Grafonnet](https://github.com/grafana/grafonnet) is a Jsonnet library for generating Grafana dashboard JSON definitions programmatically.
|
||||
- [Grizzly](https://grafana.com/docs/grafana-cloud/developer-resources/infrastructure-as-code/grizzly/dashboards-folders-datasources/) is a deprecated command-line tool that simplifies managing Grafana resources using Kubernetes-inspired YAML syntax.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user