tessl/pypi-grafana-backup

A Python-based application to backup Grafana settings using the Grafana API

—

Pending

Overview

Eval results

Files

Restore Operations

Name: tessl/pypi-grafana-backup
Author: tessl

Complete restoration functionality for Grafana configurations from backup archives. The restore system recreates Grafana objects from JSON backup files with proper dependency ordering, conflict resolution, and support for multiple storage sources.

Capabilities

Main Restore Function

The primary restore entry point that handles archive extraction, component restoration, and dependency management.

def main(args, settings):
    """
    Main restore function that orchestrates the complete restore workflow
    
    Args:
        args (dict): Command line arguments including:
            - '<archive_file>': Path to backup archive or cloud storage identifier
            - '--components': Comma-separated list of components to restore
        settings (dict): Configuration settings with cloud storage credentials
    """

Component Restoration Helper

Internal function that handles the actual restoration of components from extracted archive files.

def restore_components(args, settings, restore_functions, tmpdir):
    """
    Restore components from extracted archive directory
    
    Args:
        args (dict): Command line arguments
        settings (dict): Configuration settings
        restore_functions (OrderedDict): Mapping of file extensions to restore functions
        tmpdir (str): Temporary directory containing extracted backup files
    """

Supported Restore Components

Component Restore Order

Components are restored in dependency order to ensure proper object relationships:

Folders - Must exist before dashboards and library elements
Datasources - Required for dashboard data queries
Library Elements - Must exist before dashboards that use them
Dashboards - Can reference folders, datasources, and library elements
Alert Channels - Independent notification configurations
Organizations - Organizational structure
Users - User accounts and authentication
Snapshots - Dashboard snapshots
Annotations - Dashboard and global annotations
Teams - Team definitions
Team Members - Team membership assignments
Folder Permissions - Access control settings
Alert Rules - Unified alerting rules
Contact Points - Alerting contact configurations

Individual Component Restore Functions

Folder Restoration

def main(args, settings, file_path):
    """
    Restore folder from JSON backup file
    
    Module: grafana_backup.create_folder
    Input: *.folder files from backup
    Features: Hierarchy preservation, permission handling
    """

Datasource Restoration

def main(args, settings, file_path):
    """
    Restore datasource configuration from JSON backup file
    
    Module: grafana_backup.create_datasource
    Input: *.datasource files from backup
    Features: Credential restoration, connection validation
    """

Library Element Restoration

def main(args, settings, file_path):
    """
    Restore library element from JSON backup file
    
    Module: grafana_backup.create_library_element
    Input: *.library_element files from backup
    Features: Element type preservation, model validation
    """

Dashboard Restoration

def main(args, settings, file_path):
    """
    Restore dashboard from JSON backup file
    
    Module: grafana_backup.create_dashboard
    Input: *.dashboard files from backup
    Features: Folder assignment, UID handling, overwrite protection
    """

Alert Channel Restoration

def main(args, settings, file_path):
    """
    Restore alert notification channel from JSON backup file
    
    Module: grafana_backup.create_alert_channel
    Input: *.alert_channel files from backup
    Features: Channel type validation, credential handling
    """

Organization Restoration

def main(args, settings, file_path):
    """
    Restore organization from JSON backup file
    
    Module: grafana_backup.create_org
    Input: *.organization files from backup
    Requires: Basic authentication (admin credentials)
    """

User Restoration

def main(args, settings, file_path):
    """
    Restore user account from JSON backup file
    
    Module: grafana_backup.create_user
    Input: *.user files from backup
    Requires: Basic authentication (admin credentials)
    Note: Uses default password from configuration
    """

Snapshot Restoration

def main(args, settings, file_path):
    """
    Restore dashboard snapshot from JSON backup file
    
    Module: grafana_backup.create_snapshot
    Input: *.snapshot files from backup
    Features: Complete snapshot data restoration
    """

Annotation Restoration

def main(args, settings, file_path):
    """
    Restore annotation from JSON backup file
    
    Module: grafana_backup.create_annotation
    Input: *.annotation files from backup
    Features: Time range and tag preservation
    """

Team Restoration

def main(args, settings, file_path):
    """
    Restore team from JSON backup file
    
    Module: grafana_backup.create_team
    Input: *.team files from backup
    Features: Team metadata and settings restoration
    """

Team Member Restoration

def main(args, settings, file_path):
    """
    Restore team membership from JSON backup file
    
    Module: grafana_backup.create_team_member
    Input: *.team_member files from backup
    Features: Role assignment preservation
    """

Folder Permission Updates

def main(args, settings, file_path):
    """
    Update folder permissions from JSON backup file
    
    Module: grafana_backup.update_folder_permissions
    Input: *.folder_permission files from backup
    Features: Access control restoration
    """

Alert Rule Restoration

def main(args, settings, file_path):
    """
    Restore unified alerting rule from JSON backup file
    
    Module: grafana_backup.create_alert_rule
    Input: *.alert_rule files from backup
    Features: Rule group preservation, expression handling
    """

Contact Point Restoration

def main(args, settings, file_path):
    """
    Restore contact point from JSON backup file
    
    Module: grafana_backup.create_contact_point
    Input: *.contact_point files from backup
    Requires: Unified alerting support
    """

Archive Sources

Local File System

# Restore from local tar.gz file
args = {
    'restore': True,
    '<archive_file>': '/path/to/backup_20250101.tar.gz',
    '--components': None,
    '--config': None
}

AWS S3 Storage

# Restore from S3 (filename specified in S3 settings)
settings['AWS_S3_BUCKET_NAME'] = 'my-backup-bucket'
args = {
    'restore': True,
    '<archive_file>': 'backup_20250101.tar.gz',  # S3 object key
    '--components': None,
    '--config': None
}

Azure Storage

# Restore from Azure Storage
settings['AZURE_STORAGE_CONTAINER_NAME'] = 'grafana-backups'
args = {
    'restore': True,
    '<archive_file>': 'backup_20250101.tar.gz',  # Blob name
    '--components': None,
    '--config': None
}

Google Cloud Storage

# Restore from GCS
settings['GCS_BUCKET_NAME'] = 'grafana-backup-bucket'
args = {
    'restore': True,
    '<archive_file>': 'backup_20250101.tar.gz',  # GCS object name
    '--components': None,
    '--config': None
}

Usage Examples

Complete System Restore

from grafana_backup.restore import main as restore_backup
from grafana_backup.grafanaSettings import main as load_config

# Load configuration
settings = load_config('/path/to/grafanaSettings.json')

# Restore all components from archive
args = {
    'restore': True,
    '<archive_file>': 'backup_20250101.tar.gz',
    '--components': None,  # None means all components
    '--config': None
}

restore_backup(args, settings)

Selective Component Restore

# Restore only dashboards and datasources
args = {
    'restore': True,
    '<archive_file>': 'backup_20250101.tar.gz',
    '--components': 'dashboards,datasources',
    '--config': None
}

restore_backup(args, settings)

Cloud Storage Restore

# Configure cloud storage
settings['AWS_S3_BUCKET_NAME'] = 'my-grafana-backups'
settings['AWS_DEFAULT_REGION'] = 'us-east-1'

# Restore from S3
args = {
    'restore': True,
    '<archive_file>': 'backup_20250101.tar.gz',
    '--components': None,
    '--config': None
}

restore_backup(args, settings)

Important Limitations

Notification Policies

Notification policy restoration is disabled by default due to API issues that can lock the notification policy interface. The restore function exists but is commented out in the restore mapping.

Dashboard Versions

Dashboard version history cannot be restored - it's backup-only data that provides historical reference but cannot be imported back into Grafana.

Password Handling

User passwords are not stored in backups for security reasons. The default_user_password configuration setting is used for all restored users.

Team IDs

Teams don't have consistent unique identifiers across Grafana instances, so team deletion/recreation can break folder permissions and team member references.

Component Dependencies

The restore system automatically handles dependencies:

Folders are restored before Dashboards and Library Elements
Datasources are restored before Dashboards that reference them
Library Elements are restored before Dashboards that use them
Teams are restored before Team Members
Users are restored before Team Members and Folder Permissions

Error Handling

Comprehensive error handling throughout the restore process:

API connectivity validation before starting
Archive format verification and extraction
Component file validation before processing
Graceful handling of missing dependencies
Detailed logging for each restored object
Transaction-like behavior with cleanup on critical failures

Archive Format

The restore system expects tar.gz archives with the following structure:

backup_archive.tar.gz
├── folders/
│   └── {timestamp}/
│       └── *.folder
├── datasources/
│   └── {timestamp}/
│       └── *.datasource
├── dashboards/
│   └── {timestamp}/
│       └── *.dashboard
└── ...

File extensions must match the component type for proper routing to restore functions.

Install with Tessl CLI