{"id":22220937,"url":"https://github.com/nokia/koredump","last_synced_at":"2025-07-27T16:30:44.476Z","repository":{"id":40432834,"uuid":"459547419","full_name":"nokia/koredump","owner":"nokia","description":"REST API for accessing coredumps in Kubernetes cluster.","archived":false,"fork":false,"pushed_at":"2023-05-03T12:59:14.000Z","size":123,"stargazers_count":9,"open_issues_count":14,"forks_count":7,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-04-14T13:07:14.082Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nokia.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-15T11:21:16.000Z","updated_at":"2024-04-11T12:18:47.000Z","dependencies_parsed_at":"2023-02-08T08:45:14.387Z","dependency_job_id":null,"html_url":"https://github.com/nokia/koredump","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fkoredump","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fkoredump/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fkoredump/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fkoredump/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nokia","download_url":"https://codeload.github.com/nokia/koredump/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227817164,"owners_count":17824199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-02T23:11:02.220Z","updated_at":"2024-12-02T23:11:02.993Z","avatar_url":"https://github.com/nokia.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Coredump REST API for Kubernetes\n\nkoredump enables easy access to core dumps in a Kubernetes cluster.\nREST API and command line tools are provided, that allow user to get information\non core dumps in a cluster, and to download the core dump files.\n\nCore dumps are captured and stored on disk by the infra platform, and koredump supports Red Hat OCP\nthat uses the [`systemd-coredump`](https://www.freedesktop.org/software/systemd/man/systemd-coredump.html) service.\n\n## Design\n\n- In-cluster `http://koreapi.koredump.svc.cluster.local:80` REST API (Kubernetes Service).\n  One container per cluster, application listening port 5000.\n- One REST API server per node in k8s cluster (Kubernetes DaemonSet), listening port 5001.\n- No changes to platform `core_pattern` kernel config, use default `systemd-coredump` in OCP.\n- Access coredump files from `/var/lib/systemd/coredump`, and (optionally) read journal logs for full coredump metadata written by `systemd-coredump`.\n- `DAC_OVERRIDE` capability is used in container to access core dump files and journal logs.\n- Command line utility `koredumpctl` that uses the REST API. Automatically installed in OCP to `/usr/local/bin/koredumpctl` with Kubernetes init container.\n- Note that in OCP core dumps are deleted by default after 3 days (see `systemd-tmpfiles --cat-config | grep core`).\n- Collect all coredumps in cluster by default. Limit to predefined namespaces by setting `filter.namespaceRegex` variable when installing with Helm charts.\n- Token authentication for REST API. Server uses [TokenReview](https://kubernetes.io/docs/reference/access-authn-authz/authentication/) to verify the token.\n\n## Limitations\n\n- Red Hat OCP `privileged` [Security Context Constraint (SCC)](https://docs.openshift.com/container-platform/4.9/authentication/managing-security-context-constraints.html) is needed.\n- In-cluster traffic is unencrypted HTTP.\n- Simple implementation with python3.\n- Hard requirement on systemd-coredump, core files are processed from `/var/lib/systemd/coredump` directory only.\n  Note that if `core_pattern` is set e.g. to `/tmp/core` or similar, the cores are written to container filesystem, and not visible via this tool.\n- Core file deletion not (yet) possible. (Host paths are read-only mounted into containers)\n- REST API can return errors during installation and upgrade, when the koredump PODs are being terminated or created.\n- systemd-coredump by default limits core size to maximum 2GB, larger core files are truncated.\n  Increase the limit by setting for example `ExternalSizeMax=32G` in /etc/systemd/coredump.conf (or add conf file in `/etc/systemd/coredump.conf.d/`).\n\n## API Documentation\n\n#### `GET /apiv1/cores`\n\nJSON list of cores (metadata) available in cluster.\n\n\u003cdetails\u003e\n\u003csummary\u003eExample\u003c/summary\u003e\n\u003cpre\u003e\nbash-5.1$ curl -fsS -H \"Authorization: Bearer $token\" koreapi/apiv1/cores | jq\n[\n  {\n    \"ARCH\": \"x86_64\",\n    \"COREDUMP_CMDLINE\": \"/usr/bin/example -a -b -c\",\n    \"COREDUMP_COMM\": \"example\",\n    ...\n    \"COREDUMP_SIGNAL\": 24,\n    \"COREDUMP_SIGNAL_NAME\": \"SIGXCPU\",\n    \"container\": \"ctr-ns1-example\",\n    \"id\": \"core.example.9999.f1c1b6957ac9436d9113a86c8c905508.141241.1642081018000000.lz4\",\n    \"node\": \"ocp-example\",\n    \"pod\": \"pod-ns1-example-86b5c54447-lrbz2\"\n  },\n  {\n    ...\n  }\n]\n\u003c/pre\u003e\n\u003c/details\u003e\n\n#### `GET /apiv1/cores/metadata/\u003cnode\u003e/\u003ccore_id\u003e`\n\nJSON metadata of single core file, identified by kubernetes node name, and core file ID.\n\n\u003cdetails\u003e\n\u003csummary\u003eExample\u003c/summary\u003e\n\u003cpre\u003e\nbash-5.1$ curl -fsS -H \"Authorization: Bearer $token\" koreapi/apiv1/cores/metadata/ocp-example/core.example.9999.f1c1b6957ac9436d9113a86c8c905508.141241.1642081018000000.lz4 | jq\n{\n  \"ARCH\": \"x86_64\n  \"COREDUMP_CMDLINE\": \"/usr/bin/example -a -b -c\",\n  \"COREDUMP_COMM\": \"example\",\n  ...\n  \"COREDUMP_SIGNAL\": 24,\n  \"COREDUMP_SIGNAL_NAME\": \"SIGXCPU\",\n  \"container\": \"ctr-ns1-example\",\n  \"id\": \"core.example.9999.f1c1b6957ac9436d9113a86c8c905508.141241.1642081018000000.lz4\",\n  \"node\": \"ocp-example\",\n  \"pod\": \"pod-ns1-example-86b5c54447-lrbz2\"\n}\n\u003c/pre\u003e\n\u003c/details\u003e\n\n#### `GET /apiv1/cores/download/\u003cnode\u003e/\u003ccore_id\u003e`\n\nDownload core file, identified by kubernetes node name, and core file ID.\n\n\u003cdetails\u003e\n\u003csummary\u003eExample\u003c/summary\u003e\n\u003cpre\u003e\nbash-5.1$ curl -fvsS -O -H \"Authorization: Bearer $token\" koreapi/apiv1/cores/download/ocp-example/core.example.9999.f1c1b6957ac9436d9113a86c8c905508.141241.1642081018000000.lz4\n* Connected to koreapi (172.30.199.84) port 80 (#0)\n\u003e GET /apiv1/cores/download/ocp-example/core.example.9999.f1c1b6957ac9436d9113a86c8c905508.141241.1642081018000000.lz4 HTTP/1.1\n\u003e Host: koreapi\n\u003e User-Agent: curl/7.79.1\n\u003e Accept: */*\n\u003e \n* Mark bundle as not supporting multiuse\n\u003c HTTP/1.1 200 OK\n\u003c Server: gunicorn\n\u003c Date: Fri, 14 Jan 2022 05:48:11 GMT\n\u003c Connection: close\n\u003c Content-Disposition: attachment; filename=core.example.9999.f1c1b6957ac9436d9113a86c8c905508.141241.1642081018000000.lz4\n\u003c Content-Type: application/octet-stream\n\u003c Content-Length: 279816\n\u003c Last-Modified: Thu, 13 Jan 2022 12:29:50 GMT\n\u003c Cache-Control: no-cache\n\u003c \n* Closing connection 0\n\u003c/pre\u003e\n\u003c/details\u003e\n\n## Install and run in Red Hat OCP\n\nInstall (in Red Hat OCP as `core` user):\n```bash\noc new-project koredump\nhelm repo add koredump https://nokia.github.io/koredump/\nhelm repo update\nhelm install -n koredump koredump koredump/koredump\nwatch kubectl -n koredump get all\n```\n\nUpgrade:\n```bash\nhelm repo update\nhelm upgrade -n koredump koredump koredump/koredump\nwatch kubectl -n koredump get all\n```\n\nTest with `koredumpctl`:\n```bash\nkoredumpctl status\nkoredumpctl list\n```\n\nExample `koredumpctl list` output:\n```\n$ koredumpctl list\n- ID: core.prog.0.e36680b3d32e4f4f9899d72d34fe5fb3.207856.1638186984000000.lz4\n  Node: ocp-6\n  Pod: po-prog-oam-0\n  Container: ctr-prog\n  Namespace: demo\n  Image: image-registry.openshift-image-registry.svc:5000/demo/prog:1.2.0\n  Signal: SIGXCPU (24)\n  Timestamp: 2022-02-23T08:23:16Z\n- ID: core.stunnel.9999.29162cb2ca0d4e1eb67a4ffb549ed670.2354652.1645604596000000.lz4\n  Node: ocp-6\n  Pod: po-cran1-stunnel-d897f48fd-8q68m\n  Container: ctr-cran1-stunnel\n  Namespace: demo\n  Image: image-registry.openshift-image-registry.svc:5000/demo/stunnel:2.4.0\n  Signal: SIGXCPU (24)\n  Timestamp: 2022-02-23T08:23:16Z\n```\n\nUninstall:\n```bash\nhelm uninstall koredump\nrm /usr/local/bin/koredumpctl\n```\n\n## Development Notes\n\nInstall from git repository:\n```bash\ngit clone https://github.com/nokia/koredump.git\ncd koredump\noc new-project koredump\nhelm install koredump charts/koredump/\nwatch kubectl get all\n```\n\nRun API servers locally without Kubernetes, for example in Fedora:\n```bash\nNO_TOKENS=1 FLASK_ENV=development PORT=5001 DAEMONSET=1 FAKE_K8S=1 gunicorn --access-logfile=- app\nNO_TOKENS=1 FLASK_ENV=development PORT=5000 KOREDUMP_DAEMONSET_PORT=5001 DAEMONSET=0 FAKE_K8S=1 gunicorn --access-logfile=- app\n```\n\n## Links\n\n- https://github.com/IBM/core-dump-handler/\n- https://github.com/aspekt112/segwatcher\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Fkoredump","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnokia%2Fkoredump","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Fkoredump/lists"}