Kompose: Convert Docker-Compose to Kubernetes and Helm Charts

Kompose is an open-source tool designed to assist developers in migrating containerized applications defined in Docker Compose to Kubernetes or Helm Charts. It simplifies the transition by automatically generating Kubernetes manifests (.yaml) or Helm chart structures from docker-compose.yaml files.

This article provides an in-depth guide on Kompose, including installation steps, detailed usage scenarios, best practices, and troubleshooting common issues.

Why Use Kompose?

Benefits:

• Seamless Kubernetes Migration: Reduces complexity in manually defining Kubernetes YAML configurations.
• Automation: Automates the transformation of Docker Compose files into Kubernetes Deployments, Services, ConfigMaps, PersistentVolumes, and more.
• Multi-Platform Support: Works on Linux, macOS, and Windows.
• Customizable Output: Allows generating different Kubernetes controller types (e.g., Deployment, StatefulSet, or DaemonSet).
• Supports Persistent Storage: Converts Docker volumes into PersistentVolumeClaims (PVCs).

Installation Guide

Linux/macOS

curl -L https://github.com/kubernetes/kompose/releases/latest/download/kompose-linux-amd64 -o kompose
chmod +x kompose
sudo mv kompose /usr/local/bin/        

Windows (PowerShell)

Invoke-WebRequest -Uri "https://github.com/kubernetes/kompose/releases/latest/download/kompose-windows-amd64.exe" -OutFile "kompose.exe"        

Verify installation:

kompose version        

Usage and Examples

1. Convert Docker-Compose to Kubernetes YAML

If you have a docker-compose.yaml file like this:

version: '3'
services:
  web:
    image: nginx
    ports:
      - "80:80"
  db:
    image: postgres
    environment:
      POSTGRES_PASSWORD: example        

Run Kompose to generate Kubernetes manifests:

kompose convert        

This generates multiple Kubernetes files:

• web-deployment.yaml
• web-service.yaml
• db-deployment.yaml
• db-service.yaml

To apply them to a Kubernetes cluster:

kubectl apply -f .        

To deploy directly without generating YAML files:

kompose up        

To delete the deployed resources:

kompose down        

2. Generating Helm Charts

To generate Helm charts instead of Kubernetes YAML files:

kompose convert -c        

This creates a Helm chart structure:

./web/
  ├── charts/
  ├── templates/
  │   ├── deployment.yaml
  │   ├── service.yaml
  │   ├── _helpers.tpl
  ├── values.yaml
  ├── Chart.yaml        

To install the generated Helm chart:

helm install myapp ./web/        

To uninstall:

helm uninstall myapp        

3. Converting and Deploying Stateful Applications

If your application requires stateful storage, you should ensure volumes are correctly mapped.

Example:

version: '3'
services:
  database:
    image: mysql
    volumes:
      - db-data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: secret
volumes:
  db-data:        

Kompose will generate:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: db-data
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi        

Deploy with:

kubectl apply -f .        

Advanced Kompose Options

Define Custom Namespace

kompose convert --namespace=my-namespace        

Change Controller Type (Deployment vs StatefulSet)

kompose convert --controller statefulset        

Generate Persistent Volume Claims (PVCs)

kompose convert --volumes persistentVolumeClaim        

Label Resources Automatically

kompose convert --labels owner=myteam,env=production        

Set Replicas

kompose convert --replicas 3        

Troubleshooting Common Issues

1. Missing Service or Incomplete Configuration

If Kompose does not generate a Service for your application, check your docker-compose.yaml file for missing ports mappings.

Solution: Ensure each service that needs to be exposed includes a ports section:

services:
  app:
    image: myapp
    ports:
      - "8080:8080"        

2. Persistent Volume Issues

By default, Kompose generates emptyDir volumes, which are ephemeral.

Solution: Convert volumes to PersistentVolumeClaims:

kompose convert --volumes persistentVolumeClaim        

3. Helm Chart Structure Issues

If helm install fails, ensure that the generated Helm chart contains a valid values.yaml and Chart.yaml.

Solution: Check file contents and correct any syntax errors manually.

As a Conclusion

Kompose significantly simplifies the process of migrating Docker Compose applications to Kubernetes and Helm. With support for different controllers, namespaces, persistent storage, and Helm chart generation, Kompose is a powerful tool for Kubernetes adoption.