debugging-mwaa-workflow

调试 MWAA 工作流

AWS MCP 服务（可选，但推荐）： 通过 AWS MCP 服务运行此技能中的 AWS CLI 命令，可获得沙盒执行和审计日志记录。这里的每条命令也都适用于普通的 AWS CLI，因此此技能不要求使用 MCP 服务或任何仅限 MCP 的工具。

诊断并查明 Amazon MWAA 工作流故障的根本原因，然后报告根本原因、 影响和建议的补救措施。先按类型分流，再运行通用的 4 步诊断流程。

防护措施 — 此技能自身文件的位置（MCP 与本地安装）

此技能可以通过两种方式加载，它们会从不同位置解析技能自带的 文件。读取参考资料前，请先确定技能的加载方式：

• 通过 AWS MCP retrieve_skill 工具加载： 此技能未安装在本地文件系统中。你必须通过 retrieve_skill 并使用 file 参数获取每份参考资料（例如 file="references/failure-catalog.md"），然后阅读返回的内容。不要在本地对这些路径使用 file_read——它们在磁盘上并不存在。
• 本地安装（例如 .kiro/skills/debugging-mwaa-workflow/ 或 ~/.claude/skills/debugging-mwaa-workflow/）：使用相对路径从本地技能目录 读取文件。

此区别仅适用于技能自身打包的文件。用户数据和会话产物始终从用户的工作 目录读取并写入。切勿通过 retrieve_skill 获取或写入客户数据。

步骤 0：检测类型并确定故障范围

检测类型

1. 如果环境名称可通过 aws mwaa get-environment 解析，则该环境为已预置型。
2. workflow/... ARN 或任何 aws mwaa-serverless 上下文都表示该环境为无服务器型。单独的运行标识符不能表明类型——已预置型 DAG 运行也有运行 ID。
3. 如果两种信号都不存在，请询问：目标是 **MWAA 已预置型（Python DAG）**还是 MWAA 无服务器型（YAML 工作流）？

按复杂程度分流

• 简单 — 单个具名任务或运行失败，且异常明确。跳到步骤 2 检查该任务。
• 标准 — 运行失败，原因未知。执行完整的步骤 1 至步骤 4 排查流程。
• 复杂 — 间歇性故障或影响整个环境（多个 DAG、“昨天还好好的”、没有任何内容出现）。执行完整排查流程，重点关注步骤 3。

步骤 1：识别故障

已预置型： 通过 aws mwaa invoke-rest-api 列出失败的 DAG 运行和任务实例（路径 /dags/{id}/dagRuns 和 /dags/{id}/dagRuns/{run_id}/taskInstances）。如果 invoke-rest-api 报错 （RestApiClientException），则改查 Scheduler 和 DAGProcessing 日志组。通过 aws mwaa get-environment 获取版本和配置。参见 references/provisioned-diagnostics.md。

无服务器型： 运行 aws mwaa-serverless list-workflow-runs，然后运行 get-workflow-run。读取 RunDetail.ErrorMessage——如果 TaskInstances 为空且包含解析器消息，则是定义错误；如果 TaskInstances 已填充且出现 Workflow execution failed，则是任务执行失败。参见 references/serverless-diagnostics.md。

步骤 2：获取错误详情并分类

排除模板化内容，提取真实异常：

已预置型： 先读取 Task 日志组，然后根据症状读取 Worker/Scheduler/ DAGProcessing 日志组。

无服务器型： 先运行 list-task-instances，然后运行 get-task-instance 获取每个 任务的 LogStream，再在 CloudWatch 中读取该日志流。

然后按照优先级顺序分类——infra、drift、code-data——使用 references/failure-catalog.md。类别决定步骤 3 的检查项。

步骤 3：检查上下文（原因）

根据 references/failure-catalog.md 中匹配类别，执行上下文检查。不要只看表面异常：SIGKILL 意味着内存不足；代码未变却出现新的导入错误，意味着环境漂移；传感器超时则意味着上游健康状况异常。

步骤 4：提供可执行的输出

严格按以下结构报告：

Root Cause: <one-line diagnosis with the evidence that proves it>
Impact: <what failed, which runs, blast radius>
Immediate Fix: <the smallest change that unblocks>
Prevention: <the change that stops recurrence>
Commands: <exact read-only commands run, plus remediation commands for the user to run>

仅执行只读操作。对于会改变状态的修复措施（Provisioned 环境中的清除／重新运行／回填；Serverless 环境中的 start-workflow-run 或修复并重新部署），将其作为命令提供给用户执行，并说明影响。切勿自行执行（生产环境安全要求）。

对于修复并重新部署路径，请使用 authoring-mwaa-workflow 重新生成符合要求的制品。

注意事项

• Serverless 没有 Airflow Web UI、REST API 或 CLI 令牌。请勿尝试对 Serverless 使用 create-web-login-token、invoke-rest-api 或任何 Airflow REST 路径。
• 对于 Provisioned，始终使用 aws mwaa invoke-rest-api（而非 create-web-login-token + curl）。即使没有网络访问权限，invoke-rest-api 也能访问仅限 VPC 的 Web 服务器。
• GetWorkflowRun.RunDetail.ErrorMessage 可区分定义错误（TaskInstances 为空）和任务执行失败（Workflow execution failed，且 TaskInstances 已填充）。在获取任务日志之前先读取它。
• Serverless 日志组的默认路径为 /aws/mwaa-serverless/{workflow-id}/，但也可能使用自定义日志组；在假设路径之前，请通过 get-workflow 的 LoggingConfiguration 确认。
• DAG 未显示的原因有多种——导入／解析错误、调度器扫描间隔（scheduler.dag_dir_list_interval，或 Airflow 3.x 中的 dag_processor.refresh_interval）尚未到期、dag_id 冲突或 S3 同步延迟——而 DAG 本身损坏的情况并不常见。请通过 invoke-rest-api 检查 GET /importErrors 和 GET /dags/{dag_id}（以及 DAGProcessing 日志）；在断定代码有问题之前，请参阅故障目录中的“DAG 未显示在 UI 中”检查清单。
• Worker 的 SIGKILL 表示内存不足。建议将工作迁移到 Glue／EMR／Lambda；仅扩容 Worker 无法解决单个任务的内存压力。
• MWAA 会在环境更新时重新解析依赖，因此即使 DAG 未更改，也可能在导入时开始失败。对于代码未变却发生的导入失败，应按环境漂移处理。
• Serverless 的 PythonOperator／BashOperator 任务会从 --code 软件包运行自定义代码。如果运行因软件包提取失败或遇到 ModuleNotFoundError 而失败，这是软件包问题（平台不匹配的 wheel、缺少依赖或目录结构错误），而非 YAML 定义错误。请参阅故障目录中的 Serverless 自定义代码部分。

故障排查

错误	原因	修复方法
RestApiClientException（Provisioned）	执行角色范围配置错误或服务错误	回退到 Scheduler／DAGProcessing 日志组
get-workflow-run 出现 ResourceNotFoundException	工作流 ARN 或运行 ID 错误	使用 list-workflow-runs 重新列出
任务日志流为空（Serverless）	假定的日志组错误	从 get-workflow 读取 LoggingConfiguration
没有任务日志，但运行状态为 FAILED	定义／解析错误	读取 RunDetail.ErrorMessage；修复 YAML

参考资料

• references/provisioned-diagnostics.md — Provisioned 数据源和只读命令
• references/serverless-diagnostics.md — Serverless API、日志组和故障类别
• references/failure-catalog.md — 按类别划分的上下文检查和修复措施

安全注意事项

• 默认只读：诊断仅使用读取、列出和描述调用。 修复操作（清除／重新运行／回填、IAM 或密钥策略更改）仅以 命令形式提供给用户运行，绝不自主执行。
• IAM 最小权限原则：当 AccessDenied 确实是权限不足时， 根据错误建议最小范围的 Action／Resource，绝不使用通配符； 将这类情况与资源不存在的拼写错误区分开（此时不要扩大 IAM 权限）。
• 跨账户：KMS 密钥策略／角色切换更改需经人工审核，并与资源所有者协调。
• 不暴露机密：不要在诊断输出中展示日志或 API 响应里的凭据或连接字符串。