Pilote distant

Table des matières

Le pilote distant Buildx permet des charges de travail de construction personnalisées plus complexes, vous permettant de vous connecter à des instances BuildKit gérées de manière externe. Ceci est utile pour les scénarios qui nécessitent une gestion manuelle du démon BuildKit, ou lorsqu'un démon BuildKit est exposé depuis une autre source.

Synopsis

$ docker buildx create \
  --name remote \
  --driver remote \
  tcp://localhost:1234

Le tableau suivant décrit les options spécifiques au pilote disponibles que vous pouvez passer à --driver-opt :

Paramètre	Type	Défaut	Description
`key`	Chaîne		Définit la clé client TLS.
`cert`	Chaîne		Chemin absolu vers le certificat client TLS à présenter à `buildkitd`.
`cacert`	Chaîne		Chemin absolu vers l'autorité de certification TLS utilisée pour la validation.
`servername`	Chaîne	Nom d'hôte du point de terminaison.	Nom du serveur TLS utilisé dans les requêtes.
`default-load`	Booléen	`false`	Charge automatiquement les images dans le magasin d'images de Docker Engine.

Exemple : BuildKit distant sur des sockets Unix

Ce guide vous montre comment créer une configuration avec un démon BuildKit écoutant sur un socket Unix, et comment faire en sorte que Buildx s'y connecte.

Assurez-vous que BuildKit est installé.

Par exemple, vous pouvez lancer une instance de buildkitd avec :
$ sudo ./buildkitd --group $(id -gn) --addr unix://$HOME/buildkitd.sock
Alternativement, voir ici pour exécuter buildkitd en mode rootless ou ici pour des exemples d'exécution en tant que service systemd.

Vérifiez que vous avez un socket Unix auquel vous pouvez vous connecter.

$ ls -lh /home/user/buildkitd.sock
srw-rw---- 1 root user 0 May  5 11:04 /home/user/buildkitd.sock

Connectez Buildx à celui-ci à l'aide du pilote distant :

$ docker buildx create \
  --name remote-unix \
  --driver remote \
  unix://$HOME/buildkitd.sock

Listez les builders disponibles avec docker buildx ls. Vous devriez alors voir remote-unix parmi eux :

$ docker buildx ls
NAME/NODE           DRIVER/ENDPOINT                        STATUS  PLATFORMS
remote-unix         remote
  remote-unix0      unix:///home/.../buildkitd.sock        running linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
default *           docker
  default           default                                running linux/amd64, linux/386

Vous pouvez passer à ce nouveau builder comme builder par défaut en utilisant docker buildx use remote-unix, ou le spécifier par build en utilisant --builder:

$ docker buildx build --builder=remote-unix -t test --load .

N'oubliez pas que vous devez utiliser l'indicateur --load si vous souhaitez charger le résultat de la construction dans le démon Docker.

Exemple : BuildKit distant dans un conteneur Docker

Ce guide vous montrera comment créer une configuration similaire au pilote docker-container, en démarrant manuellement un conteneur Docker BuildKit et en s'y connectant à l'aide du pilote distant Buildx. Cette procédure créera manuellement un conteneur et y accédera via son port exposé. (Vous feriez probablement mieux d'utiliser simplement le pilote docker-container qui se connecte à BuildKit via le démon Docker, mais ceci est à des fins d'illustration.)

Générez des certificats pour BuildKit.

Vous pouvez utiliser cette définition de bake comme point de départ :
SAN="localhost 127.0.0.1" docker buildx bake "https://github.com/moby/buildkit.git#master:examples/create-certs"
Notez que bien qu'il soit possible d'exposer BuildKit sur TCP sans utiliser TLS, ce n'est pas recommandé. Cela permet un accès arbitraire à BuildKit sans informations d'identification.

Avec les certificats générés dans .certs/, démarrez le conteneur :

$ docker run -d --rm \
  --name=remote-buildkitd \
  --privileged \
  -p 1234:1234 \
  -v $PWD/.certs:/etc/buildkit/certs \
  moby/buildkit:latest \
  --addr tcp://0.0.0.0:1234 \
  --tlscacert /etc/buildkit/certs/daemon/ca.pem \
  --tlscert /etc/buildkit/certs/daemon/cert.pem \
  --tlskey /etc/buildkit/certs/daemon/key.pem

Cette commande démarre un conteneur BuildKit et expose le port 1234 du démon à localhost.

Connectez-vous à ce conteneur en cours d'exécution à l'aide de Buildx :

$ docker buildx create \
  --name remote-container \
  --driver remote \
  --driver-opt cacert=${PWD}/.certs/client/ca.pem,cert=${PWD}/.certs/client/cert.pem,key=${PWD}/.certs/client/key.pem,servername=<TLS_SERVER_NAME> \
  tcp://localhost:1234

Alternativement, utilisez le schéma d'URL docker-container:// pour vous connecter au conteneur BuildKit sans spécifier de port :

$ docker buildx create \
  --name remote-container \
  --driver remote \
  docker-container://remote-container

Exemple : BuildKit distant dans Kubernetes

Ce guide vous montrera comment créer une configuration similaire au pilote kubernetes en créant manuellement un Deployment BuildKit. Bien que le pilote kubernetes le fasse en arrière-plan, il peut parfois être souhaitable de mettre à l'échelle BuildKit manuellement. De plus, lors de l'exécution de builds depuis des pods Kubernetes, le builder Buildx devra être recréé depuis chaque pod ou copié entre eux.

Créez un déploiement Kubernetes de buildkitd, conformément aux instructions ici.

En suivant le guide, créez des certificats pour le démon et le client BuildKit en utilisant create-certs.sh, et créez un déploiement de pods BuildKit avec un service qui s'y connecte.

En supposant que le service s'appelle buildkitd, créez un builder distant dans Buildx, en vous assurant que les fichiers de certificat listés sont présents :

$ docker buildx create \
  --name remote-kubernetes \
  --driver remote \
  --driver-opt cacert=${PWD}/.certs/client/ca.pem,cert=${PWD}/.certs/client/cert.pem,key=${PWD}/.certs/client/key.pem \
  tcp://buildkitd.default.svc:1234

Notez que cela ne fonctionne qu'en interne, au sein du cluster, car le guide d'installation de BuildKit ne crée qu'un service ClusterIP. Pour accéder à un builder à distance, vous pouvez configurer et utiliser un ingress, ce qui sort du cadre de ce guide.

Déboguer un builder distant dans Kubernetes

Si vous rencontrez des difficultés pour accéder à un builder distant déployé dans Kubernetes, vous pouvez utiliser le schéma d'URL kube-pod:// pour vous connecter directement à un pod BuildKit via l'API Kubernetes. Notez que cette méthode ne se connecte qu'à un seul pod dans le déploiement.

$ kubectl get pods --selector=app=buildkitd -o json | jq -r '.items[].metadata.name'
buildkitd-XXXXXXXXXX-xxxxx
$ docker buildx create \
  --name remote-container \
  --driver remote \
  kube-pod://buildkitd-XXXXXXXXXX-xxxxx

Alternativement, utilisez le mécanisme de transfert de port de kubectl :

$ kubectl port-forward svc/buildkitd 1234:1234

Ensuite, vous pouvez pointer le pilote distant sur tcp://localhost:1234.