Utiliser un miroir de registre pour les images de conteneur

Cette page explique comment créer et mettre à jour des clusters à l'aide d'images extraites d'un miroir de registre, plutôt que d'un registre public tel que gcr.io. Cette fonctionnalité peut être activée ou désactivée à tout moment au cours du cycle de vie du cluster.

Cette page s'adresse aux opérateurs et aux spécialistes du stockage qui configurent et gèrent les performances, l'utilisation et les dépenses de stockage. Pour en savoir plus sur les rôles courants et les exemples de tâches que nous citons dans le contenu Google Cloud , consultez la section Rôles utilisateur et tâches courantes de l'utilisateur dans GKE Enterprise.

Un miroir de registre est une copie locale d'un registre public, qui copie ou reflète la structure de fichiers du registre public. Par exemple, supposons que le chemin d'accès à votre miroir de registre local soit 172.18.0.20:5000. Lorsque containerd rencontre une requête d'extraction d'image telle que gcr.io/kubernetes-e2e-test-images/nautilus:1.0, containerd tente d'extraire cette image, non pas à partir de gcr.io, mais de votre registre local, au chemin d'accès suivant : 172.18.0.20:5000/kubernetes-e2e-test-images/nautilus:1.0. Si l'image ne figure pas à cet emplacement de registre local, elle est extraite automatiquement du registre public gcr.io.

L'utilisation d'un miroir de registre offre les avantages suivants :

  • Protection contre les indisponibilités de registre public.
  • Accélération de la création de pods.
  • Vous permet d'effectuer votre propre analyse des failles.
  • Évite les limites imposées par les registres publics concernant la fréquence à laquelle vous pouvez leur envoyer des commandes

Avant de commencer

  • Vous devez avoir configuré un serveur Artifact Registry sur votre réseau.
  • Si votre serveur de registre exécute un certificat TLS privé, vous devez disposer du fichier de l'autorité de certification.
  • Si votre serveur de registre requiert une authentification, vous devez disposer des identifiants de connexion appropriés ou du fichier de configuration Docker.
  • Si vous utilisez un registre Red Hat Quay, vous devrez peut-être créer manuellement la structure de répertoire du registre local.
  • Pour utiliser un miroir de registre, vous devez définir l'environnement d'exécution du conteneur sur containerd.
  • Assurez-vous de disposer d'un espace disque suffisant sur votre poste de travail administrateur pour les importations d'images. La commande d'importation d'images, bmctl push images, décompresse le fichier de package d'images téléchargé, puis extrait tous les fichiers d'images localement avant de les importer. Vous devez disposer d'au moins trois fois plus d'espace disque que la taille du fichier de package d'images téléchargé pour pouvoir importer les images. Par exemple, le fichier bmpackages_1.31.200-gke.59.tar.xz compressé occupe environ 8,5 Go d'espace disque. Vous devez donc disposer d'au moins 25,5 Go d'espace disque libre avant de télécharger le fichier.

Télécharger toutes les images requises pour Google Distributed Cloud

Téléchargez la dernière version de l'outil bmctl et du package d'images depuis la page Télécharger.

Importer des images de conteneurs sur votre serveur de registre

Lorsque vous utilisez bmctl push images pour importer des images de conteneur sur votre serveur de dépôt, bmctl effectue les étapes suivantes dans l'ordre:

  1. Décompressez un fichier tar compressé de package d'images téléchargé, tel que bmpackages_1.32.100-gke.106.tar.xz dans bmpackages_1.32.100-gke.106.tar.

  2. Extrayez toutes les images du fichier tar décompressé dans un répertoire nommé bmpackages_1.32.100-gke.106.

  3. Transférez chaque fichier d'image vers le registre privé spécifié.

    bmctl utilise les valeurs --username et --password pour l'authentification de base afin de transférer les images vers votre registre privé.

Les sections suivantes illustrent certaines variantes courantes de la commande bmctl push images pour importer des images sur votre serveur de dépôt.

Authentifier avec votre registre et partager le certificat TLS

La commande suivante inclut les options --username et --password pour l'authentification des utilisateurs avec votre serveur de registre. La commande inclut également l'indicateur --cacert pour transmettre le certificat TLS (Transport Layer Security) de l'autorité de certification, qui est utilisé pour sécuriser la communication du serveur de registre, y compris les transferts d'images et les extractions. Ces indicateurs fournissent une sécurité de base à votre serveur de registre.

Si votre serveur de registre nécessite une authentification et que vous n'utilisez pas les options --username et --password, vous devriez être invité à saisir des identifiants lorsque vous exécutez bmctl push images. Vous pouvez saisir votre mot de passe ou choisir le fichier de configuration Docker contenant les identifiants.

Pour importer des images avec authentification et un certificat d'autorité de certification privée, utilisez une commande semblable à la suivante:

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --username USERNAME \
    --password PASSWORD \
    --cacert CERT_PATH

Remplacez les éléments suivants :

  • IMAGES_TAR_FILE_PATH: chemin d'accès au fichier tar du package d'images téléchargé, par exemple bmpackages_1.32.100-gke.106.tar.xz.

  • REGISTRY_IP:PORT: adresse IP et port du serveur de registre privé.

  • USERNAME: nom d'utilisateur d'un utilisateur disposant des autorisations d'accès nécessaires pour importer des images sur le serveur de registre.

  • PASSWORD: mot de passe de l'utilisateur pour l'authentification auprès du serveur de registre.

  • CERT_PATH: chemin d'accès au fichier de certificat CA, si votre serveur de registre utilise un certificat TLS privé.

Exemple :

bmctl push images \
    --source bmpackages_1.32.100-gke.106.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --username alex --password pa55w0rd \
    --cacert /etc/pki/tls/certs/ca-bundle.crt

Importer des images sans authentification ni certificats utilisateur

Si votre serveur de registre ne requiert pas d'identifiants, tels qu'un nom d'utilisateur et un mot de passe, spécifiez --need-credential=false dans la commande bmctl. Si votre serveur de registre utilise un certificat TLS public, vous n'avez pas besoin d'utiliser l'indicateur --cacert. Ce type de commande d'importation est particulièrement adapté aux environnements de test, où la sécurité est moins préoccupante qu'en production.

Pour importer des images sans authentification ni certificat CA privé, utilisez une commande comme celle-ci:

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --need-credential=false

Exemple :

bmctl push images \
    --source bmpackages_1.32.100-gke.106.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --need-credential=false.

Ajuster le nombre de threads

La routine d'importation d'images peut prendre du temps en raison de la taille et de la quantité d'images de conteneur dans le fichier tar du package d'images. Augmenter le nombre de threads parallèles accélère l'exécution de la routine. Vous pouvez utiliser l'indicateur --threads pour modifier le nombre de threads parallèles utilisés par bmctl push images.

Par défaut, la routine d'importation d'images utilise quatre threads. Si l'importation de vos images prend trop de temps, augmentez cette valeur. À titre de référence, dans un environnement de test Google, l'importation d'images à partir d'une station de travail avec quatre CPU prend environ 10 minutes avec huit threads parallèles.

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --cacert CERT_PATH \
    --threads NUM_THREADS

Remplacez NUM_THREADS par le nombre de threads parallèles utilisés pour traiter les importations d'images. Par défaut, bmctl push images utilise quatre threads parallèles.

La commande suivante augmente le nombre de threads d'importation de 4 à 8 pour réduire le temps d'importation:

bmctl push images \
    --source bmpackages_1.32.100-gke.106.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --cacert ~/cert.pem \
    --threads 8

Importer via un proxy

Si vous avez besoin d'un proxy pour importer les images de votre station de travail vers le serveur de registre, vous pouvez ajouter les informations du proxy avant la commande bmctl:

HTTPS_PROXY=http://PROXY_IP:PORT bmctl push images \
    --source=IMAGES_TAR_FILE_PATH \
    --private-registry=REGISTRY_IP:PORT \
    --cacert=CERT_PATH

Remplacez les éléments suivants :

  • PROXY_IP:PORT: adresse IP et port du proxy.

  • IMAGES_TAR_FILE_PATH: chemin d'accès au fichier tar du package d'images téléchargé, par exemple bmpackages_1.32.100-gke.106.tar.xz.

  • REGISTRY_IP:PORT: adresse IP et port du serveur de registre privé.

  • CERT_PATH: chemin d'accès au fichier de certificat CA, si votre serveur de registre utilise un certificat TLS privé.

Saisissez votre nom d'utilisateur et votre mot de passe lorsque vous y êtes invité, ou sélectionnez un fichier de configuration Docker.

La commande suivante importe des images via un proxy:

HTTPS_PROXY=http://10.128.0.136:3128 bmctl push images \
    --source bmpackages_1.32.100-gke.106.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --cacert ~/cert.pem

Utiliser votre propre espace de noms avec bmctl push images

Si vous souhaitez utiliser votre propre espace de noms sur votre serveur de registre au lieu de l'espace de noms racine, containerd peut extraire de cet espace de noms si vous fournissez le point de terminaison de l'API pour votre registre privé dans le champ registryMirrors.endpoint de votre fichier de configuration de cluster. Le point de terminaison est généralement au format <REGISTRY_IP:PORT>/v2/<NAMESPACE>. Pour en savoir plus, consultez le guide de l'utilisateur de votre registre privé. Pour en savoir plus, consultez la section À propos de l'utilisation de v2 dans le point de terminaison du Registre.

bmctl push images \
    --source=IMAGES_TAR_FILE_PATH \
    --private-registry=REGISTRY_IP:PORT/NAMESPACE \
    --cacert=CERT_PATH

Remplacez NAMESPACE par le nom de l'espace de noms du serveur de registre dans lequel vous souhaitez importer des images.

Par exemple, si vous n'avez accès qu'à 198.51.20:5000/test-namespace/, vous pouvez exécuter une commande comme celle-ci pour importer toutes les images sous l'espace de noms test-namespace:

bmctl push images \
    --source=./bmpackages_1.32.100-gke.106.tar.xz \
    --private-registry=198.51.20:5000/test-namespace \
    --username=alex \
    --password=pa55w0rd \
    --cacert /etc/pki/tls/certs/ca-bundle.crt

Ensuite, dans le fichier de configuration du cluster, vous pouvez ajouter ce qui suit pour que containerd effectue l'extraction à partir de l'espace de noms test-namespace:

registryMirrors:
  - endpoint: https://198.51.20:5000/v2/test-namespace

Pour en savoir plus sur la commande bmctl push images, consultez la documentation de référence sur la commande bmctl.

Configurer des clusters pour qu'ils utilisent un miroir de registre

Vous pouvez configurer un miroir de registre pour un cluster lors de sa création ou chaque fois que vous mettez à jour un cluster existant. La méthode de configuration que vous utilisez dépend du type de cluster et, pour les clusters d'utilisateurs, si vous créez ou mettez à jour un cluster. Les deux sections suivantes décrivent les deux méthodes disponibles pour configurer des miroirs de Registre.

Utiliser la section d'en-tête dans le fichier de configuration du cluster

Google Distributed Cloud vous permet de spécifier des miroirs de registre en dehors de la spécification du cluster, dans la section d'en-tête du fichier de configuration du cluster:

  • Pour les clusters administrateur, hybrides et autonomes, le seul moyen de configurer un miroir de registre consiste à utiliser la section d'en-tête du fichier de configuration du cluster. Cette méthode s'applique à la création ou à la mise à jour de clusters.

  • Pour les clusters d'utilisateurs, vous ne pouvez utiliser cette méthode que pour configurer un miroir de registre lors de la création du cluster. Pour configurer un miroir de registre pour un cluster d'utilisateur existant, vous pouvez également utiliser la section nodeConfig.registryMirrors dans la spécification du cluster.

L'exemple de fichier de configuration de cluster suivant spécifie que les images doivent être extraites d'un miroir de registre local dont le point de terminaison est https://198.51.20:5000. Certains champs figurant au début de ce fichier de configuration sont décrits dans les sections suivantes.

# Sample cluster config with registry mirror:
---
gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
sshPrivateKeyPath: /root/ssh-key/id_rsa
registryMirrors:
  - endpoint: https://198.51.20:5000
    caCertPath: /root/ca.crt
    pullCredentialConfigPath: /root/.docker/config.json
    hosts:
      - somehost.io
      - otherhost.io
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-admin1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: admin1
  namespace: cluster-admin1
spec:
  nodeConfig:
    containerRuntime: containerd
...

Utiliser la section nodeConfig.registryMirrors dans la spécification du cluster

Cette méthode de création ou de mise à jour d'un miroir de Registre ne s'applique qu'aux clusters d'utilisateurs. Étant donné que vous pouvez partager les secrets créés pour le cluster de gestion avec votre cluster d'utilisateur, vous pouvez utiliser nodeConfig.registryMirrors à partir du cluster d'administrateur ou hybride de gestion pour spécifier le miroir de registre dans la spécification du cluster pour le cluster d'utilisateur.

Pour configurer un cluster utilisateur pour qu'il utilise le même miroir de registre que le cluster administrateur, procédez comme suit:

  1. Récupérez la section nodeConfig.registryMirror, y compris les références de secret, à partir de nodeConfig.registryMirrors de la ressource de cluster d'administrateur:

    kubectl get cluster CLUSTER_NAME -n CLUSTER_NAMESPACE \
    --kubeconfig ADMIN_KUBECONFIG \
    -o yaml

    Remplacez les éléments suivants :

    • CLUSTER_NAME: nom du cluster d'administrateur ou hybride qui gère le cluster d'utilisateur.

    • CLUSTER_NAMESPACE: nom de l'espace de noms du cluster de gestion.

    • ADMIN_KUBECONFIG: chemin d'accès au fichier kubeconfig du cluster de gestion.

  2. Ajoutez la configuration nodeConfig.registryMirrors du cluster d'administrateur au fichier de configuration du cluster du cluster d'utilisateur.

    La section registryMirrors du fichier de configuration du cluster d'utilisateur doit ressembler à l'exemple suivant:

    ---
gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
sshPrivateKeyPath: /root/ssh-key/id_rsa
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-user1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: user1
  namespace: cluster-user1
spec:
  nodeConfig:
    containerRuntime: containerd
    registryMirrors:
    -   caCertSecretRef:
        name: the-secret-created-for-the-admin-cluster
        namespace: anthos-creds
      endpoint: https://172.18.0.20:5000
      hosts:
        -   somehost.io
        -   otherhost.io
      pullCredentialSecretRef:
        name: the-image-pull-creds-created-for-the-admin-cluster
        namespace: anthos-creds
...

Pour apporter des modifications ultérieures à la configuration du miroir de Registre de votre cluster d'utilisateur, modifiez nodeConfig.registryMirrors dans le fichier de configuration du cluster d'utilisateur, puis appliquez vos modifications avec bmctl update.

Vous ne pouvez pas utiliser la section d'en-tête du fichier de configuration du cluster pour mettre à jour la configuration des miroirs de Registre d'un cluster d'utilisateur.

Champ hosts

containerd vérifie la section hosts du fichier de configuration du cluster pour détecter les hôtes mis en miroir localement. Ces hôtes sont mappés sur le point de terminaison du miroir de registre spécifié dans le fichier de configuration du cluster (registryMirror.endpoint). Dans l'exemple de fichier de configuration de la section précédente, les registres publics listés dans la section hosts sont somehost.io et otherhost.io. Étant donné que ces registres publics apparaissent dans la section hosts, containerd vérifie d'abord le miroir de registre privé, lorsqu'il reçoit des demandes d'extraction d'images à partir de somehost.io ou otherhost.io.

Par exemple, supposons que containerd reçoit une commande d'extraction (pull) à somehost.io/kubernetes-e2e-test-images/nautilus:1.0. Comme somehost.io est listé comme l'un des hôtes dans la section hosts du fichier de configuration du cluster, containerd recherche l'image kubernetes-e2e-test-images/nautilus:1.0 dans le miroir de registre local. Si somehost.io n'est pas listé dans la section hosts, containerd ne sait pas qu'il existe un miroir local de somehost.io. Dans ce cas, containerd ne recherche pas l'image dans le miroir et l'extrait simplement du registre public somehost.io.

Notez que, par défaut, Google Distributed Cloud met automatiquement en miroir les images de gcr.io. Vous n'avez donc pas besoin de répertorier gcr.io en tant qu'hôte dans la section hosts.

Les valeurs hosts et la valeur endpoint ne doivent pas se chevaucher. Par exemple, l'exemple de configuration suivant montre un hôte, europe-docker.pkg.dev, qui correspond à la partie du domaine de la valeur du point de terminaison. Dans ce cas, vous n'avez pas besoin de spécifier de valeur hosts:

...
registryMirrors:
  ...
  endpoint: https://europe-docker.pkg.dev:5000/v2/cloud-data-fusion-images
  hosts:
    - europe-docker.pkg.dev
    ...

Champ gcrKeyPath

Si vous souhaitez que Google Distributed Cloud utilise automatiquement Artifact Registry (gcr.io) pour extraire des images qui n'apparaissent pas dans votre registre local, vous devez spécifier le chemin d'accès à la clé du compte de service Artifact Registry. Google Distributed Cloud ne dispose pas d'un mécanisme permettant de fournir des clés pour d'autres registres publics.

Si vous ne prévoyez pas d'utiliser la fonctionnalité dans laquelle les images sont extraites de gcr.io lorsqu'elles n'apparaissent pas dans votre registre local, vous n'avez pas besoin d'ajouter un élément gcrKeyPath au fichier de configuration du cluster.

Champ caCertPath

Si votre registre nécessite un certificat TLS (Transport Layer Security) privé, ce champ indique le chemin d'accès au fichier de certificat CA racine du serveur. Ce fichier de certificat doit se trouver sur le poste de travail administrateur, la machine exécutant les commandes bmctl. Si votre registre ne nécessite pas de certificat TLS privé, vous pouvez laisser le champ caCertPath vide.

Champ pullCredentialConfigPath

Si votre serveur de registre ne nécessite pas de fichier de configuration Docker d'authentification, vous pouvez laisser le champ pullCredentialConfigPath vide. Notez qu'il s'agit du chemin d'accès au fichier de configuration sur la machine exécutant les commandes bmctl.

Utiliser un miroir de registre avec des clusters d'utilisateurs

Les clusters d'utilisateur n'extraient pas automatiquement les images d'un miroir de registre si leur cluster d'administrateur a été configuré dans cette optique. Pour que les clusters d'utilisateur procèdent à une extraction depuis un miroir de registre, vous devez les configurer individuellement, comme décrit dans la section Configurer des clusters à partir du miroir de registre.

Mettre à jour les points de terminaison, les certificats et les identifiants d'extraction du miroir de registre

Pour mettre à jour les points de terminaison, les certificats ou les identifiants d'extraction du miroir de registre, procédez comme suit :

  1. Dans le fichier de configuration du cluster, mettez à jour le point de terminaison, le fichier de certificat CA et le chemin d'accès au fichier de configuration des identifiants.

  2. Appliquez les modifications en exécutant la commande suivante :

    bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG

    Remplacez les éléments suivants :

    • CLUSTER_NAME par le nom du cluster que vous souhaitez mettre à jour.

    • ADMIN_KUBECONFIG par le chemin d'accès de votre fichier de configuration de cluster d'administrateur.

Vérifier que les images sont extraites du miroir de registre

Vous pouvez déterminer si containerd extrait des images à partir de votre registre local en examinant le contenu d'un fichier config.toml, comme indiqué dans les étapes suivantes :

  1. Connectez-vous à un nœud et examinez le contenu du fichier suivant : /etc/containerd/config.toml

  2. Examinez la section plugins."io.containerd.grpc.v1.cri".registry.mirrors de ce fichier config.toml pour voir si votre serveur de registre est listé dans le champ endpoint. Voici un extrait d'un exemple de fichier config.toml dans lequel le champ endpoint apparaît en gras :

    version = 2
root = "/var/lib/containerd"
state = "/run/containerd"
...
[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.configs]
    [plugins."io.containerd.grpc.v1.cri".registry.configs."gcr.io"]
      [plugins."io.containerd.grpc.v1.cri".registry.configs."privateregistry2.io".tls]
        ca_file = '/etc/containerd/certs.d/privateregistry2.io/ca.crt'
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
      endpoint = ["http://privateregistry.io", "https://privateregistry2.io"]
...

    Si votre miroir de registre s'affiche dans le champ endpoint, cela signifie que le nœud extrait des images à partir de votre miroir de registre plutôt que d'un registre public.

Résoudre les problèmes liés aux paramètres des miroirs de registre

Vous pouvez utiliser crictl, l'outil de ligne de commande de l'interface d'exécution de conteneur, pour tester vos paramètres de registre en téléchargeant des fichiers d'image individuels. Chaque fichier image est tagué indépendamment avec une chaîne de version significative. Par exemple, l'image du contrôleur de l'API de cluster est taguée avec la version de Google Distributed Cloud, et l'image etcd est taguée avec la version etcd correspondante.

Pour la version 1.31.200-gke.59 de Google Distributed Cloud pour bare metal, l'image du contrôleur de l'API de cluster, cluster-api-controller, et l'image etcd, etcd, comportent les tags suivants:

  • cluster-api-controller:1.31.200-gke.59
  • etcd:v3.4.30-0-gke.1

Extraire une image du miroir du registre

Si votre miroir de registre n'utilise pas d'espaces de noms, utilisez la commande suivante pour extraire une image:

crictl pull REGISTRY_IP:PORT/IMAGE_PATH:IMAGE_TAG

Extraire une image à partir d'un miroir de registre qui utilise des espaces de noms

Si votre miroir de registre utilise des espaces de noms, utilisez la commande suivante pour extraire une image:

crictl pull REGISTRY_IP:PORT/NAMESPACE/IMAGE_PATH:IMAGE_TAG

À propos de l'utilisation de v2 dans le point de terminaison du Registre

Lorsque votre registre utilise des espaces de noms personnalisés, vous devez ajouter v2/ au début de l'espace de noms dans le point de terminaison du registre (registryMirror.endpoint) du fichier de configuration du cluster. Si vous n'utilisez pas d'espaces de noms, n'utilisez pas v2. Dans les deux cas, n'utilisez pas v2 dans la valeur de l'indicateur --private-registry ni dans les commandes de récupération d'images:

Sans espace de noms

  • Valide :
    • endpoint: https://172.18.0.20:5000
    • crictl pull 172.18.0.20:5000/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
  • Non valide :
    • endpoint: https://172.18.0.20:5000/v2
    • crictl pull 172.18.0.20:5000/v2/anthos-baremetal-release/etcd:v3.4.30-0-gke.1

Avec des espaces de noms

  • Valide :
    • endpoint: https://172.18.0.21:5000/v2/namespace
    • crictl 172.18.0.21:5000/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
  • Non valide :
    • endpoint: https://172.18.0.21:5000/namespace
    • crictl pull 172.18.0.21:5000/v2/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1