À propos des comptes robot

Ce guide explique comment créer et gérer les comptes robot pour l'accès automatisé au Container Registry Numspot.

Vue d'ensemble

Les comptes robot sont des comptes de service utilisés pour les interactions automatisées avec Harbor, telles que :

Les pipelines CI/CD qui poussent et tirent des images.
Les clusters Kubernetes qui tirent des images pour les déploiements.
Les outils automatisés qui analysent ou gèrent des images.
La réplication inter-registries.

Pourquoi utiliser des comptes robot ?

Sécurité : éviter d'utiliser les identifiants admin dans l'automatisation.
Permissions granulaires : limiter l'accès à des projets et opérations spécifiques.
Audit : suivre les opérations automatisées séparément des actions utilisateur.
Rotation des identifiants : rotation des jetons des comptes robot sans affecter les utilisateurs.
Responsabilité : distinction claire entre les accès humains et automatisés.

Types de comptes robot

Comptes robot au niveau système

Portée : tous les projets dans le registry.
Créé par : administrateurs système Harbor.
Cas d'usage : automatisation à l'échelle du registry, réplication inter-projets.

Comptes robot au niveau projet

Portée : un seul projet uniquement.
Créé par : administrateurs de projet.
Cas d'usage : CI/CD spécifique au projet, déploiements d'applications.

Créer des comptes robot

Via l'interface Harbor (niveau projet)

Connectez-vous à l'interface Harbor.
Accédez à Projects → Sélectionnez le projet → Robots.
Cliquez sur New Robot Account.
Configurez :

Champ	Valeur
Name	`ci-cd-pipeline` (préfixe ajouté automatiquement)
Description	`Robot for CI/CD pipeline pushes`
Expiration	`Never` ou date spécifique
Permissions	Sélectionnez les permissions appropriées

Cliquez sur Add

Niveaux de permission

Permission	Description	Cas d'usage
Push	Pousser des images vers le dépôt	Pipelines CI qui construisent des images
Pull	Tirer des images depuis le dépôt	Déploiements Kubernetes
Read	Voir les métadonnées du dépôt	Outils de monitoring
Delete	Supprimer des images et tags	Jobs de nettoyage
Create	Créer des dépôts	Configuration initiale du projet
Scanner pull	Récupérer les résultats de scan	Outils de sécurité

Combinaisons de permissions courantes

Cas d'usage	Permissions
CI/CD Push	Push + Create
Kubernetes Pull	Pull + Read
Accès complet	Push + Pull + Read + Delete + Create
Scanner	Pull + Read + Scanner pull

Via API (niveau projet)

curl -X POST "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project_id}/robots" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-cd-pipeline",
    "description": "Robot for CI/CD pipeline pushes",
    "expires_at": -1,
    "permissions": [
      {
        "kind": "project",
        "namespace": "{project_name}",
        "access": [
          {"action": "push"},
          {"action": "pull"},
          {"action": "create"}
        ]
      }
    ]
  }'

Réponse :

{
  "id": 1,
  "name": "robot${project_name}+ci-cd-pipeline",
  "description": "Robot for CI/CD pipeline pushes",
  "expires_at": -1,
  "secret": "generated-secret-token",
  "creation_time": "2026-05-05T10:00:00Z"
}

avertissement

Sauvegardez immédiatement la valeur du secret. Elle n'est affichée qu'une seule fois et ne peut pas être récupérée ultérieurement.

Via l'interface Harbor (niveau système)

Connectez-vous en tant qu'administrateur système.
Accédez à Administration → Robot Accounts.
Cliquez sur New Robot Account.
Configurez :

Champ	Valeur
Name	`system-replication`
Description	`System-wide replication robot`
Expiration	`Never` ou date spécifique
Scope	Niveau système
Permissions	Tous les projets ou projets spécifiques

Cliquez sur Add

Via API (niveau système)

curl -X POST "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/robots" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "system-replication",
    "description": "System-wide replication robot",
    "expires_at": -1,
    "level": "system",
    "permissions": [
      {
        "kind": "project",
        "namespace": "*",
        "access": [
          {"action": "push"},
          {"action": "pull"},
          {"action": "delete"},
          {"action": "create"}
        ]
      }
    ]
  }'

Gérer les identifiants des comptes robot

Sauvegarder les identifiants

Après avoir créé un compte robot, vous recevrez :

Nom d'utilisateur : robot${project_name}+robot-name.
Secret/Jeton : jeton généré (affiché une seule fois).

Stockez les identifiants de manière sécurisée :

## Exemple : Sauvegarder dans un secret Kubernetes
kubectl create secret docker-registry harbor-robot-secret \
  --docker-server=registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com \
  --docker-username='robot${project_name}+ci-cd-pipeline' \
  --docker-password='generated-secret-token'

## Exemple : Sauvegarder dans des variables d'environnement
export HARBOR_ROBOT_USER='robot${project_name}+ci-cd-pipeline'
export HARBOR_ROBOT_SECRET='generated-secret-token'

Utiliser les comptes robot

docker login registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com \
  -u 'robot${project_name}+ci-cd-pipeline' \
  -p 'generated-secret-token'

Docker Push/Pull

## Push image
docker push registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/myproject/myimage:v1.0

## Pull image
docker pull registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/myproject/myimage:v1.0

Kubernetes Image Pull Secret

apiVersion: v1
kind: Secret
metadata:
  name: harbor-robot-secret
  namespace: default
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: ewogICJhdXRocyI6IHsKICAgICJyZWdpc3RyeS17cmVnaXN0cnlJZH0uaGNwLmNsb3VkZ291di1ldS13ZXN0LTEubnVtc3BvdC5jb20iOiB7CiAgICAgICJ1c2VybmFtZSI6ICJyb2JvdCR7cHJvamVjdF9uYW1lfStjaS1jZC1waXBlbGluZSIsCiAgICAgICJwYXNzd29yZCI6ICJnZW5lcmF0ZWQtc2VjcmV0LXRva2VuIiwKICAgICAgImF1dGgiOiAiYjNvTlRtVm1kWEJwYm1samJtRjBaVG9qTVE9PSIKICAgIH0KICB9Cn0=

Déploiement Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      imagePullSecrets:
      - name: harbor-robot-secret
      containers:
      - name: myapp
        image: registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/myproject/myimage:v1.0

CI/CD (GitLab CI)

## .gitlab-ci.yml
variables:
  HARBOR_REGISTRY: registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com
  HARBOR_USER: robot${project_name}+ci-cd-pipeline
  HARBOR_PASSWORD: generated-secret-token

docker-build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - docker login -u "$HARBOR_USER" -p "$HARBOR_PASSWORD" $HARBOR_REGISTRY
  script:
    - docker build -t $HARBOR_REGISTRY/myproject/myimage:$CI_COMMIT_SHA .
    - docker push $HARBOR_REGISTRY/myproject/myimage:$CI_COMMIT_SHA

CI/CD (GitHub Actions)

## .github/workflows/docker.yml
name: Docker Build and Push

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Login to Harbor
        uses: docker/login-action@v2
        with:
          registry: registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com
          username: ${{ secrets.HARBOR_ROBOT_USER }}
          password: ${{ secrets.HARBOR_ROBOT_SECRET }}

      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          push: true
          tags: registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/myproject/myimage:${{ github.sha }}

Gérer les comptes robot existants

Lister les comptes robot

Via l'interface Harbor

Accédez à Projects → Sélectionnez le projet → Robots.
Consultez la liste des comptes robot.

Via API

## Lister les robots au niveau projet
curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project_id}/robots" \
  -u "admin:{password}"

## Lister les robots au niveau système
curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/robots" \
  -u "admin:{password}"

Modifier un compte robot

Via l'interface Harbor

Accédez à la liste des comptes robot
Cliquez sur Edit sur le compte robot
Modifiez :

La description
La date d'expiration
Les permissions

Cliquez sur Save

Via API

curl -X PUT "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project_id}/robots/{robot_id}" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "expires_at": 1735689600,
    "permissions": [
      {
        "kind": "project",
        "namespace": "{project_name}",
        "access": [
          {"action": "push"},
          {"action": "pull"}
        ]
      }
    ]
  }'

Rafraîchir le secret

Régénérer le secret du compte robot :

Via l'interface Harbor

Accédez à la liste des comptes robot
Cliquez sur Refresh Secret sur le compte robot
Copiez immédiatement le nouveau secret (affiché une seule fois)

Via API

curl -X PATCH "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project_id}/robots/{robot_id}" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": ""
  }'

Réponse :

{
  "secret": "new-generated-secret-token"
}

avertissement

Le rafraîchissement du secret invalide immédiatement l'ancien secret. Mettez à jour tous les systèmes utilisant le compte robot.

Désactiver un compte robot

Désactiver temporairement sans supprimer :

curl -X PUT "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project_id}/robots/{robot_id}" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "disable": true
  }'

Supprimer un compte robot

avertissement

La suppression est permanente. Tous les systèmes utilisant le compte robot perdront l'accès.

Via l'interface Harbor

Accédez à la liste des comptes robot.
Cliquez sur Delete sur le compte robot.
Confirmez la suppression.

Via API

curl -X DELETE "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project_id}/robots/{robot_id}" \
  -u "admin:{password}"

Bonnes pratiques pour les comptes robot

Sécurité

Principe du moindre privilège : Accordez les permissions minimales nécessaires
Portée projet : Utilisez des robots au niveau projet plutôt qu'au niveau système
Expiration courte : Définissez des dates d'expiration raisonnables
Rotation des secrets : Rafraîchissez régulièrement les secrets des comptes robot
Ne jamais commiter les secrets : Utilisez des variables d'environnement ou des outils de gestion de secrets
Auditer l'utilisation : Surveillez l'activité des comptes robot dans les logs d'audit

Organisation

Noms descriptifs : Utilisez des noms significatifs (ex: ci-cd-production, k8s-deploy-staging)
Documenter l'objectif : Incluez des descriptions détaillées
Taguer les environnements : Utilisez des conventions de nommage pour les environnements
Suivre la propriété : Documentez quelle équipe/système possède chaque robot

Gestion du cycle de vie

Revue régulière : Auditez les comptes robot trimestriellement
Supprimer les inutilisés : Supprimez les comptes robot qui ne sont plus utilisés
Alertes sur l'expiration : Surveillez les comptes proches de l'expiration
Mettre à jour l'automatisation : Rafraîchissez les identifiants dans le CI/CD avant l'expiration

Modèles de comptes robot

Robot pour pipeline CI/CD

curl -X POST "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project_id}/robots" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline",
    "description": "CI pipeline for building and pushing images",
    "expires_at": -1,
    "permissions": [
      {
        "kind": "project",
        "namespace": "{project_name}",
        "access": [
          {"action": "push"},
          {"action": "pull"},
          {"action": "create"}
        ]
      }
    ]
  }'

Robot pour déploiement Kubernetes

curl -X POST "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project_id}/robots" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "k8s-deploy",
    "description": "Kubernetes cluster image pull",
    "expires_at": -1,
    "permissions": [
      {
        "kind": "project",
        "namespace": "{project_name}",
        "access": [
          {"action": "pull"},
          {"action": "read"}
        ]
      }
    ]
  }'

Robot de réplication

curl -X POST "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/robots" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "replication-push",
    "description": "Cross-registry replication",
    "expires_at": -1,
    "level": "system",
    "permissions": [
      {
        "kind": "project",
        "namespace": "*",
        "access": [
          {"action": "push"},
          {"action": "pull"},
          {"action": "delete"},
          {"action": "create"}
        ]
      }
    ]
  }'

Surveiller l'utilisation des comptes robot

Via les logs d'audit

Accédez à Administration → Audit Log.
Filtrez par nom d'utilisateur du compte robot.
Consultez les opérations :
- Opérations push/pull.
- Création de dépôts.
- Suppression d'images.
- Horodatage du dernier accès.

Via API

## Récupérer les logs d'audit pour un compte robot
curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project_id}/logs?username=robot%24{project_name}%2Bci-pipeline" \
  -u "admin:{password}" | jq '.[] | {operation: .operation, repository: .repo_name, time: .op_time}'

Métriques à surveiller

Fréquence pull/push : suivez les patterns d'utilisation.
Échecs d'authentification : alertes sur les tentatives de connexion échouées.
Heure du dernier accès : identifiez les comptes robot inactifs.
Violations de permissions : alertes sur les tentatives d'accès non autorisées.

Dépannage

Problème 1 : échec de l'authentification

Symptôme : Docker login ou pull échoue avec erreur 401.

Solutions :

Vérifiez le format du nom d'utilisateur du compte robot : robot${project_name}+robot-name.
Vérifiez si le secret a été rafraîchi récemment.
Vérifiez que le compte robot n'est pas désactivé.
Vérifiez que les permissions correspondent à l'opération (pull vs push).

Problème 2 : accès refusé

Symptôme : erreur 403 Forbidden sur push/pull.

Solutions :

Vérifiez que le compte robot a les permissions correctes.
Vérifiez que le compte robot est associé au bon projet.
Vérifiez que le dépôt existe (ou que la permission create est accordée).
Vérifiez que les quotas du projet ne sont pas dépassés.

Problème 3 : compte robot expiré

Symptôme : l'authentification échoue après la date d'expiration.

Solutions :

Mettez à jour l'expiration du compte robot.
Créez un nouveau compte robot si nécessaire.
Mettez à jour les secrets dans tous les systèmes consommateurs.

Problème 4 : impossible de rafraîchir le secret

Symptôme : le rafraîchissement du secret échoue.

Solutions :

Vérifiez que vous avez les permissions d'administrateur de projet.
Vérifiez que le compte robot existe toujours.
Essayez de mettre à jour via l'API au lieu de l'interface.
Contactez le support si le problème persiste.

Référence API

Créer un compte robot (projet)

POST /api/v2.0/projects/{project_id}/robots
Authorization: Basic {base64(admin:password)}
Content-Type: application/json

{
  "name": "string",
  "description": "string",
  "expires_at": number,
  "permissions": [
    {
      "kind": "project",
      "namespace": "string",
      "access": [
        {"action": "push | pull | read | delete | create"}
      ]
    }
  ]
}

Lister les comptes robot (projet)

GET /api/v2.0/projects/{project_id}/robots
Authorization: Basic {base64(admin:password)}

Récupérer un compte robot

GET /api/v2.0/projects/{project_id}/robots/{robot_id}
Authorization: Basic {base64(admin:password)}

Modifier un compte robot

PUT /api/v2.0/projects/{project_id}/robots/{robot_id}
Authorization: Basic {base64(admin:password)}
Content-Type: application/json

{
  "description": "string",
  "expires_at": number,
  "disable": boolean,
  "permissions": []
}

Rafraîchir le secret

PATCH /api/v2.0/projects/{project_id}/robots/{robot_id}
Authorization: Basic {base64(admin:password)}
Content-Type: application/json

{
  "secret": ""
}

Supprimer un compte robot

DELETE /api/v2.0/projects/{project_id}/robots/{robot_id}
Authorization: Basic {base64(admin:password)}

Limitations

Secret affiché une seule fois : impossible de récupérer le secret après la création.
Immuabilité du nom : impossible de renommer un compte robot après sa création.
Granularité des permissions limitée : permissions au niveau Harbor uniquement.
Expiration requise : doit définir une date d'expiration pour les robots au niveau système.
Pas de restrictions IP : les comptes robot ne peuvent pas être restreints par IP (utilisez les permissions de projet).

Vue d'ensemble​

Pourquoi utiliser des comptes robot ?​

Types de comptes robot​

Comptes robot au niveau système​

Comptes robot au niveau projet​

Créer des comptes robot​

Via l'interface Harbor (niveau projet)​

Niveaux de permission​

Combinaisons de permissions courantes​

Via API (niveau projet)​

Via l'interface Harbor (niveau système)​

Via API (niveau système)​

Gérer les identifiants des comptes robot​

Sauvegarder les identifiants​

Utiliser les comptes robot​

Docker Login​

Docker Push/Pull​

Kubernetes Image Pull Secret​

Déploiement Kubernetes​

CI/CD (GitLab CI)​

CI/CD (GitHub Actions)​

Gérer les comptes robot existants​

Lister les comptes robot​

Via l'interface Harbor​

Via API​

Modifier un compte robot​

Via l'interface Harbor​

Via API​

Rafraîchir le secret​

Via l'interface Harbor​

Via API​

Désactiver un compte robot​

Supprimer un compte robot​

Via l'interface Harbor​

Via API​

Bonnes pratiques pour les comptes robot​

Sécurité​

Organisation​

Gestion du cycle de vie​

Modèles de comptes robot​

Robot pour pipeline CI/CD​

Robot pour déploiement Kubernetes​

Robot de réplication​

Surveiller l'utilisation des comptes robot​

Via les logs d'audit​

Via API​

Métriques à surveiller​

Dépannage​

Problème 1 : échec de l'authentification​

Problème 2 : accès refusé​

Problème 3 : compte robot expiré​

Problème 4 : impossible de rafraîchir le secret​

Référence API​

Créer un compte robot (projet)​

Lister les comptes robot (projet)​

Récupérer un compte robot​

Modifier un compte robot​

Rafraîchir le secret​

Supprimer un compte robot​

Limitations​

Vue d'ensemble

Pourquoi utiliser des comptes robot ?

Types de comptes robot

Comptes robot au niveau système

Comptes robot au niveau projet

Créer des comptes robot

Via l'interface Harbor (niveau projet)

Niveaux de permission

Combinaisons de permissions courantes

Via API (niveau projet)

Via l'interface Harbor (niveau système)

Via API (niveau système)

Gérer les identifiants des comptes robot

Sauvegarder les identifiants

Utiliser les comptes robot

Docker Login

Docker Push/Pull

Kubernetes Image Pull Secret

Déploiement Kubernetes

CI/CD (GitLab CI)

CI/CD (GitHub Actions)

Gérer les comptes robot existants

Lister les comptes robot

Via l'interface Harbor

Via API

Modifier un compte robot

Via l'interface Harbor

Via API

Rafraîchir le secret

Via l'interface Harbor

Via API

Désactiver un compte robot

Supprimer un compte robot

Via l'interface Harbor

Via API

Bonnes pratiques pour les comptes robot

Sécurité

Organisation

Gestion du cycle de vie

Modèles de comptes robot

Robot pour pipeline CI/CD

Robot pour déploiement Kubernetes

Robot de réplication

Surveiller l'utilisation des comptes robot

Via les logs d'audit

Via API

Métriques à surveiller

Dépannage

Problème 1 : échec de l'authentification

Problème 2 : accès refusé

Problème 3 : compte robot expiré

Problème 4 : impossible de rafraîchir le secret

Référence API

Créer un compte robot (projet)

Lister les comptes robot (projet)

Récupérer un compte robot

Modifier un compte robot

Rafraîchir le secret

Supprimer un compte robot

Limitations