Containerd

---




name: containerd
compatibility: opencode
completeness: 95
content-types:
- guidance
- examples
- do-dont
- config
description: '"Containerd in Cloud-Native Engineering - An open and reliable container"
  runtime'
license: MIT
maturity: stable
metadata:
  domain: cncf
  output-format: manifests
  related-skills: null
  role: reference
  scope: infrastructure
  triggers: cloud-native, containerd, engineering, reliable
  archetypes:
  - educational
  - strategic
  anti_triggers:
  - brainstorming
  - vague ideation
  - non-containerized architecture
  response_profile:
    verbosity: medium
    directive_strength: low
    abstraction_level: strategic
version: "1.0.0"




---




# Containerd in Cloud-Native Engineering

**Category:** cncf  
**Status:** Active  
**Stars:** 20,615  
**Last Updated:** 2026-04-22  
**Primary Language:** Go  
**Documentation:** [https://containerd.io/docs/](https://containerd.io/docs/)  

---

## Purpose and Use Cases

Containerd is a core component of the cloud-native ecosystem, serving as a industry-standard container runtime focused on simplicity, robustness, and portability for running containers.

### What Problem Does It Solve?

The need for a stable, production-grade container runtime that implements theContainer Runtime Interface (CRI) for Kubernetes while being cloud-native and extensible.

### When to Use This Project

Use containerd as your container runtime when running Kubernetes (it's the default CRI implementation), or when you need a stable, production-grade runtime for container management.

### Key Use Cases


- Kubernetes container runtime (default)
- Container image management
- Container lifecycle management
- Integration with container orchestration platforms


---

## Architecture Design Patterns

### Core Components


- **Container Runtime**: Manages container lifecycle
- **Image Manager**: Handles image pulling and extraction
- **Snapshotter**: Filesystem layering and storage
- **Task Service**: Manages process execution
- **Metadata Service**: Stores container and image metadata
- **GRPC API**: Interface for external clients


### Component Interactions


1. **Kubelet → Containerd GRPC**: Container management requests
2. **Containerd → Snapshotter**: Filesystem layering
3. **Containerd → Image Service**: Image pulling and extraction
4. **Image Service → Registry**: Pulls images from registries
5. **Task Service → Containerd**: Process execution


### Data Flow Patterns


1. **Container Creation**: Request → Metadata service → Image service → Snapshotter → Task service → Container
2. **Image Pull**: Registry API → Image download → Snapshot extraction → Metadata update
3. **Process Execution**: Task start → Process creation → Stdio pipes → Exit status


### Design Principles


- **Simplicity**: Focused, minimal API
- **Robustness**: Production-grade reliability
- **Portability**: Works across platforms
- **Extensibility**: Plugin system for features
- **CRI-Compliant**: Kubernetes compatibility


---

## Integration Approaches

### Integration with Other CNCF Projects


- **Kubernetes**: CRI implementation for container management
- **CNI**: Container networking interface
- **Containerd**: Image management integration
- **Buildkit**: Building images
- **nerdctl**: Container CLI


### API Patterns


- **GRPC API**: Client interface
- **CRI**: Container Runtime Interface
- **Image Service**: Image management API
- **Task Service**: Process execution API
- **Events API**: Event streaming


### Configuration Patterns


- **TOML Configuration**: Main config file
- **CRI Configuration**: Container runtime config
- **Plugins**: Plugin-specific configuration
- **Runtime Class**: Per-pod runtime config


### Extension Mechanisms


- **Plugins**: Add functionality
- **Runtime V2**: Custom runtimes
- **Snapshotters**: Custom storage backends
- **Content Store**: Custom image storage


---

## Common Pitfalls and How to Avoid Them

### Misconfigurations


- **Runtime Class**: Incorrect runtime specification
- **Image Pull Policy**: Misconfigured pull policies
- **Snapshotter**: Incorrect snapshotter configuration
- **Storage Path**: Insufficient disk space
- **Plugin Configuration**: Incorrect plugin settings


### Performance Issues


- **Image Pull Time**: Slow registry access
- **Snapshot Performance**: Storage backend issues
- **Metadata Database**: Large metadata size
- **GRPC Latency**: High API server latency


### Operational Challenges


- **Version Compatibility**: Kubernetes compatibility
- **Upgrade Process**: Rolling node upgrades
- **Storage Management**: Snapshot and image cleanup
- **Networking**: CNI integration


### Security Pitfalls


- **Privileged Containers**: Running containers with root
- **Image Signing**: Not validating signed images
- **Network Exposure**: Unnecessary port exposure
- **Secrets**: Insecure secret handling


---

## Coding Practices

### Idiomatic Configuration


- **TOML Format**: Human-readable config
- **Plugin Blocks**: Organized configuration
- **CRI Configuration**: Container runtime settings
- **Environment Override**: Runtime overrides


### API Usage Patterns


- **ctr CLI**: Debugging and testing
- **crictl CLI**: CRI-compatible CLI
- **GRPC API**: Programmatic control
- **CRI API**: Kubernetes integration


### Observability Best Practices


- **Metrics**: Runtime metrics
- **Audit Logging**: Container events
- **Debug Commands**: Container inspection
- **Logs**: Container stdout/stderr


### Testing Strategies


- **Unit Tests**: Component tests
- **Integration Tests**: CRI compliance
- **E2E Tests**: Full container lifecycle
- **Compatibility Tests**: Kubernetes compatibility


### Development Workflow


- **Development**: containerd development setup
- **Testing**: Go tests, integration tests
- **Debugging**: ctr, crictl, debug commands
- **Deployment**: System packages, containers
- **CI/CD**: GitHub Actions, integration tests
- **Tools**: ctr, crictl, runc


---

## Fundamentals

### Essential Concepts


- **Container**: Isolated process environment
- **Image**: Read-only template for containers
- **Snapshot**: Filesystem layer
- **Task**: Running process in container
- **Execution**: Process execution
- **Event**: Container lifecycle events
- **Namespace**: Isolated container storage
- **Content**: Image content storage
- **Metadata**: Container and image metadata
- **GRPC**: Interface for external clients


### Terminology Glossary


- **Container**: Isolated process
- **Image**: Container template
- **Snapshot**: Filesystem layer
- **Task**: Running process
- **Execution**: Process execution
- **Event**: Lifecycle event
- **Namespace**: Isolated storage
- **Content**: Image content
- **Metadata**: Container metadata
- **GRPC API**: Client interface


### Data Models and Types


- **Container**: Container definition
- **Image**: Image definition
- **Snapshot**: Snapshot metadata
- **Task**: Task definition
- **Event**: Event data
- **Namespace**: Namespace configuration
- **Metadata**: Container metadata
- **Content**: Content descriptor


### Lifecycle Management


- **Container Lifecycle**: Create → Start → Stop → Delete
- **Image Lifecycle**: Pull → Extract → Run
- **Task Lifecycle**: Start → Wait → Delete
- **Snapshot Lifecycle**: Prepare → Mount → Unmount
- **Event Lifecycle**: Emit → Buffer → Process


### State Management


- **Container State**: Running/paused/stopped
- **Image State**: Pull status
- **Snapshot State**: Mount state
- **Task State**: Process status
- **Metadata State**: Database state


---

## Scaling and Deployment Patterns

### Horizontal Scaling


- **Node Scaling**: Multiple containerd instances
- **Image Pull Parallelization**: Concurrent image pulls
- **Snapshotter Scaling**: Storage backend scaling


### High Availability


- **Node HA**: Multiple nodes with containerd
- **Image Caching**: Local image cache
- **Snapshotter HA**: Storage backend HA


### Production Deployments


- **Production Configuration**: Optimized for workload
- **Storage Configuration**: Production storage backend
- **Security**: Rootless mode, seccomp, AppArmor
- **Monitoring**: Runtime metrics collection
- **Upgrade Strategy**: Rolling node upgrades


### Upgrade Strategies


- **Node Upgrade**: Rolling node upgrade
- **Version Compatibility**: Kubernetes version support
- **Storage Migration**: Snapshotter migration
- **Graceful Shutdown**: Container task draining


### Resource Management


- **Image Storage**: Image layer storage management
- **Snapshot Storage**: Snapshot space management
- **Memory Configuration**: Container memory limits
- **CPU Configuration**: Container CPU limits


---

## Additional Resources

- **Official Documentation:** [https://containerd.io/docs/](https://containerd.io/docs/)
- **GitHub Repository:** [github.com/containerd/containerd](https://github.com/containerd/containerd)
- **CNCF Project Page:** [cncf.io/projects/containerd/](https://www.cncf.io/projects/containerd/)
- **Community:** Check the GitHub repository for community channels
- **Versioning:** Refer to project's release notes for version-specific features

---

## Examples

### Configure Registry Mirrors

```yaml
# Configure registry mirrors in /etc/containerd/config.toml
version = 2

[plugins."io.containerd.grpc.v1.cri".registry]
  config_path = "/etc/containerd/certs.d"

[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
    endpoint = ["https://registry-1.docker.io"]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
    endpoint = ["https://gcr.io"]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."ghcr.io"]
    endpoint = ["https://ghcr.io"]
```

### Configure Snapshotster

```yaml
# Configure different snapshotter for better performance
version = 2

[plugins."io.containerd.grpc.v1.cri".containerd]
  snapshotter = "overlayfs"
  default_runtime_name = "runc"

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes]
  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
    runtime_type = "io.containerd.runc.v2"
    runtime_engine = ""
    runtime_root = ""

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
  SystemdCgroup = true
  BinaryName = "containerd-shim-runc-v2"
```

### Enable Content Trust

```yaml
# Enable content trust for image verification
# Set environment variable
export DOCKER_CONTENT_TRUST=1

# Or configure in containerd config
version = 2

[plugins."io.containerd.grpc.v1.cri".containerd]
  disable_snapshot_annotations = false
  discard_unpacked_layers = false

[plugins."io.containerd.grpc.v1.cri".x509_key_pair_streaming]
  tls_cert_file = "/etc/containerd/certs/client.crt"
  tls_key_file = "/etc/containerd/certs/client.key"
```

## Troubleshooting

### Containerd fails to start

**Cause:** Incorrect config.toml syntax or missing directories

**Solution:**

```bash
# Validate configuration
containerd config dump

# Check for syntax errors
containerd config validate

# Create missing directories
sudo mkdir -p /etc/containerd/certs.d
sudo mkdir -p /var/lib/containerd

# Restart service
sudo systemctl restart containerd
```

### Image pull failures

**Cause:** Registry authentication or network issues

**Solution:**

```bash
# Configure registry credentials
sudo mkdir -p /etc/containerd/certs.d/<registry>
sudo cat > /etc/containerd/certs.d/<registry>/hosts.toml <<EOF
[host."https://<registry>"]
  capabilities = ["pull", "resolve"]
  credentials = { username = "<user>", password = "<pass>" }
EOF

# Restart containerd
sudo systemctl restart containerd

# Test image pull
ctr images pull <registry>/<image>
```

### Snapshotter errors (overlayfs/unix)

**Cause:** File system compatibility or disk space issues

**Solution:**

```bash
# Check available space
df -h /var/lib/containerd

# Change snapshotter in config
# Try 'native' snapshotter for compatibility
version = 2
[plugins."io.containerd.grpc.v1.cri".containerd]
  snapshotter = "native"

# Or try 'stargz' for lazy pulling
[plugins."io.containerd.grpc.v1.cri".containerd.snapshotter]
  name = "stargz"
```

### CRI gRPC server not starting

**Cause:** Port conflicts or socket file issues

**Solution:**

```bash
# Check for port conflicts
sudo ss -tlnp | grep 10010

# Remove stale socket file
sudo rm -f /var/run/containerd/containerd.sock

# Restart containerd
sudo systemctl restart containerd

# Verify gRPC is working
ctr version
```

### Image garbage collection not working

**Cause:** Disk usage thresholds not properly configured

**Solution:**

```bash
# Configure garbage collection
version = 2

[plugins."io.containerd.grpc.v1.cri"]
  [plugins."io.containerd.grpc.v1.cri".containerd]
    discard_unpacked_layers = true

[plugins."io.containerd.grpc.v1.cri".containerd.snapshotter]
  name = "overlayfs"

[plugins."io.containerd.grpc.v1.cri".containerd]
  [plugins."io.containerd.grpc.v1.cri".containerd.garbage_collection_policy]
    min_reclaim = "10Gi"
    threshold = 85
```
*Content generated automatically. Verify against official documentation before production use.*

## Troubleshooting

### Deployment failures

**Cause:** Configuration errors or resource constraints

**Solution:** Check pod logs with `kubectl logs <pod>`, verify configuration values, and ensure adequate cluster resources.


### Performance issues

**Cause:** Resource limits or configuration bottlenecks

**Solution:** Monitor resource usage with `kubectl top`, adjust resource limits, and optimize configuration settings.


### Configuration errors

**Cause:** YAML syntax or missing required fields

**Solution:** Validate YAML syntax, check required configuration fields, and verify environment-specific settings.


### Integration problems

**Cause:** API compatibility or version mismatches

**Solution:** Verify API compatibility, check dependency versions, and review integration documentation.


### Connectivity issues

**Cause:** Network policies or service discovery problems

**Solution:** Check network policies, verify service endpoints, and ensure proper DNS resolution.

---

## When to Use

Use this skill when:

- **Integrating a CNCF project into Kubernetes infrastructure** — You need to configure, deploy, or troubleshoot a cloud-native tool within a cluster
- **Designing cloud-native architecture** — You are selecting and integrating CNCF tools to solve specific infrastructure challenges
- **Resolving operational issues** — A CNCF component is misbehaving, underperforming, or needs configuration changes
---

## Core Workflow

1. **Assess Requirements** — Understand the use case, scale, integration needs, and existing infrastructure. **Checkpoint:** Document requirements, constraints, and success criteria.

2. **Design Architecture** — Plan component interactions, data flow, and deployment strategy using cloud-native best practices. **Checkpoint:** Verify the architecture addresses all requirements and follows CNCF conventions.

3. **Implement & Configure** — Create manifests, configurations, and deployment scripts. Include resource limits, health checks, and observability hooks. **Checkpoint:** Validate all YAML against schema and test in a staging environment.

4. **Deploy & Monitor** — Apply manifests to the cluster, verify component health, and confirm observability is working. **Checkpoint:** Confirm all pods/services are running, probes passing, and metrics/alerts configured.

---

## Constraints

### MUST DO
- Include at least one complete working YAML manifest example
- Note when content is auto-generated vs. manually verified
- Reference relevant CNCF project documentation

### MUST NOT DO
- Deploy manifests without testing in a staging environment first
- Use deprecated API versions (e.g., apps/v1beta1)
- Omit resource limits and requests in Kubernetes manifests

---

## Live References

> **These links are resolved at load time** — content is fetched and inlined to provide the latest documentation.

- [Containerd Documentation](https://containerd.io/docs/)
- [Containerd Configuration](https://github.com/containerd/containerd/blob/main/docs/man/containerd-config.toml.5.md)
- [Containerd CRI Plugin](https://github.com/containerd/containerd/blob/main/docs/cri/config.md)
- [Containerd Namespace Management](https://github.com/containerd/containerd/blob/main/docs/namespaces.md)
- [Containerd Image Management](https://github.com/containerd/containerd/blob/main/docs/getting-started.md)