0
# Grafana Backup Tool
1

2
A Python-based application to backup and restore Grafana settings using the Grafana API. It provides comprehensive command-line tool and Python library for backing up and restoring Grafana configurations, supporting multiple cloud storage providers, and offering extensive monitoring integration capabilities.
3

4
## Package Information
5

6
- **Package Name**: grafana-backup
7
- **Language**: Python
8
- **Installation**: `pip install grafana-backup`
9
- **CLI Command**: `grafana-backup`
10

11
## Core Imports
12

13
```python
14
# For programmatic usage
15
import grafana_backup.cli as cli
16
import grafana_backup.save as save_module
17
import grafana_backup.restore as restore_module
18
import grafana_backup.delete as delete_module
19
import grafana_backup.tools as tools_module
20
import grafana_backup.grafanaSettings as settings_module
21
```
22

23
Common configuration loading:
24

25
```python
26
from grafana_backup.grafanaSettings import main as load_config
27
settings = load_config('/path/to/config.json')
28
```
29

30
## Basic Usage
31

32
### Command Line Usage
33

34
```bash
35
# Backup all Grafana components
36
grafana-backup save
37

38
# Backup specific components
39
grafana-backup save --components=dashboards,datasources,folders
40

41
# Restore from archive
42
grafana-backup restore backup_20250101.tar.gz
43

44
# Delete components
45
grafana-backup delete --components=dashboards
46

47
# Tools and utilities
48
grafana-backup tools pause-alerts
49
grafana-backup tools make-users-viewers
50
```
51

52
### Python Library Usage
53

54
```python
55
from grafana_backup.grafanaSettings import main as load_config
56
from grafana_backup.save import main as save_backup
57
from grafana_backup.restore import main as restore_backup
58

59
# Load configuration
60
settings = load_config('/path/to/config.json')
61

62
# Mock command line arguments
63
save_args = {
64
    'save': True,
65
    '--components': 'dashboards,datasources',
66
    '--no-archive': False,
67
    '--config': None
68
}
69

70
# Perform backup
71
save_backup(save_args, settings)
72
```
73

74
## Architecture
75

76
The grafana-backup tool is built around a modular architecture with clear separation of concerns:
77

78
- **CLI Layer**: Command-line interface routing commands to appropriate modules
79
- **Command Modules**: High-level operations (save, restore, delete, tools)
80
- **Component Modules**: Specialized handlers for each Grafana component type
81
- **API Layer**: Low-level Grafana API interaction functions
82
- **Storage Layer**: Cloud storage integrations (S3, Azure, GCS)
83
- **Configuration Layer**: Settings management and environment variable handling
84

85
This design enables both command-line usage and programmatic integration while supporting extensible component types and storage backends.
86

87
## Capabilities
88

89
### Backup Operations
90

91
Complete backup functionality for all supported Grafana components including dashboards, datasources, folders, users, teams, and more. Supports selective component backup and automatic archiving with timestamp versioning.
92

93
```python { .api }
94
def main(args, settings):
95
    """
96
    Main backup function handling complete backup workflow
97
    
98
    Args:
99
        args (dict): Command line arguments with --components and --no-archive
100
        settings (dict): Configuration settings from grafanaSettings
101
    
102
    Returns:
103
        None: Performs backup operations and exits
104
    """
105
```
106

107
[Backup Operations](./backup-operations.md)
108

109
### Restore Operations
110

111
Complete restoration of Grafana configurations from backup archives with support for selective component restoration, dependency management, and cloud storage integration.
112

113
```python { .api }
114
def main(args, settings):
115
    """
116
    Main restore function handling archive extraction and component restoration
117
    
118
    Args:
119
        args (dict): Command line arguments including archive_file and --components
120
        settings (dict): Configuration settings from grafanaSettings
121
    
122
    Returns:
123
        None: Performs restore operations and exits
124
    """
125

126
def restore_components(args, settings, restore_functions, tmpdir):
127
    """
128
    Restore individual components from extracted archive
129
    
130
    Args:
131
        args (dict): Command line arguments
132
        settings (dict): Configuration settings
133
        restore_functions (OrderedDict): Component restoration functions
134
        tmpdir (str): Temporary directory with extracted files
135
    
136
    Returns:
137
        None: Processes component files and restores them
138
    """
139
```
140

141
[Restore Operations](./restore-operations.md)
142

143
### Delete Operations
144

145
Selective deletion of Grafana components with support for bulk operations and safety checks to prevent accidental data loss.
146

147
```python { .api }
148
def main(args, settings):
149
    """
150
    Main delete function for selective component deletion
151
    
152
    Args:
153
        args (dict): Command line arguments with --components filter
154
        settings (dict): Configuration settings from grafanaSettings
155
    
156
    Returns:
157
        None: Performs deletion operations and exits
158
    
159
    Note:
160
        Available components: dashboards, datasources, folders, alert-channels,
161
        snapshots, annotations, library-elements, team-members
162
        Teams are intentionally excluded to preserve references
163
    """
164
```
165

166
[Delete Operations](./delete-operations.md)
167

168
### Configuration Management
169

170
Comprehensive configuration loading and processing with support for JSON files, environment variables, and default settings. Handles authentication, SSL verification, and API endpoint configuration.
171

172
```python { .api }
173
def main(config_path):
174
    """
175
    Load and process configuration from JSON file with environment variable overrides
176
    
177
    Args:
178
        config_path (str): Path to JSON configuration file
179
        
180
    Returns:
181
        dict: Complete configuration dictionary with all settings processed
182
    """
183
```
184

185
[Configuration Management](./configuration.md)
186

187
### Cloud Storage Integration
188

189
Integration with major cloud storage providers including Amazon S3, Azure Storage, and Google Cloud Storage for automated backup archiving and retrieval.
190

191
```python { .api }
192
# S3 Integration (grafana_backup.s3_upload)
193
def main(args, settings):
194
    """Upload backup archives to AWS S3"""
195

196
# S3 Download (grafana_backup.s3_download)  
197
def main(args, settings):
198
    """Download backup archives from AWS S3"""
199

200
# Azure Storage Integration (grafana_backup.azure_storage_upload)
201
def main(args, settings):
202
    """Upload backup archives to Azure Storage"""
203

204
# Azure Storage Download (grafana_backup.azure_storage_download)
205
def main(args, settings):
206
    """Download backup archives from Azure Storage"""
207

208
# Google Cloud Storage Integration (grafana_backup.gcs_upload)
209
def main(args, settings):
210
    """Upload backup archives to Google Cloud Storage"""
211

212
# GCS Download (grafana_backup.gcs_download)
213
def main(args, settings):
214
    """Download backup archives from Google Cloud Storage"""
215
```
216

217
[Cloud Storage Integration](./cloud-storage.md)
218

219
### Administrative Tools
220

221
Administrative utility functions for Grafana management including alert management, user role management, and permission restoration.
222

223
```python { .api }
224
def main(precommand_args, settings):
225
    """
226
    Administrative tools entry point with command routing
227
    
228
    Args:
229
        precommand_args (dict): Pre-parsed command line arguments
230
        settings (dict): Configuration settings from grafanaSettings
231
    
232
    Returns:
233
        None: Routes to specific tool functions and exits
234
    
235
    Available tools:
236
    - pause-alerts: Pause all alert rules and save state
237
    - unpause-alerts: Restore alert rules from saved state
238
    - make-users-viewers: Convert all users to viewer role
239
    - restore-users: Restore user permissions from backup
240
    """
241
```
242

243
[Administrative Tools](./admin-tools.md)
244

245
### API Health Checking
246

247
Comprehensive API validation and feature detection to ensure compatibility with different Grafana versions and configurations.
248

249
```python { .api }
250
def main(settings):
251
    """
252
    Perform comprehensive API health checks and feature detection
253
    
254
    Args:
255
        settings (dict): Configuration settings from grafanaSettings
256
    
257
    Returns:
258
        tuple: (status_code, response_data, dashboard_uid_support, 
259
               datasource_uid_support, paging_support, contact_point_support)
260
    """
261
```
262

263
[API Health Checking](./api-health.md)
264

265
### Archive Management
266

267
Archive creation and extraction functionality with support for compressed tar.gz format and automatic timestamping.
268

269
```python { .api }
270
def main(args, settings):
271
    """
272
    Create compressed tar.gz archive from backup directory
273
    
274
    Args:
275
        args (dict): Command line arguments
276
        settings (dict): Configuration settings including BACKUP_DIR and TIMESTAMP
277
    
278
    Returns:
279
        None: Creates timestamped archive file
280
    """
281
```
282

283
[Archive Management](./archive-management.md)
284

285
### Monitoring Integration
286

287
InfluxDB integration for backup operation monitoring and metrics collection, enabling operational visibility into backup processes.
288

289
```python { .api }
290
def main(args, settings):
291
    """
292
    Send backup operation metrics to InfluxDB
293
    
294
    Args:
295
        args (dict): Command line arguments  
296
        settings (dict): Configuration including InfluxDB connection details
297
    
298
    Returns:
299
        None: Writes metrics to InfluxDB database
300
    """
301
```
302

303
[Monitoring Integration](./monitoring.md)