Administrative Tools

Specialized administrative utility functions for Grafana management including alert management, user role management, and permission restoration. These tools provide operational capabilities beyond basic backup and restore functionality.

Capabilities

Main Tools Interface

The primary tools entry point that provides access to specialized administrative functions.

def main(precommand_args, settings):
    """
    Main tools interface providing access to administrative utilities
    
    Args:
        precommand_args (dict): Arguments from main command line
        settings (dict): Configuration settings loaded from grafanaSettings
        
    Available commands: pause-alerts, unpause-alerts, make-users-viewers, restore-users
    """

Alert Management Tools

Pause All Alerts

Temporarily disable all dashboard alerts in the Grafana instance for maintenance or troubleshooting.

def main(args, settings):
    """
    Pause all dashboard alerts in Grafana instance
    
    Module: grafana_backup.pause_alerts
    Features: Bulk alert disabling, state preservation, maintenance mode
    Safety: Preserves alert configurations while disabling notifications
    Output: JSON file with paused alert details for later restoration
    """

Unpause Alerts

Restore previously paused alerts from a saved alert state file.

def main(args, settings):
    """
    Unpause alerts from saved alert state file
    
    Module: grafana_backup.unpause_alerts
    Args:
        args['<alerts_filename>']: Path to JSON file with paused alert details
    Features: Selective alert restoration, state validation, error recovery
    Safety: Only restores alerts that were previously paused by pause-alerts
    """

User Management Tools

Convert Users to Viewers

Convert all non-admin users to viewer role for security lockdown scenarios.

def main(args, settings):
    """
    Convert all users to viewer role except administrators
    
    Module: grafana_backup.make_users_viewers
    Features: Bulk role conversion, admin preservation, reversible operation
    Safety: Preserves admin users, creates backup of original user roles
    Requires: Basic authentication (admin credentials)
    """

Restore User Permissions

Restore user roles and permissions from a previously saved user state file.

def main(args, settings):
    """
    Restore user permissions from saved user state file
    
    Module: grafana_backup.restore_user_permissions
    Args:
        args['<users_filename>']: Path to JSON file with user permission details
    Features: Role restoration, permission validation, selective restoration
    Requires: Basic authentication (admin credentials)
    """

Usage Examples

Alert Management Workflow

from grafana_backup.tools import main as tools_main
from grafana_backup.grafanaSettings import main as load_config

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

# Pause all alerts before maintenance
pause_args = {
    'tools': True,
    'pause-alerts': True,
    '--config': None
}
tools_main(pause_args, settings)

# ... perform maintenance operations ...

# Unpause alerts after maintenance
unpause_args = {
    'tools': True,
    'unpause-alerts': True,
    '<alerts_filename>': 'paused_alerts_202501011200.json',
    '--config': None
}
tools_main(unpause_args, settings)

User Role Management Workflow

# Convert all users to viewers for security lockdown
viewer_args = {
    'tools': True,
    'make-users-viewers': True,
    '--config': None
}
tools_main(viewer_args, settings)

# ... security incident response ...

# Restore original user permissions
restore_args = {
    'tools': True,
    'restore-users': True,
    '<users_filename>': 'user_permissions_backup.json',
    '--config': None
}
tools_main(restore_args, settings)

Command Line Usage

# Pause all alerts
grafana-backup tools pause-alerts

# Unpause alerts from file
grafana-backup tools unpause-alerts paused_alerts_202501011200.json

# Convert users to viewers
grafana-backup tools make-users-viewers

# Restore user permissions
grafana-backup tools restore-users user_permissions_backup.json

Tool-Specific Details

Alert Pause Operations

Pause Process

1. Discovery: Retrieves all dashboards and their alert configurations
2. State Capture: Records current alert enabled/disabled state
3. Bulk Disable: Disables all enabled alerts while preserving configuration
4. State File: Creates JSON file with alert details for restoration
5. Validation: Confirms alerts are successfully paused

Pause State File Format

{
  "timestamp": "2025-01-01T12:00:00Z",
  "paused_alerts": [
    {
      "dashboard_id": 1,
      "dashboard_title": "System Metrics",
      "alert_id": 1,
      "alert_name": "High CPU Usage",
      "was_enabled": true
    }
  ]
}

Unpause Process

1. State File Loading: Reads previously saved alert state
2. Validation: Verifies alerts still exist and can be modified
3. Selective Restoration: Re-enables only alerts that were previously enabled
4. Error Handling: Reports any alerts that cannot be restored
5. Confirmation: Validates successful alert restoration

User Role Management Operations

Make Users Viewers Process

1. User Discovery: Retrieves all users in the organization
2. Admin Detection: Identifies admin users to preserve
3. Role Backup: Creates backup file with current user roles and permissions
4. Bulk Conversion: Converts non-admin users to viewer role
5. Validation: Confirms role changes are applied successfully

User Backup File Format

{
  "timestamp": "2025-01-01T12:00:00Z",
  "user_permissions": [
    {
      "user_id": 2,
      "login": "john.doe",
      "email": "john.doe@example.com",
      "original_role": "Editor",
      "is_admin": false,
      "org_id": 1
    }
  ]
}

User Restoration Process

1. Backup File Loading: Reads previously saved user permission state
2. User Validation: Verifies users still exist in the system
3. Permission Restoration: Restores original user roles and permissions
4. Admin Preservation: Ensures admin users are not downgraded
5. Error Reporting: Details any users that cannot be restored

Authentication Requirements

Basic Authentication Needed

Several tools require basic authentication (username/password) for admin operations:

• make-users-viewers: Requires admin credentials for user role modification
• restore-users: Requires admin credentials for user permission restoration

Configuration Requirements

{
  "grafana": {
    "admin_account": "admin",
    "admin_password": "admin_password"
  }
}

Or via environment variables:

export GRAFANA_ADMIN_ACCOUNT="admin"
export GRAFANA_ADMIN_PASSWORD="admin_password"
# Or pre-encoded
export GRAFANA_BASIC_AUTH="YWRtaW46YWRtaW5fcGFzc3dvcmQ="

Safety Features

State Preservation

All tools that modify system state create backup files:

• Alert pause: Creates alert state file for restoration
• User role changes: Creates user permission backup file
• Timestamped files: All backup files include timestamps for tracking

Reversible Operations

All administrative operations are designed to be reversible:

• Pause/Unpause: Alert states can be fully restored
• Role changes: User permissions can be completely restored
• Validation: Operations validate successful completion

Error Handling

Comprehensive error handling for administrative operations:

• API connectivity: Validates Grafana API access before operations
• Permission validation: Confirms sufficient privileges for operations
• Partial failure recovery: Continues with remaining operations if individual items fail
• Detailed logging: Provides complete audit trail of operations

Best Practices

Pre-Operation Backup

Always create a full backup before using administrative tools:

# Create full backup first
grafana-backup save

# Then use administrative tools
grafana-backup tools pause-alerts

State File Management

Properly manage state files created by administrative tools:

• Secure storage: Store state files in secure, backed-up locations
• Naming conventions: Use descriptive names with timestamps
• Retention policy: Establish retention policy for state files
• Access control: Restrict access to state files containing sensitive data

Testing in Development

Test administrative operations in development environments:

• Verify behavior: Confirm tools work as expected
• Practice restoration: Test restoration procedures
• Validate safety: Ensure admin users are preserved
• Timing considerations: Understand operation duration for maintenance windows

Monitoring and Alerting

Consider the impact of administrative tools on monitoring:

• Alert pause: Coordinate with monitoring systems during alert pause operations
• User role changes: Update monitoring access permissions as needed
• Audit logging: Ensure administrative operations are properly logged
• Change management: Follow organizational change management procedures

These administrative tools provide powerful capabilities for operational management while maintaining safety through state preservation and reversible operations.