stevefulme1/aap-pagerduty-cisco-demo

# AAP + PagerDuty + Cisco Catalyst/Meraki 演示 **使用 Ansible Automation Platform、PagerDuty 和 Cisco 网络基础设施进行自动化事件生命周期管理** 此仓库演示了如何使用 Red Hat Ansible Automation Platform (AAP) 结合 Event-Driven Ansible (EDA)、PagerDuty 事件管理以及 Cisco Catalyst 交换机和 Meraki 设备，实现网络事件检测、升级、修复和解决的端到端自动化。 ## 架构 ``` ┌─────────────────┐ │ Cisco Catalyst │ │ Switches │────┐ └─────────────────┘ │ │ SNMP/Syslog ┌─────────────────┐ │ Alerts │ Cisco Meraki │────┤ │ Devices │ │ └─────────────────┘ │ ▼ ┌──────────────┐ │ PagerDuty │ │ Platform │ └──────┬───────┘ │ │ Webhook │ (Incident Created) ▼ ┌──────────────┐ │ EDA │ │ Controller │ │ (Rulebook) │ └──────┬───────┘ │ │ Trigger Workflow ▼ ┌──────────────┐ │ AAP │ │ Controller │ │ (Playbook) │ └──────┬───────┘ │ │ Execute │ Remediation ▼ ┌──────────────────────────┐ │ │ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ Cisco │ │ PagerDuty │ │ Devices │ │ Resolve │ │ (Fix) │ │ Incident │ └─────────────┘ └─────────────┘ ``` ## 前提条件 - **Red Hat Ansible Automation Platform 2.5+**，包含： - Automation Controller（用于作业编排） - Event-Driven Ansible Controller（用于规则书激活） - Private Automation Hub（可选，用于内容分发） - **PagerDuty 账户**，包含： - API 访问令牌（v2 REST API） - 配置了 Events API v2 集成的服务 - Webhook 订阅功能 - **Cisco 基础设施**： - 具有网络访问权限的 Cisco Catalyst 交换机 (IOS) - 具有 Dashboard API 访问权限的 Cisco Meraki 设备 - 或用于测试的 GNS3/CML 实验室环境 - **网络连接**： - AAP 可以访问 Cisco 设备（IOS 使用 SSH，Meraki API 使用 HTTPS） - PagerDuty 可以访问 EDA Controller 的 webhook 端点（公网 IP 或 ngrok） ## 仓库结构 ``` aap-pagerduty-cisco-demo/ ├── collections/ │ └── requirements.yml # Ansible collections dependencies ├── inventory/ │ └── hosts.yml # Sample inventory (switches, Meraki, servers) ├── group_vars/ │ └── all.yml # Global variables and vault references ├── playbooks/ │ ├── remediate_port_flap.yml # Fix flapping switch ports │ ├── remediate_high_cpu.yml # Restart high-CPU processes │ ├── remediate_meraki_offline.yml # Reboot offline Meraki device │ └── resolve_incident.yml # Close PagerDuty incident ├── rulebooks/ │ └── pagerduty_cisco.yml # EDA rulebook for PagerDuty webhooks └── README.md ``` ## 设置说明 ### 1. 安装 Collections ``` cd ~/Documents/aap-pagerduty-cisco-demo ansible-galaxy collection install -r collections/requirements.yml ``` ### 2. 配置 PagerDuty 集成 #### 创建 API Token 1. 登录到 PagerDuty → **Integrations** → **API Access Keys** 2. 创建一个新的 **General Access** API 密钥（v2 REST API） 3. 记下该密钥（以 `u+` 开头） #### 创建 Events 集成 1. 导航至 **Services** → 选择您的服务 → **Integrations** 2. 添加 **Events API v2** 集成 3. 复制 **Integration Key**（用于创建事件） #### 配置 Webhook 1. 转到 **Integrations** → **Generic Webhooks (v3)** 2. 创建一个新的 webhook 订阅 3. 将端点设置为您的 EDA Controller webhook URL： https://:5000/pagerduty 4. 订阅事件类型： - `incident.triggered` - `incident.acknowledged` - `incident.resolved` 5. 如果使用身份验证，请添加自定义标头 ### 3. 配置 EDA Controller #### 创建决策环境 确保您的决策环境包含： - `ansible.eda` collection - `pagerduty` Python SDK (`pip install pagerduty`) #### 创建项目 1. 在 EDA Controller UI 中，创建一个新项目 2. 指向该 Git 仓库 3. 同步项目 #### 创建规则书激活 1. **Name**: `PagerDuty Cisco Remediation` 2. **Project**: 选择上面创建的项目 3. **Rulebook**: `rulebooks/pagerduty_cisco.yml` 4. **Decision Environment**: 选择包含所需 collection 的环境 5. **Credentials**: - 添加 PagerDuty API 凭据（带有 `api_key` 字段的自定义凭据类型） - 添加 Cisco 设备凭据（Network 凭据类型） - 添加 Meraki API 凭据（带有 `api_key` 字段的自定义凭据类型） 6. **Restart Policy**: `on-failure` 7. **Enable** 该激活 ### 4. 配置 Automation Controller #### 创建凭据 1. **PagerDuty API**: - 类型：自定义凭据（或使用 CyberArk/Vault 查找） - 字段：`api_key`, `service_id`, `integration_key` 2. **Cisco Catalyst**: - 类型：Network - Username: `admin` - Password: (使用 Ansible Vault) - Authorize: yes - Authorize Password: (enable 密码) 3. **Meraki API**: - 类型：自定义凭据 - 字段：`api_key`, `org_id` #### 创建清单 1. 导入 `inventory/hosts.yml` 或使用动态清单 2. 将网络凭据分配给 `switches` 组 3. 验证连接性：使用 ad-hoc `ios_facts` 模块进行测试 #### 创建作业模板 1. **Remediate Port Flap**: - Playbook: `playbooks/remediate_port_flap.yml` - Inventory: Cisco Inventory - Credentials: Cisco Catalyst - Extra vars: 提示输入 `interface` 和 `pagerduty_incident_id` 2. **Remediate High CPU**: - Playbook: `playbooks/remediate_high_cpu.yml` - Inventory: Linux Servers - Credentials: Machine credential - Extra vars: 提示输入 `process_name` 和 `pagerduty_incident_id` 3. **Remediate Meraki Offline**: - Playbook: `playbooks/remediate_meraki_offline.yml` - Inventory: Meraki Devices - Credentials: Meraki API - Extra vars: 提示输入 `serial` 和 `pagerduty_incident_id` 4. **Resolve PagerDuty Incident**: - Playbook: `playbooks/resolve_incident.yml` - Credentials: PagerDuty API - Extra vars: 提示输入 `incident_id` ### 5. 创建 Vault 文件 使用 Ansible Vault 加密机密信息： ``` ansible-vault create group_vars/vault.yml ``` 添加以下变量： ``` --- vault_pagerduty_api_key: "" vault_pagerduty_integration_key: "" vault_meraki_api_key: "" vault_cisco_username: "" vault_cisco_password: "" vault_cisco_enable_password: "" ``` ### 6. 配置来自 Cisco 设备的 Webhooks #### Cisco Catalyst（通过 Syslog 发送至 PagerDuty） 配置 syslog 转发到带有 PagerDuty 集成的日志聚合器（例如 Splunk、ELK），或使用 EEM 脚本直接将 HTTPS 事件发送到 PagerDuty Events API v2。 用于端口震荡的 EEM 脚本示例： ``` event manager applet PORT_FLAP event syslog pattern "LINK-3-UPDOWN" action 1.0 cli command "enable" action 2.0 syslog msg "Port flap detected, sending to PagerDuty" action 3.0 ... ``` #### Cisco Meraki（Webhook 告警） 1. 登录到 Meraki Dashboard → **Network-wide** → **Alerts** 2. 配置告警设置（例如，设备离线、端口状态改变） 3. 添加 webhook 接收器： - URL: PagerDuty Events API v2 端点 - 或直接使用 URL: EDA Controller 端点 ## 运行演示 ### 测试场景 1：Catalyst 交换机上的端口震荡 1. **触发告警**： - 在 `catalyst-core-01` 的 `GigabitEthernet1/0/1` 接口上模拟端口震荡 - 或配置 EEM 来检测真实的震荡 2. **创建 PagerDuty 事件**： - 事件标题为：`Port Flap Detected on catalyst-core-01 Gi1/0/1` - 分配给值班工程师 3. **EDA 规则书触发**： - 接收到带有 `incident.triggered` 事件的 PagerDuty webhook - 解析事件详情（设备、接口） - 触发 AAP 作业模板：**Remediate Port Flap** 4. **AAP Playbook 执行**： - 通过 SSH 连接到 `catalyst-core-01` - 执行 `cisco.ios.ios_config` 以禁用/启用接口 - 使用 `cisco.ios.ios_command` 检查接口状态 - 使用备注更新 PagerDuty 事件 5. **事件解决**： - 修复 playbook 调用 **Resolve PagerDuty Incident** - PagerDuty 事件状态变更为 → `resolved` - 值班工程师收到解决通知 ### 测试场景 2：Meraki 设备离线 1. **触发告警**： - Meraki 设备 `Q2XX-YYYY-ZZZZ` 离线 - Meraki Dashboard 向 PagerDuty 发送 webhook 2. **创建 PagerDuty 事件**： - 事件：`Meraki Device Offline: meraki-switch-01` 3. **EDA 规则书触发**： - 匹配 `meraki_offline` 条件 - 触发 AAP 作业：**Remediate Meraki Offline** 4. **AAP Playbook 执行**： - 使用 `cisco.meraki.meraki_device` 模块 - 尝试通过 Dashboard API 重启 - 等待设备重新上线 - 验证连通性 5. **事件解决**： - 使用解决详情更新 PagerDuty - 事件自动关闭 ### 测试场景 3：Linux 服务器 CPU 使用率高 1. **触发告警**： - 监控系统（例如 Prometheus、Nagios）检测到 `web-server-01` 上的 CPU 使用率过高 - 告警转发至 PagerDuty 2. **创建 PagerDuty 事件**： - 事件：`High CPU Usage on web-server-01` 3. **EDA 规则书触发**： - 匹配 `high_cpu` 条件 - 触发 AAP 作业：**Remediate High CPU** 4. **AAP Playbook 执行**： - 通过 SSH 连接到 `web-server-01` - 识别消耗 CPU 最高的进程 - 重启进程或在必要时终止 - 验证 CPU 是否恢复正常 5. **事件解决**： - PagerDuty 事件解决并附带修复摘要 ## 预期流程 ``` Alert → PagerDuty Incident → EDA Webhook → Rulebook Match → AAP Job Trigger → Playbook Execution → Device Remediation → PagerDuty Update → Incident Resolved → Notification ``` **核心优势**： - **自动化事件响应**：对已知问题无需人工干预 - **降低 MTTR**：在检测后几秒钟内即开始修复 - **审计跟踪**：所有操作均记录在 PagerDuty 和 AAP 作业历史中 - **可扩展性**：使用相同的规则书处理数百台设备 - **灵活性**：轻松添加新的修复 playbook 和条件 ## 定制化 - **添加更多修复场景**：为 BGP peer 中断、VLAN 配置错误、DNS 故障等创建 playbook。 - **增强规则书**：使用 `ansible.eda.range` 进行基于严重程度的路由，或使用 `ansible.eda.kafka` 进行事件流处理。 - **集成 ServiceNow**：在处理 PagerDuty 事件的同时，创建 CMDB CIs 和变更请求。 - **多供应商支持**：使用各自的 Ansible collection 添加 Arista、Juniper 或 Fortinet 的 playbook。 ## 故障排除 - **EDA webhook 未接收事件**：检查防火墙规则，验证 PagerDuty webhook URL，检查 EDA 日志 (`podman logs `) - **AAP 作业失败并出现身份验证错误**：验证 Automation Controller 中的凭据，手动测试 SSH/API 连接 - **PagerDuty API 401 错误**：重新生成 API token，确保 `Authorization: Token token=` 标头格式正确 - **Meraki API 速率限制**：实施退避逻辑，使用 `meraki_action_batch` 进行批量操作 ## 许可证 GNU General Public License v3.0 或更高版本 完整的许可证文本请参见 [COPYING](https://www.gnu.org/licenses/gpl-3.0.txt)。 ## 贡献 欢迎贡献！请提交 issue 或 pull request 以提供： - Playbook 增强 - 其他设备供应商 - 改进的错误处理 - 文档更新 ## 参考 - [Ansible Automation Platform 文档](https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform/) - [Event-Driven Ansible 指南](https://ansible.readthedocs.io/projects/rulebook/) - [PagerDuty Events API v2](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgw-events-api-v2-overview) - [Cisco IOS Collection](https://docs.ansible.com/ansible/latest/collections/cisco/ios/) - [Cisco Meraki Collection](https://docs.ansible.com/ansible/latest/collections/cisco/meraki/)

标签：Ansible, Docker 部署, PagerDuty, 事件管理, 思科, 系统提示词, 网络运维, 自动化响应, 自动化运维, 逆向工具