mirror of https://github.com/docker/docs.git
190 lines
6.8 KiB
Markdown
190 lines
6.8 KiB
Markdown
---
|
|
description: Overview of Docker Compose Bridge
|
|
keywords: compose, orchestration, kubernetes, bridge
|
|
title: Overview of Docker Compose Bridge
|
|
---
|
|
|
|
{{< include "compose-bridge-early-access.md" >}}
|
|
|
|
## 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](transformation.md), it produces Kubernetes manifests and a Kustomize overlay for Docker Desktop. For example:
|
|
```console
|
|
$ 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](#add-your-own-templates) 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:
|
|
|
|
```console
|
|
$ docker build --tag mycompany/transform --push .
|
|
```
|
|
|
|
You can then use your transformation as a replacement:
|
|
```console
|
|
$ compose-bridge -f compose.yaml convert --transformation mycompany/transform
|
|
```
|
|
|
|
For more information, see [Templates](./templates.md).
|
|
|
|
### 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:
|
|
|
|
```yaml
|
|
{{ $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:
|
|
|
|
```console
|
|
$ 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](https://kompose.io/):
|
|
|
|
```Dockerfile
|
|
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-`.
|
|
|
|
1. Rename or copy the `compose-bridge` binary to `kubectl-compose_bridge`:
|
|
|
|
```console
|
|
$ mv /path/to/compose-bridge /usr/local/bin/kubectl-compose_bridge
|
|
```
|
|
|
|
2. Ensure that the binary is executable:
|
|
|
|
```console
|
|
$ chmod +x /usr/local/bin/kubectl-compose_bridge
|
|
```
|
|
|
|
3. Verify that the plugin is recognized by `kubectl`:
|
|
|
|
```console
|
|
$ kubectl plugin list
|
|
```
|
|
|
|
In the output, you should see `kubectl-compose_bridge`.
|
|
|
|
4. Now you can use `compose-bridge` as a `kubectl` plugin:
|
|
|
|
```console
|
|
$ kubectl compose-bridge [command]
|
|
```
|
|
|
|
Replace `[command]` with any `compose-bridge` command you want to use.
|