Personalizar Compose Bridge

Puedes personalizar cómo Compose Bridge convierte tus archivos de Docker Compose en formatos específicos de la plataforma.

Esta página explica cómo Compose Bridge utiliza plantillas para generar manifiestos de Kubernetes y cómo puedes personalizar estas plantillas para tus requisitos y necesidades específicas, o cómo puedes compilar tu propia transformación.

Cómo funciona

Compose Bridge utiliza transformaciones que te permiten convertir un modelo de Compose a otra forma.

Una transformación se empaqueta como una imagen de Docker que recibe el modelo de Compose completamente resuelto como /in/compose.yaml y puede producir cualquier archivo en el formato de destino bajo /out.

Compose Bridge incluye una transformación de Kubernetes por defecto utilizando plantillas de Go, la cual puedes personalizar reemplazando o extendiendo las plantillas.

Sintaxis de las plantillas

Compose Bridge utiliza plantillas para transformar un archivo de configuración de Compose en manifiestos de Kubernetes. Las plantillas son archivos de texto plano que utilizan la sintaxis de plantillas de Go. Esto permite la inserción de lógica y datos, haciendo que las plantillas sean dinámicas y adaptables según el modelo de Compose.

Cuando se ejecuta una plantilla, debe producir un archivo YAML, que es el formato estándar para los manifiestos de Kubernetes. Se pueden generar múltiples archivos siempre que estén separados por ---.

Cada archivo de salida YAML comienza con una notación de cabecera personalizada, por ejemplo:

#! manifest.yaml

En el siguiente ejemplo, una plantilla itera sobre los servicios definidos en un archivo compose.yaml. Para cada servicio, se genera un archivo de manifiesto de Kubernetes dedicado, nombrado según el servicio y que contiene las configuraciones especificadas.

{{ range $name, $service := .services }}
---
#! {{ $name }}-manifest.yaml
# Código generado, no editar
key: value
## ...
{{ end }}

Modelo de entrada

Puedes generar el modelo de entrada ejecutando docker compose config.

Esta salida YAML canónica sirve como entrada para las transformaciones de Compose Bridge. Dentro de las plantillas, se accede a los datos del archivo compose.yaml mediante la notación de puntos, lo que te permite navegar a través de estructuras de datos anidadas. Por ejemplo, para acceder al modo de despliegue de un servicio, utilizarías service.deploy.mode:

# iterar sobre una secuencia yaml
{{ range $name, $service := .services }}
 # acceder a un atributo anidado usando la notación de puntos
 {{ if eq $service.deploy.mode "global" }}
kind: DaemonSet
 {{ end }}
{{ end }}

Puedes consultar el esquema JSON de la Especificación de Compose para obtener una descripción completa del modelo de Compose. Este esquema detalla todas las configuraciones posibles y sus tipos de datos en el modelo de Compose.

Funciones auxiliares

Como parte de la sintaxis de plantillas de Go, Compose Bridge ofrece un conjunto de funciones auxiliares de YAML diseñadas para manipular datos dentro de las plantillas de manera eficiente:

En el siguiente ejemplo, la plantilla comprueba si se especifica un intervalo de comprobación de estado (healthcheck) para un servicio, aplica la función seconds para convertir este intervalo a segundos y asigna el valor al atributo periodSeconds.

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

Personaliza las plantillas por defecto

Dado que Kubernetes es una plataforma versátil, existen muchas formas de mapear los conceptos de Compose en definiciones de recursos de Kubernetes. Compose Bridge te permite personalizar la transformación para que coincida con tus propias decisiones y preferencias de infraestructura, con diferentes niveles de flexibilidad y esfuerzo.

Modifica las plantillas por defecto

Puedes extraer las plantillas utilizadas por la transformación por defecto docker/compose-bridge-kubernetes:

$ docker compose bridge transformations create --from docker/compose-bridge-kubernetes my-template

Las plantillas se extraen en un directorio con el nombre de tu plantilla, en este caso my-template. Incluye:

• Un Dockerfile con el que puedes crear tu propia imagen para distribuir tu plantilla
• Un directorio que contiene los archivos de plantilla

Edita, añade o elimina plantillas según sea necesario.

A continuación, puedes utilizar el Dockerfile generado para empaquetar tus cambios en una nueva imagen de transformación, la cual podrás usar con Compose Bridge:

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

Usa tu transformación como reemplazo:

$ docker compose bridge convert --transformations mycompany/transform

Plantillas de Model Runner

La transformación por defecto también incluye plantillas para aplicaciones que utilizan LLMs:

• model-runner-deployment.tmpl: Genera el despliegue de Kubernetes para Docker Model Runner. Personalízalo para cambiar el número de réplicas, las etiquetas de imagen, las solicitudes y límites de recursos, la configuración de programación de GPU, las tolerancias o variables de entorno adicionales.
• model-runner-service.tmpl: Construye el servicio que expone Docker Model Runner. Actualízalo para alternar entre los tipos ClusterIP, NodePort o LoadBalancer, ajustar puertos o añadir anotaciones para ingress y mallas de servicios (service meshes).
• model-runner-pvc.tmpl: Define la reclamación de volumen persistente (PVC) utilizada para almacenar los modelos descargados. Edítala para establecer el tamaño de almacenamiento, la clase de almacenamiento, los modos de acceso o las anotaciones de volumen requeridas por tu proveedor de almacenamiento.
• /overlays/model-runner/kustomization.yaml: Capa (overlay) de Kustomize que se aplica cuando despliegas Model Runner en un clúster de Kubernetes independiente. Extiéndela para añadir parches para etiquetas y anotaciones, adjuntar NetworkPolicies o incluir manifiestos adicionales.
• /overlays/desktop/deployment.tmpl: Plantilla de despliegue específica de Desktop que mantiene reducido a escala el Model Runner dentro del clúster y dirige las cargas de trabajo al punto de enlace (endpoint) del host. Ajústala si cambias el punto de enlace de Desktop o si quieres desplegar Model Runner en Desktop en lugar de depender del servicio del host.

Escenarios comunes de personalización:

• Habilita el soporte de GPU añadiendo solicitudes de recursos específicas del proveedor, límites y selectores de nodos en model-runner-deployment.tmpl.
• Aumenta o ajusta el almacenamiento para artefactos de modelos editando model-runner-pvc.tmpl para establecer el tamaño deseado, la clase de almacenamiento o el modo de acceso.
• Expón Model Runner fuera del clúster cambiando el tipo de servicio en model-runner-service.tmpl o añadiendo anotaciones de ingress en la capa de model-runner.
• Alinea las políticas del clúster añadiendo etiquetas, anotaciones o NetworkPolicies a través de /overlays/model-runner/kustomization.yaml.

Para obtener más detalles, consulta Usar Model Runner.

Añade tus propias plantillas

Para los recursos que no están gestionados por la transformación por defecto de Compose Bridge, puedes construir tus propias plantillas.

Es posible que el modelo compose.yaml no ofrezca todos los atributos de configuración requeridos para rellenar el manifiesto de destino. Si este es el caso, puedes recurrir a las extensiones personalizadas de Compose para describir mejor la aplicación y ofrecer una transformación agnóstica.

Por ejemplo, si añades metadatos x-virtual-host a las definiciones de servicio en el archivo compose.yaml, puedes utilizar el siguiente atributo personalizado para producir reglas de Ingress:

{{ $project := .name }}
#! {{ $name }}-ingress.yaml
# Código generado, no editar
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: virtual-host-ingress
  namespace: {{ $project }}
spec:
  rules:
{{ range $name, $service := .services }}
{{ range index $service "x-virtual-host" }}
  - host: ${{ . }}
    http:
      paths:
      - path: "/"
        backend:
          service:
            name: ${{ name }}
            port:
              number: 80
{{ end }}
{{ end }}

Una vez empaquetado en una imagen de Docker, puedes utilizar esta plantilla personalizada al transformar modelos de Compose a Kubernetes junto con otras transformaciones:

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

Construye tu propia transformación

Aunque las plantillas de Compose Bridge facilitan la personalización con cambios mínimos, es posible que desees realizar cambios significativos o depender de una herramienta de conversión existente.

Una transformación de Compose Bridge es una imagen de Docker diseñada para obtener un modelo de Compose de /in/compose.yaml y producir manifiestos de la plataforma bajo /out. Este sencillo contrato facilita la integración de una transformación alternativa utilizando Kompose:

FROM alpine

# Obtener kompose desde la página de versiones de GitHub
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"]

Este Dockerfile incluye Kompose y define el comando para ejecutar esta herramienta de acuerdo con el contrato de transformación de Compose Bridge.