181 lines
6.7 KiB
Markdown
181 lines
6.7 KiB
Markdown
# **crictl: CLI for CRI-Compatible Container Runtimes**
|
||
|
||
## Overview
|
||
|
||
`crictl` is a **command-line interface** for **Container Runtime Interface (CRI)**–compatible runtimes such as **containerd** and **CRI-O**, primarily used within Kubernetes environments.
|
||
|
||
It provides node-level visibility and control over pods, containers, and images. While it resembles Docker CLI in syntax, it is designed for **debugging** and **inspection**, not for managing workloads outside Kubernetes control.
|
||
|
||
`crictl` is part of the **[cri-tools](https://github.com/kubernetes-sigs/cri-tools)** project, which also includes `critest`.
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
1. Navigate to the [cri-tools releases page](https://github.com/kubernetes-sigs/cri-tools/releases) to find the version compatible with your Kubernetes or CRI runtime.
|
||
2. Download and install `crictl`:
|
||
|
||
```bash
|
||
VERSION="v1.33.0"
|
||
wget https://github.com/kubernetes-sigs/cri-tools/releases/download/$VERSION/crictl-$VERSION-linux-amd64.tar.gz
|
||
tar zxvf crictl-$VERSION-linux-amd64.tar.gz
|
||
sudo mv crictl /usr/local/bin/
|
||
```
|
||
|
||
*(Adjust version and architecture as needed.)*
|
||
3. Clean up the tarball if desired.
|
||
4. Verify installation:
|
||
|
||
```bash
|
||
crictl --version
|
||
```
|
||
|
||
---
|
||
|
||
## Configuration and Endpoints
|
||
|
||
`crictl` communicates with CRI runtimes using socket endpoints.
|
||
|
||
### Configuration Methods
|
||
|
||
You can configure endpoints via:
|
||
|
||
* **Command-line flags**: `--runtime-endpoint`, `--image-endpoint`
|
||
* **Environment variables**:
|
||
`CONTAINER_RUNTIME_ENDPOINT`, `IMAGE_SERVICE_ENDPOINT`
|
||
* **Configuration file**: Default path `/etc/crictl.yaml`
|
||
* **Custom config file**: Use `--config=<path>`
|
||
|
||
### Example `/etc/crictl.yaml`
|
||
|
||
```yaml
|
||
runtime-endpoint: unix:///var/run/containerd/containerd.sock
|
||
image-endpoint: unix:///var/run/containerd/containerd.sock
|
||
timeout: 10
|
||
debug: true
|
||
```
|
||
|
||
If no endpoint is provided, `crictl` attempts to connect to a list of known sockets, which can slow operations.
|
||
|
||
### Modifying Configuration
|
||
|
||
```bash
|
||
crictl config --set debug=true
|
||
crictl config --get debug
|
||
```
|
||
|
||
Additional configuration parameters include:
|
||
|
||
* `pull-image-on-create`
|
||
* `disable-pull-on-run`
|
||
|
||
---
|
||
|
||
## Global Options
|
||
|
||
| Flag | Description |
|
||
| --------------------------- | ------------------------------------------ |
|
||
| `-h`, `--help` | Display help and usage information |
|
||
| `-v`, `--version` | Display crictl and runtime version details |
|
||
| `--runtime-endpoint <path>` | Specify CRI runtime socket |
|
||
| `--image-endpoint <path>` | Specify CRI image service socket |
|
||
| `--timeout <duration>` | Connection timeout (e.g., `5s`) |
|
||
| `-D`, `--debug` | Enable verbose output |
|
||
| `--config <path>` | Specify a custom config file |
|
||
|
||
---
|
||
|
||
## Common Commands
|
||
|
||
### Status and Information
|
||
|
||
| Command | Description |
|
||
| ---------------- | ----------------------------------------------------- |
|
||
| `crictl version` | Display version and runtime API info |
|
||
| `crictl info` | Show runtime health, plugin states, and configuration |
|
||
|
||
### Pods / Pod Sandboxes
|
||
|
||
| Command | Description |
|
||
| ----------------------------------- | ---------------------------------- |
|
||
| `crictl pods` | List all pod sandboxes on the node |
|
||
| `crictl inspectp <POD_ID>` | Inspect a specific pod sandbox |
|
||
| `crictl runp <sandbox-config.json>` | Create a new pod sandbox |
|
||
| `crictl stopp <POD_ID>` | Stop a pod sandbox |
|
||
| `crictl rmp <POD_ID>` | Remove a pod sandbox |
|
||
|
||
### Containers
|
||
|
||
| Command | Description |
|
||
| ---------------------------------------------------------------------- | ---------------------------------------- |
|
||
| `crictl ps` / `crictl ps -a` | List running / all containers |
|
||
| `crictl inspect <CONTAINER_ID>` | Inspect a specific container |
|
||
| `crictl create <POD_ID> <container-config.json> <sandbox-config.json>` | Create a container in a pod |
|
||
| `crictl start <CONTAINER_ID>` | Start a container |
|
||
| `crictl exec -i -t <CONTAINER_ID> <command>` | Execute a command inside a container |
|
||
| `crictl stop <CONTAINER_ID>` | Stop a running container |
|
||
| `crictl rm <CONTAINER_ID>` | Remove a stopped container |
|
||
| `crictl stats` | Show CPU and memory usage for containers |
|
||
|
||
### Images
|
||
|
||
| Command | Description |
|
||
| ------------------------- | ----------------------------- |
|
||
| `crictl images` | List available images |
|
||
| `crictl inspecti <IMAGE>` | Inspect image metadata |
|
||
| `crictl pull <IMAGE>` | Pull an image from a registry |
|
||
| `crictl rmi <IMAGE>` | Remove an image |
|
||
| `crictl load <tarball>` | Load an image from a tar file |
|
||
|
||
---
|
||
|
||
## Best Practices and Caveats
|
||
|
||
* **Kubelet cleanup:** Containers or pods created manually with `crictl` may be removed by the kubelet since they’re not managed by the Kubernetes control plane. Use for debugging only.
|
||
* **Permissions:** Root privileges or socket access are often required to communicate with the runtime.
|
||
* **Version compatibility:** Always match your `crictl` version to your Kubernetes or CRI runtime.
|
||
* **Timeout tuning:** Adjust `--timeout` or configuration to avoid connection failures.
|
||
* **Not a Docker replacement:** Although similar in command structure, `crictl` interacts directly with the CRI layer and may not support all Docker features.
|
||
|
||
---
|
||
|
||
## Example Debugging Workflow
|
||
|
||
1. SSH into a Kubernetes node.
|
||
2. Check runtime health:
|
||
|
||
```bash
|
||
crictl info
|
||
crictl version
|
||
```
|
||
3. List pod sandboxes:
|
||
|
||
```bash
|
||
crictl pods
|
||
```
|
||
4. Inspect a pod:
|
||
|
||
```bash
|
||
crictl inspectp <POD_ID>
|
||
```
|
||
5. List and inspect containers:
|
||
|
||
```bash
|
||
crictl ps -a
|
||
crictl inspect <CONTAINER_ID>
|
||
```
|
||
6. Execute into or inspect logs:
|
||
|
||
```bash
|
||
crictl exec -it <CONTAINER_ID> sh
|
||
```
|
||
7. Clean up stuck containers or unused images:
|
||
|
||
```bash
|
||
crictl stop <CONTAINER_ID>
|
||
crictl rm <CONTAINER_ID>
|
||
crictl rmi <IMAGE>
|
||
```
|
||
|
||
This workflow is typically used for **node-level debugging**, especially when `kubectl` cannot access or display runtime state.
|