Personnaliser Compose Bridge

Table des matières

Availability: Beta

Cette page explique comment Compose Bridge utilise les modèles pour traduire efficacement les fichiers Docker Compose en manifestes Kubernetes. Elle explique également comment vous pouvez personnaliser ces modèles pour vos exigences et besoins spécifiques, ou comment vous pouvez construire votre propre transformation.

Comment ça marche

Compose Bridge utilise des transformations pour vous permettre de convertir un modèle Compose en une autre forme.

Une transformation est empaquetée sous forme d'image Docker qui reçoit le modèle Compose entièrement résolu comme /in/compose.yaml et peut produire n'importe quel fichier de format cible sous /out.

Compose Bridge fournit sa transformation pour Kubernetes en utilisant des modèles Go, de sorte qu'il soit facile de l'étendre pour la personnalisation en remplaçant simplement ou en ajoutant vos propres modèles.

Syntaxe

Compose Bridge utilise des modèles pour transformer un fichier de configuration Compose en manifestes Kubernetes. Les modèles sont des fichiers de texte brut qui utilisent la syntaxe de modélisation Go. Cela permet l'insertion de logique et de données, rendant les modèles dynamiques et adaptables selon le modèle Compose.

Quand un modèle est exécuté, il doit produire un fichier YAML qui est le format standard pour les manifestes Kubernetes. Plusieurs fichiers peuvent être générés tant qu'ils sont séparés par ---

Chaque fichier de sortie YAML commence par une notation d'en-tête personnalisée, par exemple :

#! manifest.yaml

Dans l'exemple suivant, un modèle itère sur les services définis dans un fichier compose.yaml. Pour chaque service, un fichier manifeste Kubernetes dédié est généré, nommé selon le service et contenant les configurations spécifiées.

{{ range $name, $service := .services }}
---
#! {{ $name }}-manifest.yaml
# Code généré, ne pas éditer
key: value
## ...
{{ end }}

Entrée

Le modèle Compose d'entrée est le modèle YAML canonique que vous pouvez obtenir en exécutant docker compose config. Dans les modèles, les données du compose.yaml sont accessibles en utilisant la notation par points, vous permettant de naviguer à travers les structures de données imbriquées. Par exemple, pour accéder au mode de déploiement d'un service, vous utiliseriez service.deploy.mode :

# itérer sur une séquence yaml
{{ range $name, $service := .services }}
 # accéder à un attribut imbriqué en utilisant la notation par points
 {{ if eq $service.deploy.mode "global" }}
kind: DaemonSet
 {{ end }}
{{ end }}

Vous pouvez consulter le schéma JSON de la spécification Compose pour avoir un aperçu complet du modèle Compose. Ce schéma décrit toutes les configurations possibles et leurs types de données dans le modèle Compose.

Assistants

Dans le cadre de la syntaxe de modélisation Go, Compose Bridge offre un ensemble de fonctions d'assistance YAML conçues pour manipuler les données dans les modèles efficacement :

seconds : Convertit une durée en entier
uppercase : Convertit une chaîne en caractères majuscules
title : Convertit une chaîne en capitalisant la première lettre de chaque mot
safe : Convertit une chaîne en identifiant sûr, remplaçant tous les caractères (sauf a-z minuscules) par -
truncate : Supprime les N premiers éléments d'une liste
join : Groupe les éléments d'une liste en une seule chaîne, en utilisant un séparateur
base64 : Encode une chaîne en base64 utilisée dans Kubernetes pour encoder les secrets
map : Transforme une valeur selon des mappages exprimés comme des chaînes "valeur -> nouvelleValeur"
indent : Écrit le contenu de la chaîne indenté de N espaces
helmValue : Écrit le contenu de la chaîne comme valeur de modèle dans le fichier final

Dans l'exemple suivant, le modèle vérifie si un intervalle de vérification de santé est spécifié pour un service, applique la fonction seconds pour convertir cet intervalle en secondes et assigne la valeur à l'attribut periodSeconds.

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

Personnalisation

Comme Kubernetes est une plateforme polyvalente, il y a de nombreuses façons de mapper les concepts Compose en définitions de ressources Kubernetes. Compose Bridge vous permet de personnaliser la transformation pour correspondre à vos propres décisions d'infrastructure et préférences, avec différents niveaux de flexibilité et d'effort.

Modifier les modèles par défaut

Vous pouvez extraire les modèles utilisés par la transformation par défaut docker/compose-bridge-kubernetes, en exécutant docker compose bridge transformations create --from docker/compose-bridge-kubernetes my-template et en ajustant les modèles pour répondre à vos besoins.

Les modèles sont extraits dans un répertoire nommé d'après votre nom de modèle, dans ce cas my-template. Il inclut un Dockerfile qui vous permet de créer votre propre image pour distribuer votre modèle, ainsi qu'un répertoire contenant les fichiers de modélisation. Vous êtes libre de modifier les fichiers existants, de les supprimer, ou d'ajouter de nouveaux pour générer par la suite des manifestes Kubernetes qui répondent à vos besoins. Vous pouvez ensuite utiliser le Dockerfile généré pour empaqueter vos modifications dans une nouvelle image de transformation, que vous pouvez ensuite utiliser avec Compose Bridge :

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

Vous pouvez ensuite utiliser votre transformation comme remplacement :

$ docker compose bridge convert --transformations mycompany/transform

Ajouter vos propres modèles

Pour les ressources qui ne sont pas gérées par la transformation par défaut de Compose Bridge, vous pouvez construire vos propres modèles. Le modèle compose.yaml peut ne pas offrir tous les attributs de configuration requis pour remplir le manifeste cible. Si c'est le cas, vous pouvez alors vous appuyer sur les extensions personnalisées Compose pour mieux décrire l'application, et offrir une transformation agnostique.

Par exemple, si vous ajoutez des métadonnées x-virtual-host aux définitions de service dans le fichier compose.yaml, vous pouvez utiliser l'attribut personnalisé suivant pour produire des règles Ingress :

{{ $project := .name }}
#! {{ $name }}-ingress.yaml
# Code généré, ne pas éditer
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 }}

Une fois empaqueté dans une image Docker, vous pouvez utiliser ce modèle personnalisé lors de la transformation de modèles Compose en Kubernetes en plus d'autres transformations :

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

Construire votre propre transformation

Bien que les modèles Compose Bridge facilitent la personnalisation avec des modifications minimales, vous pourriez vouloir apporter des changements significatifs, ou vous appuyer sur un outil de conversion existant.

Une transformation Compose Bridge est une image Docker qui est conçue pour obtenir un modèle Compose depuis /in/compose.yaml et produire des manifestes de plateforme sous /out. Ce contrat simple facilite l'empaquetage d'une transformation alternative en utilisant Kompose :

FROM alpine

# Obtenir kompose depuis la page de release 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"]

Ce Dockerfile empaquette Kompose et définit la commande pour exécuter cet outil selon le contrat de transformation Compose Bridge.