| Name | kindps JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Find host PIDs for processes in Kind cluster |
| upload_time | 2025-01-19 10:11:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
kubernetes
kind
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Find host PIDs for processes in Kind cluster
## Introduction
This Python script identifies the host PID for a process running inside a pod in a [Kind](https://kind.sigs.k8s.io/) Kubernetes cluster.
It uses `docker exec` to execute [`crictl`](https://kubernetes.io/docs/tasks/debug/debug-cluster/crictl/) on the Kind node to list the pods and containers running on the node.
It then navigates through `/sys/fs/cgroup/` and the nested cgroups to find the host PIDs.
Finally `/proc/` is used to get the process details.
The script requires only Python and does not depend on any external packages.
Since it directly accesses the `cgroup` and `proc` filesystems, it works only on Linux hosts where `kind` is executed and is not compatible with MacOS.
```
usage: kindps [-h] [-o {tabular,json}] [--debug] [-v] docker_filter [pod_filter]
Find host PIDs for processes in Kind cluster
positional arguments:
docker_filter filter for Kind Docker container names
pod_filter optional filter for pod names
options:
-h, --help show this help message and exit
-o {tabular,json}, --output {tabular,json}
output format (default: tabular)
--debug activate debug logging
-v, --version show program's version number and exit
```
## Installation
Either download [`kindps.py`](kindps.py) or install as a Python package:
```
pip install kindps
```
## Example usage
First, list the nodes in the Kind cluster:
```console
$ kubectl get nodes
NAME STATUS ROLES AGE VERSION
contour-control-plane Ready control-plane 11h v1.32.0
contour-worker Ready <none> 11h v1.32.0
```
These nodes correspond to the Docker containers that are running:
```console
$ docker ps --format "table {{.ID}}\t{{.Names}}"
CONTAINER ID NAMES
992ec6ccbeed contour-control-plane
22c9d82b69f2 contour-worker
```
To list the containers running in pods that contain `envoy` in their names and are running on nodes that contain `contour` in their names, run:
```console
$ kindps contour envoy
```
Result is printed in tabular format by default:
```console
Containers:
envoy:
Pod: envoy-z5lp9
Node: contour-worker
Process:
pid: 2367787
cmd: envoy -c /config/envoy.json --service-cluster projectcontour --service-node
envoy-z5lp9 --log-level info
Image: docker.io/envoyproxy/envoy:v1.31.5
Created: 2025-01-18T10:37:07.655928
Labels:
app: envoy
controller-revision-hash: dd8c68b4b
pod-template-generation: 1
shutdown-manager:
Pod: envoy-z5lp9
Node: contour-worker
Process:
pid: 2367735
cmd: /bin/contour envoy shutdown-manager
Image: ghcr.io/projectcontour/contour:v1.30.2
Created: 2025-01-18T10:37:07.511818
Labels:
app: envoy
controller-revision-hash: dd8c68b4b
pod-template-generation: 1
Summary:
Containers: 2
Processes: 2
```
To get JSON format output, include the `--output json` option:
```json
[
{
"node": "contour-worker",
"pod": "envoy-z5lp9",
"container": "envoy",
"image": "docker.io/envoyproxy/envoy:v1.31.5",
"created": "2025-01-18T10:37:07.655928",
"pids": [
{
"pid": "2367787",
"cmd": "envoy -c /config/envoy.json --service-cluster projectcontour --service-node envoy-z5lp9 --log-level info"
}
],
"labels": {
"app": "envoy",
"controller-revision-hash": "dd8c68b4b",
"pod-template-generation": "1"
}
},
{
"node": "contour-worker",
"pod": "envoy-z5lp9",
"container": "shutdown-manager",
"image": "ghcr.io/projectcontour/contour:v1.30.2",
"created": "2025-01-18T10:37:07.511818",
"pids": [
{
"pid": "2367735",
"cmd": "/bin/contour envoy shutdown-manager"
}
],
"labels": {
"app": "envoy",
"controller-revision-hash": "dd8c68b4b",
"pod-template-generation": "1"
}
}
]
```
The PIDs listed are the host PIDs for the processes running inside the containers.
These PIDs can be used on the host to access the process:
```console
$ ps 2367787
PID TTY STAT TIME COMMAND
2367787 ? Ssl 0:00 envoy -c /config/envoy.json --service-cluster projectcontour
--service-node envoy-z5lp9 --log-level info
```
For example, to access the root filesystem of the container:
```console
$ sudo ls /proc/2367787/root/
admin config home libx32 proc run tmp
bin dev lib media product_name sbin usr
boot docker-entrypoint.sh lib32 mnt product_uuid srv var
certs etc lib64 opt root sys
```
To send a signal to the process, even if the container lacks the `kill` command:
```console
$ sudo kill -STOP 2367787
```
Alternatively, `nsenter` can be used to enter the network namespace of the process to run `wireshark`:
```console
$ sudo nsenter \
--target $(kindps contour-worker envoy --output json | jq -r '.[0].pids[0].pid') \
--net wireshark -i any -k
```
Raw data
{
"_id": null,
"home_page": null,
"name": "kindps",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "kubernetes, kind",
"author": null,
"author_email": "Tero Saarni <tero.saarni@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f5/f8/aa570c684f85b52f5936a12f2239c3e507e46bd9a84801219dfdab2d5197/kindps-0.1.0.tar.gz",
"platform": null,
"description": "# Find host PIDs for processes in Kind cluster\n\n## Introduction\n\nThis Python script identifies the host PID for a process running inside a pod in a [Kind](https://kind.sigs.k8s.io/) Kubernetes cluster.\nIt uses `docker exec` to execute [`crictl`](https://kubernetes.io/docs/tasks/debug/debug-cluster/crictl/) on the Kind node to list the pods and containers running on the node.\nIt then navigates through `/sys/fs/cgroup/` and the nested cgroups to find the host PIDs.\nFinally `/proc/` is used to get the process details.\n\nThe script requires only Python and does not depend on any external packages.\nSince it directly accesses the `cgroup` and `proc` filesystems, it works only on Linux hosts where `kind` is executed and is not compatible with MacOS.\n\n\n```\nusage: kindps [-h] [-o {tabular,json}] [--debug] [-v] docker_filter [pod_filter]\n\nFind host PIDs for processes in Kind cluster\n\npositional arguments:\n docker_filter filter for Kind Docker container names\n pod_filter optional filter for pod names\n\noptions:\n -h, --help show this help message and exit\n -o {tabular,json}, --output {tabular,json}\n output format (default: tabular)\n --debug activate debug logging\n -v, --version show program's version number and exit\n```\n\n## Installation\n\nEither download [`kindps.py`](kindps.py) or install as a Python package:\n\n```\npip install kindps\n```\n\n## Example usage\n\nFirst, list the nodes in the Kind cluster:\n\n```console\n$ kubectl get nodes\nNAME STATUS ROLES AGE VERSION\ncontour-control-plane Ready control-plane 11h v1.32.0\ncontour-worker Ready <none> 11h v1.32.0\n```\n\nThese nodes correspond to the Docker containers that are running:\n\n```console\n$ docker ps --format \"table {{.ID}}\\t{{.Names}}\"\nCONTAINER ID NAMES\n992ec6ccbeed contour-control-plane\n22c9d82b69f2 contour-worker\n```\n\nTo list the containers running in pods that contain `envoy` in their names and are running on nodes that contain `contour` in their names, run:\n\n```console\n$ kindps contour envoy\n```\n\nResult is printed in tabular format by default:\n\n```console\nContainers:\n envoy:\n Pod: envoy-z5lp9\n Node: contour-worker\n Process:\n pid: 2367787\n cmd: envoy -c /config/envoy.json --service-cluster projectcontour --service-node\n envoy-z5lp9 --log-level info\n Image: docker.io/envoyproxy/envoy:v1.31.5\n Created: 2025-01-18T10:37:07.655928\n Labels:\n app: envoy\n controller-revision-hash: dd8c68b4b\n pod-template-generation: 1\n\n shutdown-manager:\n Pod: envoy-z5lp9\n Node: contour-worker\n Process:\n pid: 2367735\n cmd: /bin/contour envoy shutdown-manager\n Image: ghcr.io/projectcontour/contour:v1.30.2\n Created: 2025-01-18T10:37:07.511818\n Labels:\n app: envoy\n controller-revision-hash: dd8c68b4b\n pod-template-generation: 1\n\nSummary:\n Containers: 2\n Processes: 2\n```\n\nTo get JSON format output, include the `--output json` option:\n\n```json\n[\n {\n \"node\": \"contour-worker\",\n \"pod\": \"envoy-z5lp9\",\n \"container\": \"envoy\",\n \"image\": \"docker.io/envoyproxy/envoy:v1.31.5\",\n \"created\": \"2025-01-18T10:37:07.655928\",\n \"pids\": [\n {\n \"pid\": \"2367787\",\n \"cmd\": \"envoy -c /config/envoy.json --service-cluster projectcontour --service-node envoy-z5lp9 --log-level info\"\n }\n ],\n \"labels\": {\n \"app\": \"envoy\",\n \"controller-revision-hash\": \"dd8c68b4b\",\n \"pod-template-generation\": \"1\"\n }\n },\n {\n \"node\": \"contour-worker\",\n \"pod\": \"envoy-z5lp9\",\n \"container\": \"shutdown-manager\",\n \"image\": \"ghcr.io/projectcontour/contour:v1.30.2\",\n \"created\": \"2025-01-18T10:37:07.511818\",\n \"pids\": [\n {\n \"pid\": \"2367735\",\n \"cmd\": \"/bin/contour envoy shutdown-manager\"\n }\n ],\n \"labels\": {\n \"app\": \"envoy\",\n \"controller-revision-hash\": \"dd8c68b4b\",\n \"pod-template-generation\": \"1\"\n }\n }\n]\n```\n\nThe PIDs listed are the host PIDs for the processes running inside the containers.\nThese PIDs can be used on the host to access the process:\n\n```console\n$ ps 2367787\n PID TTY STAT TIME COMMAND\n2367787 ? Ssl 0:00 envoy -c /config/envoy.json --service-cluster projectcontour\n --service-node envoy-z5lp9 --log-level info\n```\n\nFor example, to access the root filesystem of the container:\n\n```console\n$ sudo ls /proc/2367787/root/\nadmin config home libx32 proc run tmp\nbin dev lib media product_name sbin usr\nboot docker-entrypoint.sh lib32 mnt product_uuid srv var\ncerts etc lib64 opt root sys\n```\n\nTo send a signal to the process, even if the container lacks the `kill` command:\n\n```console\n$ sudo kill -STOP 2367787\n```\n\nAlternatively, `nsenter` can be used to enter the network namespace of the process to run `wireshark`:\n\n```console\n$ sudo nsenter \\\n --target $(kindps contour-worker envoy --output json | jq -r '.[0].pids[0].pid') \\\n --net wireshark -i any -k\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Find host PIDs for processes in Kind cluster",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/tsaarni/kind-ps",
"Source": "https://github.com/tsaarni/kind-ps"
},
"split_keywords": [
"kubernetes",
" kind"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f6faa5effe45c8015afd8d9d9562d6ac58e7c59944b2386c121fcc06fe8bb776",
"md5": "1f47ee96ee2d730b07ca84ca2eedfd6f",
"sha256": "177f67c13ccd4b9a84a6be74a1667f84d12c0e622ba25be943d15bb3a17a9d12"
},
"downloads": -1,
"filename": "kindps-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f47ee96ee2d730b07ca84ca2eedfd6f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10201,
"upload_time": "2025-01-19T10:11:13",
"upload_time_iso_8601": "2025-01-19T10:11:13.768001Z",
"url": "https://files.pythonhosted.org/packages/f6/fa/a5effe45c8015afd8d9d9562d6ac58e7c59944b2386c121fcc06fe8bb776/kindps-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f5f8aa570c684f85b52f5936a12f2239c3e507e46bd9a84801219dfdab2d5197",
"md5": "1fc1e23ef41aec066008ad72273817c8",
"sha256": "4b4cbb1bb9225e97a09d93c8c34a42d02d71d289bd1938d78d4047c803c1ed33"
},
"downloads": -1,
"filename": "kindps-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "1fc1e23ef41aec066008ad72273817c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 10779,
"upload_time": "2025-01-19T10:11:16",
"upload_time_iso_8601": "2025-01-19T10:11:16.039474Z",
"url": "https://files.pythonhosted.org/packages/f5/f8/aa570c684f85b52f5936a12f2239c3e507e46bd9a84801219dfdab2d5197/kindps-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-19 10:11:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tsaarni",
"github_project": "kind-ps",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "kindps"
}
