自定义 Compose Bridge

实验性

Compose Bridge 是一个实验性产品。

本页面解释了 Compose Bridge 如何利用模板高效地将 Docker Compose 文件转换为 Kubernetes 清单。它还说明了您如何根据特定需求自定义这些模板，或如何构建自己的转换方案。

工作原理

Compose Bridge 使用转换功能，让您能够将 Compose 模型转换为其他形式。

转换被打包为一个 Docker 镜像，该镜像接收完全解析的 Compose 模型作为 /in/compose.yaml，并可在 /out 下生成任意目标格式文件。

Compose Bridge 使用 Go 模板为 Kubernetes 提供转换功能，因此只需替换或追加您自己的模板，即可轻松进行自定义扩展。

语法

Compose Bridge 利用模板将 Compose 配置文件转换为 Kubernetes 清单。模板是使用 Go 模板语法的纯文本文件。这使得可以插入逻辑和数据，从而让模板能够根据 Compose 模型动态调整并具备适应性。

当模板执行时，它必须生成一个 YAML 文件，这是 Kubernetes 清单的标准格式。只要文件之间用 --- 分隔，就可以生成多个文件。

每个 YAML 输出文件都以自定义头部标记开始，例如：

#! manifest.yaml

在以下示例中，模板会遍历 compose.yaml 文件中定义的服务。对于每个服务，都会生成一个专用的 Kubernetes 清单文件，该文件根据服务名称命名，并包含指定的配置。

{{ range $name, $service := .services }}
---
#! {{ $name }}-manifest.yaml
# Generated code, do not edit
key: value
## ...
{{ end }}

输入

输入的 Compose 模型是通过运行 docker compose config 可获得的标准 YAML 模型。在模板中，使用点表示法访问来自 compose.yaml 的数据，使您能够遍历嵌套的数据结构。例如，要访问服务的部署模式，您可以使用 service.deploy.mode：

# 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 }}

您可以查看 Compose 规范 JSON 模式，以全面了解 Compose 模型。该模式概述了 Compose 模型中所有可能的配置及其数据类型。

帮助工具

作为 Go 模板语法的一部分，Compose Bridge 提供了一组 YAML 辅助函数，旨在高效地操作模板内的数据：

seconds: 将一个持续时间转换为整数
uppercase: 将字符串转换为大写字母
title: 通过将每个单词的首字母大写来转换字符串
safe: 将字符串转换为安全的标识符，将所有字符（小写 a-z 除外）替换为 -
truncate: 从列表中移除前 N 个元素
join: 使用分隔符将列表中的元素组合成单个字符串
base64: 将字符串编码为 base64，用于 Kubernetes 中的密钥编码
map: 根据表示为 "value -> newValue" 字符串的映射转换值
indent: 写入缩进 N 个空格的字符串内容
helmValue：将字符串内容作为模板值写入最终文件

在以下示例中，模板会检查是否为服务指定了健康检查间隔，应用 seconds 函数将该间隔转换为秒，并将值赋给 periodSeconds 属性。

{{ if $service.healthcheck.interval }}
            periodSeconds: {{ $service.healthcheck.interval | seconds }}{{ end }}
{{ end }}

自定义

由于 Kubernetes 是一个多功能平台，因此有多种方法可以将 Compose 概念映射到 Kubernetes 资源定义中。Compose Bridge 允许您自定义转换过程，以匹配您自身的基础设施决策和偏好，并提供不同级别的灵活性和工作量。

修改默认模板

您可以通过运行 compose-bridge transformations create --from docker/compose-bridge-kubernetes my-template 提取默认转换 docker/compose-bridge-kubernetes 所使用的模板，并根据您的需求调整这些模板。

模板被提取到一个以您的模板名称命名的目录中，在本例中为my-template.
它包含一个 Dockerfile，可让您创建自己的镜像以分发模板，同时还包含一个存放模板文件的目录。
您可以自由编辑现有文件、删除它们，或添加新的内容随后生成符合您需求的 Kubernetes 清单。
然后，您可以使用生成的 Dockerfile 将您的更改打包到新的转换镜像中，随后便可将其与 Compose Bridge 配合使用：

$ docker build --tag mycompany/transform --push .

然后您可以将您的转换用作替换：

$ compose-bridge convert --transformations mycompany/transform

添加您自己的模板

对于未被 Compose Bridge 默认转换所管理的资源，您可以构建自己的模板。compose.yaml 模型可能无法提供填充目标清单所需的所有配置属性。如果是这种情况，您可以借助 Compose 自定义扩展来更准确地描述应用程序，并提供一种与平台无关的转换方式。

例如，如果您在 compose.yaml 文件的服务定义中添加 x-virtual-host 元数据，则可以使用以下自定义属性来生成 Ingress 规则：

{{ $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 }}

一旦打包成 Docker 镜像，除了其他转换之外，您还可以在将 Compose 模型转换为 Kubernetes 时使用此自定义模板：

$ compose-bridge convert \
    --transformation docker/compose-bridge-kubernetes \
    --transformation mycompany/transform

构建您自己的转型方案

虽然 Compose Bridge 模板只需少量更改即可轻松自定义，但您可能希望进行重大更改，或依赖现有的转换工具。

Compose Bridge 转换是一个 Docker 镜像，旨在从 /in/compose.yaml 获取 Compose 模型，并在 /out 下生成平台清单。这种简单的约定使得使用 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"]

此 Dockerfile 捆绑了 Kompose，并根据 Compose Bridge 转换契约定义了运行该工具的命令。

接下来是什么？

探索高级集成