Overview of Docker Compose Bridge
Early Access
Compose Bridge command line is an early access product.
Introduction
Docker Compose makes it easy to define a multi-container application
to be run on a single-node Docker Engine, relying on a compose.yaml
file to
describe resources with a simple abstraction.
Compose Bridge lets you reuse this exact same compose.yaml
file but
translate it into another platform's definition format, with a primary
focus on Kubernetes. This transformation can be customized to match
specific needs and requirements.
Usage
Compose Bridge is a command line tool that consumes a compose.yaml
file
and runs a transformation to produce resource definitions for another platform.
By default, it produces Kubernetes manifests and a Kustomize overlay for Docker Desktop. For example:
$ compose-bridge -f compose.yaml convert
Kubernetes resource api-deployment.yaml created
Kubernetes resource db-deployment.yaml created
Kubernetes resource web-deployment.yaml created
Kubernetes resource api-expose.yaml created
Kubernetes resource db-expose.yaml created
Kubernetes resource web-expose.yaml created
Kubernetes resource 0-avatars-namespace.yaml created
Kubernetes resource default-network-policy.yaml created
Kubernetes resource private-network-policy.yaml created
Kubernetes resource public-network-policy.yaml created
Kubernetes resource db-db_data-persistentVolumeClaim.yaml created
Kubernetes resource api-service.yaml created
Kubernetes resource web-service.yaml created
Kubernetes resource kustomization.yaml created
Kubernetes resource db-db_data-persistentVolumeClaim.yaml created
Kubernetes resource api-service.yaml created
Kubernetes resource web-service.yaml created
Kubernetes resource kustomization.yaml created
Such manifests can then be used to run the application on Kubernetes using
the standard deployment command kubectl apply -k out/overlays/desktop/
.
Customization
The Kubernetes manifests produced by Compose Bridge are designed to allow deployment on Docker Desktop with Kubernetes enabled.
Kubernetes is such a versatile platform that there are many ways to map Compose concepts into a Kubernetes resource definitions. Compose Bridge lets you customize the transformation to match your own infrastructure decisions and preferences, with various level of flexibility / investment.
Modify the default templates
You can extract templates used by default transformation docker/compose-bridge-kubernetes
by running compose-bridge transformations create my-template --from docker/compose-bridge-kubernetes
and adjusting those to match your needs.
The templates will be extracted into a directory named after your template name (ie my-template
).
Inside, you will find a Dockerfile that allows you to create your own image to distribute your template, as well as a directory containing the templating files.
You are free to edit the existing files, delete them, or
add new ones to subsequently generate Kubernetes manifests that meet your needs.
You can then use the generated Dockerfile to package your changes into a new Transformer image, which you can then use with Compose Bridge:
$ docker build --tag mycompany/transform --push .
You can then use your transformation as a replacement:
$ compose-bridge -f compose.yaml convert --transformation mycompany/transform
For more information, see Templates.
Add your own templates
For resources that are not managed by Compose Bridge's default transformation,
you can build your own templates. The compose.yaml
model may not offer all
the configuration attributes required to populate the target manifest. If this is the case, you can
then rely on Compose custom extensions to let developers better describe the
application, and offer an agnostic transformation.
As an illustration, if developers add x-virtual-host
metadata
to service definitions in the compose.yaml
file, you can use the following custom attribute
to produce Ingress rules:
{{ $project := .name }}
#! {{ $name }}-ingress.yaml
# Generated code, do not edit
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: virtual-host-ingress
namespace: {{ $project }}
spec:
rules:
{{ range $name, $service := .services }}
{{ if $service.x-virtual-host }}
- host: ${{ $service.x-virtual-host }}
http:
paths:
- path: "/"
backend:
service:
name: ${{ name }}
port:
number: 80
{{ end }}
{{ end }}
Once packaged into a Docker image, you can use this custom template when transforming Compose models into Kubernetes in addition to other transformations:
$ compose-bridge -f compose.yaml convert \
--transformation docker/compose-bridge-kubernetes \
--transformation mycompany/transform
Build your own transformation
While Compose Bridge templates make it easy to customize with minimal changes, you may want to make significant changes, or rely on an existing conversion tool.
A Compose Bridge transformation is a Docker image that is designed to get a Compose model
from /in/compose.yaml
and produce platform manifests under /out
. This simple
contract makes it easy to bundle an alternate transformation, as illustrated below using
Kompose:
FROM alpine
# Get kompose from github release page
RUN apk add --no-cache curl
ARG VERSION=1.32.0
RUN ARCH=$(uname -m | sed 's/armv7l/arm/g' | sed 's/aarch64/arm64/g' | sed 's/x86_64/amd64/g') && \
curl -fsL \
"https://github.com/kubernetes/kompose/releases/download/v${VERSION}/kompose-linux-${ARCH}" \
-o /usr/bin/kompose
RUN chmod +x /usr/bin/kompose
CMD ["/usr/bin/kompose", "convert", "-f", "/in/compose.yaml", "--out", "/out"]
This Dockerfile bundles Kompose and defines the command to run this tool according to the Compose Bridge transformation contract.
Use compose-bridge
as a kubectl
plugin
To use the compose-bridge
binary as a kubectl
plugin, you need to make sure that the binary is available in your PATH and the name of the binary is prefixed with kubectl-
.
-
Rename or copy the
compose-bridge
binary tokubectl-compose_bridge
:$ mv /path/to/compose-bridge /usr/local/bin/kubectl-compose_bridge
-
Ensure that the binary is executable:
$ chmod +x /usr/local/bin/kubectl-compose_bridge
-
Verify that the plugin is recognized by
kubectl
:$ kubectl plugin list
In the output, you should see
kubectl-compose_bridge
. -
Now you can use
compose-bridge
as akubectl
plugin:$ kubectl compose-bridge [command]
Replace [command]
with any compose-bridge
command you want to use.