## container-runtime-interface-api
Python library for communication with the Kubernetes [Container Runtime Interface API](https://github.com/kubernetes/cri-api).
### Usage
Install `container-runtime-interface-api` with `pipenv` or `pip`:
```shell
$ pipenv install container-runtime-interface-api
Adding container-runtime-interface-api to Pipfile's [packages]…
✔ Installation Succeeded
...
```
This project currently supports Python 3.10+.
#### Connection
Connection to the CRI API is generally done through a UNIX socket, but any gRPC address supported by [insecure_channel](https://grpc.github.io/grpc/python/grpc.html#grpc.insecure_channel) will work.
```python
from cri_api.channel import Channel
channel = Channel.from_env() # Loads from RUNTIME_SOCK
channel = Channel("unix:///var/run/dockershim.sock") # Explicit argument
```
#### Images
The `Images` class is a thin wrapper around the existing ImageService API:
```python
from cri_api.images import Images
channel = Channel.from_env()
images = Images(channel)
images.list_images()
images.pull_image("busybox")
busybox_images = [i["id"] for i in images.list_images() if any("busybox" in r for r in i["repoTags"])]
[images.remove_image(i) for i in busybox_images]
```
#### Containers
The `Containers` class is a thin wrapper around the existing RuntimeService API:
```python
from cri_api.images import Images
from cri_api import ContainerFilter, ContainerState, ContainerStateValue
channel = Channel.from_env()
images = Containers(channel)
containers.list_containers()
containers.list_containers(ContainerFilter(state=ContainerStateValue(state=ContainerState.CONTAINER_EXITED)))
containers.get_container("9d81052cc027a1fb2ec61b898ea0fd6fc88216ce730ad75f4c52b29849cb440f")
```
#### Raw
Raw access to the underlying CRI API objects can be done by importing from `cri_api`:
```python
from os import getenv
from grpc import insecure_channel
from cri_api import RuntimeServiceStub, ListContainersRequest
stub = RuntimeServiceStub(insecure_channel(getenv("RUNTIME_SOCK")))
response = stub.ListContainers(ListContainersRequest())
containers = response.containers
```
### Updating Protobuf Python Generated Code
```shell
$ bin/update-proto.sh
```
Commit & create a new pull request!
### Development
Interactive development on MacOS can be done by leveraging [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/):
```shell
$ minikube start --container-runtime=cri-o
$ minikube ssh
$ socat -d -d TCP4-LISTEN:15432,fork UNIX-CONNECT:/var/run/crio/crio.sock
# In another window, you can now connect on $(minikube ip):15432
$ export RUNTIME_SOCK=$(minikube ip):15432
...
```
### Testing
Unit tests are run against all supported Python versions: 3.10, 3.11, and 3.12.
A basic set of integration tests is included alongside the unit tests, but are only run if the `RUNTIME_SOCK` environment variable is set correctly.
They are verified in CI against a minikube installation running Docker and `dockershim`.
Run unit tests with:
```shell
$ pytest
```
Raw data
{
"_id": null,
"home_page": "https://github.com/dominodatalab/container-runtime-interface-api",
"name": "container-runtime-interface-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Domino Data Lab",
"author_email": "steven.davidovitz@dominodatalab.com",
"download_url": "https://files.pythonhosted.org/packages/8b/66/beb7eee12926644243c4d1d51e9c9fe88430dc1b3e8b115eb047526ddb6f/container_runtime_interface_api-2.0.1.tar.gz",
"platform": null,
"description": "## container-runtime-interface-api\n\nPython library for communication with the Kubernetes [Container Runtime Interface API](https://github.com/kubernetes/cri-api).\n\n### Usage\n\nInstall `container-runtime-interface-api` with `pipenv` or `pip`:\n\n```shell\n$ pipenv install container-runtime-interface-api\nAdding container-runtime-interface-api to Pipfile's [packages]\u2026\n\u2714 Installation Succeeded\n...\n```\n\nThis project currently supports Python 3.10+.\n\n#### Connection\n\nConnection to the CRI API is generally done through a UNIX socket, but any gRPC address supported by [insecure_channel](https://grpc.github.io/grpc/python/grpc.html#grpc.insecure_channel) will work.\n\n```python\nfrom cri_api.channel import Channel\nchannel = Channel.from_env() # Loads from RUNTIME_SOCK\nchannel = Channel(\"unix:///var/run/dockershim.sock\") # Explicit argument\n```\n\n#### Images\n\nThe `Images` class is a thin wrapper around the existing ImageService API:\n\n```python\nfrom cri_api.images import Images\n\nchannel = Channel.from_env()\nimages = Images(channel)\n\nimages.list_images()\nimages.pull_image(\"busybox\")\n\nbusybox_images = [i[\"id\"] for i in images.list_images() if any(\"busybox\" in r for r in i[\"repoTags\"])]\n[images.remove_image(i) for i in busybox_images]\n```\n\n#### Containers\n\nThe `Containers` class is a thin wrapper around the existing RuntimeService API:\n\n```python\nfrom cri_api.images import Images\nfrom cri_api import ContainerFilter, ContainerState, ContainerStateValue\n\nchannel = Channel.from_env()\nimages = Containers(channel)\n\ncontainers.list_containers()\ncontainers.list_containers(ContainerFilter(state=ContainerStateValue(state=ContainerState.CONTAINER_EXITED)))\n\ncontainers.get_container(\"9d81052cc027a1fb2ec61b898ea0fd6fc88216ce730ad75f4c52b29849cb440f\")\n```\n\n#### Raw\n\nRaw access to the underlying CRI API objects can be done by importing from `cri_api`:\n\n```python\nfrom os import getenv\nfrom grpc import insecure_channel\nfrom cri_api import RuntimeServiceStub, ListContainersRequest\n\nstub = RuntimeServiceStub(insecure_channel(getenv(\"RUNTIME_SOCK\")))\nresponse = stub.ListContainers(ListContainersRequest())\ncontainers = response.containers\n```\n\n### Updating Protobuf Python Generated Code\n\n```shell\n$ bin/update-proto.sh\n```\n\nCommit & create a new pull request!\n\n### Development\n\nInteractive development on MacOS can be done by leveraging [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/):\n\n```shell\n$ minikube start --container-runtime=cri-o\n$ minikube ssh\n$ socat -d -d TCP4-LISTEN:15432,fork UNIX-CONNECT:/var/run/crio/crio.sock\n\n# In another window, you can now connect on $(minikube ip):15432\n$ export RUNTIME_SOCK=$(minikube ip):15432\n...\n```\n\n### Testing\n\nUnit tests are run against all supported Python versions: 3.10, 3.11, and 3.12.\n\nA basic set of integration tests is included alongside the unit tests, but are only run if the `RUNTIME_SOCK` environment variable is set correctly.\nThey are verified in CI against a minikube installation running Docker and `dockershim`.\n\nRun unit tests with:\n\n```shell\n$ pytest\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library for interaction with the Kubernetes container runtime interface API.",
"version": "2.0.1",
"project_urls": {
"Homepage": "https://github.com/dominodatalab/container-runtime-interface-api"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "da81591b7dd9329ad8d26f75a167745985a5b2f67d5258e00a6f7ecd43a9f1da",
"md5": "708dbdb77be950606389afaf80b391d7",
"sha256": "3c48c7492585b4387bd704ea30907ccd0200dcd845eb89eb2ddee1582c2845df"
},
"downloads": -1,
"filename": "container_runtime_interface_api-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "708dbdb77be950606389afaf80b391d7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 102728,
"upload_time": "2025-07-09T00:33:57",
"upload_time_iso_8601": "2025-07-09T00:33:57.897719Z",
"url": "https://files.pythonhosted.org/packages/da/81/591b7dd9329ad8d26f75a167745985a5b2f67d5258e00a6f7ecd43a9f1da/container_runtime_interface_api-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8b66beb7eee12926644243c4d1d51e9c9fe88430dc1b3e8b115eb047526ddb6f",
"md5": "3a81bd05316f8e735963bcb576548720",
"sha256": "04684bc160c2c5ad1937057f0dbe3b30b58da85cb7ab96bea0b2a037221297aa"
},
"downloads": -1,
"filename": "container_runtime_interface_api-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "3a81bd05316f8e735963bcb576548720",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 100654,
"upload_time": "2025-07-09T00:33:59",
"upload_time_iso_8601": "2025-07-09T00:33:59.582678Z",
"url": "https://files.pythonhosted.org/packages/8b/66/beb7eee12926644243c4d1d51e9c9fe88430dc1b3e8b115eb047526ddb6f/container_runtime_interface_api-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 00:33:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dominodatalab",
"github_project": "container-runtime-interface-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "container-runtime-interface-api"
}
JSON
