Add eks-node-join-diagnostic skill - #56
Open
LearningNewbie wants to merge 2 commits into
Open
Conversation
Diagnoses why EKS worker nodes fail to join or register with a cluster. Performs 64 read-only, API-side checks across 25 failure domains (IAM/auth, security groups, VPC/DNS, bootstrap, AMI, STS, Karpenter, containerd/runtime, VPC CNI IP management, kernel/OS compatibility, credential lifecycle, control plane pressure, launch template edge cases, admission webhooks, EKS addon conflicts, network edge cases, instance tagging, and control plane audit logs) without requiring SSM/SSH access to the node. Uses adaptive depth routing: primary checks (NJ1-NJ27) stay inline in SKILL.md for the common case, extended checks (NJ28-NJ64) load from references/extended-checks.md only when needed. Includes a complementary handoff table to the aws-eks-node-diagnostics-mcp server's node-side log tools for confirmation when SSM is available. Validated against a live EKS Auto Mode cluster: correctly adapted NJ3/NJ4 for Auto Mode (no managed node groups expected) and correctly diagnosed a dual API_AND_CONFIG_MAP auth-mode conflict. Also updates llms.txt with the new skill entry.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds the EKS Node Join Diagnostic skill (
skills/eks-node-join-diagnostic): a read-only, API-side diagnostic skill that identifies why Amazon EKS worker nodes fail to join or register with a cluster, covering 64 failure modes across 25 domains — without requiring SSM/SSH access to the node.Key design points:
• Adaptive depth routing: Three diagnostic paths (fast/standard/deep) based on symptom clarity. Clear-cut symptoms skip irrelevant checks; ambiguous symptoms walk the full decision tree; extended checks (NJ28–NJ64) load on demand only when primary checks pass.
• Progressive disclosure architecture: Primary checks (NJ1–NJ27) inline in SKILL.md (~400 lines); extended checks (NJ28–NJ64) in
references/extended-checks.md— keeps context lean for the common cases resolved by primary checks alone.• 64 checks across 25 failure domains: IAM/auth mapping, security groups, VPC/DNS, endpoints, bootstrap user-data, AMI compatibility, STS, Karpenter, containerd/runtime, VPC CNI IP management, kernel/OS compatibility, credential lifecycle, control plane pressure, launch template edge cases, admission webhooks, EKS addon conflicts, network edge cases, instance tagging, and control plane audit logs.
• Read-only and safe: Only
describe*,list*,get*APIs. All fixes are recommendations for human execution.• Complementary to
aws-eks-node-diagnostics-mcp: includes a handoff table mapping specific checks to MCP tool calls (collect,quick_triage,search,network_diagnostics) for node-side log confirmation when the MCP server and SSM access are available. Cross-referenced against that skill's A4 worker-node-join-failure SOP to close coverage gaps (added NJ62–NJ64 for instance tagging and control-plane audit-log checks as a result).Type of change
Testing
• Skill structure validated against repo contribution guidelines (SKILL.md + references + evals + CHANGELOG + .skilleval.yaml)
• Frontmatter passes DevOps Agent upload validation (description under 1024 chars)
•
evals/evals.json— 5 functional test scenarios with assertions covering managed node groups, private clusters, AMI compatibility, Karpenter, and IAM role path issues•
evals/eval_queries.json— 20 trigger accuracy queries (10 positive, 10 negative)• No secrets, AWS access keys, or real account IDs in committed files (verified via diff scan)
•
llms.txtentry addedLicense confirmation
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache License 2.0.