centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-03-27 06:18:55 +07:00
Code Issues Packages Projects Releases Wiki Activity

Engdocs 3051 (#23568)

Browse Source 
<!--Delete sections as needed -->

## Description

Freshens Compose Bridge content
Adds model runner support

## Related issues or tickets

<!-- Related issues, pull requests, or Jira tickets -->

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
This commit is contained in:
Allie Sadler
2025-10-21 09:51:34 +01:00
committed by GitHub
parent af67ce72e4
commit 7e3ab99961
4 changed files with 221 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
content/manuals/compose/bridge/_index.md
View File

@@ -8,15 +8,20 @@ weight: 50
{{< summary-bar feature_name="Compose bridge" >}}
Compose Bridge converts your Docker Compose configuration into platform-specific formats—primarily Kubernetes manifests. The default transformation generates Kubernetes manifests and a Kustomize overlay which are designed for deployment on Docker Desktop with Kubernetes enabled.
Compose Bridge converts your Docker Compose configuration into platform-specific deployment formats such as Kubernetes manifests. By default, it geneterates:
It's a flexible tool that lets you either take advantage of the [default transformation](usage.md) or [create a custom transformation](customize.md) to suit specific project needs and requirements.
- Kubernetes manifests
- A Kustomize overlay
Compose Bridge significantly simplifies the transition from Docker Compose to Kubernetes, making it easier for you to leverage the power of Kubernetes while maintaining the simplicity and efficiency of Docker Compose.
These outputs are ready for deployment on Docker Desktop with [Kubernetes enabled](/manuals/desktop/settings-and-maintenance/settings.md#kubernetes).
Compose Bridge helps you bridge the gap between Compose and Kubernetes, making it easier to adopt Kubernetes while keeping the simplicity and efficiency of Compose.
It's a flexible tool that lets you either take advantage of the [default transformation](usage.md) or [create a custom transformation](customize.md) to suit specific project needs and requirements.
## How it works
Compose Bridge uses transformations to let you convert a Compose model into another form.
Compose Bridge uses transformations to convert a Compose model into another form.
A transformation is packaged as a Docker image that receives the fully resolved Compose model as `/in/compose.yaml` and can produce any target format file under `/out`.
@@ -24,6 +29,10 @@ Compose Bridge provides its own transformation for Kubernetes using Go templates
For more detailed information on how these transformations work and how you can customize them for your projects, see [Customize](customize.md).
Compose Bridge also supports applications that use LLMs via Docker Model Runner.
For more details, see [Use Model Runner](use-model-runner.md).
## What's next?
- [Use Compose Bridge](usage.md)

79
content/manuals/compose/bridge/customize.md
View File

@@ -4,12 +4,13 @@ linkTitle: Customize
weight: 20
description: Learn how to customize Compose Bridge transformations using Go templates and Compose extensions
keywords: docker compose bridge, customize compose bridge, compose bridge templates, compose to kubernetes, compose bridge transformation, go templates docker
---
{{< summary-bar feature_name="Compose bridge" >}}
This page explains how Compose Bridge utilizes templating to efficiently translate Docker Compose files into Kubernetes manifests. It also explains how you can customize these templates for your specific requirements and needs, or how you can build your own transformation.
You can customize how Compose Bridge converts your Docker Compose files into platform-specific formats.
This page explains how Compose Bridge uses templating to generate Kubernetes manifests and how you can customize these templates for your specific requirements and needs, or how you can build your own transformation.
## How it works
@@ -19,7 +20,7 @@ A transformation is packaged as a Docker image that receives the fully-resolved
Compose Bridge includes a default Kubernetes transformation using Go templates, which you can customize by replacing or extending templates.
### Syntax
### Template syntax
Compose Bridge makes use of templates to transform a Compose configuration file into Kubernetes manifests. Templates are plain text files that use the [Go templating syntax](https://pkg.go.dev/text/template). This enables the insertion of logic and data, making the templates dynamic and adaptable according to the Compose model.
@@ -43,9 +44,11 @@ key: value
{{ end }}
```
### Input
### Input model
You can generate the input model by running `docker compose config`. This canonical YAML output serves as the input for Compose Bridge transformations. Within the templates, data from the `compose.yaml` is accessed using dot notation, allowing you to navigate through nested data structures. For example, to access the deployment mode of a service, you would use `service.deploy.mode`:
You can generate the input model by running `docker compose config`.
This canonical YAML output serves as the input for Compose Bridge transformations. Within the templates, data from the `compose.yaml` is accessed using dot notation, allowing you to navigate through nested data structures. For example, to access the deployment mode of a service, you would use `service.deploy.mode`:
```yaml
# iterate over a yaml sequence
@@ -57,22 +60,24 @@ kind: DaemonSet
{{ end }}
```
You can check the [Compose Specification JSON schema](https://github.com/compose-spec/compose-go/blob/main/schema/compose-spec.json) to have a full overview of the Compose model. This schema outlines all possible configurations and their data types in the Compose model.
You can check the [Compose Specification JSON schema](https://github.com/compose-spec/compose-go/blob/main/schema/compose-spec.json) for a full overview of the Compose model. This schema outlines all possible configurations and their data types in the Compose model.
### Helpers
### Helper functions
As part of the Go templating syntax, Compose Bridge offers a set of YAML helper functions designed to manipulate data within the templates efficiently:
- `seconds`: Converts a [duration](/reference/compose-file/extension.md#specifying-durations) into an integer
- `uppercase`: Converts a string into upper case characters
- `title`: Converts a string by capitalizing the first letter of each word
- `safe`: Converts a string into a safe identifier, replacing all characters (except lowercase a-z) with `-`
- `truncate`: Removes the N first elements from a list
- `join`: Groups elements from a list into a single string, using a separator
- `base64`: Encodes a string as base64 used in Kubernetes for encoding secrets
- `map`: Transforms a value according to mappings expressed as `"value -> newValue"` strings
- `indent`: Writes string content indented by N spaces
- `helmValue`: Writes the string content as a template value in the final file
| Function | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `seconds` | Converts a [duration](/reference/compose-file/extension.md#specifying-durations) into an integer (seconds). |
| `uppercase` | Converts a string to uppercase. |
| `title` | Capitalizes the first letter of each word. |
| `safe` | Converts a string into a safe identifier (replaces non-lowercase characters with `-`). |
| `truncate` | Removes the first N elements from a list. |
| `join` | Joins list elements into a single string with a separator. |
| `base64` | Encodes a string as base64 (used for Kubernetes secrets). |
| `map` | Maps values using `“value -> newValue”` syntax. |
| `indent` | Indents string content by N spaces. |
| `helmValue` | Outputs a Helm-style template value. |
In the following example, the template checks if a healthcheck interval is specified for a service, applies the `seconds` function to convert this interval into seconds and assigns the value to the `periodSeconds` attribute.
@@ -82,7 +87,7 @@ In the following example, the template checks if a healthcheck interval is speci
{{ end }}
```
## Customization
## Customize the default templates
As Kubernetes is a versatile platform, there are many ways
to map Compose concepts into Kubernetes resource definitions. Compose
@@ -91,29 +96,51 @@ decisions and preferences, with varying level of flexibility and effort.
### Modify the default templates
You can extract templates used by the default transformation `docker/compose-bridge-kubernetes`,
by running `docker compose bridge transformations create --from docker/compose-bridge-kubernetes my-template`
and adjusting the templates to match your needs.
You can extract templates used by the default transformation `docker/compose-bridge-kubernetes`:
```console
$ docker compose bridge transformations create --from docker/compose-bridge-kubernetes my-template
```
The templates are extracted into a directory named after your template name, in this case `my-template`. It includes:
- A Dockerfile that lets you create your own image to distribute your template
- A directory containing the templating files
Edit, [add](#add-your-own-templates), or remove templates as needed.
The templates are extracted into a directory named after your template name, in this case `my-template`.
It includes a Dockerfile that lets you 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 transformation 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:
Use your transformation as a replacement:
```console
$ docker compose bridge convert --transformations mycompany/transform
```
#### Model Runner templates
The default transformation also includes templates for applications that use LLMs:
- `model-runner-deployment.tmpl`
- `model-runner-service.tmpl`
- `model-runner-pvc.tmpl`
- `/overlays/model-runner/kustomization.yaml`
- `/overlays/desktop/deployment.tmpl`
These templates can be extended or replaced to change how Docker Model Runner is deployed or configured.
For more details, see [Use Model Runner](use-model-runner.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
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 better describe the
application, and offer an agnostic transformation.

98
content/manuals/compose/bridge/usage.md
View File

@@ -8,7 +8,9 @@ keywords: docker compose bridge, compose kubernetes transform, kubernetes from c
{{< summary-bar feature_name="Compose bridge" >}}
Compose Bridge supplies an out-of-the-box transformation for your Compose configuration file. Based on an arbitrary `compose.yaml` file, Compose Bridge produces:
Compose Bridge includes a built-in transformation that automatically converts your Compose configuration into a set of Kubernetes manifests.
Based on your `compose.yaml` file, it produces:
- A [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) so all your resources are isolated and don't conflict with resources from other deployments.
- A [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) with an entry for each and every [config](/reference/compose-file/configs.md) resource in your Compose application.
@@ -22,61 +24,74 @@ Compose Bridge supplies an out-of-the-box transformation for your Compose config
It also supplies a Kustomize overlay dedicated to Docker Desktop with:
- `Loadbalancer` for services which need to expose ports on host.
- A `PersistentVolumeClaim` to use the Docker Desktop storage provisioner `desktop-storage-provisioner` to handle volume provisioning more effectively.
- A Kustomize file to link all the resources together.
- A `Kustomization.yaml` file to link all the resources together.
If your Compose file defines a `models` section for a service, Compose Bridge automatically configures your deployment so your service can locate and use its models via Docker Model Runner.
For each declared model, the transformation injects two environment variables:
- `<MODELNAME>_URL`: The endpoint for Docker Model Runner serving that model
- `<MODELNAME>_MODEL`: The model’s name or identifier
You can optionally customize these variable names using `endpoint_var` and `model_var`.
The default transformation generates two different overlays - one for Docker Desktop whilst using a local instance of Docker Model Runner, and a `model-runner` overlay with all the relevant Kubernetes resources to deploy Docker Model Runner in a pod.
| Environment | Endpoint |
| -------------- | ----------------------------------------------- |
| Docker Desktop | `http://host.docker.internal:12434/engines/v1/` |
| Kubernetes | `http://model-runner/engines/v1/` |
For more details, see [Use Model Runner](use-model-runner.md).
## Use the default Compose Bridge transformation
To use the default transformation run the following command:
To convert your Compose file using the default transformation:
```console
$ docker compose bridge convert
```
Compose looks for a `compose.yaml` file inside the current directory and then converts it.
Compose looks for a `compose.yaml` file inside the current directory and generates Kubernetes manifests.
When successful, Compose Bridge generates Kubernetes manifests and logs output similar to the following:
Example output:
```console
$ docker compose bridge convert -f compose.yaml
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
$ docker compose -f compose.yaml bridge convert
Kubernetes resource backend-deployment.yaml created
Kubernetes resource frontend-deployment.yaml created
Kubernetes resource backend-expose.yaml created
Kubernetes resource frontend-expose.yaml created
Kubernetes resource 0-my-project-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 backend-service.yaml created
Kubernetes resource frontend-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 backend-deployment.yaml created
Kubernetes resource frontend-deployment.yaml created
Kubernetes resource backend-service.yaml created
Kubernetes resource frontend-service.yaml created
Kubernetes resource kustomization.yaml created
Kubernetes resource model-runner-configmap.yaml created
Kubernetes resource model-runner-deployment.yaml created
Kubernetes resource model-runner-service.yaml created
Kubernetes resource model-runner-volume-claim.yaml created
Kubernetes resource kustomization.yaml created
```
These files are then stored within your project in the `/out` folder.
All generated files are stored in the `/out` directory in your project.
The Kubernetes manifests can then be used to run the application on Kubernetes using
the standard deployment command `kubectl apply -k out/overlays/desktop/`.
## Deploy the generated manifests
> [!IMPORTANT]
>
> Make sure you have enabled Kubernetes in Docker Desktop before you deploy your Compose Bridge transformations.
> Before you deploy your Compose Bridge transformations, make sure you have [enabled Kubernetes](/manuals/desktop/settings-and-maintenance/settings.md#kubernetes) in Docker Desktop.
If you want to convert a `compose.yaml` file that is located in another directory, you can run:
Once the manifests are generated, deploy them to your local Kubernetes cluster:
```console
$ docker compose bridge convert -f <path-to-file>/compose.yaml
```
To see all available flags, run:
```console
$ docker compose bridge convert --help
$ kubectl apply -k out/overlays/desktop/
```
> [!TIP]
@@ -85,6 +100,21 @@ $ docker compose bridge convert --help
>
> Make sure you are signed in to your Docker account, navigate to your container in the **Containers** view, and in the top-right corner select **View configurations** and then **Convert and Deploy to Kubernetes**.
## Additional commands
Convert a `compose.yaml` file located in another directory:
```console
$ docker compose -f <path-to-file>/compose.yaml bridge convert
```
To see all available flags, run:
```console
$ docker compose bridge convert --help
```
## What's next?
- [Explore how you can customize Compose Bridge](customize.md)
- [Explore how you can customize Compose Bridge](customize.md)
- [Use Model Runner](use-model-runner.md).

91
content/manuals/compose/bridge/use-model-runner.md Normal file
View File

@@ -0,0 +1,91 @@
---
title: Use Docker Model Runner with Compose Bridge
linkTitle: Use Model Runner
weight: 30
description: How to use Docker Model Runner with Compose Bridge for consistent deployments
keywords: docker compose bridge, customize compose bridge, compose bridge templates, compose to kubernetes, compose bridge transformation, go templates docker, model runner, ai, llms
---
Compose Bridge supports model-aware deployments. It can deploy and configure Docker Model Runner, a lightweight service that hosts and serves machine LLMs.
This reduces manual setup for LLM-enabled services and keeps deployments consistent across Docker Desktop and Kubernetes environments.
If you have a `models` top-level element in your `compose.yaml` file, Compose Bridge:
- Automatically injects environment variables for each model’s endpoint and name.
- Configures model endpoints differently for Docker Desktop vs Kubernetes.
- Optionally deploys Docker Model Runner in Kubernetes when enabled in Helm values
## Configure model runner settings
When deploying using generated Helm Charts, you can control the model runner configuration through Helm values.
```yaml
# Model Runner settings
modelRunner:
# Set to false for Docker Desktop (uses host instance)
# Set to true for standalone Kubernetes clusters
enabled: false
# Endpoint used when enabled=false (Docker Desktop)
hostEndpoint: "http://host.docker.internal:12434/engines/v1/"
# Deployment settings when enabled=true
image: "docker/model-runner:latest"
imagePullPolicy: "IfNotPresent"
# GPU support
gpu:
enabled: false
vendor: "nvidia" # nvidia or amd
count: 1
# Node scheduling (uncomment and customize as needed)
# nodeSelector:
# accelerator: nvidia-tesla-t4
# tolerations: []
# affinity: {}
# Security context
securityContext:
allowPrivilegeEscalation: false
# Environment variables (uncomment and add as needed)
# env:
# DMR_ORIGINS: "http://localhost:31246"
resources:
limits:
cpu: "1000m"
memory: "2Gi"
requests:
cpu: "100m"
memory: "256Mi"
# Storage for models
storage:
size: "100Gi"
storageClass: "" # Empty uses default storage class
# Models to pre-pull
models:
- ai/qwen2.5:latest
- ai/mxbai-embed-large
```
## Deploying a model runner
### Docker Desktop
When `modelRunner.enabled` is `false`, Compose Bridge configures your workloads to connect to Docker Model Runner running on the host:
```text
http://host.docker.internal:12434/engines/v1/
```
The endpoint is automatically injected into your service containers.
### Kubernetes
When `modelRunner.enabled` is `true`, Compose Bridge uses the generated manifests to deploy Docker Model Runner in your cluster, including:
- Deployment: Runs the `docker-model-runner` container
- Service: Exposes port `80` (maps to container port `12434`)
- `PersistentVolumeClaim`: Stores model files
The `modelRunner.enabled` setting also determines the number of replicas for the `model-runner-deployment`:
- When `true`, the deployment replica count is set to 1, and Docker Model Runner is deployed in the Kubernetes cluster.
- When `false`, the replica count is 0, and no Docker Model Runner resources are deployed.