Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Uso de registros de terceros compatibles con la caché de extracción Puedes usar las reglas de caché de extracción de Amazon ECR para sincronizar los repositorios de un registro ascendente compatible con tus repositorios privados de Amazon ECR. Para obtener más información, consulte [Sincronizar un registro ascendente](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache.html) en el *Guía del usuario de Amazon Elastic Container Registry*. La primera vez que se extrae una imagen, la caché de extracción crea el repositorio de imágenes en tu registro privado y lo mantiene sincronizado con la imagen original, siempre que las etiquetas de imagen del repositorio permanezcan mutables. HealthOmics admite la caché de extracción para los siguientes registros ascendentes: + Amazon ECR Public + Registro de imágenes de contenedores de Kubernetes + Quay + Docker Hub + Para Microsoft Azure Container Registry + GitHub Registro de contenedores + GitLab Registro de contenedores En el caso de los registros que extraen la memoria caché no es compatible, HealthOmics copia las imágenes en sus repositorios privados de Amazon ECR. Para obtener más información, consulte [Uso de registros de terceros no compatibles con la caché de extracción](containers-non-ptc-registries.md). Las ventajas de usar la caché de extracción de Amazon ECR incluyen: 1. Evita tener que migrar manualmente las imágenes de los contenedores a Amazon ECR o sincronizar las actualizaciones del repositorio de terceros. 1. Los flujos de trabajo acceden a las imágenes de contenedor sincronizadas de su repositorio privado, lo que resulta más fiable que descargar contenido en tiempo de ejecución desde un registro público. 1. Como las cachés extraíbles de Amazon ECR utilizan una estructura de URI predecible, puede mantener los URI de las imágenes anteriores en la definición de su flujo de trabajo y añadir un mapa de registro de contenedores que los resuelva en sus repositorios de caché. Para obtener más información, consulte [Paso 4: Añadir un mapa de registro de contenedores (si su flujo de trabajo usa URI ascendentes)](#ecr-ptc-registry-map). **Topics** + [Requisitos previos](#ecr-ptc-prerequisites) + [Configuración de la caché de extracción](#ecr-pull-through-configure) + [Re-running la configuración](#rerun-ecr-ptc) + [Solución de problemas: extraer la memoria caché](#ecr-ptc-troubleshooting) ## Requisitos previos Si un registro ascendente requiere autenticación, el AWS Secrets Manager el secreto debe estar en el mismo Cuenta de AWS y Region como regla de extracción de caché. Al crear la regla, pase `--credential-arn` el ARN del secreto exactamente como lo devuelve Secrets Manager, incluido el sufijo que Secrets Manager añade al nombre. El administrador de secretos **create-secret** y **describe-secret** ambas respuestas lo devuelven. Los ARN de ejemplo de este tema abrevian el nombre secreto. | Registro upstream | URL de registro | Se requiere el secreto de Secrets Manager | | --- | --- | --- | | Amazon ECR Public | `public.ecr.aws` | No | | Registro de imágenes de contenedores de Kubernetes | `registry.k8s.io` | No | | Quay | `quay.io` | No | | Docker Hub | `registry-1.docker.io` | Sí | | Para Microsoft Azure Container Registry | `{{registry-name}}.azurecr.io` | Sí | | GitHub Registro de contenedores | `ghcr.io` | Sí | | GitLab Registro de contenedores | `registry.gitlab.com` | Sí | El nombre secreto debe empezar por `ecr-pullthroughcache/`. Para conocer los demás requisitos, consulte [Almacenar las credenciales de su repositorio principal en un AWS Secrets Manager secreto](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-secret.html) en el *Guía del usuario de Amazon Elastic Container Registry*. ## Configuración de la caché de extracción Amazon ECR proporciona un registro para su Cuenta de AWS en cada región. Asegúrese de crear la configuración de Amazon ECR en la misma región en la que planea ejecutar el flujo de trabajo. Complete las siguientes tareas de configuración en orden. El paso 4 solo se aplica si la definición de flujo de trabajo usa los URI de la imagen ascendente. **Topics** + [Paso 1: Crear una regla de extracción de caché](#create-ecr-ptc) + [Paso 2: Configurar los permisos para el registro ascendente](#reg-ecr-ptc) + [Paso 3: Crear plantillas de repositorio](#repo-create-templates-ptc) + [Paso 4: Añadir un mapa de registro de contenedores (si su flujo de trabajo usa URI ascendentes)](#ecr-ptc-registry-map) + [Paso 5: Verificar la configuración de la caché de extracción](#verify-ecr-ptc) ### Paso 1: Crear una regla de extracción de caché Cree una regla de extracción de caché de Amazon ECR para cada registro ascendente que contenga imágenes que desee almacenar en caché. Una regla especifica un mapeo entre un registro ascendente y el repositorio privado de Amazon ECR. En el caso de un registro ascendente que requiera autenticación, debe proporcionar sus credenciales mediante AWS Secrets Manager. **nota** No cambies una regla de extracción de caché mientras una ejecución activa esté usando el repositorio privado. La ejecución podría fallar o, lo que es más importante, provocar que tu canalización utilice imágenes inesperadas. Para obtener más información, consulte [Crear una regla de extracción de caché](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html) en el *Guía del usuario de Amazon Elastic Container Registry*. #### Crear una regla de extracción de caché mediante la consola Para configurar la caché de extracción, siga estos pasos con la consola Amazon ECR: **Parte 1: Elegir el registro ascendente** 1. Abra la [consola de Amazon ECR](https://console.aws.amazon.com/ecr/). 1. En el panel de navegación, en **Registro privado**, ampliar **Funciones y ajustes**y, a continuación, elija **Extraiga la memoria caché**. 1. En el **Extraiga el caché** página, elige **Agregar regla**. 1. En el **Registro upstream** panel, elige el registro ascendente para sincronizarlo con tu registro privado y, a continuación, elige **Siguiente**. 1. Si el registro anterior requiere autenticación, en la página siguiente, especifique el secreto de Secrets Manager que contiene sus credenciales. Elija **Siguiente**. **Parte 2: Especificar los espacios de nombres y crear la regla** 1. En **Especifique los espacios de nombres**, en **Espacio de nombres de caché** panel, elija si desea crear los repositorios privados con un prefijo de repositorio específico o sin prefijo. Si eliges usar un prefijo, especifica el nombre del prefijo en **Prefijo del repositorio de caché**. 1. En el **Espacio de nombres Upstream** panel, elija si desea extraer de los repositorios ascendentes con un prefijo de repositorio específico o sin prefijo. Si eliges usar un prefijo, especifica el nombre del prefijo en **Prefijo del repositorio ascendente**. El **Ejemplo de espacio de nombres** El panel muestra un ejemplo de solicitud de extracción, la URL ascendente y la URL del repositorio de caché que se ha creado. 1. Elija **Siguiente**. 1. Revise la configuración y elija **Crear** para crear la regla. #### Crear una regla de extracción de caché mediante AWS CLI Utilice el Amazon ECR **create-pull-through-cache-rule** comando para crear una regla de extracción de caché. En el caso de los registros iniciales que requieren autenticación, guarde las credenciales en un secreto de Secrets Manager. En los siguientes ejemplos se muestra cómo crear una regla para cada registro ascendente compatible. ------ #### [ Amazon ECR Public ] En el siguiente ejemplo se crea una regla de caché de extracción para el registro público de Amazon ECR. Especifica un prefijo de repositorio de `ecr-public`, por lo que cada repositorio que crea la regla usa el esquema de nomenclatura `ecr-public/{{upstream-repository-name}}`. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix {{ecr-public}} \ --upstream-registry-url public.ecr.aws \ --region {{us-east-1}} ``` ------ #### [ Kubernetes container image registry ] En el siguiente ejemplo se crea una regla de extracción de caché para el registro público de Kubernetes. Especifica un prefijo de repositorio de `kubernetes`, por lo que cada repositorio que crea la regla usa el esquema de nomenclatura `kubernetes/{{upstream-repository-name}}`. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix {{kubernetes}} \ --upstream-registry-url registry.k8s.io \ --region {{us-east-1}} ``` ------ #### [ Quay ] El siguiente ejemplo crea una regla de extracción de caché para el registro público de Quay. Especifica un prefijo de repositorio de `quay`, por lo que cada repositorio que crea la regla usa el esquema de nomenclatura `quay/{{upstream-repository-name}}`. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix {{quay}} \ --upstream-registry-url quay.io \ --region {{us-east-1}} ``` ------ #### [ Docker Hub ] El siguiente ejemplo crea una regla de caché de extracción para el registro de Docker Hub. Especifica un prefijo de repositorio de `docker-hub`, por lo que cada repositorio que crea la regla usa el esquema de nomenclatura `docker-hub/{{upstream-repository-name}}`. Debe especificar el nombre de recurso de Amazon (ARN) completo del secreto que contiene las credenciales de Docker Hub. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix {{docker-hub}} \ --upstream-registry-url registry-1.docker.io \ --credential-arn arn:aws:secretsmanager:{{us-east-1}}:{{111122223333}}:secret:{{ecr-pullthroughcache/example1234}} \ --region {{us-east-1}} ``` ------ #### [ GitHub Container Registry ] El siguiente ejemplo crea una regla de extracción de caché para GitHub Registro de contenedores. Especifica un prefijo de repositorio de `github`, por lo que cada repositorio que crea la regla usa el esquema de nomenclatura `github/{{upstream-repository-name}}`. Debes especificar el nombre de recurso de Amazon (ARN) completo del secreto que contiene tu GitHub Credenciales de registro de contenedores. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix {{github}} \ --upstream-registry-url ghcr.io \ --credential-arn arn:aws:secretsmanager:{{us-east-1}}:{{111122223333}}:secret:{{ecr-pullthroughcache/example1234}} \ --region {{us-east-1}} ``` ------ #### [ Microsoft Azure Container Registry ] El siguiente ejemplo crea una regla de caché de extracción para el Microsoft Azure Container Registry. Especifica un prefijo de repositorio de `azure`, por lo que cada repositorio que crea la regla usa el esquema de nomenclatura `azure/{{upstream-repository-name}}`. Debe especificar el nombre de recurso de Amazon (ARN) completo del secreto que contiene las credenciales de Microsoft Azure Container Registry. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix {{azure}} \ --upstream-registry-url {{myregistry}}.azurecr.io \ --credential-arn arn:aws:secretsmanager:{{us-east-1}}:{{111122223333}}:secret:{{ecr-pullthroughcache/example1234}} \ --region {{us-east-1}} ``` ------ #### [ GitLab Container Registry ] El siguiente ejemplo crea una regla de extracción de caché para GitLab Registro de contenedores. Especifica un prefijo de repositorio de `gitlab`, por lo que cada repositorio que crea la regla usa el esquema de nomenclatura `gitlab/{{upstream-repository-name}}`. Debes especificar el nombre de recurso de Amazon (ARN) completo del secreto que contiene tu GitLab Credenciales de registro de contenedores. ``` aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix {{gitlab}} \ --upstream-registry-url registry.gitlab.com \ --credential-arn arn:aws:secretsmanager:{{us-east-1}}:{{111122223333}}:secret:{{ecr-pullthroughcache/example1234}} \ --region {{us-east-1}} ``` ------ Puede utilizar el **get-run-task** AWS CLI comando para recuperar información sobre la imagen del contenedor utilizada para una tarea específica: ``` aws omics get-run-task --id {{run-id}} --task-id {{task-id}} ``` El resultado incluye la siguiente información sobre la imagen del contenedor: ``` "imageDetails": { "image": "string", "imageDigest": "string", "sourceImage": "string", ... } ``` ### Paso 2: Configurar los permisos para el registro ascendente Utilice los permisos de registro para permitir HealthOmics para usar la caché de extracción y colocar las imágenes del contenedor en el registro privado de Amazon ECR. Añada una política de registro de Amazon ECR al registro que proporcione los contenedores utilizados en las ejecuciones. La siguiente política otorga el permiso para HealthOmics servicio para crear repositorios con los prefijos de caché de extracción especificados e iniciar extracciones ascendentes hacia estos repositorios. Asegúrese `Resource` cubre todos los prefijos de repositorio de caché que ha creado y establece la región y el Cuenta de AWS en cada repositorio, el ARN del registro que esté configurando, ya que una política de registro se aplica solo a su propia región y cuenta. 1. Abra la [consola de Amazon ECR](https://console.aws.amazon.com/ecr/). 1. En el panel de navegación, en **Registro privado**, ampliar **Permisos de registro**y, a continuación, elija **Generar declaración**. 1. En la parte superior derecha, elige JSON. Introduce una política similar a la siguiente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowPTCinRegPermissions", "Effect": "Allow", "Principal": { "Service": "omics.amazonaws.com" }, "Action": [ "ecr:CreateRepository", "ecr:BatchImportUpstreamImage" ], "Resource": [ "arn:aws:ecr:{{us-east-1}}:{{123456789012}}:repository/ecr-public/*", "arn:aws:ecr:{{us-east-1}}:{{123456789012}}:repository/docker-hub/*" ] } ] } ``` ------ 1. Guarde la política. Para adjuntar la política al AWS CLI en su lugar, guárdela en un archivo y, a continuación, utilice el ECR de Amazon **put-registry-policy** comando: ``` aws ecr put-registry-policy \ --policy-text file://{{registry-policy-file}}.json \ --region {{region}} ``` **importante** **put-registry-policy** reemplaza toda la política de registro. Si su registro ya tiene una política, recupérela con **get-registry-policy**, añada el HealthOmics declaración y devuelva la póliza combinada. Para obtener más información sobre las políticas de extracción de la caché de Amazon ECR, consulte [Las políticas de Amazon ECR extraen la caché](permissions-ecr.md#permissions-ecr-ptc). ### Paso 3: Crear plantillas de repositorio Para usar el almacenamiento en caché mediante extracción, en HealthOmics, el repositorio de Amazon ECR debe tener una plantilla de creación de repositorios. La plantilla define los ajustes de configuración para cuando usted o Amazon ECR creen un repositorio privado para un registro ascendente. Cada plantilla contiene un prefijo de espacio de nombres del repositorio, que Amazon ECR utiliza para hacer coincidir los nuevos repositorios con una plantilla específica. Las plantillas especifican la configuración de todos los ajustes del repositorio, incluidas las políticas de acceso basadas en los recursos, la inmutabilidad de las etiquetas, el cifrado y las políticas de ciclo de vida. Para obtener más información, consulte [Plantillas de creación de repositorios](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-creation-templates.html) en el *Guía del usuario de Amazon Elastic Container Registry*. **nota** Cree la plantilla antes de la primera ejecución que utilice el prefijo. Un prefijo sin plantilla propia y sin `ROOT` plantilla, no recibe ninguna política de repositorio, por lo que HealthOmics no puede extraer sus imágenes almacenadas en caché. Deje la mutabilidad de las etiquetas en `MUTABLE`, para que Amazon ECR pueda actualizar una imagen en caché cuando cambie la etiqueta de origen. Para los repositorios que ya existen, consulte [Actualización de los repositorios creados antes de la plantilla](#ecr-ptc-troubleshoot-template-late). Para crear una plantilla de creación de repositorios, siga estos pasos con la consola Amazon ECR: **Parte 1: Definir la plantilla** 1. Abra la [consola de Amazon ECR](https://console.aws.amazon.com/ecr/). 1. En el panel de navegación, en **Registro privado**, ampliar **Características y ajustes**y, a continuación, elija **Plantillas de creación de repositorios**. 1. Seleccione **Crear plantilla**. 1. En **Detalles de la plantilla**, elige **Extraiga la memoria caché**. 1. Elige si quieres aplicar esta plantilla a un prefijo específico o a todos los repositorios que no coincidan con otra plantilla. Si eliges **Un prefijo específico**, introduzca el valor del prefijo del espacio de nombres en **Prefijo**. Especificó este prefijo al crear la regla de extracción de caché. 1. Elija **Siguiente**. **Parte 2: Agregar la configuración de creación del repositorio** 1. En el **Agregar configuración de creación de repositorios** página, para **permisos de repositorio**, utilice una de las declaraciones de política de ejemplo o introduzca una similar a la del siguiente ejemplo: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "PTCRepoCreationTemplate", "Effect": "Allow", "Principal": { "Service": "omics.amazonaws.com" }, "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ], "Resource": "*" } ] } ``` ------ 1. (Opcional) Agregue la configuración del repositorio, como la política del ciclo de vida y las etiquetas. Amazon ECR aplica estas reglas a todas las imágenes de contenedor creadas para la caché de extracción que utilizan el prefijo especificado. 1. Elija **Siguiente**. 1. Revise la configuración y elija **Crear** para crear la plantilla. Para crear la plantilla con AWS CLI en su lugar, guarde la política de repositorio del procedimiento anterior en un archivo y, a continuación, utilice el ECR de Amazon **create-repository-creation-template** comando con `--prefix` defina el prefijo del repositorio de caché de su regla de extracción de caché. La descripción es opcional: ``` aws ecr create-repository-creation-template \ --prefix {{ecr-repository-prefix}} \ --applied-for PULL_THROUGH_CACHE \ --repository-policy file://{{repository-policy-file}}.json \ --image-tag-mutability MUTABLE \ --description "{{description}}" \ --region {{region}} ``` Si ya existe una plantilla para el prefijo, **create-repository-creation-template** falla con TemplateAlreadyExistsException. En su lugar, actualice la plantilla existente en su lugar: ``` aws ecr update-repository-creation-template \ --prefix {{ecr-repository-prefix}} \ --applied-for PULL_THROUGH_CACHE \ --repository-policy file://{{repository-policy-file}}.json \ --image-tag-mutability MUTABLE \ --region {{region}} ``` **importante** **update-repository-creation-template** reemplaza cada valor que se pasa, por lo que `--applied-for` y `--repository-policy` sobrescribe la lista y la política existentes en lugar de fusionarlas con ellas. Recupera la plantilla actual con **describe-repository-creation-templates**, combine los cambios y transfiera los valores completos. Amazon ECR está configurado, pero el HealthOmics la configuración no ha finalizado. Si la definición de su flujo de trabajo usa los URI de la imagen ascendente, continúe con [Paso 4: Añadir un mapa de registro de contenedores (si su flujo de trabajo usa URI ascendentes)](#ecr-ptc-registry-map): sin un mapa de registro de contenedores, la ejecución falla una vez iniciada. De lo contrario, siga en [Paso 5: Verificar la configuración de la caché de extracción](#verify-ecr-ptc). ### Paso 4: Añadir un mapa de registro de contenedores (si su flujo de trabajo usa URI ascendentes) Los URI de imagen de la definición de tu flujo de trabajo deciden si necesitas un mapa de registro de contenedores: | Los URI de imagen en la definición de su flujo de trabajo | Mapa de registro | | --- | --- | | Los URI ascendentes, en el formulario `{{upstream-registry-url}}/{{upstream-repository-name}}:{{tag}}` | Agrega un mapa. El mapa dice HealthOmics qué prefijo de repositorio de caché pertenece a qué registro anterior, porque HealthOmics no lee tus reglas de caché de extracción. | | Los URI privados de Amazon ECR de sus repositorios de caché, en el formulario `{{account-id}}.dkr.ecr.{{region}}.amazonaws.com/{{ecr-repository-prefix}}/{{upstream-repository-name}}:{{tag}}` | No necesita un mapa. HealthOmics usa cada URI tal como se indica. | Un nombre de imagen escrito sin un host de registro es un nombre abreviado de Docker Hub, que cuenta como un URI ascendente y necesita un mapa. Si tu definición usa ambos tipos de URI, agrega un mapa para las imágenes que usan los URI ascendentes. **importante** Con los URI ascendentes, `StartRun` tiene éxito incluso si falta el mapa o no tiene ningún mapeo para el registro ascendente de una imagen. HealthOmics valida cada imagen cuando crea la tarea que la usa, por lo que la ejecución falla una vez iniciada. En ambos casos se indica el motivo del error INVALID\_ECR\_IMAGE\_URI, y el mensaje de estado de la ejecución los distingue. En cambio, un mapeo que convierte una imagen en un repositorio de caché que no existe da ECR\_REPOSITORY\_NOT\_FOUND. Refleje su regla de extracción de caché en el mapeo: establecer `upstreamRegistryUrl` a la URL de registro anterior de la regla, `ecrRepositoryPrefix` al prefijo de su repositorio de caché, y `upstreamRepositoryPrefix` a su prefijo de repositorio anterior si la regla usa uno. Si sus repositorios de caché están en un lugar diferente Cuenta de AWS desde el flujo de trabajo, defina `ecrAccountId` a la cuenta propietaria de los repositorios de caché y agregue las políticas multicuenta que se describen en [Políticas para el acceso multicuenta a Amazon ECR](permissions-ecr.md#permissions-cross-account). `ecrAccountId` por defecto es la propia cuenta del flujo de trabajo. **nota** Para Docker Hub, defina `upstreamRegistryUrl` a `registry-1.docker.io`, el valor en [Requisitos previos](#ecr-ptc-prerequisites). HealthOmics regalos `registry-1.docker.io` y `docker.io` como el mismo host, de modo que una asignación también cubre los URI de imágenes escritos con `docker.io`. HealthOmics también amplía un nombre corto de Docker Hub antes de que coincida con la asignación: `ubuntu:22.04` se convierte `docker.io/library/ubuntu:22.04`, y `myorg/image:tag` se convierte `docker.io/myorg/image:tag`. HealthOmics inserta `library/` solo cuando el nombre de la imagen en su definición no tiene barra. El nombre expandido también determina la ruta del repositorio de la caché, por lo que `ubuntu:22.04` se resuelve en `{{ecr-repository-prefix}}/library/ubuntu:22.04` en tu registro privado. El mapa se suministra al crear el flujo de trabajo o la versión del flujo de trabajo. Para conocer el formato del mapa y las reglas que deciden qué mapeos necesita su flujo de trabajo, consulte [Mapeos de registro](containers-workflow-creation.md#ecr-pull-through-registry-mapping). Para ver los mapeos de imágenes, consulte [Mapeos de imágenes](containers-workflow-creation.md#ecr-pull-through-mapping-format). Después de añadir el mapa, continúe con [Paso 5: Verificar la configuración de la caché de extracción](#verify-ecr-ptc). ### Paso 5: Verificar la configuración de la caché de extracción Ejecute el **aws ecr** comandos de la cuenta propietaria de los repositorios de caché, porque **get-registry-policy** y **describe-repository-creation-templates** lea siempre el registro de la cuenta de llamada y ejecute el **aws omics** los comandos de la cuenta propietaria del flujo de trabajo. Usa la región en la que ejecutas tus flujos de trabajo para ambos. Las tres comprobaciones del procedimiento siguiente son independientes, por lo que debe ejecutarlas todas y recopilar todos los problemas antes de volver a solucionarlos. La comprobación del mapa de registro tras el procedimiento se aplica una vez creado el flujo de trabajo o la versión del flujo de trabajo, tal y como se describe en [Añadir contenedores privados o de terceros durante la creación del flujo de trabajo](containers-workflow-creation.md). La comprobación de principio a fin también requiere iniciar la ejecución. 1. Confirme que la regla de extracción de la memoria caché existe y que apunta al registro ascendente esperado: ``` aws ecr describe-pull-through-cache-rules \ --region {{region}} ``` Cada regla que ha creado aparece con su `ecrRepositoryPrefix` y `upstreamRegistryUrl`. También se muestra una regla que establece un prefijo de repositorio ascendente `upstreamRepositoryPrefix`, y también se muestra una regla que usa una credencial `credentialArn`; Amazon ECR omite cada uno de esos campos cuando la regla no lo establece. Un vacío `pullThroughCacheRules` la lista significa que no existe ninguna regla en esta región. Vuelva a [Paso 1: Crear una regla de extracción de caché](#create-ecr-ptc). Si la regla utiliza una credencial, confirme también que Amazon ECR puede leer el secreto e iniciar sesión en el registro inicial: ``` aws ecr validate-pull-through-cache-rule \ --ecr-repository-prefix {{ecr-repository-prefix}} \ --region {{region}} ``` La salida incluye `"isValid": true` cuando la autenticación se realiza correctamente y, de lo contrario, indica el motivo en `failure`. Si el comando falla con PullThroughCacheRuleNotFoundException, ninguna regla usa ese prefijo. ¿Un AccessDeniedException significa que la persona que llama carece de `ecr:ValidatePullThroughCacheRule` permiso, que las políticas de solo lectura no siempre incluyen, no es que la regla sea incorrecta. Para obtener más información, consulte [Validación de las reglas de extracción de caché](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-working-validating.html) en el *Guía del usuario de Amazon Elastic Container Registry*. 1. Confirme que la política de registro otorga HealthOmics acceso: ``` aws ecr get-registry-policy \ --region {{region}} ``` El `policyText` valor de la salida, que devuelve Amazon ECR JSON-escaped, debe contener la declaración de [Paso 2: Configurar los permisos para el registro ascendente](#reg-ecr-ptc), concediendo `omics.amazonaws.com` ambos `ecr:CreateRepository` y `ecr:BatchImportUpstreamImage`, de forma individual o mediante un comodín, y cubriendo todos los prefijos del repositorio de caché que haya creado. Un prefijo está cubierto por un `Resource` entrada que coincide con los repositorios de caché que contiene, como el ARN de un repositorio que termina en el prefijo seguido de `/*`, un ARN de repositorio que termina en `/*` solo, o un `Resource` de `*`. Un ARN que termina en el propio prefijo, sin `/*`, no cubre nada: el nombre de un repositorio de caché siempre tiene una ruta debajo del prefijo. Un ARN que nombra una región o Cuenta de AWS aparte del propio registro, tampoco cubre nada, como se describe en [Paso 2: Configurar los permisos para el registro ascendente](#reg-ecr-ptc). Si ninguna instrucción cubre un prefijo o si el comando falla con RegistryPolicyNotFoundException, vuelve a [Paso 2: Configurar los permisos para el registro ascendente](#reg-ecr-ptc) y asegúrese de haber guardado la política. 1. Confirme que existe una plantilla de creación de repositorios para cada prefijo de repositorio de caché. Pase todos los prefijos que creó: ``` aws ecr describe-repository-creation-templates \ --prefixes {{ecr-repository-prefix-1}} {{ecr-repository-prefix-2}} \ --region {{region}} ``` Para cada prefijo, la plantilla que Amazon ECR aplica a sus repositorios de caché (identificada en el párrafo siguiente) debe tener `PULL_THROUGH_CACHE` en `appliedFor` y un `repositoryPolicy` eso otorga `omics.amazonaws.com` las acciones de atracción de [Paso 3: Crear plantillas de repositorio](#repo-create-templates-ptc), `ecr:BatchGetImage` y `ecr:GetDownloadUrlForLayer`. Una política que no esté vacía no es suficiente: confirme el director y las acciones. Amazon ECR aplica la plantilla cuyo prefijo sea el más largo que coincida con el repositorio, o un `ROOT` plantilla si ningún prefijo coincide. Ejecute el comando sin `--prefixes` para ver todas las plantillas, porque `--prefixes` coincide exactamente con cada prefijo en lugar de hacerlo por una ruta, por lo que ni un `ROOT` ni una plantilla con un prefijo más largo aparecen en la salida filtrada. Vuelva a ese paso para cualquier prefijo cuya plantilla aplicable falte o no cumpla alguno de los requisitos. `imageTagMutability` no afecta a si HealthOmics puede extraer la imagen, pero una plantilla que la establezca en cualquier otra cosa que `MUTABLE` impide que Amazon ECR actualice una imagen en caché cuando la etiqueta ascendente se mueve, tal y como se describe en [Paso 3: Crear plantillas de repositorio](#repo-create-templates-ptc). Si existía algún repositorio de caché antes de crear la plantilla, confirme también la política de repositorio de cada uno de ellos, tal y como se describe en [Actualización de los repositorios creados antes de la plantilla](#ecr-ptc-troubleshoot-template-late). Si su definición usa los URI ascendentes, confirme el mapa de registro que agregó [Paso 4: Añadir un mapa de registro de contenedores (si su flujo de trabajo usa URI ascendentes)](#ecr-ptc-registry-map). Un mapa pertenece al flujo de trabajo o a la versión del flujo de trabajo que le suministró, así que compruebe la que utilizan sus ejecuciones: la versión que pasa por `--workflow-version-name` a **start-run**, o el flujo de trabajo si tus ejecuciones no dan nombre a ninguna. Para una ejecución que ya existe, `workflowVersionName` en el **get-run** la salida nombra su versión. Para un flujo de trabajo: ``` aws omics get-workflow \ --id {{workflow-id}} \ --region {{region}} ``` Para una versión de flujo de trabajo: ``` aws omics get-workflow-version \ --workflow-id {{workflow-id}} \ --version-name {{version-name}} \ --region {{region}} ``` Compruebe el `containerRegistryMap` valor en la salida. Si no tiene ningún mapa, la respuesta omite el campo. Confirme que `status` es `ACTIVE`: si todavía está `CREATING`, espere y vuelva a intentarlo, y si es `FAILED`, el motivo está en `statusMessage`. No puede cambiar un mapa en su lugar, así que si falta o es incorrecto, cree una nueva versión del flujo de trabajo como se describe en [Re-running la configuración](#rerun-ecr-ptc). Para confirmar de principio a fin que una ejecución usó una imagen en caché, lee el resultado de una ejecución que usa la caché. Una ejecución que ya ha finalizado funciona, incluida una que ha fallado, pero es posible que una ejecución cancelada nunca haya resuelto sus imágenes; inicia una ejecución solo si aún no tienes una: ``` aws omics get-run \ --id {{run-id}} \ --region {{region}} ``` El `resourceDigests` el campo de la salida, cuando la ejecución informa de una, registra los recursos que la ejecución ha resuelto, incluidas las imágenes del contenedor. Una entrada cuya clave es un URI privado de Amazon ECR bajo el prefijo del repositorio de caché, con un `sha256` digest como valor, confirma que la ejecución resolvió la imagen en su caché. Esta es la comprobación más rápida y funciona incluso en una ejecución en la que se ha producido un error por un motivo no relacionado. Si la ejecución se detuvo sin éxito, `failureReason` y `statusMessage` juntos le dirán si esta configuración está involucrada. Compruébelos antes de analizar las tareas de la ejecución, ya que una ejecución que produce un error en una imagen puede no generar ninguna tarea: + ECR\_REPOSITORY\_NOT\_FOUND, ECR\_IMAGE\_NOT\_FOUND o ECR\_PERMISSION\_ERROR para una URI de imagen con uno de los prefijos de tu repositorio de caché, continúa con [Solución de problemas: extraer la memoria caché](#ecr-ptc-troubleshooting). Una de las razones por las que un URI no aparece debajo de uno de tus prefijos es un problema de Amazon ECR con ese repositorio y no un problema de extracción de la caché, ya que no se le aplica ninguna regla de caché. En el caso de un repositorio que gestione usted mismo en Amazon ECR, proporcione HealthOmics acceda con una política de repositorios, tal y como se describe en [Cree una política de recursos para el repositorio de Amazon ECR](permissions-ecr.md#permissions-resource-policy). + INVALID\_ECR\_IMAGE\_URI — falta el mapa de registro, no tiene ningún mapeo para el registro anterior de la imagen, su `upstreamRepositoryPrefix` no cubre la ruta de la imagen o el URI de la imagen no es válido. Lee el mensaje de estado para distinguirlos y comprueba el URI antes de cambiar el mapa. Consulte [Paso 4: Añadir un mapa de registro de contenedores (si su flujo de trabajo usa URI ascendentes)](#ecr-ptc-registry-map). + CANNOT\_START\_CONTAINER\_ERROR o IMAGE\_VERIFICATION\_FAILURE para una URI de imagen con uno de tus prefijos: la imagen llegó a tu repositorio de caché pero la tarea no pudo usarla. Si cambiaste o volviste a crear la regla de caché, una imagen guardada en caché obsoleta puede provocar este problema; consulta [Cambiar una regla de caché mientras una ejecución está activa](#ecr-ptc-troubleshoot-rule-change). De lo contrario, el problema es la imagen almacenada en caché en sí misma, no esta configuración, y la imagen ascendente o la tarea que la utiliza es el lugar donde buscar. + Cualquier otro motivo de error, o ninguno, como indica una ejecución cancelada: la ejecución se detuvo por un motivo no relacionado con esta configuración. Para conocer los estados de ejecución y los demás motivos del error, consulte [Obtenga información sobre la carrera](getinfo-about-runs.md) y [Motivos de error de ejecución](workflows-run-errors.md). No todas las ejecuciones informan `resourceDigests`, y una ejecución que aún no ha resuelto sus imágenes no tiene ninguna entrada para ellas. Si falta el campo o la entrada, o si quieres confirmar qué imagen ha extraído una tarea individual, lista las tareas de la ejecución: ``` aws omics list-run-tasks \ --id {{run-id}} \ --region {{region}} ``` Un vacío `items` una lista de una carrera que aún está en curso significa que HealthOmics aún no ha creado las tareas, así que espera y vuelve a listarlas. Si una ejecución se detiene, significa que nunca se creó ninguna tarea: en el caso de una ejecución fallida, los motivos de error anteriores explican el motivo del error, y en una ejecución cancelada antes de empezar no tiene nada que confirmar, así que utilice una ejecución diferente. De lo contrario, recupere los detalles de la imagen de una de las tareas mediante un `taskId` de la salida anterior: ``` aws omics get-run-task \ --id {{run-id}} \ --task-id {{task-id}} \ --region {{region}} \ --query imageDetails ``` En `imageDetails`, `sourceImage` es el URI de la imagen de la definición de su flujo de trabajo, y `image` es el URI privado de Amazon ECR que obtuvo la tarea. Un `image` un valor bajo el prefijo de tu repositorio de caché, en el formato de URI privado que se muestra en [Paso 4: Añadir un mapa de registro de contenedores (si su flujo de trabajo usa URI ascendentes)](#ecr-ptc-registry-map) y posiblemente con un resumen de imagen adjunto, confirma que la tarea utilizó tu caché de extracción. `imageDetails` puede estar vacío, para una tarea que aún no ha extraído su imagen y para algunas tareas que ya han finalizado. Una tarea en la que no se han registrado detalles de imagen tampoco aparece en el registro de manifiestos de ejecución, así que comprueba otra tarea de la misma ejecución. Si ninguna tarea de una ejecución finalizada las grabó, aún puede confirmar que la imagen está en caché, tal y como se describe en [Resolver una política de registro faltante o incompleta](#ecr-ptc-troubleshoot-registry-policy). Esto confirma la configuración en lugar de la imagen extraída por una tarea en particular, ya que es posible que una ejecución anterior haya llenado la memoria caché. Una vez finalizada una ejecución, su registro de manifiestos de ejecución repite la información de esta imagen para que puedas comprobar las tareas de la ejecución de una vez en lugar de realizar una llamada **get-run-task** para cada una. En el registro de cada tarea, el campo denominado `originalImage` corresponde a `sourceImage` aquí, y `image` es el mismo valor que el anterior. Para saber dónde encontrar el registro, consulte [Monitorización HealthOmics con CloudWatch Registros](monitoring-cloudwatch-logs.md), y para ver el resto del registro de una tarea, consulte [Obtenga información sobre la carrera](getinfo-about-runs.md). Tras configurar la caché de extracción, puede crear un nuevo flujo de trabajo o una nueva versión del flujo de trabajo para usar los contenedores de los registros configurados. Para obtener más información, consulte [Añadir contenedores privados o de terceros durante la creación del flujo de trabajo](containers-workflow-creation.md). ## Re-running la configuración Puede repetir estos pasos, por ejemplo, para agregar un prefijo o corregir una política. Los comandos de creación fallan con un código de salida distinto de cero cuando el recurso ya existe, sin cambiarlo. **put-registry-policy** no falla, pero reemplaza toda la política de registro, tal y como se describe en [Paso 2: Configurar los permisos para el registro ascendente](#reg-ecr-ptc). + Regla de extracción de caché — **create-pull-through-cache-rule** falla con PullThroughCacheRuleAlreadyExistsException. Si el registro que va a agregar necesita autenticación, cree primero su secreto de Secrets Manager, tal y como se describe en [Requisitos previos](#ecr-ptc-prerequisites). + Política de permisos de registro: agregue un `Resource` entrada para cada nuevo prefijo de repositorio de caché, tal y como se describe en [Paso 2: Configurar los permisos para el registro ascendente](#reg-ecr-ptc); una política que enumere los prefijos de forma individual no cubrirá uno nuevo. Confirme la cobertura con **get-registry-policy**, tal y como se describe en [Paso 5: Verificar la configuración de la caché de extracción](#verify-ecr-ptc). + Plantilla de creación de repositorios: cree una plantilla para un prefijo de repositorio de caché que no lo tenga y actualice la plantilla existente para cambiar un prefijo que ya lo tenga, tal y como se describe en [Paso 3: Crear plantillas de repositorio](#repo-create-templates-ptc). Al ejecutar la actualización con la plantilla de otro prefijo, se sobrescribe esa plantilla. Para actualizar los repositorios que Amazon ECR ya creó, consulte [Actualización de los repositorios creados antes de la plantilla](#ecr-ptc-troubleshoot-template-late). + Mapa de registro de contenedores: el mapa se suministra al crear un flujo de trabajo o una versión del flujo de trabajo, y **update-workflow** y **update-workflow-version** no puedo cambiarlo. Antes de crear una versión, ten preparado el mapa completo: una nueva versión no hereda el mapa de la versión anterior, por lo que debes enumerar todos los mapas que el flujo de trabajo aún necesite, no solo el nuevo. **create-workflow-version** toma la versión completa y no solo el mapa, por lo que también necesitará la definición del flujo de trabajo y los demás parámetros de la versión, tal y como se describe en [Crear una versión de flujo de trabajo](workflows-version-create.md). A continuación, cree la versión con el mapa actualizado, tal y como se describe en [Paso 4: Añadir un mapa de registro de contenedores (si su flujo de trabajo usa URI ascendentes)](#ecr-ptc-registry-map), e inicie sus carreras con esa versión. Una ejecución que no nombra una versión usa la versión predeterminada del flujo de trabajo, que conserva el mapa con el que se creó, por lo que falla igual que antes. Para obtener más información, consulte [Versión de flujo de trabajo predeterminada](workflows-default-version.md). ## Solución de problemas: extraer la memoria caché Los siguientes problemas de configuración provocan un error en la ejecución cuando se utilizan contenedores de la caché de extracción. Si la definición de su flujo de trabajo usa los URI de la imagen ascendente y se produce un error en la ejecución con INVALID\_ECR\_IMAGE\_URI, comience con el mapa de registro, tal y como se describe en [Paso 4: Añadir un mapa de registro de contenedores (si su flujo de trabajo usa URI ascendentes)](#ecr-ptc-registry-map). Para conocer otros motivos por los que se produce un error de ejecución, consulte [Motivos de error de ejecución](workflows-run-errors.md). Ejecuta el **aws ecr** los comandos de esta sección en la misma cuenta que en [Paso 5: Verificar la configuración de la caché de extracción](#verify-ecr-ptc), o pasar `--registry-id {{ecr-account-id}}`. Usa los nombres de los repositorios exactamente como **describe-repositories** los devuelve: el nombre de un repositorio de caché es el prefijo del repositorio de caché seguido de la ruta del repositorio anterior, que en el caso de un nombre abreviado de Docker Hub incluye `library/` segmento descrito en [Paso 4: Añadir un mapa de registro de contenedores (si su flujo de trabajo usa URI ascendentes)](#ecr-ptc-registry-map). ### Resolver una política de registro faltante o incompleta **Síntoma**—Se produce un error al ejecutar el URI de la imagen por uno de los siguientes motivos de error: + ECR\_REPOSITORY\_NOT\_FOUND — el repositorio de caché no existe en su registro privado. + ECR\_IMAGE\_NOT\_FOUND — el repositorio de caché existe, pero la imagen nunca se importó a él. + ECR\_PERMISSION\_ERROR — Amazon ECR deniega el acceso. Si falta el repositorio de caché, el siguiente comando no devuelve ningún repositorio para el prefijo: ``` aws ecr describe-repositories \ --region {{region}} \ --query "repositories[?starts_with(repositoryName, '{{ecr-repository-prefix}}/')]" ``` Se espera un resultado vacío para un prefijo del que todavía no se ha extraído nada y no es un problema de configuración en sí mismo. Cuando se produce un error al ejecutar el URI de la imagen, la falta de un repositorio suele indicar que Amazon ECR no ha podido crearlo. Si el repositorio existe, confirme si la imagen llegó a él: ``` aws ecr describe-images \ --repository-name {{cache-repository-name}} \ --image-ids imageTag={{tag}} \ --region {{region}} ``` Una imagen devuelta significa que la etiqueta está en caché. ImageNotFoundException significa que el repositorio existe pero esa etiqueta no está en él, y RepositoryNotFoundException significa que el nombre del repositorio es incorrecto o que aún no se ha extraído el prefijo. Pase `--image-ids`: sin él, el comando informa de todas las etiquetas del repositorio, por lo que la presencia de otra etiqueta puede parecer correcta para la etiqueta que necesita la ejecución. **Causa**—La política de registro no concede HealthOmics lo que necesita: no hay ninguna política, a la política le falta una acción o su `Resource` la lista no cubre este prefijo de caché. **¿Solución?**—Agregue o corrija la política de registro tal como se describe en [Paso 2: Configurar los permisos para el registro ascendente](#reg-ecr-ptc), y confírmela tal como se describe en [Paso 5: Verificar la configuración de la caché de extracción](#verify-ecr-ptc). Si la política de registro ya cubre el prefijo del repositorio de caché, la política de registro no es el problema. Para ECR\_IMAGE\_NOT\_FOUND, cuando el repositorio existe pero la imagen nunca llegó, se produjo un error en la importación inicial: confirme la credencial de la regla con **validate-pull-through-cache-rule**, tal y como se describe en [Paso 5: Verificar la configuración de la caché de extracción](#verify-ecr-ptc). Para ECR\_PERMISSION\_ERROR en un repositorio que ya exista, continúe con [Resolver una plantilla de creación de repositorios o una política de repositorios que falta](#ecr-ptc-troubleshoot-template). Luego vuelve a iniciar la carrera. ### Resolver una plantilla de creación de repositorios o una política de repositorios que falta **Síntoma**—El repositorio de caché existe con la imagen importada y la ejecución sigue fallando con ECR\_PERMISSION\_ERROR para la URI de la imagen. **Causa**—Ninguna plantilla de creación de repositorios coincide con el prefijo del repositorio de caché, la plantilla no incluye `PULL_THROUGH_CACHE` en `appliedFor`, o la plantilla no tiene ninguna política de repositorio. Por lo tanto, el repositorio no tiene ninguna política que permita HealthOmics extraiga de él. **¿Solución?**—Cree o actualice la plantilla como se describe en [Paso 3: Crear plantillas de repositorio](#repo-create-templates-ptc). Como los repositorios ya existen, aplíqueles también la política, tal y como se describe en [Actualización de los repositorios creados antes de la plantilla](#ecr-ptc-troubleshoot-template-late). ### Actualización de los repositorios creados antes de la plantilla **Síntoma**—Ha creado o corregido la plantilla de creación del repositorio, **describe-repository-creation-templates** la muestra como correcta y la ejecución sigue fallando debido a un error de acceso a Amazon ECR para la misma imagen. Confirma la política que falta en un repositorio afectado: ``` aws ecr get-repository-policy \ --repository-name {{cache-repository-name}} \ --region {{region}} ``` La `policyText` el valor debe conceder `omics.amazonaws.com` al menos las acciones que otorga la política de repositorios de la plantilla. Si el repositorio no tiene ninguna política, el comando fallará con RepositoryPolicyNotFoundException. Si falla con RepositoryNotFoundException, el nombre del repositorio es incorrecto o el repositorio aún no existe. **Causa**—Una plantilla solo se aplica cuando Amazon ECR crea un repositorio, por lo que los repositorios creados antes de añadir la plantilla no tienen una política de repositorio para HealthOmics. **Solución**—Actualice los repositorios existentes de una de las siguientes maneras. **aviso** Al eliminar un repositorio, también se eliminan todas las imágenes almacenadas en caché y no puedes deshacerlo. No elimines un repositorio mientras una ejecución lo esté usando. + Configura la política directamente en cada repositorio existente. Guarda la política de repositorio de la plantilla en un archivo y, a continuación, ejecuta el siguiente comando para cada repositorio afectado: ``` aws ecr set-repository-policy \ --repository-name {{cache-repository-name}} \ --policy-text file://{{repository-policy-file}}.json \ --region {{region}} ``` + Elimina todos los repositorios afectados. La siguiente vez que una tarea extraiga la imagen, la recrea a partir de la plantilla, de modo que la imagen almacenada en caché no estará disponible hasta que finalice la extracción. ``` aws ecr delete-repository \ --repository-name {{cache-repository-name}} \ --force \ --region {{region}} ``` ### Cambiar una regla de caché mientras una ejecución está activa **Síntoma**—Tras cambiar o volver a crear una regla de extracción de caché, una ejecución que ya esté utilizando el repositorio afectado puede fallar con CANNOT\_START\_CONTAINER\_ERROR o IMAGE\_VERIFICATION\_FAILURE, o puedes completar usando una imagen que no esperabas. **Causa**—El prefijo del repositorio de caché ahora se resuelve en un repositorio ascendente diferente, mientras que las ejecuciones ya se extraen de los repositorios que creó la regla anterior. **Solución**—Espere a que finalicen las tiradas activas antes de cambiar la regla, como se indica en [Paso 1: Crear una regla de extracción de caché](#create-ecr-ptc) describe. Para confirmar qué imagen usó realmente una tarea, compruebe `imageDetails` en el **get-run-task** salida, como se describe en [Paso 5: Verificar la configuración de la caché de extracción](#verify-ecr-ptc). Si en una ejecución se utilizó una imagen guardada en caché obsoleta, elimínela del repositorio de caché para que en la próxima extracción se actualice desde el registro anterior.