Sample Eks Node Diagnostics MCP

EKS节点诊断MCP

⚠️ 概念验证（POC）： 这个项目是一个概念验证，应该首先在非生产环境中进行测试。在与生产工作负载一起使用之前，在过渡或开发帐户中进行彻底验证。

AWS DevOps代理的MCP服务器，用于使用SSM Automation从EKS工作节点收集和分析诊断日志。涵盖20多个日志源，包括kubelet、containerd、iptables、CNI config、路由表、dmesg、IPAMD等，这些工件位于节点操作系统上，无法通过Kubernetes API或CloudWatch访问。

想了解内部吗？ 看 建筑与设计 深入了解组件的工作原理、数据流、工具设计和安全模型。

______________________________________________________________________

先决条件

1.Node.js（v18.x或更高版本）

macOS（Homebrew）：

brew install node

Linux（Ubuntu/Debian）：

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

2.AWS CLI v2

macOS：

brew install awscli

Linux：

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

3.AWS-CDK-CLI

npm install -g aws-cdk

4.Python 3

大多数系统都预装了它：

python3 --version

5.AWS证书

您需要权限来创建IAM角色、Lambda函数、S3 Bucket、KMS密钥、Cognito用户池和BedrockAgentCore网关。

aws configure
# Or use AWS SSO:
aws sso login --profile your-profile
export AWS_PROFILE=your-profile

6.Worker节点上的crictl（适用于pod级别的tcpdump）

仅适用于 tcpdump_capture 和 podName/podNamespace默认情况下，EKS优化的AMI包括它。

______________________________________________________________________

部署

# Clone the repository
git clone https://github.com/aws-samples/sample-eks-node-diagnostics-mcp.git
cd sample-eks-node-diagnostics-mcp

# Make the script executable
chmod +x deploy.sh

# Deploy (defaults to us-east-1)
./deploy.sh

# Or deploy to a specific region
AWS_REGION=us-west-2 ./deploy.sh

交互式部署流程

部署脚本将引导您完成三个交互式提示：

步骤1——区域选择：

Which AWS regions should be scanned for EKS clusters?

  1) All enabled regions
  2) Current deploy region only (us-east-1)
  3) Enter a specific region

Select [1/2/3] (default: 1):

步骤2——集群选择：

Found 4 EKS cluster(s):

  1) prod-cluster    (us-east-1)
  2) dev-cluster     (us-east-1)
  3) analytics        (us-west-2)
  4) eu-cluster       (eu-west-1)

  a) All clusters

Select clusters (comma-separated numbers, or 'a' for all) [default: a]:

步骤3——节点角色选择：

Found 3 unique node role(s):

  1) arn:aws:iam::123456789012:role/eks-prod-node-role
     └─ eks-prod-node-role  (prod-cluster / us-east-1)
  2) arn:aws:iam::123456789012:role/eks-dev-node-role
     └─ eks-dev-node-role  (dev-cluster / us-east-1)
  3) arn:aws:iam::123456789012:role/eks-eu-node-role
     └─ eks-eu-node-role  (eu-cluster / eu-west-1)

  a) All roles

Select node roles (comma-separated numbers, or 'a' for all) [default: a]:

回退——手动输入ARN：

如果找不到EKS集群或节点角色，则脚本会提示您手动输入角色ARN：

WARNING: No EKS clusters found in the selected region(s).

Would you like to manually enter node role ARN(s)? [y/N]: y
Enter comma-separated role ARNs (e.g. arn:aws:iam::123456789012:role/MyNodeRole):
>

非交互/CI模式

直接提供角色ARN跳过所有提示：

# Via environment variable
EKS_NODE_ROLE_ARNS="arn:aws:iam::123456789012:role/MyNodeRole" ./deploy.sh

# Or as a positional argument
./deploy.sh EksNodeLogMcpStack arn:aws:iam::123456789012:role/MyNodeRole

# Multiple roles (comma-separated)
EKS_NODE_ROLE_ARNS="arn:aws:iam::123456789012:role/Role1,arn:aws:iam::123456789012:role/Role2" ./deploy.sh

部署什么

______________________________________________________________________

部署后：EKS节点IAM设置

什么是自动

如果您在交互式部署流程中选择了节点角色（或通过 EKS_NODE_ROLE_ARNS)，CDK堆栈会自动授予：

• S3存储桶策略： s3:PutObject, s3:GetBucketPolicyStatus, s3:GetBucketAcl 在原木桶上
• KMS密钥策略： kms:GenerateDataKey, kms:Encrypt, kms:Decrypt 关于加密密钥(kms:Decrypt 需要S3多部分上传大于~8 MiB的文件）

这些角色不需要手动设置S3或KMS。

如果在部署期间没有提供节点角色，则堆栈将回退到帐户范围的策略（帐户中的任何主体都可以上传）。这限制较少，但仍然有效。

你可能还需要什么

CDK堆栈唯一没有附加的是SSM代理管理的策略。EKS优化的AMI默认包括SSM代理，但IAM角色需要以下策略：

# Only needed if not already attached
aws iam attach-role-policy \
  --role-name  \
  --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

部署后添加节点角色

如果稍后添加新的EKS集群，请重新运行部署脚本——它将检测新的节点角色并自动更新S3存储桶和KMS密钥策略。

或者，直接传递新角色：

EKS_NODE_ROLE_ARNS="arn:aws:iam::123456789012:role/ExistingRole,arn:aws:iam::123456789012:role/NewRole" ./deploy.sh

每个集群的检查表

• \[\]部署期间选择了节点角色（或通过重新部署添加）
• \[\]节点角色具有 AmazonSSMManagedInstanceCore 管理策略（用于SSM代理）
• \[\]SSM代理正在节点上运行（EKS优化AMI上的默认设置）
• \[ \] AWSSupport-CollectEKSInstanceLogs 目标区域中存在SSM文档

______________________________________________________________________

DevOps代理中的配置

部署后，脚本输出MCP服务器配置所需的所有值：

值也保存到 mcp-config.txt 以供参考。

______________________________________________________________________

代理技能

A预制 代理技能 包含在 skills/ 教AWS DevOps Agent如何有效地使用此MCP服务器。该技能将调查工作流程、抗幻觉护栏和所有41个runbook程序加载到代理的上下文中，从而补充了运行时 list_sops/get_sop 工具。

上传技能

1. 导航至 技能 您的页面 代理空间运营商Web应用程序
2. 点击 添加技能 → 上传技巧
3. 上传 skills/eks-node-diagnostics.zip
4. 将代理类型设置为 通用的 （所有代理类型）
5. 点击 上传

有关更多详细信息，请参阅 AWS DevOps代理技能文档.

技能vs SOP：调查开始时的技能负荷（前期方法和陷阱）。SOP通过以下方式按需获取 get_sop （详细的分步程序）。两者结合使用可获得最佳效果。

______________________________________________________________________

运作原理

该服务器使MCP兼容代理能够从EKS工作节点收集完整的诊断包，对严重性分类的错误进行预索引，在不截断的情况下流式传输多GB日志文件，跨日志源关联事件，运行实时tcpdump捕获，比较节点，并遵循结构化的运行手册——所有这些都是通过分为5层的19个MCP工具完成的。

有关架构、数据流、工具设计、跨区域机制、安全模型和抗幻觉设计的详细演练，请参阅：

建筑与设计→

MCP工具（快速参考）

代理工作流

collect → status (poll) → validate → errors → search → correlate → read → summarize

Runbook库（41 SOP）

______________________________________________________________________

使用示例

基础调查

Node i-0abc123def in us-west-2 went NotReady around 3am. Collect its logs
and correlate what happened in the 5 minutes before it went down.

集群范围分类

We have a 200-node cluster and something is off. Do a dry run batch collection
first — show me which nodes you'd sample. Then collect from the unhealthy ones.

实时数据包捕获

Pods on node i-0abc123def can't reach the API server. Run a 2-minute tcpdump
filtered on port 443, then analyze — show me RST counts and retransmissions.

吊舱液位捕捉

DNS lookups are timing out. CoreDNS pod coredns-5d78c9869d-abc12 is on node
i-0abc123def in kube-system. Capture UDP port 53 from inside the pod for 60s.

SOP指导

I don't know what's wrong — just investigate. List the available SOPs, run a
general triage, and follow whichever runbook matches.

______________________________________________________________________

云形成输出

______________________________________________________________________

故障排除

______________________________________________________________________

清理

cdk destroy

S3铲斗具有 removalPolicy: RETAIN。如果需要，在堆栈销毁后手动删除。

______________________________________________________________________

许可证

本项目根据麻省理工学院无署名（MIT-0）许可证获得许可。看 许可证 文件。