Container Image Management
Registering OCI images from Docker Hub and GHCR, cluster node pre-fetching, and gVisor compatibility guidelines.
OCI Image Support
microsrv natively supports standard OCI (Open Container Initiative) container images built with Docker, Podman, Buildah, or standard CI/CD workflows.
You can import images from any public or private container registry:
- Docker Hub:
nginx:1.27,postgres:16-alpine,python:3.12-slim,node:20-bookworm-slim - GitHub Packages (GHCR):
ghcr.io/my-org/my-service:v1.0.0 - Quay.io, GitLab Container Registry, and custom registry endpoints.
Adding Images to a Project
Before running a container, register the image reference in your project to allow cluster worker nodes to pre-pull and cache its layers.
Via Web Console:
- Navigate to Console → Container Images.
- Click Create Image.
- Provide the OCI image reference string (e.g.,
docker.io/library/nginx:alpineorpython:3.12-slim). - Click Create.
Via REST API:
curl -X POST "https://api.microsrv.ru/api/v1/projects/${PROJECT_ID}/container-images" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"region_id": "ru-central1",
"ref": "docker.io/library/nginx:alpine"
}'Image States & Lifecycle
Once submitted, the image transitions through the following states:
| State | Description |
|---|---|
| Pending | Request registered; worker nodes are dispatched to pull layers. |
| Downloading | Layer downloading, verification, and local unpack in progress. |
| Ready | Image is cached and ready for instantaneous container launches. |
| Failed | Pull failed (e.g., nonexistent repository tag or network timeout). |
[!TIP] Pre-caching image layers enables instant container startup from the Ready state (~1–2 seconds).
Application & Runtime Compatibility
The container sandbox runtime implements Linux kernel system calls in user-space, supporting virtually all modern application stacks:
Fully Supported:
- Languages and Runtimes: Go, Rust, Python, Node.js / TypeScript, Java, C / C++, PHP, Ruby, .NET.
- Web Servers and Proxies: Nginx, Envoy, Caddy, Traefik.
- Databases and Brokers: PostgreSQL, MySQL, Redis, SQLite, MongoDB, ClickHouse.
- Standard Linux Utilities:
curl,git,ffmpeg,tar,bash, etc.
Sandbox Restrictions:
- Host kernel module loading (
insmod,modprobe) is blocked for sandbox security. - Direct access to raw host kernel devices (such as
/dev/kmem) is restricted.