nthlayer-generate 1.0.0__py3-none-any.whl

nthlayer_generate/__init__.py

@@ -0,0 +1,5 @@
+"""NthLayer control plane package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

nthlayer_generate/alertmanager/__init__.py

@@ -0,0 +1,24 @@
+"""
+Alertmanager configuration generation.
+
+Generates Alertmanager configuration with PagerDuty receivers,
+routing rules, and inhibition rules based on service definitions.
+"""
+
+from nthlayer_generate.alertmanager.config import (
+    AlertmanagerConfig,
+    InhibitRule,
+    PagerDutyReceiver,
+    Receiver,
+    Route,
+    generate_alertmanager_config,
+)
+
+__all__ = [
+    "AlertmanagerConfig",
+    "generate_alertmanager_config",
+    "InhibitRule",
+    "PagerDutyReceiver",
+    "Receiver",
+    "Route",
+]

nthlayer_generate/alertmanager/config.py

@@ -0,0 +1,265 @@
+"""
+Alertmanager configuration generator.
+
+Generates Alertmanager configuration with PagerDuty receivers
+and routing rules based on service definitions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class PagerDutyReceiver:
+    """PagerDuty receiver configuration."""
+
+    service_key: str  # Integration key from PagerDuty
+    severity: str = "error"  # PagerDuty severity
+    class_: str = ""  # Alert class
+    component: str = ""  # Component that generated the alert
+    group: str = ""  # Logical grouping
+    send_resolved: bool = True
+    url: str = "https://events.pagerduty.com/v2/enqueue"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to Alertmanager config format."""
+        config: dict[str, Any] = {
+            "service_key": self.service_key,
+            "send_resolved": self.send_resolved,
+        }
+        if self.url != "https://events.pagerduty.com/v2/enqueue":
+            config["url"] = self.url
+        if self.severity:
+            config["severity"] = self.severity
+        if self.class_:
+            config["class"] = self.class_
+        if self.component:
+            config["component"] = self.component
+        if self.group:
+            config["group"] = self.group
+        return config
+
+
+@dataclass
+class Receiver:
+    """Alertmanager receiver configuration."""
+
+    name: str
+    pagerduty_configs: list[PagerDutyReceiver] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to Alertmanager config format."""
+        result: dict[str, Any] = {"name": self.name}
+        if self.pagerduty_configs:
+            result["pagerduty_configs"] = [pd.to_dict() for pd in self.pagerduty_configs]
+        return result
+
+
+@dataclass
+class Route:
+    """Alertmanager routing rule."""
+
+    receiver: str
+    group_by: list[str] = field(default_factory=lambda: ["alertname", "service"])
+    group_wait: str = "30s"
+    group_interval: str = "5m"
+    repeat_interval: str = "4h"
+    matchers: list[str] = field(default_factory=list)
+    routes: list[Route] = field(default_factory=list)
+    continue_: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to Alertmanager config format."""
+        result: dict[str, Any] = {"receiver": self.receiver}
+        if self.group_by:
+            result["group_by"] = self.group_by
+        if self.group_wait:
+            result["group_wait"] = self.group_wait
+        if self.group_interval:
+            result["group_interval"] = self.group_interval
+        if self.repeat_interval:
+            result["repeat_interval"] = self.repeat_interval
+        if self.matchers:
+            result["matchers"] = self.matchers
+        if self.routes:
+            result["routes"] = [r.to_dict() for r in self.routes]
+        if self.continue_:
+            result["continue"] = True
+        return result
+
+
+@dataclass
+class InhibitRule:
+    """Alertmanager inhibition rule."""
+
+    source_matchers: list[str] = field(default_factory=list)
+    target_matchers: list[str] = field(default_factory=list)
+    equal: list[str] = field(default_factory=lambda: ["alertname", "service"])
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to Alertmanager config format."""
+        return {
+            "source_matchers": self.source_matchers,
+            "target_matchers": self.target_matchers,
+            "equal": self.equal,
+        }
+
+
+@dataclass
+class AlertmanagerConfig:
+    """Complete Alertmanager configuration."""
+
+    route: Route
+    receivers: list[Receiver] = field(default_factory=list)
+    inhibit_rules: list[InhibitRule] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to Alertmanager config format."""
+        return {
+            "route": self.route.to_dict(),
+            "receivers": [r.to_dict() for r in self.receivers],
+            "inhibit_rules": [ir.to_dict() for ir in self.inhibit_rules],
+        }
+
+    def to_yaml(self) -> str:
+        """Convert to YAML string."""
+        return yaml.dump(self.to_dict(), default_flow_style=False, sort_keys=False)
+
+    def write(self, path: Path) -> None:
+        """Write configuration to file."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w") as f:
+            f.write("# Alertmanager configuration generated by NthLayer\n")
+            f.write("# Do not edit manually - regenerate with: nthlayer apply\n\n")
+            f.write(self.to_yaml())
+
+
+def generate_alertmanager_config(
+    service_name: str,
+    team: str,
+    pagerduty_integration_key: str,
+    support_model: str = "self",
+    tier: str = "medium",
+    sre_integration_key: str | None = None,
+) -> AlertmanagerConfig:
+    """
+    Generate Alertmanager configuration for a service.
+
+    Args:
+        service_name: Name of the service
+        team: Team owning the service
+        pagerduty_integration_key: PagerDuty Events API v2 integration key
+        support_model: Support model (self, shared, sre, business_hours)
+        tier: Service tier (critical, high, medium, low)
+        sre_integration_key: Optional SRE PagerDuty integration key for routing
+
+    Returns:
+        AlertmanagerConfig with receivers and routes
+    """
+    receivers: list[Receiver] = []
+    routes: list[Route] = []
+
+    # Create team receiver
+    team_receiver = Receiver(
+        name=f"{team}-pagerduty",
+        pagerduty_configs=[
+            PagerDutyReceiver(
+                service_key=pagerduty_integration_key,
+                severity=_tier_to_severity(tier),
+                component=service_name,
+                group=team,
+            )
+        ],
+    )
+    receivers.append(team_receiver)
+
+    # Create SRE receiver if integration key provided
+    if sre_integration_key:
+        sre_receiver = Receiver(
+            name="sre-pagerduty",
+            pagerduty_configs=[
+                PagerDutyReceiver(
+                    service_key=sre_integration_key,
+                    severity="critical",
+                    component=service_name,
+                    group="sre",
+                )
+            ],
+        )
+        receivers.append(sre_receiver)
+
+        # Add route for SRE routing label
+        sre_route = Route(
+            receiver="sre-pagerduty",
+            matchers=['routing="sre"'],
+            group_by=["alertname", "service"],
+        )
+        routes.append(sre_route)
+
+    # Create default route to team
+    default_route = Route(
+        receiver=f"{team}-pagerduty",
+        matchers=[f'service="{service_name}"'],
+        group_by=["alertname", "service"],
+        group_wait=_tier_to_group_wait(tier),
+        repeat_interval=_tier_to_repeat_interval(tier),
+    )
+    routes.append(default_route)
+
+    # Create root route
+    root_route = Route(
+        receiver=f"{team}-pagerduty",
+        group_by=["alertname", "service"],
+        routes=routes,
+    )
+
+    # Create inhibit rules
+    inhibit_rules = [
+        # Critical inhibits warning for same alert
+        InhibitRule(
+            source_matchers=['severity="critical"'],
+            target_matchers=['severity="warning"'],
+            equal=["alertname", "service"],
+        ),
+    ]
+
+    return AlertmanagerConfig(
+        route=root_route,
+        receivers=receivers,
+        inhibit_rules=inhibit_rules,
+    )
+
+
+def _tier_to_severity(tier: str) -> str:
+    """Map service tier to PagerDuty severity."""
+    return {
+        "critical": "critical",
+        "high": "error",
+        "medium": "warning",
+        "low": "info",
+    }.get(tier.lower(), "warning")
+
+
+def _tier_to_group_wait(tier: str) -> str:
+    """Map service tier to group wait time."""
+    return {
+        "critical": "10s",
+        "high": "30s",
+        "medium": "1m",
+        "low": "5m",
+    }.get(tier.lower(), "30s")
+
+
+def _tier_to_repeat_interval(tier: str) -> str:
+    """Map service tier to repeat interval."""
+    return {
+        "critical": "1h",
+        "high": "2h",
+        "medium": "4h",
+        "low": "12h",
+    }.get(tier.lower(), "4h")

nthlayer_generate/alerts/__init__.py

@@ -0,0 +1,17 @@
+"""
+NthLayer Alerts Module
+
+Automatic alert generation from awesome-prometheus-alerts templates.
+
+Features:
+- 580+ battle-tested alerting rules
+- Automatic dependency detection
+- Tier-based filtering
+- Multi-platform support (Prometheus, Datadog, CloudWatch)
+"""
+
+from .loader import AlertTemplateLoader
+from .models import AlertRule
+from .validator import ValidationResult, validate_and_fix_alert
+
+__all__ = ["AlertRule", "AlertTemplateLoader", "ValidationResult", "validate_and_fix_alert"]

nthlayer_generate/alerts/loader.py

@@ -0,0 +1,206 @@
+"""
+Alert Template Loader
+
+Loads alerting rules from awesome-prometheus-alerts templates.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import structlog
+import yaml
+
+from .models import AlertRule
+
+logger = structlog.get_logger()
+
+
+class AlertTemplateLoader:
+    """
+    Load alerting rules from awesome-prometheus-alerts templates.
+
+    Templates are organized by technology:
+        templates/databases/postgres.yaml
+        templates/databases/mysql.yaml
+        templates/proxies/nginx.yaml
+        etc.
+
+    Usage:
+        loader = AlertTemplateLoader()
+        alerts = loader.load_technology("postgres")
+        # Returns List[AlertRule] for PostgreSQL
+    """
+
+    def __init__(self, templates_dir: Optional[Path] = None):
+        """
+        Initialize loader.
+
+        Args:
+            templates_dir: Path to templates directory.
+                          Defaults to ./templates relative to this file.
+        """
+        if templates_dir is None:
+            templates_dir = Path(__file__).parent / "templates"
+
+        self.templates_dir = Path(templates_dir)
+        self.cache: Dict[str, List[AlertRule]] = {}
+
+        logger.debug("alert_template_loader_init", templates_dir=str(self.templates_dir))
+
+    def load_technology(self, technology: str) -> List[AlertRule]:
+        """
+        Load alerts for a specific technology.
+
+        Args:
+            technology: Technology name (e.g., "postgres", "redis", "nginx")
+
+        Returns:
+            List of AlertRule objects for that technology
+
+        Raises:
+            ValueError: If technology not found
+        """
+        # Check cache first
+        if technology in self.cache:
+            logger.debug(f"Returning cached alerts for {technology}")
+            return self.cache[technology]
+
+        # Find template file
+        template_file = self._find_template(technology)
+        if not template_file:
+            logger.warning(f"No template found for technology: {technology}")
+            return []
+
+        # Load and parse
+        alerts = self._load_from_file(template_file, technology)
+
+        # Cache results
+        self.cache[technology] = alerts
+
+        logger.debug(
+            "alerts_loaded", technology=technology, count=len(alerts), template=str(template_file)
+        )
+        return alerts
+
+    def _find_template(self, technology: str) -> Optional[Path]:
+        """
+        Find template file for a technology.
+
+        Searches across all categories (databases, proxies, orchestrators, etc.)
+        with fuzzy matching (postgres, postgresql, pg all match postgres.yaml)
+        """
+        # Normalize technology name
+        tech_lower = technology.lower()
+
+        # Common aliases
+        aliases = {
+            "pg": "postgres",
+            "postgresql": "postgres",
+            "mysql": "mysql",
+            "mariadb": "mysql",
+            "mongo": "mongodb",
+            "mongodb": "mongodb",
+            "k8s": "kubernetes",
+            "kubernetes": "kubernetes",
+        }
+
+        # Try alias first
+        if tech_lower in aliases:
+            tech_lower = aliases[tech_lower]
+
+        # Search for exact match
+        for category_dir in self.templates_dir.iterdir():
+            if not category_dir.is_dir():
+                continue
+
+            template_file = category_dir / f"{tech_lower}.yaml"
+            if template_file.exists():
+                return template_file
+
+        # Try fuzzy match
+        for category_dir in self.templates_dir.iterdir():
+            if not category_dir.is_dir():
+                continue
+
+            for template_file in category_dir.glob("*.yaml"):
+                if tech_lower in template_file.stem.lower():
+                    return template_file
+
+        return None
+
+    def _load_from_file(self, template_file: Path, technology: str) -> List[AlertRule]:
+        """
+        Load alerts from a YAML template file.
+
+        Expected format (awesome-prometheus-alerts):
+            groups:
+              - name: <technology>
+                rules:
+                  - alert: AlertName
+                    expr: <promql>
+                    for: 5m
+                    labels:
+                      severity: critical
+                    annotations:
+                      summary: Alert summary
+                      description: Alert description
+        """
+        try:
+            with open(template_file) as f:
+                data = yaml.safe_load(f)
+        except (FileNotFoundError, yaml.YAMLError, OSError) as e:
+            logger.error(f"Failed to load {template_file}: {e}")
+            return []
+
+        # Determine category from parent directory
+        category = template_file.parent.name
+
+        # Parse rules
+        alerts = []
+        for group in data.get("groups", []):
+            for rule_dict in group.get("rules", []):
+                if "alert" not in rule_dict:
+                    # Skip recording rules (not alerts)
+                    continue
+
+                try:
+                    alert = AlertRule.from_dict(rule_dict, technology=technology, category=category)
+                    alerts.append(alert)
+                except (KeyError, ValueError, TypeError) as e:
+                    logger.warning(f"Failed to parse alert {rule_dict.get('alert')}: {e}")
+
+        return alerts
+
+    def list_available_technologies(self) -> List[str]:
+        """
+        List all available technologies with templates.
+
+        Returns:
+            List of technology names (e.g., ["postgres", "redis", "nginx"])
+        """
+        technologies = []
+
+        for category_dir in self.templates_dir.iterdir():
+            if not category_dir.is_dir():
+                continue
+
+            for template_file in category_dir.glob("*.yaml"):
+                tech = template_file.stem
+                technologies.append(tech)
+
+        return sorted(technologies)
+
+    def get_category_for_technology(self, technology: str) -> Optional[str]:
+        """
+        Get the category (databases, proxies, etc.) for a technology.
+
+        Args:
+            technology: Technology name
+
+        Returns:
+            Category name or None if not found
+        """
+        template_file = self._find_template(technology)
+        if template_file:
+            return template_file.parent.name
+        return None