API 와 MCP

무엇이 있나

여러 회사가 공개한 장애 보고서를 한 건씩 읽고, 같은 틀에 맞춰 정리한 사례 모음입니다. 지금 겪는 장애와 비슷한 사례를 찾아 보려는 엔지니어와, 그런 엔지니어를 돕는 AI 도구가 씁니다.

사례

사례 하나는 보고서 한 건입니다. 모든 사례에 같은 항목이 있습니다. 엔지니어가 본 증상, 장애를 촉발한 일, 원인, 문제가 난 구성 요소, 장애를 키운 기여 요인, 장애를 끝내려고 한 조치, 그 뒤에 조직이 하기로 한 일, 교훈, 원문 주소와 보관본 주소입니다.

모든 사례는 영어로 썼습니다. 한국어로도 쓴 사례가 있고, 그런 사례는 한국어로 받을 수 있습니다.

분류

사례마다 네 가지 분류가 있습니다. 원인, 구성 요소, 증상, 기여 요인입니다. 분류의 값은 정해진 목록에서 고릅니다. 예를 들어 원인에는 용량 한계, 설정 변경, 인증서 만료 같은 값이 있고, 구성 요소에는 CoreDNS, kubelet, VPC CNI 같은 값이 있습니다.

분류 값에는 이름이 두 가지 있습니다. 화면에 보이는 이름과, API 와 MCP 에서 쓰는 영문 식별자입니다. 인증서·자격 증명 만료라는 원인의 식별자는 certificate-expiry 이고, CoreDNS 라는 구성 요소의 식별자는 coredns 입니다. 식별자를 모를 때는 생각나는 단어로 찾을 수 있습니다. 방법은 아래에 적었습니다.

할 수 있는 일

증상으로 찾기. 지금 보이는 증상을 한 문장으로 적으면 가장 비슷한 사례부터 차례로 나옵니다. 찾은 사례를 원인, 구성 요소, 증상, 기여 요인별로 몇 건인지 세어서 함께 보여 줍니다. 그 숫자를 보면 이런 증상이 무엇 때문에 자주 나는지 알 수 있습니다.
사례 한 건 읽기. 사례 번호로 전체 내용을 받습니다. 같은 원인에 같은 구성 요소를 가진 다른 사례도 함께 받습니다.
분류로 거르기. 원인, 구성 요소, 증상, 기여 요인, 영역, 조직으로 사례 목록을 거릅니다.
분류 하나를 들여다보기. 분류 값 하나를 고르면 그 값을 가진 사례가 전부 나옵니다. 그 사례들에 다른 분류 값이 몇 건씩 있는지도 나옵니다. 예를 들어 DNS 조회 실패라는 증상을 고르면 그 증상이 어떤 원인에서 몇 번 나왔는지 보입니다. 증상 문장을 함께 주면 그 문장과 비슷한 사례만 남깁니다.
식별자 찾기. 생각나는 단어 몇 개를 주면 뜻이 가장 가까운 분류 값을 찾아 줍니다. cert ran out 이라고 주면 certificate-expiry 가 나옵니다.

AI 도구에 붙이기

MCP 서버 주소는 https://incidentlib-mcp.benchlet.com/mcp 입니다. 연결 방식은 Streamable HTTP 이고 주소만 등록하면 됩니다. 인증은 없습니다.

Claude Code 에서는 아래 명령 한 줄이면 됩니다.

claude mcp add --transport http incidentlib https://incidentlib-mcp.benchlet.com/mcp

Cursor 에서는 프로젝트의 .cursor/mcp.json 에 아래 내용을 넣습니다. MCP 서버를 주소로 등록하는 다른 도구에도 같은 주소를 넣으면 됩니다.

{
  "mcpServers": {
    "incidentlib": { "url": "https://incidentlib-mcp.benchlet.com/mcp" }
  }
}

Claude Desktop 에서는 설정의 Connectors 에서 사용자 지정 커넥터를 추가하고 위 주소를 넣습니다.

이렇게 물어보면 됩니다

Our pods stopped resolving DNS after CoreDNS restarted. Which public incidents look like this, and what caused them?

AI 는 아래처럼 도구를 부르고, 사례 번호와 원문 주소를 인용해서 답합니다.

search_incidents(symptoms="pods cannot resolve dns after coredns restarts", limit=5)
→ interpreted: [{ kind, slug, en, ko, alias }, …]
  total, results: [{ id, url, title, org, date, root_cause, symptoms, components, contributing, summary, snippet, source }, …], matched: [{ id, title, org, root_cause, … }, …], next_cursor
  facets: { root_causes: [{ slug, en, ko, count, cases }], components: [...], symptoms: [...], factors: [...], orgs: [...] }

get_incident(id="IL-0001")
→ symptoms_text, trigger, root_cause, components, contributing, summary, detection, remediation, action_items, lessons, sources, similar_cases

도구 다섯

search_incidents: 누군가 장애 증상을 말하면 가장 먼저 쓰는 도구입니다. 증상 문장을 넣으면 가장 비슷한 사례부터 차례로 나오고, 찾은 사례를 분류별로 센 숫자도 함께 옵니다. 문장 없이 분류 필터만 주면 그 값을 가진 사례 전부가 최근 것부터 나옵니다.
get_incident: 사례 번호를 알 때 전체 내용을 읽는 도구입니다. 같은 원인과 구성 요소를 가진 다른 사례도 함께 옵니다.
list_incidents: 특정 원인이나 구성 요소의 사례를 전부 보고 싶을 때 쓰는 도구입니다. 식별자로 거릅니다. 조건을 여럿 주면 모두 만족하는 사례만 나옵니다. 한 번에 한 페이지가 오고, 다음 페이지가 있으면 그 페이지 주소가 함께 옵니다.
get_topic: 분류 값 하나를 들여다보는 도구입니다. 그 값의 사례와, 그 사례들에 다른 분류 값이 몇 건씩 있는지가 옵니다. 증상 문장을 주면 비슷한 사례만 남깁니다.
vocab: 식별자를 찾는 도구입니다. 단어를 주면 뜻이 가까운 분류 값이 나오고, 단어 없이 부르면 모든 분류 값과 이름이 나옵니다.

한도

같은 주소에서는 1분에 60번까지 부를 수 있습니다. 넘으면 429 응답이 오고, 응답의 Retry-After 헤더에 몇 초 뒤에 다시 보내면 되는지 적혀 있습니다.

프로그램에서 부르기

기본 주소는 https://incidentlib-api.benchlet.com 입니다. 모든 호출은 GET 이고, 인증도 꼭 넣어야 하는 헤더도 없습니다. 응답은 JSON 이고 필드 이름은 소문자와 밑줄로 씁니다. 사례와 분류 값에는 늘 url 필드가 있고, 사람이 읽는 페이지 주소가 들어 있습니다.

증상으로 찾기

curl 'https://incidentlib-api.benchlet.com/search?q=pods+cannot+resolve+dns+after+coredns+restarts&limit=3'

아래는 실제 응답을 줄여서 보인 예시입니다. 검색이 찾은 사례의 수가 total 입니다. results 는 그중 한 페이지를 가장 비슷한 것부터 전부 담아 돌려주고, matched 는 찾은 사례 전부를 한 줄씩(번호, 제목, 조직, 날짜, 원인, 증상, 구성 요소, 기여 요인) 돌려줍니다. 다음 페이지가 있으면 next 에 그 주소가 옵니다. 검색어에서 찾은 분류 값이 interpreted 에 오고 그 값을 가진 사례는 위로 올라옵니다. 찾은 사례 전부를 분류별로 센 결과가 facets 입니다. 찾은 사례가 없으면 total 이 0 이고 results 와 matched 는 비어 있습니다.

{
  "query": "coredns oom",
  "interpreted": [
    {
      "kind": "component",
      "slug": "coredns",
      "en": "CoreDNS",
      "ko": "CoreDNS",
      "alias": "coredns",
      "url": "https://benchlet.com/incidentlib/app/components/coredns"
    },
    {
      "kind": "symptom",
      "slug": "oom-killed",
      "en": "OOMKilled",
      "ko": "OOMKilled",
      "alias": "oom",
      "url": "https://benchlet.com/incidentlib/app/symptoms/oom-killed"
    }
  ],
  "total": 23,
  "offset": 0,
  "results": [
    {
      "id": "IL-0102",
      "url": "https://benchlet.com/incidentlib/app/cases/IL-0102",
      "title": {
        "en": "CoreDNS pods on a production EKS cluster ran out of memory under a burst of new pods, endp…",
        "ko": "배포와 워커 오토스케일링 폭주가 겹치자 크기를 고정해 둔 CoreDNS 가 메모리 한도를 넘겨 재시작된 뒤 회복하지 못했고, Buildkite 사이트 전체가 약 …"
      },
      "org": "Buildkite",
      "org_slug": "buildkite",
      "date": "2026-08-25",
      "root_cause": "capacity",
      "contributing": [
        "no-spare-capacity",
        "automation-amplified",
        "… 2 more"
      ],
      "symptoms": [
        "service-unavailable",
        "dns-resolution-failures",
        "… 2 more"
      ],
      "components": [
        "coredns",
        "memory-limit",
        "… 2 more"
      ],
      "domain": [
        "kubernetes",
        "aws"
      ],
      "severity": "unknown",
      "summary": {
        "en": "Buildkite had spent four months moving its production workloads from AWS ECS to an AWS EKS…",
        "ko": "Buildkite 는 넉 달째 운영 워크로드를 AWS ECS 에서 AWS EKS 클러스터로 옮기고 있었고, 그동안 클러스터는 꾸준히 커졌다. 이 클러스터의 서비스…"
      },
      "match": {
        "field": "action_items",
        "lang": "ko",
        "ord": 2,
        "text": "CoreDNS 쿼리 처리 시간, 쿼리량, 고루틴 증가, 메모리 압박, OOM 재시작, 사용 가능한 레플리카 수에 직접 알림을 건다. 장기 추세도 용량 계획에 넣어…"
      },
      "sources": [
        {
          "url": "https://www.buildkitestatus.com/incidents/tm6746k61p73",
          "kind": "official-status",
          "license": "unknown",
          "archived": null
        }
      ]
    },
    {
      "id": "IL-0027",
      "url": "https://benchlet.com/incidentlib/app/cases/IL-0027",
      "title": {
        "en": "All CoreDNS pods landed on one node, the node ran out of memory, and DNS for the whole ser…",
        "ko": "CoreDNS 파드가 모두 한 노드에 몰린 채 그 노드의 메모리가 고갈되자 DNS 가 응답하지 못해 아이디어스 서비스 전체가 멈췄다"
      },
      "org": "Backpackr",
      "org_slug": "backpackr",
      "date": "2025-05-07",
      "root_cause": "capacity",
      "contributing": [
        "default-config-unchanged",
        "single-point-of-failure",
        "… 1 more"
      ],
      "symptoms": [
        "dns-resolution-failures",
        "intermittent-connection-failures",
        "… 3 more"
      ],
      "components": [
        "coredns",
        "dns-resolver",
        "… 3 more"
      ],
      "domain": [
        "kubernetes",
        "aws",
        "… 1 more"
      ],
      "severity": "unknown",
      "summary": {
        "en": "Backpackr runs the idus handmade marketplace and the Tumblbug crowdfunding platform on Ama…",
        "ko": "백패커는 아이디어스를 운영하는 EKS 클러스터를 처음 구성할 때 CoreDNS 를 따로 최적화하지 않고 기본 설정 그대로 두었다. CoreDNS 파드는 2개였고,…"
      },
      "match": {
        "field": "symptoms_text",
        "lang": "ko",
        "ord": 3,
        "text": "어느 시점에는 CoreDNS 파드가 모두 한 노드에 몰려 있었다. 그 노드의 메모리 사용률이 갑자기 치솟았고 노드에서 OOM 이 났다. kubelet 이 멈추면서…"
      },
      "sources": [
        {
          "url": "https://aws.amazon.com/ko/blogs/tech/optimizing-amazon-eks-journey-of-backpackr-part1",
          "kind": "blog",
          "license": "unknown",
          "archived": null
        }
      ]
    }
  ],
  "next": "https://incidentlib-api.benchlet.com/search?q=coredns+oom&limit=3&lang=en&after=cmFuazoz",
  "matched": [
    {
      "id": "IL-0102",
      "url": "https://benchlet.com/incidentlib/app/cases/IL-0102",
      "title": {
        "en": "CoreDNS pods on a production EKS cluster ran out of memory under a burst of new pods, endp…",
        "ko": "배포와 워커 오토스케일링 폭주가 겹치자 크기를 고정해 둔 CoreDNS 가 메모리 한도를 넘겨 재시작된 뒤 회복하지 못했고, Buildkite 사이트 전체가 약 …"
      },
      "org": "Buildkite",
      "org_slug": "buildkite",
      "date": "2026-08-25",
      "severity": "unknown",
      "root_cause": "capacity",
      "symptoms": [
        "service-unavailable",
        "dns-resolution-failures",
        "… 2 more"
      ],
      "components": [
        "coredns",
        "memory-limit",
        "… 2 more"
      ],
      "contributing": [
        "no-spare-capacity",
        "automation-amplified",
        "… 2 more"
      ]
    },
    {
      "id": "IL-0027",
      "url": "https://benchlet.com/incidentlib/app/cases/IL-0027",
      "title": {
        "en": "All CoreDNS pods landed on one node, the node ran out of memory, and DNS for the whole ser…",
        "ko": "CoreDNS 파드가 모두 한 노드에 몰린 채 그 노드의 메모리가 고갈되자 DNS 가 응답하지 못해 아이디어스 서비스 전체가 멈췄다"
      },
      "org": "Backpackr",
      "org_slug": "backpackr",
      "date": "2025-05-07",
      "severity": "unknown",
      "root_cause": "capacity",
      "symptoms": [
        "dns-resolution-failures",
        "intermittent-connection-failures",
        "… 3 more"
      ],
      "components": [
        "coredns",
        "dns-resolver",
        "… 3 more"
      ],
      "contributing": [
        "default-config-unchanged",
        "single-point-of-failure",
        "… 1 more"
      ]
    },
    "… 3 more"
  ],
  "facets": {
    "root_causes": [
      {
        "slug": "capacity",
        "en": "Capacity exhaustion",
        "ko": "용량 한계",
        "count": 15,
        "cases": [
          "IL-0102",
          "IL-0027",
          "… 13 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/root-causes/capacity"
      },
      {
        "slug": "config-change",
        "en": "Configuration change",
        "ko": "설정 변경",
        "count": 3,
        "cases": [
          "IL-0004",
          "IL-0019",
          "… 1 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/root-causes/config-change"
      },
      "… 1 more"
    ],
    "components": [
      {
        "slug": "coredns",
        "en": "CoreDNS",
        "ko": "CoreDNS",
        "count": 11,
        "cases": [
          "IL-0102",
          "IL-0027",
          "… 9 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/components/coredns"
      },
      {
        "slug": "memory-limit",
        "en": "Container memory limit",
        "ko": "컨테이너 메모리 한도",
        "count": 7,
        "cases": [
          "IL-0102",
          "IL-0027",
          "… 5 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/components/memory-limit"
      },
      "… 1 more"
    ],
    "symptoms": [
      {
        "slug": "oom-killed",
        "en": "OOMKilled",
        "ko": "OOMKilled",
        "count": 11,
        "cases": [
          "IL-0102",
          "IL-0027",
          "… 9 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/symptoms/oom-killed"
      },
      {
        "slug": "dns-resolution-failures",
        "en": "DNS resolution failures",
        "ko": "DNS 조회 실패",
        "count": 9,
        "cases": [
          "IL-0102",
          "IL-0027",
          "… 7 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/symptoms/dns-resolution-failures"
      },
      "… 1 more"
    ],
    "factors": [
      {
        "slug": "default-config-unchanged",
        "en": "Unreviewed defaults",
        "ko": "기본 설정 방치",
        "count": 7,
        "cases": [
          "IL-0027",
          "IL-0001",
          "… 5 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/factors/default-config-unchanged"
      },
      {
        "slug": "no-spare-capacity",
        "en": "No headroom",
        "ko": "여유 용량 부재",
        "count": 6,
        "cases": [
          "IL-0102",
          "IL-0004",
          "… 4 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/factors/no-spare-capacity"
      },
      "… 1 more"
    ],
    "orgs": [
      {
        "slug": "uk-ministry-of-justice",
        "en": "UK Ministry of Justice",
        "ko": "UK Ministry of Justice",
        "count": 2,
        "cases": [
          "IL-0019",
          "IL-0020"
        ],
        "url": "https://benchlet.com/incidentlib/app/orgs/uk-ministry-of-justice"
      },
      {
        "slug": "zalando",
        "en": "Zalando",
        "ko": "Zalando",
        "count": 2,
        "cases": [
          "IL-0001",
          "IL-0031"
        ],
        "url": "https://benchlet.com/incidentlib/app/orgs/zalando"
      },
      "… 1 more"
    ]
  }
}

q 는 증상이고 문장이든 단어 몇 개든 됩니다. 꼭 있어야 합니다. limit 은 한 페이지에 몇 건을 받을지 정합니다. 기본은 5건이고 최대 50건입니다. after 에 앞 페이지의 next 가 담은 값을 주면 다음 페이지가 옵니다. lang=ko 를 붙이면 한국어가 있는 글은 한국어로 옵니다. root_cause, component, symptom, factor, domain 에 slug 를 주면 그 값을 가진 사례만 남고, org 에 조직의 slug 를 주면 그 조직의 사례만 남습니다. slug 는 facets, interpreted, /vocab 에서 얻습니다.

사례 한 건과 비슷한 사례

curl 'https://incidentlib-api.benchlet.com/cases/IL-0001'

{
  "id": "IL-0001",
  "org": "Zalando",
  "date": "2019-01-07",
  "docs": [
    "https://nodejs.org/docs/latest/api/dns.html#dns_implementation_considerations",
    "https://github.com/kubernetes/dns/issues/159#issuecomment-336449931",
    "… 4 more"
  ],
  "title": {
    "en": "Cluster-wide DNS outage after CoreDNS pods were OOM-killed again and again under a burst o…",
    "ko": "CoreDNS 파드가 메모리 한도 100Mi 에 걸려 OOM 으로 계속 죽으면서 쿠버네티스 클러스터 전체의 DNS 가 멈췄다"
  },
  "domain": [
    "kubernetes",
    "aws"
  ],
  "impact": {
    "scope": "all web product and outfit pages of the Zalando Fashion Store; DNS for the entire Kubernet…",
    "users": "unknown",
    "region": "unknown"
  },
  "review": {
    "written_by": "session",
    "reviewed_at": null,
    "reviewed_by": null
  },
  "lessons": {
    "en": "The Kubernetes DNS setup was far from resilient enough: a single application could take do…",
    "ko": "쿠버네티스 DNS 구성은 충분히 튼튼하지 않았다. 애플리케이션 하나가 DNS 를 사실상 서비스 거부 공격하듯 몰아붙여 클러스터 전체를 멈추게 할 수 있어서는 안 …"
  },
  "related": [
    "IL-0005"
  ],
  "sources": [
    {
      "url": "https://github.com/zalando-incubator/kubernetes-on-aws/blob/dev/docs/postmortems/jan-2019-…",
      "kind": "github",
      "license": "unknown",
      "archived": "http://web.archive.org/web/20261004005813/https://github.com/zalando-incubator/kubernetes-…"
    }
  ],
  "summary": {
    "en": "The CoreDNS pods in the cluster had a memory limit of 100Mi, set from historical resource …",
    "ko": "2019년 1월 7일 월요일, Zalando Fashion Store 의 모든 웹 상품 페이지와 코디 페이지가 한 시간 넘게 오류를 냈다. 오류는 쿠버네티스 클러…"
  },
  "trigger": {
    "en": "Calls from the aggregation layer to a single, not very important downstream service starte…",
    "ko": "그리 중요하지 않은 하위 서비스 하나로 가는 호출이 타임아웃 나기 시작했다. 집계 계층이 이 호출에 404 로 응답하자 클라이언트가 재시도했고, 집계 계층으로 가…"
  },
  "severity": "unknown",
  "symptoms": [
    "high-error-rate",
    "dns-resolution-failures",
    "… 2 more"
  ],
  "timeline": {
    "detected_after": null,
    "resolved_after": null
  },
  "date_kind": "incident",
  "detection": {
    "en": "The on-call engineer for the aggregation layer phoned the on-call Kubernetes engineer. Aut…",
    "ko": "DNS 장애로 클러스터 내부 모니터링이 함께 멈춰 당직 호출이 자동으로 가지 않았다. 집계 계층 서비스 당직 엔지니어가 평소처럼 자동 호출에 기대지 못하고 쿠버네…"
  },
  "components": [
    "coredns",
    "memory-limit",
    "… 1 more"
  ],
  "root_cause": "capacity",
  "remediation": [
    {
      "text": {
        "en": "Raised the CoreDNS memory requests and limits by hand from 100Mi to 2000Mi",
        "ko": "쿠버네티스 당직 엔지니어가 CoreDNS 파드의 메모리 request 와 limit 을 100Mi 에서 2000Mi 로 직접 올렸다."
      }
    }
  ],
  "action_items": [
    {
      "text": {
        "en": "Introduce a more resilient DNS setup: CoreDNS fronted by dnsmasq on every node",
        "ko": "노드마다 dnsmasq 를 앞에 둔 CoreDNS 를 띄우는 방식으로 더 튼튼한 DNS 구성을 도입한다. 검토하고 시험한 다른 어떤 구성보다 이 방식의 성능이 좋…"
      }
    },
    {
      "text": {
        "en": "Improve high-level alerting from outside the clusters, so that a cluster problem is known …",
        "ko": "클러스터 바깥에서 클러스터 전체 상태를 보는 알림을 강화한다. 팀은 클러스터 안 애플리케이션이 영향을 받기 전에, 늦어도 같은 시점에는 클러스터 이상을 알아야 한…"
      }
    },
    "… 1 more"
  ],
  "contributing": [
    "limit-unknown",
    "no-caching",
    "… 4 more"
  ],
  "recurrence_of": null,
  "symptoms_text": {
    "en": "Customers of the Zalando Fashion Store got a high rate of errors on all web product pages …",
    "ko": "Zalando Fashion Store 의 모든 웹 상품 페이지와 코디 페이지가 한 시간 넘게 고객에게 오류를 많이 냈다. 오류는 쿠버네티스 클러스터 하나에서 도…"
  },
  "updated_at": "2026-11-08T19:10:26.982343Z",
  "url": "https://benchlet.com/incidentlib/app/cases/IL-0001"
}

curl 'https://incidentlib-api.benchlet.com/cases/IL-0001/similar'

같은 원인이면서 구성 요소를 하나 이상 공유하는 사례입니다. 공유하는 구성 요소가 많은 사례부터 옵니다.

[
  {
    "id": "IL-0027",
    "title": {
      "en": "All CoreDNS pods landed on one node, the node ran out of memory, and DNS for the whole ser…",
      "ko": "CoreDNS 파드가 모두 한 노드에 몰린 채 그 노드의 메모리가 고갈되자 DNS 가 응답하지 못해 아이디어스 서비스 전체가 멈췄다"
    },
    "org": "Backpackr",
    "date": "2025-05-07",
    "severity": "unknown",
    "root_cause": "capacity",
    "url": "https://benchlet.com/incidentlib/app/cases/IL-0027",
    "shared_components": [
      "dns-resolver",
      "memory-limit",
      "… 1 more"
    ]
  },
  {
    "id": "IL-0048",
    "title": {
      "en": "DNS lookups timed out in a large EKS cluster when CoreDNS hit the 1024 packets-per-second …",
      "ko": "대형 EKS 클러스터에서 CoreDNS 가 VPC DNS 리졸버로 보내는 질의가 링크 로컬 트래픽의 초당 1024 패킷 한도에 걸려 DNS 조회가 간헐적으로 타임…"
    },
    "org": "unknown",
    "date": "2025-08-12",
    "severity": "unknown",
    "root_cause": "capacity",
    "url": "https://benchlet.com/incidentlib/app/cases/IL-0048",
    "shared_components": [
      "coredns",
      "dns-resolver"
    ]
  },
  "… 4 more"
]

분류로 거르기

curl 'https://incidentlib-api.benchlet.com/cases?root_cause=capacity&limit=2'

거르는 매개변수는 root_cause, component, symptom, factor, domain, org 이고 값은 식별자입니다. 여러 개를 주면 모두 만족하는 사례만 옵니다. 최근 사례가 먼저 옵니다.

목록은 페이지로 나뉘어 옵니다. items 에 이번 페이지의 사례가 있고, 다음 페이지가 있으면 next 에 그 페이지의 전체 주소가 있습니다. next 가 없으면 마지막 페이지입니다. 한 페이지는 기본 50건, 최대 200건입니다. 다음 페이지 주소는 직접 만들지 말고 next 를 그대로 쓰면 됩니다.

{
  "items": [
    {
      "id": "IL-0071",
      "org": "Onkar Raghunath Shelke",
      "date": "2026-09-17",
      "docs": [
        "https://dev.to/onkar_s/kubelet-watches-inodes-just-not-until-its-an-emergency-351c"
      ],
      "title": {
        "en": "Worker node running out of inodes while disk space looked fine, because containerd kept a …",
        "ko": "작은 파일이 4만 개 넘게 든 단일 스테이지 이미지의 containerd 스냅샷이 쌓여 워커 노드의 inode 가 디스크보다 빠르게 소진되고 있었다"
      },
      "domain": [
        "kubernetes",
        "observability"
      ],
      "impact": {
        "scope": "one worker node trending towards inode exhaustion; no outage reported",
        "users": "unknown",
        "region": "unknown"
      },
      "review": {
        "written_by": "session",
        "reviewed_at": null,
        "reviewed_by": null
      },
      "lessons": {
        "en": "kubelet's background cleanup works on bytes only. A workload heavy in small files gets no …",
        "ko": "kubelet 의 백그라운드 정리는 바이트를 기준으로 돈다. 용량보다 파일 수가 먼저 차는 워크로드에는 미리 손쓸 장치가 없다. kubelet 은 inode 가 …"
      },
      "related": [],
      "sources": [
        {
          "url": "https://www.cncf.io/blog/2026/10/05/kubelet-watches-inodes-just-not-until-its-an-emergency…",
          "kind": "blog",
          "license": "cc-by",
          "archived": null
        }
      ],
      "summary": {
        "en": "The application image was built in one stage, so it carried the source, the build output a…",
        "ko": "글쓴이가 운영하던 클러스터에서 워커 노드 한 대의 inode 가 바닥날 추세라는 알림이 왔다. 디스크 사용률은 83%, inode 사용률은 67% 였다. 알림이 …"
      },
      "trigger": {
        "en": "Several versions of a single-stage Node.js image, each shipping more than 40,000 files, we…",
        "ko": "단일 스테이지로 빌드한 이미지에 소스, 빌드 결과물, 개발 의존성까지 포함한 node_modules 전체가 들어갔고, 새 레이어 다이제스트가 생길 때마다 노드에 …"
      },
      "severity": "unknown",
      "symptoms": [
        "node-disk-full"
      ],
      "timeline": {
        "detected_after": null,
        "resolved_after": null
      },
      "date_kind": "published",
      "detection": {
        "en": "The NodeFilesystemFilesFillingUp alert from the node_exporter mixin fired on the predicted…",
        "ko": "node_exporter mixin 에 들어 있는 NodeFilesystemFilesFillingUp 알림이 inode 사용률 67% 에서 울렸다. predict…"
      },
      "components": [
        "node-disk",
        "kubelet",
        "… 1 more"
      ],
      "root_cause": "capacity",
      "remediation": [],
      "action_items": [
        {
          "text": {
            "en": "Build the image in multiple stages so the final image contains only the compiled assets",
            "ko": "멀티 스테이지 Dockerfile 로 바꿔, 한 스테이지에서 의존성을 설치하고 빌드한 뒤 최종 이미지에는 nginx:alpine 위에 컴파일된 결과물만 넣는다."
          }
        },
        {
          "text": {
            "en": "Add a flat alert on root filesystem inode use above 80% for 30 minutes alongside the predi…",
            "ko": "추세 알림과 별도로 루트 파일 시스템의 inode 사용률이 0.80 을 넘으면 울리는 고정 기준 알림을 for: 30m 으로 둔다."
          }
        },
        "… 2 more"
      ],
      "contributing": [
        "default-config-unchanged",
        "monitoring-blind-spot",
        "… 1 more"
      ],
      "recurrence_of": null,
      "symptoms_text": {
        "en": "A Kubernetes worker node paged with NodeFilesystemFilesFillingUp, the node_exporter mixin …",
        "ko": "워커 노드 한 대에서 NodeFilesystemFilesFillingUp 알림이 울려 담당자가 호출됐다. inode 가 바닥날 추세라는 알림이었다.\n\n담당자는 누…"
      },
      "updated_at": "2026-11-08T19:10:32.156375Z",
      "url": "https://benchlet.com/incidentlib/app/cases/IL-0071"
    },
    {
      "id": "IL-0048",
      "org": "unknown",
      "date": "2025-08-12",
      "docs": [
        "https://cep.dev/posts/eks-dns-timeouts-sudo-hostname-lookups/"
      ],
      "title": {
        "en": "DNS lookups timed out in a large EKS cluster when CoreDNS hit the 1024 packets-per-second …",
        "ko": "대형 EKS 클러스터에서 CoreDNS 가 VPC DNS 리졸버로 보내는 질의가 링크 로컬 트래픽의 초당 1024 패킷 한도에 걸려 DNS 조회가 간헐적으로 타임…"
      },
      "domain": [
        "kubernetes",
        "aws",
        "… 1 more"
      ],
      "impact": {
        "scope": "DNS resolution in a very large EKS cluster, seen as intermittent CI failures",
        "users": "unknown",
        "region": "us-east-2, per the hostnames quoted in the post"
      },
      "review": {
        "written_by": "session",
        "reviewed_at": null,
        "reviewed_by": null
      },
      "lessons": {
        "en": "Traffic from CoreDNS to the VPC DNS resolver is limited to 1024 packets per second per int…",
        "ko": "EC2 에서 링크 로컬 주소로 가는 VPC DNS 질의에는 초당 1024 패킷의 한도가 있다. 한도를 넘은 UDP 패킷은 버려지는데, 보낸 쪽은 이를 알 수 없다…"
      },
      "related": [],
      "sources": [
        {
          "url": "https://medium.com/@cep21/my-process-to-debug-dns-timeouts-in-a-large-eks-cluster-9f731bd5…",
          "kind": "blog",
          "license": "unknown",
          "archived": "https://web.archive.org/web/20250821234026/https://medium.com/@cep21/my-process-to-debug-d…"
        }
      ],
      "summary": {
        "en": "Jack Lindamood describes an investigation in a very large AWS EKS cluster. Intermittent DN…",
        "ko": "글쓴이의 팀은 아주 큰 AWS EKS 클러스터를 운영한다. CI 가 간헐적으로 실패한다는 보고를 따라가 보니 DNS 조회 실패였다. CoreDNS 로그에는 VPC…"
      },
      "trigger": {
        "en": "An administrative pod running with host networking called sudo in a loop. Each sudo call l…",
        "ko": "호스트 네트워크를 쓰는 시스템 관리용 파드가 몇 초마다 sudo 명령을 실행했다. sudo 는 기본 설정에서 실행할 때마다 노드 자신의 호스트 이름을 조회했다. …"
      },
      "severity": "unknown",
      "symptoms": [
        "dns-resolution-failures",
        "intermittent-timeouts"
      ],
      "timeline": {
        "detected_after": null,
        "resolved_after": null
      },
      "date_kind": "published",
      "detection": {
        "en": "Reports of flaky CI jobs that could not resolve an S3 bucket hostname, followed by i/o tim…",
        "ko": "CI 가 간헐적으로 실패한다는 보고가 시작이었다. tensorstore 가 company-bucket.s3.amazonaws.com 의 DNS 조회에 실패했다는 …"
      },
      "components": [
        "coredns",
        "dns-resolver",
        "… 1 more"
      ],
      "root_cause": "capacity",
      "remediation": [
        {
          "text": {
            "en": "added 'Defaults !fqdn' in /etc/sudoers.d/00-no-fqdn (mode 440) to the container image so s…",
            "ko": "컨테이너 이미지에 /etc/sudoers.d/00-no-fqdn 파일로 Defaults !fqdn 을 넣어 sudo 가 호스트 이름을 조회하지 않게 했다."
          }
        }
      ],
      "action_items": [],
      "contributing": [
        "limit-unknown",
        "default-config-unchanged"
      ],
      "recurrence_of": null,
      "symptoms_text": {
        "en": "CI jobs failed now and then because a hostname could not be resolved. The failures came fr…",
        "ko": "처음 들어온 보고는 CI 가 간헐적으로 실패한다는 것이었다. 실패는 tensorstore 안에서 났고, 오류는 ./tensorstore/util/result.h:…"
      },
      "updated_at": "2026-11-08T19:10:30.194994Z",
      "url": "https://benchlet.com/incidentlib/app/cases/IL-0048"
    }
  ],
  "next": "https://incidentlib-api.benchlet.com/cases?root_cause=capacity&limit=2&after=MjAyNS0wOC0xM…"
}

분류 하나를 들여다보기

curl 'https://incidentlib-api.benchlet.com/symptoms/dns-resolution-failures'

원인은 /root-causes/식별자, 구성 요소는 /components/식별자, 증상은 /symptoms/식별자, 기여 요인은 /factors/식별자, 조직은 /orgs/식별자 입니다. 다섯 가지 모두 같은 모양으로 옵니다. 식별자 없이 부르면 그 분류의 모든 값과 사례 수가 옵니다. 아래는 DNS 조회 실패라는 증상의 예시입니다. related.root_causes 가 이 증상을 낸 원인과 건수입니다.

{
  "kind": "symptom",
  "slug": "dns-resolution-failures",
  "en": "DNS resolution failures",
  "ko": "DNS 조회 실패",
  "url": "https://benchlet.com/incidentlib/app/symptoms/dns-resolution-failures",
  "count": 11,
  "first_date": "2018-07-19",
  "last_date": "2025-08-12",
  "cases": [
    {
      "id": "IL-0048",
      "title": {
        "en": "DNS lookups timed out in a large EKS cluster when CoreDNS hit the 1024 packets-per-second …",
        "ko": "대형 EKS 클러스터에서 CoreDNS 가 VPC DNS 리졸버로 보내는 질의가 링크 로컬 트래픽의 초당 1024 패킷 한도에 걸려 DNS 조회가 간헐적으로 타임…"
      },
      "org": "unknown",
      "date": "2025-08-12",
      "severity": "unknown",
      "root_cause": "capacity",
      "url": "https://benchlet.com/incidentlib/app/cases/IL-0048"
    },
    {
      "id": "IL-0027",
      "title": {
        "en": "All CoreDNS pods landed on one node, the node ran out of memory, and DNS for the whole ser…",
        "ko": "CoreDNS 파드가 모두 한 노드에 몰린 채 그 노드의 메모리가 고갈되자 DNS 가 응답하지 못해 아이디어스 서비스 전체가 멈췄다"
      },
      "org": "Backpackr",
      "date": "2025-05-07",
      "severity": "unknown",
      "root_cause": "capacity",
      "url": "https://benchlet.com/incidentlib/app/cases/IL-0027"
    },
    "… 9 more"
  ],
  "related": {
    "root_causes": [
      {
        "slug": "capacity",
        "en": "Capacity exhaustion",
        "ko": "용량 한계",
        "count": 5,
        "cases": [
          "IL-0075",
          "IL-0048",
          "… 3 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/root-causes/capacity"
      },
      {
        "slug": "dns-network",
        "en": "DNS or network fault",
        "ko": "DNS·네트워크 장애",
        "count": 2,
        "cases": [
          "IL-0049",
          "IL-0047"
        ],
        "url": "https://benchlet.com/incidentlib/app/root-causes/dns-network"
      },
      "… 3 more"
    ],
    "components": [
      {
        "slug": "dns-resolver",
        "en": "Client-side DNS resolver and cache",
        "ko": "클라이언트 쪽 DNS 리졸버와 캐시",
        "count": 7,
        "cases": [
          "IL-0050",
          "IL-0048",
          "… 5 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/components/dns-resolver"
      },
      {
        "slug": "coredns",
        "en": "CoreDNS",
        "ko": "CoreDNS",
        "count": 4,
        "cases": [
          "IL-0049",
          "IL-0048",
          "… 2 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/components/coredns"
      },
      "… 13 more"
    ],
    "factors": [
      {
        "slug": "default-config-unchanged",
        "en": "Unreviewed defaults",
        "ko": "기본 설정 방치",
        "count": 6,
        "cases": [
          "IL-0050",
          "IL-0048",
          "… 4 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/factors/default-config-unchanged"
      },
      {
        "slug": "monitoring-blind-spot",
        "en": "Monitoring blind spot",
        "ko": "모니터링 사각지대",
        "count": 4,
        "cases": [
          "IL-0075",
          "IL-0060",
          "… 2 more"
        ],
        "url": "https://benchlet.com/incidentlib/app/factors/monitoring-blind-spot"
      },
      "… 16 more"
    ]
  }
}

q 에 증상 문장을 주면 그 문장과 비슷한 사례만 남고, 다른 분류의 건수도 그 사례들만 셉니다.

curl 'https://incidentlib-api.benchlet.com/root-causes/capacity?q=dns+lookups+fail'

식별자 찾기

curl 'https://incidentlib-api.benchlet.com/vocab?q=cert+ran+out&kind=root_causes&limit=3'

q 에 생각나는 단어를 주면 뜻이 가까운 순서로 분류 값이 옵니다. kind 로 한 분류만 볼 수 있고, 값은 root_causes, components, symptoms, factors, orgs 중 하나입니다. q 없이 부르면 모든 분류 값과 영어·한국어 이름이 옵니다.

{
  "matches": [
    {
      "kind": "root_cause",
      "slug": "certificate-expiry",
      "en": "Certificate or credential expiry",
      "ko": "인증서·자격 증명 만료",
      "url": "https://benchlet.com/incidentlib/app/root-causes/certificate-expiry"
    },
    {
      "kind": "root_cause",
      "slug": "credential-exposure",
      "en": "Credential exposure",
      "ko": "자격 증명 유출",
      "url": "https://benchlet.com/incidentlib/app/root-causes/credential-exposure"
    },
    "… 1 more"
  ],
  "query": "cert ran out"
}

사례의 필드

`id`	사례 번호입니다. IL-0001 처럼 생겼고 바뀌지 않습니다.
`url`	이 사례를 사람이 읽는 페이지 주소입니다.
`title`	제목입니다. 영어와 한국어가 각각 들어 있습니다.
`org`	장애를 겪은 조직입니다.
`date`	장애가 난 날 또는 보고서가 공개된 날입니다.
`severity`	심각도입니다. sev1 부터 sev4 까지이고, 보고서에 없으면 unknown 입니다.
`domain`	영역입니다. kubernetes 또는 ai-infra 입니다.
`root_cause`	원인 분류의 영문 식별자입니다. 예를 들어 certificate-expiry 입니다.
`components`	문제가 난 구성 요소 분류의 식별자 목록입니다.
`symptoms`	증상 분류의 식별자 목록입니다.
`contributing`	기여 요인 분류의 식별자 목록입니다.
`symptoms_text`	엔지니어가 본 증상을 문장으로 적은 글입니다.
`trigger`	장애를 촉발한 일입니다.
`summary`	무슨 일이 어떻게 일어났는지 요약한 글입니다.
`detection`	장애를 어떻게 알아차렸는지 적은 글입니다.
`remediation`	장애를 끝내려고 한 조치 목록입니다.
`action_items`	그 뒤에 조직이 하기로 한 일입니다.
`lessons`	보고서가 남긴 교훈입니다.
`sources`	원문 주소, 보관본 주소, 자료 종류, 라이선스입니다.
`impact`	영향 범위, 영향 받은 사용자, 지역입니다.
`timeline`	알아차리기까지 걸린 시간과 복구까지 걸린 시간입니다.
`recurrence_of`	같은 장애가 전에도 있었다면 그 사례 번호입니다.
`related`	편집자가 관련 있다고 연결한 사례 번호 목록입니다.
`updated_at`	이 사례가 마지막으로 바뀐 시각입니다.

영어와 한국어가 함께 있는 글 필드는 en 과 ko 두 항목으로 옵니다. 한국어가 없는 사례는 en 만 있습니다.

오류 응답

모든 오류는 같은 모양입니다. 응답 형식은 application/problem+json 이고, status 에 상태 코드, title 에 그 코드의 이름, detail 에 무엇이 잘못됐는지 한 문장, instance 에 요청한 경로가 들어 있습니다. 없는 사례를 부르면 이렇게 옵니다.

curl -i 'https://incidentlib-api.benchlet.com/cases/IL-9999'

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "no approved case IL-9999",
  "instance": "/cases/IL-9999"
}

`400`	매개변수가 빠졌거나 범위를 벗어났습니다. 무엇이 문제인지 `detail` 에 있습니다.
`404`	그 번호의 사례나 그 식별자의 분류 값이 없습니다.
`429`	같은 주소에서 1분에 부를 수 있는 횟수를 넘겼습니다. `Retry-After` 헤더에 몇 초 뒤에 다시 보내면 되는지 적혀 있습니다.
`503`	잠시 뒤 다시 보내면 됩니다.
`500`	서버 안에서 예상 못 한 오류가 났습니다. 잠시 뒤 다시 보내고, 계속되면 아래 제보처에 알려 주세요.

한도

같은 주소에서는 1분에 검색 30번, 그 밖의 호출 120번까지 부를 수 있습니다. 넘으면 429 응답이 오고, 1분 뒤에 다시 부를 수 있습니다. 더 많이 필요하면 아래 제보처로 알려 주세요.

헤더

요청	필요한 헤더가 없습니다.
`Content-Type`	정상 응답은 `application/json; charset=utf-8`, 오류 응답은 `application/problem+json` 입니다.
`Access-Control-Allow-Origin`	항상 `*` 입니다. 어느 사이트의 브라우저 코드에서든 이 API 를 읽을 수 있습니다.
`Retry-After`	429 응답에만 있고, 몇 초 뒤에 다시 보내면 되는지 적혀 있습니다.

프로그램이 읽는 명세는 OpenAPI 문서에 있습니다.

내 클러스터 점검하기

사례는 다른 곳에서 무엇이 잘못됐는지를 말해 줍니다. kubegap 은 같은 상태가 내 쿠버네티스 클러스터에 있는지 찾아 줍니다. Claude Code 나 Codex 가 따르는 절차와 스크립트를 담은 폴더, 곧 Agent Skill 이고, /kubegap 을 치면 에이전트가 kubectl 로 클러스터를 읽어 수백 개 점검 항목에 대조한 뒤 문제마다 근거와 원인과 권하는 조치를 적은 보고서를 씁니다. 읽기만 하고, 클러스터에 아무것도 설치하지 않으며, 수집한 자료는 내 컴퓨터에 남습니다.

점검 항목 가운데 많은 수가 이 라이브러리에 있는 공개 보고서를 근거로 들기 때문에, 여기서 찾은 사례와 거기서 나온 문제가 같은 보고서를 가리키는 일이 잦습니다. 설치 명령과 점검 항목 전체 목록은 kubegap 페이지에 있습니다.

데이터는 어디서 왔나

사례는 전부 공개된 장애 보고서에서 왔습니다. 회사의 기술 블로그, 상태 페이지, 발표 자료, 논문, 코드 저장소입니다. 사례 글은 보고서가 말한 사실을 우리 말로 다시 쓴 요약이고, 보고서에 없는 사실은 비워 둡니다. 원문을 보관본으로 남길 수 있으면 보관본 주소도 함께 둡니다.

사례 글, 분류 목록, API 응답은 출처만 밝히면 자유롭게 쓸 수 있는 CC BY 4.0 라이선스입니다. 원문 보고서는 각자의 라이선스를 따르고, 그 라이선스는 사례의 출처 항목에 적혀 있습니다. 틀린 곳을 알리거나 사례를 제안하려면 GitHub 이슈를 열어 주세요.

Incident Library