From 36954ebd9ee97a9e3a8f8dbdf3d8632432f47872 Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Wed, 27 Mar 2024 16:39:04 +0100 Subject: [PATCH 1/3] compose-bridge doc - release v0.0.1 Signed-off-by: Nicolas De Loof Signed-off-by: Guillaume Lours <705411+glours@users.noreply.github.com> --- content/compose/bridge/_index.md | 188 +++++++++++++++++++++++ content/compose/bridge/templates.md | 72 +++++++++ content/compose/bridge/transformation.md | 24 +++ 3 files changed, 284 insertions(+) create mode 100644 content/compose/bridge/_index.md create mode 100644 content/compose/bridge/templates.md create mode 100644 content/compose/bridge/transformation.md diff --git a/content/compose/bridge/_index.md b/content/compose/bridge/_index.md new file mode 100644 index 000000000000..a56e1d5639c3 --- /dev/null +++ b/content/compose/bridge/_index.md @@ -0,0 +1,188 @@ +--- +description: Overview of Docker Compose Bridge +keywords: compose, orchestration, kubernetes, bridge +title: Overview of Docker Compose Bridge +--- + +This page provides usage information for the `compose-bridge` command. + +## Introduction + +Docker Compose makes it easy to define a multi-container application +to be ran on a single-node Docker engine, relying on compose.yaml to +describe resources with a simple abstraction. + +Compose bridge allows to reuse this exact same compose.yaml model but +translate it into another platform 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 that consumes a compose.yaml model +and run transformation to produce resource definitions for another platform. +[By default](transformation.md), it produces Kubernetes manifests and a Kustomize overlay for Docker Desktop +```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 based on a compose.yaml +model 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 let 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 adjust 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: + +```bash +$ docker build --tag mycompany/transform --push . +``` + +You can then use your transformation in replacement for the default one: +```bash +$ compose-bridge -f compose.yaml convert --transformation mycompany/transform +``` + +For more details check the [templates](./templates.md) documentation page. + +### Add your own templates + +For resources that are not managed by Compose Bridge default transformation, +you can build your own templates. The compose.yaml model maybe does not offer +the configuration attributes required to populate the target manifest, you can +then rely on Compose custom extensions to let developers better describe the +application, and offer an agnostic transformation. + +For illustration, let's consider developers can add `x-virtual-host` metadata +to service definitions in compose.yaml. You can use this 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 template make it easy to customize with minimal changes, +you maybe 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 compose model +from `/in/compose.yaml` and produce platform manifests under `/out`. This simple +contract make it easy to bundle an alternate transformation, as illustrated here 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 command to run this tool according +to 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-`. Here are the steps: + +1. Rename or copy the `compose-bridge` binary to `kubectl-compose_bridge`: + + ```bash + mv /path/to/compose-bridge /usr/local/bin/kubectl-compose_bridge + ``` + +2. Ensure that the binary is executable: + + ```bash + chmod +x /usr/local/bin/kubectl-compose_bridge + ``` + +3. Verify that the plugin is recognized by `kubectl`: + + ```bash + kubectl plugin list + ``` + + In the output, you should see `kubectl-compose_bridge`. + +4. Now you can use `compose-bridge` as a `kubectl` plugin: + + ```bash + kubectl compose-bridge [command] + ``` + +Replace `[command]` with any `compose-bridge` command you want to use. diff --git a/content/compose/bridge/templates.md b/content/compose/bridge/templates.md new file mode 100644 index 000000000000..a13aa1670746 --- /dev/null +++ b/content/compose/bridge/templates.md @@ -0,0 +1,72 @@ +--- +title: Compose Bridge templates +description: Learn about the Compose Bridge templates syntax +keywords: compose, bridge, templates +--- + +Compose Bridge default transformation uses templates to produce Kubernetes manifests. +This page describes the templating mechanism. + +## Syntax + +Templates are plain text files, using [go-template](https://pkg.go.dev/text/template) +to allow logic and data injection based on the compose.yaml model. + +Template when executed must produce yaml documents. Multiple document can be generated +as long as those are separated by `---` + +First comment in produce yaml document defines the file being generated using a custom notation: +```yaml +#! manifest.yaml +``` +With this header comment, `manifest.yaml` will be created by Compose Bridge with yalml document +content. + +By combining those together, you can write a template to iterate over some compose resource, +then for each of those produce a dedicated manifest: + +```yaml +{{ range $name, $service := .services }} +--- +#! {{ $name }}-manifest.yaml +# Generated code, do not edit +key: value +## ... +{{ end }} +``` + +This example will produce a manifest file for each and every compose services in you compose model. + + +## Input + +The input compose model is the canonical yaml model you can get by running + `docker compose config`. Within a template you can access model nodes using + dot notation: + + ```yaml +# iterate over a yaml sequence +{{ range $name, $service := .services }} + # access a nested attribute using dot notation + {{ if eq $service.deploy.mode "global" }} +kind: DaemonSet + {{ end }} +{{ end }} +``` + +You can check the [Compose Specification json-spec file](https://github.com/compose-spec/compose-go/blob/main/schema/compose-spec.json) to have a full overview of the Compose model. + +## Helpers + +As part of the go template syntax, Compose Bridge offers a set of helper functions: + +- `seconds` convert a [duration](https://github.com/compose-spec/compose-spec/blob/master/11-extension.md#specifying-durations) into an integer +- `uppercase` convert a string into upper case characters +- `title`: convert a string by capitalizing first letter of each word +- `safe`: convert a string into a safe identifier, replacing all characters but \[a-z\] with `-` +- `truncate`: removes the N first elements from a list +- `join`: group elements from a list into a single string, using sepearator +- `base64`: encode string as base64 +- `map`: transform value according to mappings expressed as `"value -> newValue"` strings +- `indent`: writes string content indented by N spaces +- `helmValue`: write the string content as a template value in final file diff --git a/content/compose/bridge/transformation.md b/content/compose/bridge/transformation.md new file mode 100644 index 000000000000..6da44ec3ff9d --- /dev/null +++ b/content/compose/bridge/transformation.md @@ -0,0 +1,24 @@ +--- +title: Compose Bridge default transformation +description: Learn about the Compose Bridge default transformation +keywords: compose, bridge, kubernetes +--- + +Compose Bridge default transformation produces Kubernetes manifests so you can deploy +your compose application to Kubernetes enabled inside Docker Desktop. + +Based on an arbitrary compose.yaml project, Compose Bridge will produce: + +- A [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) so all your resources are isolated and don't colide with another deployment +- A [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) with an entry for each and every config resource in your compose model +- [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)s for application services +- [Service](https://kubernetes.io/docs/concepts/services-networking/service/)s for ports exposed by your services, used for service-to-service communication +- [Service](https://kubernetes.io/docs/concepts/services-networking/service/)s for ports published by your services, with type `LoadBalancer` so that Docker Desktop will also expose same port on host +- [Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) to replicate the networking topology expressed in compose +- [PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)s for your volumes, using `hostpath` storage class so that Docker Desktop manage volume creation +- [Secret](https://kubernetes.io/docs/concepts/configuration/secret/)s with your secret encoded - this is designed for local use in a testing environment + +And 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` + - A Kustomize file to link the all those resources together From 835ee630697a588e3144d10eaefb6b2fc80c7899 Mon Sep 17 00:00:00 2001 From: Guillaume Lours <705411+glours@users.noreply.github.com> Date: Tue, 23 Apr 2024 18:00:56 +0200 Subject: [PATCH 2/3] Apply Ally's suggestions from first code review Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> --- content/compose/bridge/_index.md | 73 ++++++++++++------------ content/compose/bridge/templates.md | 22 +++---- content/compose/bridge/transformation.md | 20 +++---- 3 files changed, 57 insertions(+), 58 deletions(-) diff --git a/content/compose/bridge/_index.md b/content/compose/bridge/_index.md index a56e1d5639c3..70f172eeeb07 100644 --- a/content/compose/bridge/_index.md +++ b/content/compose/bridge/_index.md @@ -4,24 +4,23 @@ keywords: compose, orchestration, kubernetes, bridge title: Overview of Docker Compose Bridge --- -This page provides usage information for the `compose-bridge` command. ## Introduction Docker Compose makes it easy to define a multi-container application -to be ran on a single-node Docker engine, relying on compose.yaml to +to be run on a single-node Docker Engine, relying on a `compose.yaml` file to describe resources with a simple abstraction. -Compose bridge allows to reuse this exact same compose.yaml model but -translate it into another platform definition format, with a primary +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 that consumes a compose.yaml model -and run transformation to produce resource definitions for another platform. -[By default](transformation.md), it produces Kubernetes manifests and a Kustomize overlay for Docker Desktop +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 @@ -49,12 +48,12 @@ the standard deployment command `kubectl apply -k out/overlays/desktop/`. ## Customization -The Kubernetes manifests produced by Compose Bridge based on a compose.yaml -model are designed to allow deployment on Docker Desktop with Kubernetes enabled. +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 let you customize the transformation to match your own infrastructure +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. @@ -62,34 +61,34 @@ decisions and preferences, with various level of flexibility / investment. 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 adjust those to match your needs. +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: -```bash +```console $ docker build --tag mycompany/transform --push . ``` -You can then use your transformation in replacement for the default one: -```bash +You can then use your transformation as a replacement: +```console $ compose-bridge -f compose.yaml convert --transformation mycompany/transform ``` -For more details check the [templates](./templates.md) documentation page. +For more information, see [Templates](./templates.md). ### Add your own templates -For resources that are not managed by Compose Bridge default transformation, +For resources that are not managed by Compose Bridge's default transformation, you can build your own templates. The compose.yaml model maybe does not offer -the configuration attributes required to populate the target manifest, you can +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. -For illustration, let's consider developers can add `x-virtual-host` metadata -to service definitions in compose.yaml. You can use this custom attribute +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 @@ -118,8 +117,8 @@ spec: {{ end }} ``` -Once packaged into a docker image, you can use this custom template -when transforming compose models into kubernetes in addition to other +Once packaged into a Docker image, you can use this custom template +when transforming Compose models into Kubernetes in addition to other transformations: ```console @@ -130,13 +129,13 @@ $ compose-bridge -f compose.yaml convert \ ### Build your own transformation -While Compose Bridge template make it easy to customize with minimal changes, -you maybe want to make significant changes, or rely on an existing conversion tool. +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 compose model from `/in/compose.yaml` and produce platform manifests under `/out`. This simple -contract make it easy to bundle an alternate transformation, as illustrated here using -[kompose](https://kompose.io/): +contract makes it easy to bundle an alternate transformation, as illustrated below using +[Kompose](https://kompose.io/): ```Dockerfile FROM alpine @@ -153,36 +152,36 @@ RUN chmod +x /usr/bin/kompose CMD ["/usr/bin/kompose", "convert", "-f", "/in/compose.yaml", "--out", "/out"] ``` -This Dockerfile bundles kompose and defines command to run this tool according -to Compose Bridge transformation contract. +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-`. Here are the steps: +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`: - ```bash - mv /path/to/compose-bridge /usr/local/bin/kubectl-compose_bridge + ```console + $ mv /path/to/compose-bridge /usr/local/bin/kubectl-compose_bridge ``` 2. Ensure that the binary is executable: - ```bash - chmod +x /usr/local/bin/kubectl-compose_bridge + ```console + $ chmod +x /usr/local/bin/kubectl-compose_bridge ``` 3. Verify that the plugin is recognized by `kubectl`: - ```bash - kubectl plugin list + ```console + $ kubectl plugin list ``` In the output, you should see `kubectl-compose_bridge`. 4. Now you can use `compose-bridge` as a `kubectl` plugin: - ```bash - kubectl compose-bridge [command] + ```console + $ kubectl compose-bridge [command] ``` Replace `[command]` with any `compose-bridge` command you want to use. diff --git a/content/compose/bridge/templates.md b/content/compose/bridge/templates.md index a13aa1670746..c4e8bbeda5df 100644 --- a/content/compose/bridge/templates.md +++ b/content/compose/bridge/templates.md @@ -4,26 +4,26 @@ description: Learn about the Compose Bridge templates syntax keywords: compose, bridge, templates --- -Compose Bridge default transformation uses templates to produce Kubernetes manifests. +Compose Bridge's default transformation uses templates to produce Kubernetes manifests. This page describes the templating mechanism. ## Syntax Templates are plain text files, using [go-template](https://pkg.go.dev/text/template) -to allow logic and data injection based on the compose.yaml model. +to allow logic and data injection based on the `compose.yaml` model. -Template when executed must produce yaml documents. Multiple document can be generated +When a template is executed, it must produce a YAML file. Multiple files can be generated as long as those are separated by `---` -First comment in produce yaml document defines the file being generated using a custom notation: +The first line, when creating the YAML file, defines the file being generated using a custom notation: ```yaml #! manifest.yaml ``` With this header comment, `manifest.yaml` will be created by Compose Bridge with yalml document content. -By combining those together, you can write a template to iterate over some compose resource, -then for each of those produce a dedicated manifest: +Combining these together, you can write a template to iterate over some of Compose resources, +then for each resource you can produce a dedicated manifest: ```yaml {{ range $name, $service := .services }} @@ -35,7 +35,7 @@ key: value {{ end }} ``` -This example will produce a manifest file for each and every compose services in you compose model. +This example produces a manifest file for each and every Compose service in you Compose model. ## Input @@ -58,14 +58,14 @@ You can check the [Compose Specification json-spec file](https://github.com/comp ## Helpers -As part of the go template syntax, Compose Bridge offers a set of helper functions: +As part of the Go templating syntax, Compose Bridge offers a set of helper functions: -- `seconds` convert a [duration](https://github.com/compose-spec/compose-spec/blob/master/11-extension.md#specifying-durations) into an integer +- `seconds`: convert a [duration](https://github.com/compose-spec/compose-spec/blob/master/11-extension.md#specifying-durations) into an integer - `uppercase` convert a string into upper case characters - `title`: convert a string by capitalizing first letter of each word - `safe`: convert a string into a safe identifier, replacing all characters but \[a-z\] with `-` -- `truncate`: removes the N first elements from a list -- `join`: group elements from a list into a single string, using sepearator +- `truncate`: removes the N first elements from a list +- `join`: group elements from a list into a single string, using a separator - `base64`: encode string as base64 - `map`: transform value according to mappings expressed as `"value -> newValue"` strings - `indent`: writes string content indented by N spaces diff --git a/content/compose/bridge/transformation.md b/content/compose/bridge/transformation.md index 6da44ec3ff9d..e24d890d9220 100644 --- a/content/compose/bridge/transformation.md +++ b/content/compose/bridge/transformation.md @@ -4,19 +4,19 @@ description: Learn about the Compose Bridge default transformation keywords: compose, bridge, kubernetes --- -Compose Bridge default transformation produces Kubernetes manifests so you can deploy -your compose application to Kubernetes enabled inside Docker Desktop. +Compose Bridge produces Kubernetes manifests so you can deploy +your Compose application to Kubernetes that is enabled on Docker Desktop. -Based on an arbitrary compose.yaml project, Compose Bridge will produce: +Based on an arbitrary `compose.yaml` project, Compose Bridge will produce: - A [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) so all your resources are isolated and don't colide with another deployment -- A [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) with an entry for each and every config resource in your compose model -- [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)s for application services -- [Service](https://kubernetes.io/docs/concepts/services-networking/service/)s for ports exposed by your services, used for service-to-service communication -- [Service](https://kubernetes.io/docs/concepts/services-networking/service/)s for ports published by your services, with type `LoadBalancer` so that Docker Desktop will also expose same port on host -- [Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) to replicate the networking topology expressed in compose -- [PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)s for your volumes, using `hostpath` storage class so that Docker Desktop manage volume creation -- [Secret](https://kubernetes.io/docs/concepts/configuration/secret/)s with your secret encoded - this is designed for local use in a testing environment +- A [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) with an entry for each and every config resource in your Compose model +- [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) for application services +- [Services](https://kubernetes.io/docs/concepts/services-networking/service/) for ports exposed by your services, used for service-to-service communication +- [Services](https://kubernetes.io/docs/concepts/services-networking/service/) for ports published by your services, with type `LoadBalancer` so that Docker Desktop will also expose same port on host +- [Network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) to replicate the networking topology expressed in Compose +- [PersistentVolumeClaims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) for your volumes, using `hostpath` storage class so that Docker Desktop manages volume creation +- [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) with your secret encoded - this is designed for local use in a testing environment And a Kustomize overlay dedicated to Docker Desktop with: - Loadbalancer for services which need to expose ports on host From 5f2e2b6486179b409c0d960b13af2e3027d37e54 Mon Sep 17 00:00:00 2001 From: Guillaume Lours <705411+glours@users.noreply.github.com> Date: Tue, 23 Apr 2024 18:06:32 +0200 Subject: [PATCH 3/3] manually adapt some review feedback Signed-off-by: Guillaume Lours <705411+glours@users.noreply.github.com> --- content/compose/bridge/_index.md | 6 ++++-- content/compose/bridge/templates.md | 6 ++++-- content/compose/bridge/transformation.md | 2 ++ content/includes/compose-bridge-early-access.md | 5 +++++ 4 files changed, 15 insertions(+), 4 deletions(-) create mode 100644 content/includes/compose-bridge-early-access.md diff --git a/content/compose/bridge/_index.md b/content/compose/bridge/_index.md index 70f172eeeb07..86d2319202b9 100644 --- a/content/compose/bridge/_index.md +++ b/content/compose/bridge/_index.md @@ -4,6 +4,7 @@ keywords: compose, orchestration, kubernetes, bridge title: Overview of Docker Compose Bridge --- +{{< include "compose-bridge-early-access.md" >}} ## Introduction @@ -82,7 +83,7 @@ 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 maybe does not offer +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. @@ -132,7 +133,7 @@ $ compose-bridge -f compose.yaml convert \ 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 compose model +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/): @@ -156,6 +157,7 @@ This Dockerfile bundles Kompose and defines the command to run this tool accordi 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`: diff --git a/content/compose/bridge/templates.md b/content/compose/bridge/templates.md index c4e8bbeda5df..f42af1bb15f8 100644 --- a/content/compose/bridge/templates.md +++ b/content/compose/bridge/templates.md @@ -4,6 +4,8 @@ description: Learn about the Compose Bridge templates syntax keywords: compose, bridge, templates --- +{{< include "compose-bridge-early-access.md" >}} + Compose Bridge's default transformation uses templates to produce Kubernetes manifests. This page describes the templating mechanism. @@ -19,8 +21,8 @@ The first line, when creating the YAML file, defines the file being generated us ```yaml #! manifest.yaml ``` -With this header comment, `manifest.yaml` will be created by Compose Bridge with yalml document -content. +With this header comment, `manifest.yaml` will be created by Compose Bridge with the content following +the annotation. Combining these together, you can write a template to iterate over some of Compose resources, then for each resource you can produce a dedicated manifest: diff --git a/content/compose/bridge/transformation.md b/content/compose/bridge/transformation.md index e24d890d9220..37425bd518e7 100644 --- a/content/compose/bridge/transformation.md +++ b/content/compose/bridge/transformation.md @@ -4,6 +4,8 @@ description: Learn about the Compose Bridge default transformation keywords: compose, bridge, kubernetes --- +{{< include "compose-bridge-early-access.md" >}} + Compose Bridge produces Kubernetes manifests so you can deploy your Compose application to Kubernetes that is enabled on Docker Desktop. diff --git a/content/includes/compose-bridge-early-access.md b/content/includes/compose-bridge-early-access.md new file mode 100644 index 000000000000..fd1acf8d1cbb --- /dev/null +++ b/content/includes/compose-bridge-early-access.md @@ -0,0 +1,5 @@ +> **Early Access** +> +> Compose Bridge command line is an [early access](/release-lifecycle#early-access-ea) product. +> +{ .restricted } \ No newline at end of file