Crear instancias de registro de Harbor

Usa el servicio Managed Harbor Service (MHS) de Google Distributed Cloud (GDC) aislado para crear una instancia de registro de Harbor en cada proyecto. Una instancia de registro de Harbor sirve como repositorio central para almacenar y gestionar imágenes de contenedor en un entorno nativo de la nube. Amplía las funciones de la distribución de Docker de código abierto. Se aplican las siguientes limitaciones:

  • Puedes crear un máximo de una instancia por proyecto.
  • Las instancias están aisladas y no comparten datos ni recursos de computación.

Antes de empezar

Si eres responsable de crear instancias de registro de Harbor, ponte en contacto con el administrador de proyectos de gestión de identidades y accesos para solicitar el rol de administrador de instancias de Harbor (harbor-instance-admin), que te permite obtener, enumerar, ver, crear, actualizar, parchear y eliminar instancias de Harbor, repositorios de copias de seguridad, planes de copias de seguridad, copias de seguridad y restauraciones dentro de un espacio de nombres de proyecto. Este rol incluye los permisos necesarios para aprovisionar nuevas instancias de Harbor.

Crear una instancia de registro de Harbor

Crea una instancia de registro de Harbor en la consola de GDC o en la CLI gdcloud.

Consola

En la consola de GDC, sigue estos pasos:

  1. En el menú de navegación, en la sección CI/CD, haz clic en Harbor Container Registry.
  2. Haz clic en Crear instancia.
  3. En el campo Nombre de la instancia, escribe un nombre para la instancia.
  4. Opcional: En la sección Proyectos, para crear un proyecto predeterminado para esta instancia de Harbor, activa la opción Crear un proyecto predeterminado al crear esta instancia y, a continuación, haz lo siguiente:
    1. En el campo Project Name (Nombre del proyecto), introduce un nombre.
  5. Lee los Términos del Servicio de Harbor y, si los aceptas, marca la casilla.
  6. Haz clic en Crear. En Estado se muestra En curso y en Nombre se muestra un enlace externo que contiene el nombre de la instancia de Harbor que acabas de crear.
  7. Una vez que se haya creado la instancia y el estado sea Listo, haz clic en el enlace externo de la página para visitar la interfaz web de la instancia de Harbor.

gdcloud

Crea la instancia de registro de Harbor:

gdcloud harbor instances create INSTANCE \
  --project=PROJECT

Haz los cambios siguientes:

  • INSTANCE: el nombre de la instancia
  • PROJECT: el nombre del proyecto de GDC en el que se creará la instancia

Confianza de los nodos de clúster para las instancias de registro de Harbor

Cuando una instancia de registro de Harbor está lista, GDC configura automáticamente los nodos de los clústeres de Kubernetes compartidos y estándar de tu organización para que confíen en el certificado TLS de la instancia, que emite la autoridad de certificación raíz de confianza de tu organización. Para extraer imágenes de la instancia, no es necesario instalar la CA raíz ni cambiar la configuración del entorno de ejecución de contenedores en los nodos del clúster.

La configuración automática tiene el siguiente comportamiento:

  • Tiempo de actualización de los nodos: GDC añade la instancia a la configuración de registro privado de cada clúster y, a continuación, actualiza todos los nodos del clúster. Un nodo solo puede extraer imágenes de la instancia una vez que se haya completado la actualización en ese nodo, lo que puede tardar hasta 60 minutos en todos los nodos.
  • Clústeres nuevos y de varias zonas: GDC también configura los clústeres que creas después de que la instancia esté lista y los clústeres de otras zonas de tu organización.
  • Nombre de host de confianza: los nodos solo confían en el nombre de host de la instancia, que es la URL de la instancia sin el prefijo https://, como harbor-1-my-project.org-1.zone1.google.gdc.test. Puedes encontrar la URL de la instancia en el enlace de la instancia de la consola de GDC o en el campo status.url del resultado del comando gdcloud harbor instances describe. Usa el nombre de host de la instancia en tus referencias de imagen, como INSTANCE_HOSTNAME/HARBOR_PROJECT/IMAGE:TAG, donde HARBOR_PROJECT es el proyecto de Harbor que almacena la imagen.
  • Cliente de Docker de la estación de trabajo: la confianza automática solo se aplica a los nodos del clúster. Para enviar o extraer imágenes con Docker desde tu estación de trabajo, debes configurar tu cliente de Docker local para que confíe en la CA raíz. Para obtener más información, consulta Configurar Docker para que confíe en la CA raíz de Harbor.

Si los nodos del clúster no confían en tu instancia, consulta el artículo Solucionar errores de certificados al extraer imágenes.

Solucionar errores de certificados al extraer imágenes

Si los nodos del clúster no confían en el certificado del nombre de host de una referencia de imagen, los pods no podrán extraer la imagen. Los pods muestran el estado ErrImagePull o ImagePullBackOff, y los eventos de pod muestran un error similar al siguiente:

failed to pull and unpack image "INSTANCE_HOSTNAME/HARBOR_PROJECT/IMAGE:TAG": ... x509: certificate signed by unknown authority

Para solucionar errores de certificados, necesitas lo siguiente:

  • El rol Lector de instancias de Harbor (harbor-instance-viewer) o Administrador de instancias de Harbor (harbor-instance-admin) en el proyecto de GDC que contiene la instancia.
  • Un rol que te permite ver eventos de pods y eliminar pods en el clúster afectado:
    • En el caso de un clúster compartido, el rol Administrador de espacio de nombres (namespace-admin) en el espacio de nombres del proyecto de la carga de trabajo.
    • En el caso de un clúster estándar, el rol Desarrollador de clústeres (cluster-developer) en el proyecto que contiene el clúster.
  • Un archivo kubeconfig del clúster de Kubernetes afectado:

Para solucionar este problema, sigue estos pasos:

  1. Consulta los eventos del pod y el nodo que ejecuta el pod:

    kubectl --kubeconfig CLUSTER_KUBECONFIG \
      -n NAMESPACE describe pod POD_NAME
    

    Haz los cambios siguientes:

    • CLUSTER_KUBECONFIG: la ruta al archivo kubeconfig del clúster de Kubernetes afectado.
    • NAMESPACE: el espacio de nombres del pod. En el caso de un clúster compartido, se trata de un espacio de nombres de proyecto.
    • POD_NAME: el nombre del pod.

    En el resultado, el campo Node muestra el nodo que ejecuta el pod, y la sección Events muestra el mensaje de error y la referencia de la imagen.

  2. Comprueba que la instancia esté lista y no tenga códigos de error:

    • En la consola de GDC, comprueba que el estado de la instancia sea Listo. Aunque el estado sea Listo, usa la CLI gdcloud para comprobar si hay códigos de error.
    • Usa la CLI gdcloud para comprobar el estado de la instancia y los códigos de error:

      gdcloud harbor instances describe INSTANCE \
        --project=PROJECT
      

      Haz los cambios siguientes:

      • INSTANCE: el nombre de la instancia de registro de Harbor.
      • PROJECT: el nombre del proyecto de GDC que contiene la instancia.

      En el resultado, comprueba que la condición con type: Ready en la lista status.conditions tenga status: "True". El resultado es similar al siguiente:

      # Several lines of code are omitted here.
      status:
        conditions:
        - message: HarborInstance reconciled
          reason: Reconciled
          status: "True"
          type: Ready
        # Several lines of code are omitted here.
        url: https://harbor-1-my-project.org-1.zone1.google.gdc.test
      

    Si el estado sigue siendo En curso o muestra Desconocido o Error, o si la condición Ready no tiene status: "True", ponte en contacto con tu operador de infraestructura. Si la sección status del resultado de gdcloud harbor instances describe contiene un campo errorStatus con códigos de error, como HAAS0008, ponte en contacto con tu IO aunque la condición Ready sea True. Incluye los códigos de error y los mensajes.

  3. Verifica que la referencia de la imagen de tu carga de trabajo use el nombre de host de la instancia tal como aparece en la URL de la instancia, sin el prefijo https://. Los nodos no confían en otros nombres de la instancia, como una dirección IP. Si la referencia de la imagen usa un nombre diferente, actualiza la referencia para usar el nombre de host de la instancia y, a continuación, vuelve a desplegar la carga de trabajo.

  4. Si han pasado menos de 60 minutos desde que la instancia mostró el estado Listo o desde que creaste el clúster (lo que haya ocurrido más tarde), espera a que GDC termine de actualizar los nodos del clúster:

    • Actualizaciones parciales de nodos: si las extracciones de imágenes se realizan correctamente en algunos nodos y fallan en otros, la actualización seguirá en curso.
    • Copias de seguridad y restauraciones: las actualizaciones de nodos se pausan mientras se realiza una copia de seguridad o una restauración de la instancia. Inicia el periodo de 60 minutos después de que finalice la copia de seguridad o la restauración.
    • Clústeres nuevos o de varias zonas: en el caso de los clústeres que crees después de que la instancia esté lista y de los clústeres que se encuentren en una zona diferente a la de la instancia, el estado Listo de la instancia no indica si los nodos del clúster están actualizados.
  5. Cuando termine la actualización del nodo, verifica que tu carga de trabajo pueda extraer la imagen. Kubernetes reintenta automáticamente las extracciones de imágenes fallidas. Para volver a intentarlo inmediatamente, elimina el pod que falla para que su controlador, como un Deployment, lo vuelva a crear:

    kubectl --kubeconfig CLUSTER_KUBECONFIG \
      -n NAMESPACE delete pod POD_NAME
    

    Si ningún controlador gestiona el pod, vuelve a crearlo. Para confirmar que el problema se ha resuelto, comprueba que el nuevo pod muestre el estado Running en lugar de ErrImagePull o ImagePullBackOff:

    kubectl --kubeconfig CLUSTER_KUBECONFIG \
      -n NAMESPACE get pods
    
  6. Si el error continúa durante más de 60 minutos después de que la instancia haya mostrado el estado Listo o después de que hayas creado el clúster (lo que ocurra más tarde), ponte en contacto con tu IO. Introduce la información siguiente:

    • La organización y la zona de la instancia y del clúster afectado
    • El nombre de la instancia y el proyecto de GDC que contiene la instancia
    • El nombre del clúster de Kubernetes afectado, si es un clúster compartido o estándar y, en el caso de un clúster estándar, el proyecto que lo contiene.
    • La referencia completa de la imagen y el mensaje de error completo de los eventos del pod
    • Los nombres de los nodos en los que no se han podido extraer imágenes y si se han podido extraer en otros nodos
    • Cuándo se creó el clúster, cuándo se mostró el estado Listo de la instancia y si se estaba creando o restaurando una copia de seguridad de la instancia.
    • La sección status de la salida de gdcloud harbor instances describe, incluidos los códigos de error de errorStatus

Siguientes pasos

Cuando la instancia de registro de Harbor esté lista, podrás crear proyectos para alojar tus colecciones de imágenes o gestionar tus instancias: