Usar una réplica de registro para imágenes de contenedor

En esta página se explica cómo crear y actualizar clústeres usando imágenes extraídas de un mirror de registro, en lugar de un registro público como gcr.io. Esta función se puede habilitar o inhabilitar en cualquier momento del ciclo de vida del clúster.

Esta página está dirigida a operadores y especialistas en almacenamiento que configuran y gestionan el rendimiento, el uso y los gastos del almacenamiento. Para obtener más información sobre los roles habituales y las tareas de ejemplo a las que hacemos referencia en el contenido, consulta Roles y tareas habituales de los usuarios de GKE. Google Cloud

Un mirror de un registro es una copia local de un registro público que copia o refleja la estructura de archivos del registro público. Por ejemplo, supongamos que la ruta a tu réplica de registro local es 172.18.0.20:5000. Cuando containerd recibe una solicitud para extraer una imagen, como gcr.io/kubernetes-e2e-test-images/nautilus:1.0, intenta extraerla, no de gcr.io, sino de tu registro local en la siguiente ruta: 172.18.0.20:5000/kubernetes-e2e-test-images/nautilus:1.0.containerd Si la imagen no está en esta ruta del registro local, se extraerá automáticamente del registro público gcr.io.

Usar una réplica de registro ofrece las siguientes ventajas:

• Te protege frente a las interrupciones del registro público.
• Acelera la creación de pódcasts.
• Te permite realizar tus propios análisis de vulnerabilidades.
• Evita los límites impuestos por los registros públicos sobre la frecuencia con la que puedes enviarles comandos.

Nota: Las imágenes de gcr.io/anthos-baremetal-release/kindest/node no se sustituyen por las de gcr.io. Estas imágenes solo se extraen del mirror del registro. Si el registro de réplica no funciona, la extracción falla.

Antes de empezar

• Debes tener un servidor de Artifact Registry configurado en tu red.
• Si tu servidor de registro usa un certificado TLS privado, debes tener el archivo de la autoridad de certificación (CA).
• Si tu servidor de registro necesita autenticación, debes tener las credenciales de inicio de sesión o el archivo de configuración de Docker adecuados.
• Si usas un registro de Red Hat Quay, puede que tengas que crear manualmente la estructura de directorios del registro local.
• Para usar una réplica de registro, debes definir el entorno de ejecución del contenedor como containerd.

• Asegúrate de que tienes suficiente espacio en disco en tu estación de trabajo de administrador para subir imágenes. El comando de subida de imágenes, bmctl push images, descomprime el archivo del paquete de imágenes descargado y, a continuación, extrae todos los archivos de imagen localmente antes de subirlos. Necesitas al menos tres veces el tamaño del archivo del paquete de imágenes descargadas en espacio de disco para subir la imagen.

  Por ejemplo, el archivo bmpackages_1.33.0-gke.799.tar.xz comprimido ocupa aproximadamente 12 GB de espacio en disco, por lo que debes tener al menos 36 GB de espacio libre en disco antes de descargar el archivo.

  Si vas a realizar una actualización de salto (actualizar dos versiones secundarias en una sola operación), debes subir imágenes de archivos de paquetes de imágenes tanto para la versión de destino (N+2) como para la versión intermedia (N+1). Según este ejemplo, necesitas aproximadamente 72 GB de espacio libre en disco para subir la imagen. Para obtener más información sobre la versión intermedia, consulta Requisito adicional para réplicas de registros.

Descargar todas las imágenes necesarias para Google Distributed Cloud

Descarga la versión más reciente de la bmctl herramienta y el paquete de imágenes desde la página Descargas.

Nota: Antes de la versión secundaria 1.29, el formato de archivo tar del paquete de imágenes era compatible con Docker. En la versión secundaria 1.29 y posteriores, el archivo tar del paquete de imágenes está en formato de imagen de Open Container Initiative (OCI), que no es compatible con Docker.

Subir imágenes de contenedor al servidor de registro

Cuando usas bmctl push images para subir imágenes de contenedor a tu servidor de repositorio, bmctl sigue estos pasos en orden:

1. Descomprime un paquete de imágenes descargado comprimido en un archivo tar, como bmpackages_1.33.100-gke.89.tar.xz en bmpackages_1.33.100-gke.89.tar.

2. Extrae todas las imágenes del archivo tar descomprimido en un directorio llamado bmpackages_1.33.100-gke.89.

3. Sube cada archivo de imagen al registro privado especificado.

   bmctl usa los valores --username y --password para la autenticación básica con el fin de insertar las imágenes en tu registro privado.

En las siguientes secciones se muestran algunas variaciones habituales del comando bmctl push images para subir imágenes al servidor de tu repositorio.

Autenticarte con tu registro y compartir el certificado TLS

El siguiente comando incluye las marcas --username y --password para la autenticación de usuarios con tu servidor de registro. El comando también incluye la marca --cacert para transferir el certificado de seguridad de la capa de transporte (TLS) de la AC, que se usa para la comunicación segura con el servidor de registro, incluidas las inserciones y las extracciones de imágenes. Estas marcas proporcionan seguridad básica para tu servidor de registro.

Si tu servidor de registro requiere autenticación y no usas las marcas --username y --password, se te pedirán las credenciales cuando ejecutes bmctl push images. Puedes escribir tu contraseña o elegir el archivo de configuración de Docker que contiene las credenciales.

Para subir imágenes con autenticación y un certificado de AC privada, usa un comando como el siguiente:

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

Haz los cambios siguientes:

• IMAGES_TAR_FILE_PATH: la ruta del archivo tar del paquete de imágenes descargadas, como bmpackages_1.33.100-gke.89.tar.xz.

• REGISTRY_IP:PORT: la dirección IP y el puerto del servidor de registro privado.

• USERNAME: nombre de usuario de un usuario con permisos de acceso para subir imágenes al servidor de registro.

• PASSWORD: la contraseña del usuario para autenticarse en el servidor del registro.

• CERT_PATH: la ruta del archivo de certificado de la AC, si tu servidor de registro usa un certificado TLS privado.

Por ejemplo:

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

Subir imágenes sin autenticación de usuario ni certificados

Si tu servidor de registro no requiere credenciales, como un nombre de usuario y una contraseña, especifica --need-credential=false en el comando bmctl. Si tu servidor de registro usa un certificado TLS público, no tienes que usar la marca --cacert. Este tipo de comando de subida es el más adecuado para entornos de prueba, donde la seguridad es menos importante que en producción.

Para subir imágenes sin autenticación ni un certificado de CA privada, usa un comando como el siguiente:

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

Por ejemplo:

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

Ajustar el número de hilos

La rutina de subida de imágenes puede llevar mucho tiempo debido al tamaño y la cantidad de imágenes de contenedor del archivo tar del paquete de imágenes. Si aumentas el número de hilos paralelos, la rutina se ejecutará más rápido. Puedes usar la marca --threads para cambiar el número de subprocesos paralelos que usa bmctl push images.

De forma predeterminada, la rutina de subida de imágenes usa 4 hilos. Si las cargas de imágenes tardan demasiado, aumenta este valor. Como referencia, en un entorno de prueba de Google, se tardan unos 10 minutos en subir imágenes desde una estación de trabajo con 4 CPUs y 8 hilos paralelos.

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

Sustituye NUM_THREADS por el número de subprocesos paralelos que se usan para procesar las subidas de imágenes. De forma predeterminada, bmctl push images usa cuatro subprocesos paralelos.

El siguiente comando aumenta el número de subprocesos de la subida de 4 a 8 para reducir el tiempo de subida:

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

Subida a través de un proxy

Si necesitas un proxy para subir las imágenes de tu estación de trabajo al servidor del registro, puedes añadir los detalles del proxy antes del comando bmctl:

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

Haz los cambios siguientes:

• PROXY_IP:PORT: la dirección IP y el puerto del proxy.

• IMAGES_TAR_FILE_PATH: la ruta del archivo tar del paquete de imágenes descargadas, como bmpackages_1.33.100-gke.89.tar.xz.

• REGISTRY_IP:PORT: la dirección IP y el puerto del servidor de registro privado.

• CERT_PATH: la ruta del archivo de certificado de la AC, si tu servidor de registro usa un certificado TLS privado.

Introduce tu nombre de usuario y contraseña cuando se te solicite o selecciona un archivo de configuración de Docker.

El siguiente comando sube imágenes a través de un proxy:

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

Usar tu propio espacio de nombres con bmctl push images

Si quieres usar tu propio espacio de nombres en el servidor de registro en lugar del espacio de nombres raíz, containerd puede extraer datos de este espacio de nombres si proporcionas el endpoint de la API de tu registro privado en el campo registryMirrors.endpoint de tu archivo de configuración de clúster. El punto final suele tener el formato <REGISTRY_IP:PORT>/v2/<NAMESPACE>. Consulta la guía de usuario de tu registro privado para obtener información específica. Para obtener más información, consulta Acerca del uso de v2 en el endpoint del registro.

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

Sustituye NAMESPACE por el nombre del espacio de nombres del servidor de registro en el que quieras subir imágenes.

Por ejemplo, si solo tienes acceso a 198.51.20:5000/test-namespace/, puedes usar un comando como el siguiente para subir todas las imágenes del espacio de nombres test-namespace:

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

A continuación, en el archivo de configuración del clúster, puedes añadir lo siguiente para que containerd extraiga datos del espacio de nombres test-namespace:

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

Para obtener más información sobre el comando bmctl push images, consulta la bmctlreferencia de comandos.

Configurar clústeres para usar una réplica de registro

Puedes configurar un mirror de registro para un clúster al crear el clúster o cuando actualices uno que ya tengas. El método de configuración que utilices dependerá del tipo de clúster y, en el caso de los clústeres de usuarios, de si vas a crear o actualizar un clúster. En las dos secciones siguientes se describen los dos métodos disponibles para configurar réplicas de registros.

Usar la sección de encabezado del archivo de configuración del clúster

Google Distributed Cloud te permite especificar réplicas de registro fuera de la especificación del clúster, en la sección de encabezado del archivo de configuración del clúster. En el caso de los clústeres de administrador, híbridos e independientes, este es el único método admitido para especificar réplicas de registro. Este método se aplica a la creación o actualización de clústeres.

En el caso de los clústeres de usuarios, te recomendamos que utilices la sección nodeConfig.registryMirrors del recurso Cluster para especificar y mantener las configuraciones de réplica del registro. Aunque puedes usar la sección de encabezado del archivo de configuración del clúster para especificar réplicas del registro al crear un clúster de usuario, la especificación no se conserva en las actualizaciones.

El siguiente archivo de configuración de clúster de ejemplo especifica que las imágenes se deben extraer de un mirror de registro local cuyo endpoint es https://198.51.20:5000. En las secciones siguientes se describen algunos de los campos que aparecen al principio de este archivo de configuración.

# 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
...

Usa la sección nodeConfig.registryMirrors de la especificación del clúster

Este método para crear o actualizar un mirror de registro solo se aplica a los clústeres de usuarios. Como puedes compartir los secretos creados para el clúster de gestión con tu clúster de usuario, puedes usar nodeConfig.registryMirrors del clúster de gestión o híbrido para especificar el mirror del registro en la especificación del clúster del clúster de usuario.

Para configurar un clúster de usuario de forma que use el mismo mirror de registro que el clúster de administrador, sigue estos pasos:

1. Obtén la sección nodeConfig.registryMirror, incluidas las referencias de secretos, de nodeConfig.registryMirrors del recurso de clúster de administrador:

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

   Haz los cambios siguientes:

   • CLUSTER_NAME: nombre del clúster de administrador o híbrido que gestiona el clúster de usuario.

   • CLUSTER_NAMESPACE: el nombre del espacio de nombres del clúster de gestión.

   • ADMIN_KUBECONFIG: la ruta del archivo kubeconfig del clúster de gestión.

2. Añade la configuración nodeConfig.registryMirrors del clúster de administrador al archivo de configuración del clúster de usuario.

   La sección registryMirrors del archivo de configuración del clúster de usuarios debe ser similar al siguiente ejemplo:

   ---
   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
   ...
   

Para hacer cambios posteriores en la configuración del mirror del registro de tu clúster de usuarios, edita el nodeConfig.registryMirrors en el archivo de configuración del clúster de usuarios y aplica los cambios con bmctl update.

No puedes usar la sección de encabezado del archivo de configuración del clúster para actualizar la configuración de los mirror de registro de un clúster de usuarios.

Campo hosts

containerd comprueba la sección hosts del archivo de configuración del clúster para descubrir qué hosts se replican localmente. Estos hosts se asignan al endpoint del mirror del registro especificado en el archivo de configuración del clúster (registryMirror.endpoint). En el archivo de configuración de ejemplo de la sección anterior, los registros públicos que se indican en la sección hosts son somehost.io y otherhost.io. Como estos registros públicos aparecen en la sección hosts, containerd comprueba primero el mirror del registro privado cuando recibe solicitudes de extracción de imágenes de somehost.io o otherhost.io.

Por ejemplo, supongamos que containerd recibe un comando pull para somehost.io/kubernetes-e2e-test-images/nautilus:1.0. Como somehost.io aparece en la sección hosts del archivo de configuración del clúster, containerd busca la imagen kubernetes-e2e-test-images/nautilus:1.0 en el mirror del registro local. Si somehost.io no aparece en la sección hosts, significa que containerd no sabe que existe una réplica local de somehost.io. En ese caso, containerd no comprueba la imagen en el mirror y la extrae del registro público de somehost.io.

Ten en cuenta que, de forma predeterminada, Google Distributed Cloud crea automáticamente una réplica de las imágenes de gcr.io, por lo que no es necesario que incluyas gcr.io como host en la sección hosts.

Los valores de hosts y endpoint no deben superponerse. Por ejemplo, en la siguiente configuración de muestra se muestra un host, europe-docker.pkg.dev, que coincide con la parte del dominio del valor del endpoint. En ese caso, no es necesario que especifique ningún valor de hosts:

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

Campo gcrKeyPath

Si quieres que Google Distributed Cloud use automáticamente Artifact Registry (gcr.io) para extraer imágenes que no aparezcan en tu registro local, debes especificar la ruta a la clave de la cuenta de servicio de Artifact Registry. Google Distributed Cloud no tiene ningún mecanismo para proporcionar claves para otros registros públicos.

Si no tienes previsto usar la función en la que se extraen imágenes de gcr.io cuando no aparecen en tu registro local, no es necesario que añadas un gcrKeyPath al archivo de configuración del clúster.

Campo caCertPath

Si tu registro requiere un certificado de seguridad en la capa de transporte (TLS) privado, este campo toma la ruta al archivo del certificado de la AC raíz del servidor. Este archivo de certificado debe estar en la estación de trabajo del administrador, es decir, en el equipo que ejecuta los comandos bmctl. Si tu registro no requiere un certificado TLS privado, puedes dejar el campo caCertPath en blanco.

Campo pullCredentialConfigPath

Si tu servidor de registro no requiere un archivo de configuración de Docker de autenticación, puedes dejar el campo pullCredentialConfigPath en blanco. Ten en cuenta que esta es la ruta al archivo de configuración en el equipo que ejecuta los comandos bmctl.

Usar una réplica de registro con clústeres de usuarios

Los clústeres de usuario no extraen automáticamente imágenes de un mirror de registro si su clúster de administrador se ha configurado para hacerlo. Para que los clústeres de usuario extraigan imágenes de un mirror de registro, debes configurarlos individualmente tal como se describe en Configurar clústeres para que usen un mirror de registro.

Actualizar los endpoints, los certificados y las credenciales de extracción del mirror del registro

Para actualizar los endpoints de réplica del registro, los certificados o las credenciales de extracción, sigue estos pasos:

1. En el archivo de configuración del clúster, actualiza el endpoint, el archivo de certificado de CA y la ruta del archivo de configuración de credenciales de extracción.

2. Aplica los cambios ejecutando el siguiente comando:

   bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG
   

   Haz los cambios siguientes:

   • CLUSTER_NAME con el nombre del clúster que quieras actualizar.

   • ADMIN_KUBECONFIG con la ruta de su archivo de configuración de clúster de administrador.

Verificar que las imágenes se extraen de la réplica del registro

Para determinar si containerd está obteniendo imágenes de tu registro local, examina el contenido de un archivo config.toml, tal como se muestra en los siguientes pasos:

1. Inicia sesión en un nodo y examina el contenido del siguiente archivo: /etc/containerd/config.toml

2. Consulta la sección plugins."io.containerd.grpc.v1.cri".registry.mirrors del archivo config.toml para ver si tu servidor de registro aparece en el campo endpoint. Aquí tienes un fragmento de un archivo config.toml de ejemplo en el que el campo endpoint aparece en negrita:

   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 la réplica de tu registro aparece en el campo endpoint, significa que el nodo está obteniendo imágenes de la réplica de tu registro en lugar de un registro público.

Solucionar problemas con la configuración de réplicas de registro

Puedes usar crictl, la herramienta de línea de comandos de la interfaz de tiempo de ejecución de contenedores, para probar la configuración de tu registro descargando archivos de imagen individuales. Cada archivo de imagen se etiqueta de forma independiente con una cadena de versión significativa. Por ejemplo, la imagen del controlador de la API del clúster se etiqueta con la versión de lanzamiento de Google Distributed Cloud y la imagen de etcd se etiqueta con la versión de etcd correspondiente.

En la versión 1.31.200-gke.59 de Google Distributed Cloud para bare metal, la imagen del controlador de la API de clústeres, cluster-api-controller, y la imagen de etcd, etcd, tienen las siguientes etiquetas:

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

Extraer una imagen de la réplica del registro

Si tu réplica del registro no usa espacios de nombres, usa el siguiente comando para extraer una imagen:

crictl pull REGISTRY_IP:PORT/IMAGE_PATH:IMAGE_TAG

Extraer una imagen de una réplica de registro que usa espacios de nombres

Si tu réplica del registro usa espacios de nombres, utiliza el siguiente comando para extraer una imagen:

crictl pull REGISTRY_IP:PORT/NAMESPACE/IMAGE_PATH:IMAGE_TAG

Acerca del uso de v2 en el endpoint de registro

Si tu registro usa espacios de nombres personalizados, debes anteponer el espacio de nombres al endpoint del registro (registryMirror.endpoint) en el archivo de configuración del clúster con v2/. Si no utilizas espacios de nombres, no uses v2. En cualquier caso, no uses v2 en el valor de la marca --private-registry ni en los comandos de extracción de imágenes:

Sin espacios de nombres

• Válido:
  • endpoint: https://172.18.0.20:5000
  • crictl pull 172.18.0.20:5000/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
• No válido:
  • 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

Con espacios de nombres

• Válido:
  • 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
• No válido:
  • 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