Configuration des Référentiels Externes avec Red Hat OpenShift Local (CRC)

Introduction

Qu’est-ce que Red Hat OpenShift Local (CRC)?

Red Hat OpenShift Local, anciennement connu sous le nom de CodeReady Containers (CRC), est un outil conçu pour exécuter un cluster OpenShift minimal sur une machine locale.
Il fournit un environnement OpenShift Container Platform 4 ou MicroShift à nœud unique sur un poste de travail exécutant Linux, macOS ou Windows.
L’objectif principal d’OpenShift Local est de simplifier la configuration et les tests pour les développeurs et les testeurs en émulant un environnement de développement cloud localement.
Il regroupe les outils nécessaires au développement d’applications basées sur des conteneurs, permettant de créer des microservices, de les construire en images et de les exécuter dans des conteneurs hébergés par Kubernetes directement sur l’ordinateur portable ou de bureau.  

Il est important de noter qu’OpenShift Local est destiné aux environnements de développement et de test. Le cluster fourni est éphémère et n’est pas conçu pour une utilisation en production.
Il fonctionne sur une machine virtuelle et utilise un nœud unique agissant à la fois comme plan de contrôle et comme nœud de travail. Pour optimiser l’utilisation des ressources locales, certains opérateurs OpenShift, comme l’Operator de surveillance de cluster (Cluster Monitoring Operator), sont désactivés par défaut.
Cette nature minimale signifie que, bien qu’il offre une expérience OpenShift/Kubernetes fondamentale, il ne réplique pas toutes les fonctionnalités d’un cluster de production multi-nœuds.
La transition de nom de “CodeReady Containers” à “OpenShift Local” est également un point à noter ; les ressources plus anciennes peuvent encore faire référence à “CRC”.

Pourquoi Utiliser des Référentiels Externes avec OpenShift Local?

Bien qu’OpenShift Local inclue un registre d’images interne , de nombreux flux de travail de développement nécessitent l’accès à des référentiels externes. Les scénarios courants incluent :   L’extraction d’images de base ou d’applications à partir de registres privés d’entreprise (par exemple, Artifactory, Nexus). L’accès à des logiciels tiers hébergés sur des registres spécifiques.
L’utilisation d’images provenant de registres publics nécessitant une authentification (par exemple, des dépôts privés sur Docker Hub, Quay.io, GitLab Container Registry). Se fier uniquement aux registres publics par défaut ou au registre interne peut s’avérer limitant. La configuration de l’accès aux référentiels externes est donc une étape essentielle pour de nombreux développeurs utilisant OpenShift Local.

Portée de ce Guide

Ce guide fournit une procédure détaillée pour configurer et utiliser des référentiels externes, principalement des registres d’images de conteneurs, au sein d’un environnement Red Hat OpenShift Local.
Il couvre les aspects suivants :

• Prérequis nécessaires.
• Configuration de l’accès aux registres authentifiés à l’aide de secrets d’extraction (pull secrets).
• Gestion des registres sécurisés (TLS) et non sécurisés (HTTP ou certificats auto-signés).
• Ajout d’autorités de certification (CA) personnalisées pour faire confiance aux registres internes.
• Considérations réseau, y compris la configuration d’un proxy HTTP/HTTPS.
• Envoi (push) d’images construites localement vers des registres externes ou internes.
• Dépannage des problèmes courants tels que les erreurs ImagePullBackOff, les erreurs de certificat et les échecs d’authentification.

Prérequis

Avant de configurer l’accès aux référentiels externes, assurez-vous que les conditions suivantes sont remplies :

• Installation d’OpenShift Local: OpenShift Local doit être installé et en cours d’exécution sur la machine hôte. Le processus d’installation implique généralement le téléchargement du binaire crc et d’un fichier de secret d’extraction (pull secret) depuis le portail Red Hat, l’exécution de crc setup pour configurer le système, puis le démarrage du cluster avec crc start.
  Le secret d’extraction (pull secret) Red Hat est nécessaire même pour une utilisation développeur gratuite, car il authentifie le téléchargement des composants OpenShift depuis les registres Red Hat. Il faut donc disposer d’un compte développeur Red Hat (gratuit).
  Le système hôte doit répondre aux exigences minimales en termes de CPU (4+ cœurs physiques), de RAM (9 Go minimum, 16 Go+ recommandés) et d’espace disque (35 Go+).  
• Outils en Ligne de Commande: oc (OpenShift CLI): L’interface de ligne de commande OpenShift (oc) doit être installée et configurée pour interagir avec le cluster OpenShift Local. L’environnement shell peut être configuré en exécutant eval $(crc oc-env) (sur Linux/macOS) ou la commande équivalente pour Windows indiquée par crc oc-env.   podman ou docker : Un moteur de conteneurisation comme Podman ou Docker est requis sur la machine hôte si l’objectif est de construire des images localement et de les pousser vers des registres (internes ou externes).
  OpenShift Local inclut podman dans son environnement configuré par crc podman-env.  

• Identifiants de Registre:

Les informations d’authentification nécessaires (nom d’utilisateur/mot de passe, jeton d’accès) pour les registres externes privés doivent être disponibles.  

• Connectivité Réseau: La machine hôte, et par conséquent la machine virtuelle OpenShift Local, doit pouvoir atteindre les registres externes cibles sur le réseau. Les pare-feux locaux ou d’entreprise peuvent nécessiter une configuration spécifique. Les exigences de proxy sont traitées plus loin dans ce guide. La commande crc setup joue un rôle crucial en configurant le DNS de l’hôte pour résoudre les domaines internes *.crc.testing et *.apps-crc.testing. Cette étape modifie activement la configuration réseau de l’hôte et est essentielle au bon fonctionnement d’OpenShift Local.
  Des problèmes lors de crc setup ou des conflits avec des configurations DNS existantes peuvent entraîner des difficultés à atteindre l’API du cluster (api.crc.testing) ou d’autres services internes.  

Comprendre la Gestion des Images dans OpenShift Local

OpenShift Local utilise les mêmes concepts de base qu’OpenShift standard pour la gestion des images, mais dans un contexte à nœud unique.

• Le Registre Interne: OpenShift Local déploie un registre d’images de conteneurs intégré. Ce registre est principalement utilisé pour stocker les images construites au sein du cluster, par exemple via des builds Source-to-Image (S2I), ou comme cible pour les images poussées localement.   Son nom de service interne est généralement image-registry.openshift-image-registry.svc:5000. Il peut également être exposé à l’extérieur du cluster via une Route, dont l’URL peut être trouvée avec oc get route default-route -n openshift-image-registry –template=’{{.spec.host }}’. Ce guide se concentre sur les registres externes, mais l’interaction avec le registre interne exposé sera abordée dans la section sur le push d’images.  
• ImageStreams: Les ImageStreams sont une ressource OpenShift qui fournit une abstraction pour référencer les images de conteneurs. Ils peuvent pointer vers des images dans le registre interne ou dans des registres externes.   Un ImageStream peut être configuré pour suivre les mises à jour d’un tag d’image dans un registre distant. La commande oc import-image –from=/: –confirm peut être utilisée pour synchroniser manuellement les informations d’une image externe dans un ImageStream.  
• Secrets d’Extraction (Pull Secrets): Pour accéder aux registres externes qui nécessitent une authentification, Kubernetes et OpenShift utilisent des Secrets de type kubernetes.io/dockerconfig.json (ou l’ancien type kubernetes.io/dockercfg).   Ces secrets stockent les informations d’identification (jeton, nom d’utilisateur/mot de passe) nécessaires pour que le Kubelet (l’agent s’exécutant sur le nœud) puisse s’authentifier auprès du registre privé lors de l’extraction d’une image pour un Pod.   Bien que oc import-image puisse fonctionner pour importer les métadonnées d’une image privée (en utilisant potentiellement l’authentification locale de l’utilisateur), le Pod lui-même échouera à extraire l’image au moment de l’exécution s’il ne dispose pas du secret d’extraction approprié. Le secret est donc essentiel pour l’accès runtime aux registres privés.  

Configuration de l’Accès aux Registres Externes

Il existe deux méthodes principales pour configurer l’accès aux registres externes dans OpenShift Local : les secrets d’extraction (pull secrets) liés aux comptes de service et la configuration globale du cluster via la ressource image.config.openshift.io/cluster.

Méthode 1: Secrets d’Extraction (Pull Secrets) (Par Projet/Compte de Service)

C’est la méthode recommandée et la plus courante pour gérer l’accès aux registres externes authentifiés (privés). Elle offre un contrôle granulaire par projet (namespace) et par compte de service (Service Account).

Quand l’utiliser : Pour tout registre nécessitant une authentification (Docker Hub privé, Quay.io, Artifactory, Nexus, GitLab Registry`, etc.).

• Création du Secret :

1. À partir des identifiants :

oc create secret docker-registry <nom-du-secret>
--docker-server=<serveur-du-registre>
--docker-username=<nom-utilisateur>
--docker-password=<mot-de-passe-ou-jeton>
--docker-email=<email>

Remplacez les espaces réservés par les informations réelles.
<serveur-du-registre> est l’adresse du registre (par ex., docker.io, quay.io, monregistre.entreprise.com:5000).
<email> est souvent requis mais peut parfois être une valeur factice.

2. À partir d’un fichier config.json existant :
   Si podman login ou docker login a déjà été exécuté sur la machine hôte, un fichier `~/.docker/config.json contenant les identifiants existe. Il est souvent plus simple de créer le secret à partir de ce fichier :

oc create secret generic <nom-du-secret> \
    --from-file=.dockerconfigjson=<chemin/vers/config.json> \
    --type=kubernetes.io/dockerconfigjson

C’est la méthode préférée car elle utilise le format standard dockerconfigjson. L’ancien type .dockercfg existe mais est moins courant.  

• Liaison du Secret au Compte de Service :
  Les Pods s’exécutent sous l’identité d’un Compte de Service (Service Account ou SA). Par défaut, dans un projet, le SA default est utilisé s’il n’est pas spécifié autrement. Pour permettre aux Pods utilisant un SA spécifique de tirer parti du secret, il faut lier le secret au SA pour l’opération pull :

oc secrets link default <nom-du-secret> --for=pull

Remplacez default par le nom du SA approprié si nécessaire. Si des builds (comme S2I) doivent également extraire des images de ce registre, liez également le secret au SA builder.  

• Utilisation du Secret :
  Une fois le secret lié au compte de service default (ou au SA utilisé par le Pod), aucune configuration supplémentaire n’est nécessaire dans la définition du Pod/Deployment. Kubernetes utilisera automatiquement le secret lié pour s’authentifier auprès du registre spécifié dans le champ image: du conteneur. Il est également possible de spécifier les secrets d’extraction directement dans la spécification du Pod via le champ spec.imagePullSecrets, mais lier au compte de service est généralement plus pratique pour un projet.  

Méthode 2 : Configuration Globale du Cluster (image.config.openshift.io/cluster)

Cette méthode permet d’appliquer des paramètres à l’ensemble du cluster OpenShift Local. Elle nécessite des privilèges d’administrateur de cluster (kubeadmin).
Elle est utilisée pour :

• Autoriser ou bloquer globalement l’accès à certains registres (souvent publics).

• Configurer l’accès à des registres non sécurisés (HTTP ou certificats non valides).

• Ajouter des autorités de certification (CA) personnalisées pour faire confiance aux certificats TLS de registres privés/internes.

• Modification de la Ressource : La configuration se fait en éditant la ressource personnalisée (CR) Image nommée cluster :

oc edit image.config.openshift.io/cluster

Les modifications sont apportées dans la section spec.  

• Autoriser/Bloquer des Registres (allowedRegistries / blockedRegistries) :
  spec.registrySources.allowedRegistries: Liste blanche des registres autorisés pour l’extraction (pull) et l’envoi (push). Tout registre non listé est bloqué.
  spec.registrySources.blockedRegistries: Liste noire des registres bloqués. Tout registre non listé est autorisé.  

  Important

  Un seul de ces deux paramètres peut être défini. Point critique : Si allowedRegistries est utilisé, il est impératif d’inclure les registres essentiels au fonctionnement d’OpenShift, tels que registry.redhat.io, uay.io, et le registre interne (image-registry.openshift-image-registry.svc:5000). Omettre ces registres entraînera des dysfonctionnements du cluster, car les composants OpenShift eux-mêmes ne pourront plus extraire leurs propres images. Il est fortement déconseillé de bloquer registry.redhat.io ou quay.io avec blockedRegistries.

  Exemple avec allowedRegistries :

spec:
  registrySources:
    allowedRegistries:
      - quay.io
      - registry.redhat.io
      - image-registry.openshift-image-registry.svc:5000 # Registre interne
      - monregistre.entreprise.com:5000 # Registre externe autorisé
      - docker.io # Si Docker Hub est nécessaire

• Gestion des Registres Non Sécurisés (insecureRegistries) :
  spec.registrySources.insecureRegistries: Liste des registres qui utilisent HTTP ou dont le certificat TLS n’est pas valide (par exemple, auto-signé).   Procédure spécifique à OpenShift Local/CRC :
  La configuration d’un registre non sécurisé nécessite deux étapes distinctes : Patch image.config :

1. Ajouter le registre à la liste spec.registrySources.insecureRegistries.
   Si allowedRegistries est utilisé, le registre doit également y figurer.

oc patch image.config.openshift.io/cluster --type=merge --patch \
  '{"spec":{"registrySources":{"insecureRegistries":["monregistre-insecure.local:5000"]}}}'

2. Ajouter aussi à allowedRegistries si nécessaire Modifier registries.conf dans la VM :
   Se connecter à la VM via SSH (crc ssh ou ssh -i ~/.crc/machines/crc/id_rsa core@$(crc ip)) et éditer le fichier /etc/containers/registries.conf pour ajouter une section pour le registre non sécurisé :

# Exemple d'ajout dans /etc/containers/registries.conf
[[registry]]
  location = "monregistre-insecure.local:5000"
  insecure = true
  # blocked = false # Assurez-vous qu'il n'est pas bloqué
  # prefix = ""
  # mirror-by-digest-only = false

Après modification, redémarrer les services crio et kubelet dans la VM :

sudo systemctl restart crio
sudo systemctl restart kubelet
exit

Cette double configuration est nécessaire car la première étape informe OpenShift, tandis que la seconde configure directement le runtime de conteneur (CRI-O) sur le nœud pour accepter les connexions non sécurisées vers ce registre spécifique.
L’utilisation de registres non sécurisés réduit la sécurité et doit être évitée si possible.  

• Ajout d’Autorités de Certification (CA) Personnalisées (additionalTrustedCA) :
  spec.additionalTrustedCA: Permet au cluster de faire confiance aux certificats TLS signés par une autorité de certification privée ou interne, souvent utilisée pour les registres d’entreprise.   Procédure :
  Créer une ConfigMap dans le namespace openshift-config.
  La clé de la ConfigMap doit être le nom d’hôte du registre (remplacer : par .. si le port est inclus, ex: monregistre.corp.com..5000) et la valeur doit être le certificat CA encodé en PEM.

oc create configmap ca-registre-perso -n openshift-config \
  --from-file=monregistre.corp.com=/chemin/vers/ca-registre.crt \
  --from-file=autre.registre.com..5000=/chemin/vers/autre-ca.crt
```  
Référencer cette ConfigMap dans `image.config.openshift.io/cluster` :
```YAML
spec:
  additionalTrustedCA:
    name: ca-registre-perso

Application des Changements et Impact sur le Nœud :

Les modifications apportées à image.config.openshift.io/cluster sont détectées par l’Operator de Configuration Machine (Machine Config Operator - MCO).   Le MCO applique ensuite ces changements au nœud OpenShift Local. Ce processus peut impliquer le drainage du nœud (le marquer comme non programmable), la mise à jour des fichiers de configuration (comme /etc/containers/registries.conf ou /etc/containers/policy.json), le redémarrage du runtime de conteneur (CRI-O), et potentiellement un redémarrage complet du nœud. Par conséquent, l’application de ces configurations globales n’est pas instantanée et peut entraîner une interruption temporaire du cluster OpenShift Local.
Ceci contraste avec la création et la liaison de secrets d’extraction, qui n’entraînent généralement pas d’interruption du nœud.

Tableau Comparatif : Pull Secrets vs Configuration Globale

Envoi (Push) d’Images Construites Localement

Une fois une image de conteneur construite localement (avec podman build ou docker build), elle peut être poussée vers un registre pour être utilisée dans OpenShift Local.

Envoi vers des Registres Externes

C’est le flux de travail standard pour partager des images ou utiliser des registres centralisés.

• Se connecter au Registre Externe :
  Utiliser les identifiants appropriés.

podman login monregistre.entreprise.com:5000
# Ou docker login...

• Construire l’Image Locale : (Si ce n’est pas déjà fait)

podman build -t mon-image-locale:latest.

• Tagger l’Image :
  Le tag doit inclure le chemin complet du registre externe.

podman tag mon-image-locale:latest monregistre.entreprise.com:5000/mon-projet/mon-image:latest

• Pousser l’Image :

podman push monregistre.entreprise.com:5000/mon-projet/mon-image:latest

Envoi vers le Registre Interne d’OpenShift Local (Alternative)

Pour un développement rapide et local, il peut être pratique de pousser l’image directement dans le registre interne d’OpenShift Local, le rendant immédiatement disponible pour les déploiements dans le cluster sans passer par un registre externe.

• Exposer le Registre Interne (si nécessaire) :
  Par défaut, le registre interne n’est pas exposé à l’extérieur du cluster. Une route doit être créée ou activée.
  Vérifier si la route par défaut existe :

oc get route default-route -n openshift-image-registry

Si elle n’existe pas ou n’est pas configurée, on peut la créer (nécessite potentiellement des ajustements selon la version d’OpenShift) ou la patcher pour l’activer.
Une commande courante pour l’activer est :  

oc patch config.imageregistry.operator.openshift.io/cluster --patch '{"spec":{"defaultRoute":true}}' --type=merge

Récupérer l’URL de la route :  

REGISTRY_URL=$(oc get route default-route -n openshift-image-registry --template='{{.spec.host }}')
echo $REGISTRY_URL

Cela devrait afficher quelque chose comme default-route-openshift-image-registry.apps-crc.testing.  

• Se connecter au Registre Interne :
  L’authentification se fait avec un utilisateur OpenShift (comme developer ou kubeadmin) et un jeton oc comme mot de passe.
  Le registre interne utilise souvent un certificat auto-signé, nécessitant une option pour ignorer la vérification TLS ou une configuration de confiance préalable sur le client podman/docker hôte.

podman login -u developer -p $(oc whoami -t) $REGISTRY_URL --tls-verify=false
# Ou utiliser kubeadmin si nécessaire :
# podman login -u kubeadmin -p $(oc whoami -t) $REGISTRY_URL --tls-verify=false

• Construire l’Image Locale : (Si ce n’est pas déjà fait)

podman build -t mon-image-locale:latest.

• Tagger l’Image :
  Le tag doit inclure l’URL du registre interne, le nom du projet OpenShift cible, et le nom/tag de l’image.

podman tag mon-image-locale:latest $REGISTRY_URL/mon-projet-openshift/mon-image:latest

• Pousser l’Image :

podman push $REGISTRY_URL/mon-projet-openshift/mon-image:latest --tls-verify=false

• Vérifier l’ImageStream : Pousser une image vers le registre interne crée ou met à jour automatiquement un ImageStream correspondant dans le projet cible.

oc get is -n mon-projet-openshift

Cette méthode interne nécessite de gérer l’authentification par jeton OpenShift et potentiellement les certificats auto-signés, contrairement à l’authentification standard des registres externes.

Considérations Réseau

La connectivité réseau entre OpenShift Local et les registres externes peut être affectée par la configuration DNS et les proxys.

• Résolution DNS

  • OpenShift Local repose sur les domaines *.crc.testing (pour les services internes comme l’API) et *.apps-crc.testing (pour les applications exposées via des Routes).  
  • La commande crc setup configure normalement le système hôte (via NetworkManager/dnsmasq sur Linux, ou des méthodes natives sur macOS/Windows) pour résoudre ces domaines vers l’adresse IP de la VM CRC.  
  • Des conflits peuvent survenir si l’hôte utilise déjà une configuration DNS complexe, ou si des plages d’adresses IP internes (comme 172.*.*.* utilisées par le cluster) sont en conflit avec le réseau local ou un VPN.  
  • Bien que le dépannage DNS détaillé sorte du cadre de l’accès aux registres externes, une résolution DNS fonctionnelle pour les domaines *.crc.testing est fondamentale pour interagir avec le cluster via oc ou la console web.
  • Des configurations avancées existent pour accéder à une instance CRC distante (impliquant haproxy, dnsmasq sur le serveur et/ou le client), mais elles sont complexes et ne représentent pas le cas d’usage principal de CRC.

• Configuration du Proxy HTTP/HTTPS Si la machine hôte ne peut accéder aux registres externes (ou à Internet en général) que via un proxy HTTP ou HTTPS, OpenShift Local doit être configuré pour utiliser ce proxy.

  • Méthode recommandée pour OpenShift Local : crc config
    • Cette méthode configure directement la machine virtuelle CRC pour utiliser le proxy pour son trafic sortant, ce qui inclut les tentatives d’extraction d’images par le runtime de conteneur.
    • Utiliser les commandes crc config set avant de démarrer le cluster (crc start), ou redémarrer le cluster (crc stop && crc start) si les paramètres sont modifiés pendant qu’il est en cours d’exécution.

crc config set http-proxy http://<proxy_host>:<proxy_port>    
crc config set https-proxy http://<proxy_host>:<proxy_port> (ou https:// si le proxy écoute en HTTPS)    
crc config set no-proxy <liste_no_proxy>    
crc config set proxy-ca-file /chemin/vers/ca-proxy.crt (si le proxy HTTPS utilise un certificat signé par une CA interne/personnalisée)    

• Configuration no-proxy critique :
  La liste no-proxy (séparée par des virgules, sans espaces) doit inclure les domaines et adresses IP qui ne doivent pas passer par le proxy.
  Pour OpenShift Local, cela inclut au minimum :
  • localhost,127.0.0.1
  • Les domaines internes : .crc.testing,.apps-crc.testing (ou *.crc.testing,*.apps-crc.testing)
  • L’adresse IP de la VM CRC (obtenue via crc ip)
  • Les CIDR des réseaux internes du cluster (par exemple, 10.128.0.0/14, 172.30.0.0/16, vérifier la documentation spécifique à la version si nécessaire)
  • Tout autre service ou registre interne au réseau local qui doit être accessible directement.
    Une configuration no-proxy incorrecte est une cause fréquente d’échec, car elle peut empêcher la communication interne du cluster ou l’accès à l’API.  
  • Les paramètres définis via crc config ont priorité sur les variables d’environnement système (http_proxy, https_proxy, no_proxy) pour la configuration de la VM CRC.  
• Alternative : Proxy Egress du Cluster (oc edit proxy/cluster)
  • OpenShift standard permet de configurer un proxy egress à l’échelle du cluster via la ressource Proxy nommée cluster. Cela affecte la manière dont les composants du cluster (Operators, etc.) et potentiellement les charges de travail des utilisateurs accèdent aux réseaux externes.
  • Cependant, dans l’environnement minimal d’OpenShift Local où de nombreux Operators sont désactivés , la pertinence et l’efficacité de cette méthode pour simplement permettre l’extraction d’images depuis des registres externes sont moins claires par rapport à la méthode crc config. L’extraction d’image provient du runtime de conteneur (CRI-O) sur le nœud, dont l’environnement réseau est directement influencé par crc config.
  • Il est donc recommandé de privilégier crc config set pour configurer l’accès aux registres externes via un proxy dans OpenShift Local.

Dépannage des Problèmes Courants

Lors de l’utilisation de registres externes, plusieurs problèmes peuvent survenir. Les plus fréquents concernent l’échec de l’extraction d’images (ImagePullBackOff), les erreurs de certificat TLS et les problèmes d’authentification.

Tableau de Dépannage Rapide

Diagnostic de ImagePullBackOff / ErrImagePull

Ces statuts indiquent que Kubernetes n’a pas réussi à extraire l’image requise pour un conteneur dans un Pod, même après plusieurs tentatives. ErrImagePull est l’erreur initiale signalée par le Kubelet, tandis que ImagePullBackOff est le statut indiquant que Kubernetes attend avant de réessayer, avec un délai croissant entre les tentatives. Ce n’est pas une erreur en soi, mais le symptôme d’un problème sous-jacent.  

• La première et principale étape de diagnostic est d’inspecter les événements du Pod :

oc describe pod <nom-du-pod>

Faites défiler jusqu’à la section Events à la fin de la sortie. Ces événements fournissent généralement des messages d’erreur détaillés expliquant pourquoi l’extraction a échoué.
Recherchez des messages comme :

• Failed to pull image "...": rpc error: code = Unknown desc = Error response from daemon: manifest for... not found (Image ou tag incorrect).
• Failed to pull image "...": rpc error: code = Unknown desc = unauthorized: authentication required (Problème d’authentification/secret).
• Failed to pull image "...": rpc error: code = Unknown desc =... x509: certificate signed by unknown authority (Problème de certificat TLS).
• Erreurs liées à la connectivité réseau (timeout, connection refused).
  Si les événements ne sont pas clairs ou si le Pod est en ImagePullBackOff depuis longtemps sans nouveaux événements, il peut être utile de supprimer le Pod (oc delete pod <nom-du-pod>) et d’observer les événements du nouveau Pod créé par le Deployment/ReplicaSet.   Les logs du Pod (oc logs <nom-du-pod>) sont rarement utiles pour les erreurs d’extraction d’image elles-mêmes, car le conteneur n’a pas pu démarrer.
  Cependant, les logs des composants système comme le Kubelet (difficilement accessibles directement dans CRC mais potentiellement visibles via oc adm node-logs si configuré) pourraient contenir plus de détails.  

Résolution des Erreurs de Certificat (x509: certificate signed by unknown authority)

Cette erreur survient lorsque le nœud OpenShift Local (la VM CRC) tente de se connecter à un registre externe via HTTPS, mais ne fait pas confiance à l’autorité de certification (CA) qui a signé le certificat TLS du registre.
Cela se produit typiquement avec des registres internes utilisant une CA privée.

Solution 1 (Préférée): Ajouter la CA aux autorités de confiance du cluster.

• Obtenir le certificat de la CA du registre (fichier .crt ou .pem).
• Créer une ConfigMap dans le namespace openshift-config contenant ce certificat, avec le nom d’hôte du registre comme clé.  
• Éditer image.config.openshift.io/cluster et ajouter une référence à cette ConfigMap sous spec.additionalTrustedCA.name.  
• Attendre que le MCO applique la configuration (peut impliquer un redémarrage du nœud).  

Solution 2 (Moins sécurisée) : Marquer le registre comme non sécurisé. Suivre la procédure en deux étapes décrite dans la Section 4 : patcher image.config.openshift.io/cluster pour ajouter le registre à insecureRegistries ET se connecter en SSH à la VM CRC pour modifier /etc/containers/registries.conf et redémarrer crio/kubelet. À n’utiliser que si l’ajout de la CA n’est pas possible.  

Correction des Erreurs d’Authentification (unauthorized: authentication required)

Ce message indique clairement que le registre a refusé l’accès car les informations d’identification fournies (ou absentes) sont incorrectes.  

1. Vérifier le Secret d’Extraction: Le secret existe-t-il dans le bon namespace? (oc get secret -n ).   Est-il correctement lié au compte de service utilisé par le Pod (généralement default)? (oc describe sa default -n et vérifier la section Image pull secrets).   Les données dans le secret sont-elles correctes? Il peut être nécessaire de décoder la section data[".dockerconfigjson"] (encodée en base64) pour vérifier le serveur, le nom d’utilisateur et le jeton/mot de passe.   Le Pod utilise-t-il le bon compte de service (spec.serviceAccountName)?

2. Vérifier les Connexions Manuelles : Si l’erreur survient lors d’un podman push ou docker push, revérifier la commande login exécutée précédemment sur l’hôte.  

3. Cas Spécifique du Registre Interne : Si l’erreur se produit lors de l’interaction avec le registre interne exposé (default-route-openshift-image-registry…), s’assurer d’utiliser oc whoami -t comme mot de passe et le nom d’utilisateur approprié (developer ou kubeadmin). Vérifier également les rôles associés à l’utilisateur (par exemple, registry-viewer, system:image-puller). L’ajout du registre interne aux containerRuntimeSearchRegistries peut parfois interférer avec l’authentification si elle n’est pas gérée correctement par un secret global ou lié.  

Conclusion

L’intégration de référentiels externes est une capacité essentielle pour utiliser efficacement Red Hat OpenShift Local (CRC) dans des scénarios de développement réalistes. Ce guide a présenté les méthodes et considérations clés pour y parvenir.

Résumé des Méthodes

• Secrets d’Extraction (Pull Secrets):
  La méthode privilégiée pour accéder aux registres externes authentifiés. Ils offrent un contrôle granulaire par projet/compte de service et n’entraînent généralement pas d’interruption du cluster.
• Configuration Globale (image.config.openshift.io/cluster) :
  Utilisée pour appliquer des règles à l’échelle du cluster, telles que l’autorisation/blocage de registres, la configuration de l’accès aux registres non sécurisés (nécessitant une modification supplémentaire dans la VM CRC), et l’ajout de CA personnalisées. L’application de ces paramètres peut entraîner un redémarrage du nœud par le MCO.

Meilleures Pratiques

• Privilégier les Pull Secrets : Pour les registres nécessitant une authentification, utiliser oc create secret et oc secrets link est la méthode la plus propre et la moins perturbatrice.
• Utiliser la Config Globale Judicieusement : Réserver la modification de image.config.openshift.io/cluster pour les cas où une configuration à l’échelle du cluster est nécessaire (confiance CA, gestion globale des registres publics/insecure). Être conscient de l’impact potentiel sur la disponibilité du nœud.
• Éviter les Registres Non Sécurisés : Ne configurer un registre comme non sécurisé qu’en dernier recours. Donner la priorité à la configuration TLS correcte et à l’ajout de CA personnalisées via additionalTrustedCA.
• Configurer no-proxy avec Soin : Lors de l’utilisation d’un proxy via crc config, s’assurer que la liste no-proxy est complète et correcte pour éviter de perturber la communication interne du cluster.
• Dépanner Méthodiquement : Commencer par oc describe pod pour analyser les événements en cas d’erreur ImagePullBackOff ou ErrImagePull. Vérifier ensuite systématiquement le nom de l’image, la connectivité, l’authentification (secrets) et les certificats selon le message d’erreur.

Red Hat OpenShift Local offre un puissant environnement de développement local pour les applications conteneurisées. En maîtrisant la configuration de l’accès aux registres d’images externes, les développeurs peuvent intégrer de manière transparente les ressources nécessaires à leurs projets, se rapprochant ainsi des conditions réelles de déploiement et accélérant le cycle de développement et de test.