mirror of https://github.com/docker/docs.git
add how-to page explaining usage of Compose provider services (#22586)
<!--Delete sections as needed --> ## Description Add how-to page for Compose provider services explaining usage and configuration of this new feature allowing extending Compose behaviour ## Related issues or tickets https://docker.atlassian.net/browse/APCLI-1091 ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [x] Technical review - [x] Editorial review - [ ] Product review --------- Signed-off-by: Guillaume Lours <705411+glours@users.noreply.github.com> Co-authored-by: Nicolas De loof <nicolas.deloof@gmail.com> Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
This commit is contained in:
parent
751d6681cc
commit
f6bb42e96d
|
@ -0,0 +1,125 @@
|
|||
---
|
||||
title: Use provider services
|
||||
description: Learn how to use provider services in Docker Compose to integrate external capabilities into your applications
|
||||
keywords: compose, docker compose, provider, services, platform capabilities, integration, model runner, ai
|
||||
weight: 112
|
||||
params:
|
||||
sidebar:
|
||||
badge:
|
||||
color: green
|
||||
text: New
|
||||
---
|
||||
|
||||
{{< summary-bar feature_name="Compose provider services" >}}
|
||||
|
||||
Docker Compose supports provider services, which allow integration with services whose lifecycles are managed by third-party components rather than by Compose itself.
|
||||
This feature enables you to define and utilize platform-specific services without the need for manual setup or direct lifecycle management.
|
||||
|
||||
|
||||
## What are provider services?
|
||||
|
||||
Provider services are a special type of service in Compose that represents platform capabilities rather than containers.
|
||||
They allow you to declare dependencies on specific platform features that your application needs.
|
||||
|
||||
When you define a provider service in your Compose file, Compose works with the platform to provision and configure
|
||||
the requested capability, making it available to your application services.
|
||||
|
||||
## Using provider services
|
||||
|
||||
To use a provider service in your Compose file, you need to:
|
||||
|
||||
1. Define a service with the `provider` attribute
|
||||
2. Specify the `type` of provider you want to use
|
||||
3. Configure any provider-specific options
|
||||
4. Declare dependencies from your application services to the provider service
|
||||
|
||||
Here's a basic example:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
database:
|
||||
provider:
|
||||
type: awesomecloud
|
||||
options:
|
||||
type: mysql
|
||||
foo: bar
|
||||
app:
|
||||
image: myapp
|
||||
depends_on:
|
||||
- database
|
||||
```
|
||||
|
||||
Notice the dedicated `provider` attribute in the `database` service.
|
||||
This attribute specifies that the service is managed by a provider and lets you define options specific to that provider type.
|
||||
|
||||
The `depends_on` attribute in the `app` service specifies that it depends on the `database` service.
|
||||
This means that the `database` service will be started before the `app` service, allowing the provider information
|
||||
to be injected into the `app` service.
|
||||
|
||||
## How it works
|
||||
|
||||
During the `docker compose up` command execution, Compose identifies services relying on providers and works with them to provision
|
||||
the requested capabilities. The provider then populates Compose model with information about how to access the provisioned resource.
|
||||
|
||||
This information is passed to services that declare a dependency on the provider service, typically through environment
|
||||
variables. The naming convention for these variables is:
|
||||
|
||||
```env
|
||||
<<PROVIDER_SERVICE_NAME>>_<<VARIABLE_NAME>>
|
||||
```
|
||||
|
||||
For example, if your provider service is named `database`, your application service might receive environment variables like:
|
||||
|
||||
- `DATABASE_URL` with the URL to access the provisioned resource
|
||||
- `DATABASE_TOKEN` with an authentication token
|
||||
- Other provider-specific variables
|
||||
|
||||
Your application can then use these environment variables to interact with the provisioned resource.
|
||||
|
||||
## Provider types
|
||||
|
||||
The `type` field in a provider service references the name of either:
|
||||
|
||||
1. A Docker CLI plugin (e.g., `docker-model`)
|
||||
2. A binary available in the user's PATH
|
||||
|
||||
When Compose encounters a provider service, it looks for a plugin or binary with the specified name to handle the provisioning of the requested capability.
|
||||
|
||||
For example, if you specify `type: model`, Compose will look for a Docker CLI plugin named `docker-model` or a binary named `model` in the PATH.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
ai-runner:
|
||||
provider:
|
||||
type: model # Looks for docker-model plugin or model binary
|
||||
options:
|
||||
model: ai/example-model
|
||||
```
|
||||
|
||||
The plugin or binary is responsible for:
|
||||
|
||||
1. Interpreting the options provided in the provider service
|
||||
2. Provisioning the requested capability
|
||||
3. Returning information about how to access the provisioned resource
|
||||
|
||||
This information is then passed to dependent services as environment variables.
|
||||
|
||||
## Benefits of using provider services
|
||||
|
||||
Using provider services in your Compose applications offers several benefits:
|
||||
|
||||
1. Simplified configuration: You don't need to manually configure and manage platform capabilities
|
||||
2. Declarative approach: You can declare all your application's dependencies in one place
|
||||
3. Consistent workflow: You use the same Compose commands to manage your entire application, including platform capabilities
|
||||
|
||||
## Creating your own provider
|
||||
|
||||
If you want to create your own provider to extend Compose with custom capabilities, you can implement a Compose plugin that registers provider types.
|
||||
|
||||
For detailed information on how to create and implement your own provider, refer to the [Compose Extensions documentation](https://github.com/docker/compose/blob/main/docs/extension.md).
|
||||
This guide explains the extension mechanism that allows you to add new provider types to Compose.
|
||||
|
||||
## Reference
|
||||
|
||||
- [Docker Model Runner documentation](/manuals/ai/model-runner.md)
|
||||
- [Compose Extensions documentation](https://github.com/docker/compose/blob/main/docs/extension.md)
|
|
@ -109,6 +109,8 @@ Compose model runner:
|
|||
requires: Docker Compose [2.35.0](/manuals/compose/releases/release-notes.md#2300) and later, and Docker Desktop 4.41 and later
|
||||
Compose OCI artifact:
|
||||
requires: Docker Compose [2.34.0](/manuals/compose/releases/release-notes.md#2340) and later
|
||||
Compose provider services:
|
||||
requires: Docker Compose [2.36.0](/manuals/compose/releases/release-notes.md) and later
|
||||
Compose replace file:
|
||||
requires: Docker Compose [2.24.4](/manuals/compose/releases/release-notes.md#2244) and later
|
||||
Compose required:
|
||||
|
|
Loading…
Reference in New Issue