Aller au contenu

GitlabCI runners sous Kubernetes

Parce que l'exécuteur Docker des GitLab Runners me permet de donner mes cours sans soucis, en proposant même un minimum de parallélisation via le paramètre global concurrent du runner, j'ai dû, pour la réalisation du cours de Buildx/BuildKit, me faire un dépôt dédié avec un exécuteur Kubernetes, afin que tout ce petit monde puisse bien communiquer.

Pourquoi l'exécuteur Kubernetes

Avec l'exécuteur Kubernetes, le runner lui-même est un simple pod qui interroge GitLab. Pour chaque job, il crée un nouveau pod éphémère qui contient :

  • le conteneur build, basé sur l'image de ton job, qui exécute ton script ;
  • le conteneur helper, qui gère le clone Git, les artifacts et le cache ;
  • un conteneur par service déclaré dans le job (une base de données de test, par exemple).

Le pod est supprimé à la fin du job. Tu profites donc directement de l'ordonnancement et de l'autoscaling de ton cluster : pas de VM de build qui tourne à vide la nuit, et chaque job part d'un environnement propre.

Installation des runners

On va utiliser Helm pour déployer le GitLab Runner dans Kubernetes.

Mais avant de lancer la commande magique, prépare un petit fichier values.yaml qui contiendra ta configuration personnalisée.

# values.yaml
gitlabUrl: https://gitlab.com/
runnerToken: "glrt-ton_token"
rbac:
  create: true
serviceAccount:
  create: true
runners:
  config: |
    [[runners]]
      executor = "kubernetes"
      [runners.kubernetes]
        namespace = "{{.Release.Namespace}}"
        image = "alpine"
        helper_image = "gitlab/gitlab-runner-helper:arm64-${CI_RUNNER_REVISION}"

Plusieurs choses à dire ici :

  • Je fixe gitlabUrl sur l'URL SaaS de GitLab, je n'ai pas d'instance auto-hébergée sous la main.
  • Le runnerToken (token d'authentification préfixé par glrt-) t'est fourni directement par l'interface GitLab lorsque tu crées un nouveau runner dans Settings > CI/CD > Runners (l'ancien runnerRegistrationToken est désactivé par défaut depuis GitLab 17.0, et sa suppression est prévue pour GitLab 20.0).
  • rbac et serviceAccount sont à la racine des values du Helm chart afin que le chart crée les rôles nécessaires à l'orchestration des pods de jobs.
  • Dans la partie config, le champ image est l'image de base utilisée pour exécuter tes jobs si tu ne leur en spécifies pas. Quant à helper_image, j'ai dû la surcharger pour forcer la version arm64 et tourner sur mon MacBook, car de base il me tirait la version x86_64 😭. Le tag du helper doit correspondre à la version du runner : ${CI_RUNNER_REVISION} est remplacé automatiquement par la révision du runner déployé, ce qui évite de devoir le mettre à jour à chaque upgrade du chart.

Cluster multi-architecture

Le runner choisit normalement le helper qui correspond à l'architecture visée. Sur un cluster qui mélange des nœuds amd64 et arm64, le plus fiable est de dire explicitement où tourner tes jobs avec un node_selector sur kubernetes.io/arch dans [runners.kubernetes.node_selector] : le runner s'en sert aussi pour sélectionner le bon helper.

Il ne reste plus qu'à lancer la commande magique :

helm repo add gitlab https://charts.gitlab.io
helm repo update
helm upgrade --install gitlab-runner gitlab/gitlab-runner \
  --namespace gitlab --create-namespace \
  -f values.yaml

Ton runner doit apparaître en ligne dans Settings > CI/CD > Runners au bout de quelques secondes. Sinon, regarde les logs du pod : kubectl logs -n gitlab deploy/gitlab-runner.

Sortir le token du fichier de values

Un token de runner en clair dans un values.yaml versionné, c'est un secret qui fuit. Le chart sait lire le token depuis un Secret Kubernetes existant (créé à la main, ou mieux par External Secrets ou Sealed Secrets). Le Secret doit contenir les deux clés attendues par le chart :

kubectl create secret generic gitlab-runner-secret -n gitlab \
  --from-literal=runner-registration-token="" \
  --from-literal=runner-token="glrt-ton_token"

Puis, dans ton values.yaml, retire runnerToken et indique le nom du Secret :

runners:
  secret: gitlab-runner-secret

Dimensionner les pods de jobs

Sans requests ni limits, un job gourmand peut affamer les autres pods du nœud, et le scheduler place tes jobs à l'aveugle. Fixe des valeurs par défaut raisonnables, et autorise les jobs à les augmenter jusqu'à un plafond :

[runners.kubernetes]
  cpu_request = "500m"
  memory_request = "512Mi"
  memory_limit = "2Gi"
  cpu_request_overwrite_max_allowed = "2"
  memory_limit_overwrite_max_allowed = "4Gi"

Un job qui en a besoin demande alors plus de ressources via ses variables, sans jamais dépasser les maximums fixés par l'équipe plateforme :

build-lourd:
  variables:
    KUBERNETES_CPU_REQUEST: "2"
    KUBERNETES_MEMORY_LIMIT: "4Gi"
  script:
    - make build

Note

Si aucun maximum *_overwrite_max_allowed n'est défini pour une ressource, la variable correspondante est tout simplement ignorée.

Partager le cache entre les jobs

Chaque job tourne dans un pod neuf, potentiellement sur un autre nœud : le cache local d'un job n'est donc pas retrouvé par le suivant. Pour que cache: serve vraiment, configure un cache distribué sur un stockage objet (S3, GCS, Azure Blob ou un MinIO interne) :

runners:
  config: |
    [[runners]]
      [runners.kubernetes]
        image = "alpine"
      [runners.cache]
        Type = "s3"
        Path = "runner"
        Shared = true
        [runners.cache.s3]
          ServerAddress = "s3.amazonaws.com"
          BucketName = "mon-bucket-de-cache"
          BucketLocation = "eu-west-3"
          AuthenticationType = "access-key"
  cache:
    secretName: s3access # Secret contenant les clés accesskey et secretkey

Shared = true permet à plusieurs runners de partager le même cache, ce qui est pratique si tu en déploies un par équipe ou par architecture.

Construire des images Docker dans un runner Kubernetes

C'est la question qui arrive toujours. La solution historique, Docker-in-Docker, impose privileged = true sur les pods de jobs : un job compromis obtient alors des droits très élevés sur le nœud. Kaniko, souvent cité comme alternative sans privilèges, a été archivé par Google en 2025 et n'est plus maintenu.

Aujourd'hui, privilégie BuildKit en mode rootless ou Buildah. Je détaille le déploiement de BuildKit rootless sur Kubernetes et son utilisation depuis GitLab CI dans le cours Accélère tes pipelines Docker avec Buildx et BuildKit.

Sécuriser les runners

  • Isole les jobs dans un namespace dédié, avec des quotas (ResourceQuota) et des NetworkPolicies : un job de CI n'a aucune raison de parler à ta base de production.
  • Restreins les images autorisées avec allowed_images (par exemple ["node:*", "python:*"]) si tes runners sont partagés entre plusieurs équipes.
  • Sépare les runners de déploiement : un runner qui détient des droits sur la production ne doit exécuter que des jobs de branches protégées. Marque-le comme protégé et donne-lui un tag dédié.
  • Mets à jour régulièrement le chart et le runner : le helper image embarque Git et ses dépendances, qui reçoivent des correctifs de sécurité.

Pièges courants

  • Jobs bloqués en Pending : le pod de job ne trouve pas de nœud (requests trop élevées, quota atteint, node_selector impossible). Regarde les événements avec kubectl get events -n gitlab ; le runner abandonne au bout de poll_timeout secondes.
  • Moins de jobs en parallèle que prévu : le paramètre global concurrent du chart plafonne le nombre de jobs simultanés, quelle que soit la taille du cluster.
  • Erreurs de permissions à la création des pods : vérifie que rbac.create est actif, ou que le ServiceAccount fourni a bien les droits sur le namespace des jobs.
  • Cache qui ne sert jamais : sans cache distribué, voir plus haut, chaque job repart de zéro.

Pour aller plus loin