How to Migrate Docker Compose Apps to Kubernetes with containerd and Kompose

Scenario

Assume a Docker‑Compose file that defines a front‑end service and a MySQL database. The goal is to redeploy this stack on a Kubernetes cluster that uses containerd as the container runtime.

containerd and the CRI

Kubernetes interacts with a container runtime through the Container Runtime Interface (CRI). containerd implements the CRI, providing a lightweight, secure runtime focused on container lifecycle management.

CLI tools for containerd

crictl – a Kubernetes‑oriented debugging tool with commands similar to kubectl (e.g., crictl pods, crictl ps, crictl exec). Useful for inspecting pod status, viewing logs, and executing commands inside containers.

ctr – a low‑level client for advanced containerd users. It can manipulate namespaces, tasks, snapshots and other internal resources.

Convert Docker‑Compose to Kubernetes manifests

The official conversion tool Kompose generates Deployments, Services, PersistentVolumeClaims and other resources from a docker‑compose.yml file. kompose convert After conversion, edit the generated YAML as needed and apply it to the cluster:

kubectl apply -f <filename.yaml>

Keeping a container alive

Kubernetes terminates a pod when the container’s main process exits. For containers that would otherwise exit immediately (e.g., a static front‑end image), add a long‑running command to the pod spec, such as:

tail -f /dev/null – reads from an empty device forever (recommended).

sleep infinity – puts the process into an indefinite sleep.

Custom entrypoint script – run a user‑defined script that blocks for the required lifetime.

Accessing external services

Kubernetes can reach services outside the cluster via two patterns.

Endpoints (manual IP)

Create a Service object and an associated Endpoints object that point to the external IP and port.

apiVersion: v1
kind: Service
metadata:
  name: mysql-external
spec:
  ports:
  - protocol: TCP
    port: 3306
    targetPort: 3306
---
apiVersion: v1
kind: Endpoints
metadata:
  name: mysql-external
subsets:
- addresses:
  - ip: 172.16.66.6
  ports:
  - port: 3306

ExternalName Service (DNS alias)

If the external service has a DNS name, a Service of type ExternalName creates a CNAME record automatically.

apiVersion: v1
kind: Service
metadata:
  name: mysql-external
spec:
  type: ExternalName
  externalName: mysql.example.com

Use the Endpoints method when only an IP address is available; use ExternalName when a DNS name exists for simpler maintenance.

kubectl autocomplete troubleshooting

If autocomplete fails with “command not found” errors, the completion script is missing or not sourced. Install it for the current shell, for example Bash:

kubectl completion bash > ~/.kubectl_completion
echo "source ~/.kubectl_completion" >> ~/.bashrc
source ~/.bashrc

Summary

Migrating a Docker‑Compose stack to Kubernetes with containerd involves:

Understanding containerd’s role and using crictl / ctr for inspection.

Converting manifests with Kompose and applying them via kubectl.

Ensuring containers stay alive by adding a persistent command.

Configuring external service access with either Endpoints or an ExternalName Service.