---
title: "Construire, pousser et déployer vos images"
description: "Le cycle complet d'une image privée : build Docker, push vers un registre (Froggit, GitLab, GHCR), pull secret et déploiement sur Kontainers."
source_url:
  html: https://docs.blackswift.cloud/deployer/registry-prive/
  md: https://docs.blackswift.cloud/deployer/registry-prive.md
---

# Construire, pousser et déployer vos images

> Le cycle complet d'une image privée : build Docker, push vers un registre (Froggit, GitLab, GHCR), pull secret et déploiement sur Kontainers.

Les guides précédents déploient des images publiques (`nginx:alpine`…). Pour
votre propre application, il faut construire une image, la stocker dans un
**registre**, et permettre à Kontainers de l'y récupérer. Le cycle complet :

```text
docker build  →  docker push  →  pull secret  →  Deployment
   (local/CI)      (registre)      (namespace)     (Kontainers)
```

## 1. Choisir un registre

N'importe quel registre d'images fonctionne. Suggestions :

| Registre | Pour qui |
| --- | --- |
| **[Froggit](https://froggit.fr)** | GitLab managé **français** — cohérent avec un hébergement souverain |
| **gitlab.com** | Si votre code y est déjà (registre intégré) |
| **GitHub Container Registry** (ghcr.io) | Si votre code est sur GitHub |
| **Docker Hub** | Images publiques, comptes personnels |

Les exemples ci-dessous utilisent un registre GitLab (Froggit ou gitlab.com) —
adaptez simplement les URLs pour un autre fournisseur.

## 2. Construire et pousser l'image

Depuis la racine de votre projet (là où vit le `Dockerfile`) :

```bash
# Construire (--platform garantit une image compatible avec le cluster,
# indispensable depuis un Mac Apple Silicon)
docker build --platform linux/amd64 -t registry.exemple.com/acme/mon-app:1.0.0 .

# Se connecter au registre puis pousser
docker login registry.exemple.com
docker push registry.exemple.com/acme/mon-app:1.0.0
```

:::tip[Taguez immuablement]
Préférez un tag de version (`1.0.0`, un SHA de commit) à `latest`. Sur Kontainers,
[`imagePullPolicy` est forcé à `Always`](https://docs.blackswift.cloud/reference/mutations-et-politiques.md) :
avec `latest`, chaque redémarrage de pod peut ramasser une image différente.
:::

En CI, cette étape est généralement faite par votre pipeline (GitLab CI propose
des variables prêtes à l'emploi : `$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA`).

## 3. Créer le token de lecture

Kontainers a besoin d'identifiants **en lecture seule** sur votre registre.
Ne réutilisez jamais votre compte personnel.

Sur GitLab (Froggit ou gitlab.com) : projet → **Settings › Access tokens** →
**Add new token** :

- **Nom** : `kontainers-pull`
- **Rôle** : Reporter
- **Scope** : `read_registry` uniquement
- **Expiration** : selon votre politique — et notez-la quelque part (voir
  l'avertissement plus bas)

Copiez le token affiché : il ne sera plus jamais montré.

## 4. Créer le pull secret dans votre namespace

```bash
kubectl -n <namespace> create secret docker-registry registry-pull \
  --docker-server=registry.exemple.com \
  --docker-username=kontainers-pull \
  --docker-password='<le-token>'
```

## 5. Référencer le secret dans vos Deployments

```yaml
spec:
  template:
    spec:
      imagePullSecrets:
        - name: registry-pull
      containers:
        - name: app
          image: registry.exemple.com/acme/mon-app:1.0.0
          resources:
            requests: {cpu: 100m, memory: 256Mi}
```

Déployez, et vérifiez que l'image se télécharge :

```bash
kubectl get pods -n <namespace>
# ImagePullBackOff ? → kubectl describe pod <pod> pour le message exact
```

:::caution[Un token expiré casse les redémarrages, pas seulement les déploiements]
Avec [`imagePullPolicy: Always`](https://docs.blackswift.cloud/reference/mutations-et-politiques.md), le registre
est contacté à **chaque** démarrage de pod. Si votre token expire, ce ne sont pas
seulement vos prochains déploiements qui échouent : **un simple redémarrage d'un
pod qui tournait très bien tombera en `ImagePullBackOff`**. Mettez une date
d'expiration longue ou un rappel calendrier, et surveillez
[cette erreur](https://docs.blackswift.cloud/depanner/pod-en-erreur.md#imagepullbackoff).
:::

## Registres alternatifs : les mêmes commandes

Seul le `--docker-server` et le format des identifiants changent :

| Registre | `--docker-server` | Username / password |
| --- | --- | --- |
| GitLab (Froggit, gitlab.com) | `registry.<instance>` | nom du token / token |
| GHCR | `ghcr.io` | user GitHub / PAT scope `read:packages` |
| Docker Hub | `https://index.docker.io/v1/` | user / access token |