View a markdown version of this page

풀스루 캐시에서 지원하는 타사 레지스트리 사용 - AWS HealthOmics
사전 조건풀스루 캐시 구성구성 재실행풀스루 캐시 문제 해결

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

풀스루 캐시에서 지원하는 타사 레지스트리 사용

Amazon ECR 풀스루 캐시 규칙을 사용하여 지원되는 업스트림 레지스트리의 리포지토리를 Amazon ECR 프라이빗 리포지토리와 동기화할 수 있습니다. 자세한 내용은 Amazon Elastic Container Registry 사용 설명서의 업스트림 레지스트리 동기화를 참조하세요.

이미지를 처음 가져올 때 풀스루 캐시는 프라이빗 레지스트리에 이미지 리포지토리를 생성하고 리포지토리의 이미지 태그가 변경 가능한 상태로 유지되는 한 업스트림 이미지와 동기화된 상태를 유지합니다.

HealthOmics는 다음 업스트림 레지스트리에 대한 풀스루 캐시를 지원합니다.

  • Amazon ECR 퍼블릭

  • Kubernetes 컨테이너 이미지 레지스트리

  • Quay

  • Docker Hub

  • Microsoft Azure 컨테이너 레지스트리

  • GitHub 컨테이너 레지스트리

  • GitLab 컨테이너 레지스트리

풀스루 캐시가 지원하지 않는 레지스트리의 경우 HealthOmics는 이미지를 Amazon ECR 프라이빗 리포지토리에 복사합니다. 자세한 내용은 풀스루 캐시에서 지원되지 않는 타사 레지스트리 사용 섹션을 참조하세요.

Amazon ECR 풀스루 캐시 사용의 이점은 다음과 같습니다.

  1. 컨테이너 이미지를 Amazon ECR로 수동으로 마이그레이션하거나 타사 리포지토리에서 업데이트를 동기화할 필요가 없습니다.

  2. 워크플로는 프라이빗 리포지토리의 동기화된 컨테이너 이미지에 액세스하며, 이는 퍼블릭 레지스트리에서 런타임에 콘텐츠를 다운로드하는 것보다 더 안정적입니다.

  3. Amazon ECR 풀스루 캐시는 예측 가능한 URI 구조를 사용하므로 워크플로 정의에 업스트림 이미지 URIs 유지하고 캐시 리포지토리에 확인하는 컨테이너 레지스트리 맵을 추가할 수 있습니다. 자세한 내용은 4단계: 컨테이너 레지스트리 맵 추가(워크플로에서 업스트림 URIs 사용하는 경우) 섹션을 참조하세요.

사전 조건

업스트림 레지스트리에 인증이 필요한 경우 보안 AWS Secrets Manager 암호는 풀스루 캐시 규칙과 동일한 AWS 계정 및 리전에 있어야 합니다. 규칙을 생성할 때 Secrets Manager가 이름--credential-arn에 추가하는 접미사를 포함하여 Secrets Manager가 반환하는 대로 보안 암호의 ARN을 정확히 전달합니다. Secrets Managercreate-secret와 describe-secret 응답 모두 이를 반환합니다. 이 주제의 예제 ARNs은 보안 암호 이름을 약어로 사용합니다.

업스트림 레지스트리 레지스트리 URL Secrets Manager 보안 암호 필요

Amazon ECR 퍼블릭

public.ecr.aws

아니요

Kubernetes 컨테이너 이미지 레지스트리

registry.k8s.io

아니요

Quay

quay.io

아니요

Docker Hub

registry-1.docker.io

예

Microsoft Azure 컨테이너 레지스트리

registry-name.azurecr.io

예

GitHub 컨테이너 레지스트리

ghcr.io

예

GitLab 컨테이너 레지스트리

registry.gitlab.com

예

보안 암호 이름은 로 시작해야 합니다ecr-pullthroughcache/. 다른 요구 사항은 Amazon Elastic Container Registry 사용 설명서의 AWS Secrets Manager 보안 암호에 업스트림 리포지토리 자격 증명 저장을 참조하세요.

풀스루 캐시 구성

Amazon ECR은 각 리전 AWS 계정 에서에 대한 레지스트리를 제공합니다. 워크플로를 실행하려는 리전과 동일한 리전에서 Amazon ECR 구성을 생성해야 합니다.

다음 구성 작업을 순서대로 완료합니다. 4단계는 워크플로 정의가 업스트림 이미지 URIs를 사용하는 경우에만 적용됩니다.

1단계: 풀스루 캐시 규칙 생성

캐시하려는 이미지가 있는 각 업스트림 레지스트리에 대해 Amazon ECR 풀스루 캐시 규칙을 생성합니다. 규칙은 업스트림 레지스트리와 Amazon ECR 프라이빗 리포지토리 간의 매핑을 지정합니다.

인증이 필요한 업스트림 레지스트리의 경우를 사용하여 자격 증명을 제공합니다 AWS Secrets Manager.

참고

활성 실행이 프라이빗 리포지토리를 사용하는 동안에는 풀스루 캐시 규칙을 변경하지 마십시오. 실행이 실패하거나 더 심각하게는 예상치 못한 이미지를 사용하는 파이프라인이 발생할 수 있습니다.

자세한 내용은 Amazon Elastic Container Registry 사용 설명서의 풀스루 캐시 규칙 생성을 참조하세요.

콘솔을 사용하여 풀스루 캐시 규칙 생성

풀스루 캐시를 구성하려면 Amazon ECR 콘솔을 사용하여 다음 단계를 따릅니다.

1부: 업스트림 레지스트리 선택

  1. Amazon ECR 콘솔을 엽니다.

  2. 탐색 창의 프라이빗 레지스트리에서 기능 및 설정을 확장한 다음 캐시 풀스루를 선택합니다.

  3. 풀스루 캐시 페이지에서 규칙 추가를 선택합니다.

  4. 업스트림 레지스트리 패널에서 프라이빗 레지스트리와 동기화할 업스트림 레지스트리를 선택한 후 다음을 선택합니다.

  5. 업스트림 레지스트리에 인증이 필요한 경우 다음 페이지에서 자격 증명이 포함된 Secrets Manager 보안 암호를 지정합니다. 다음(Next)을 선택합니다.

2부: 네임스페이스 지정 및 규칙 생성

  1. 네임스페이스 지정의 캐시 네임스페이스 패널에서 특정 리포지토리 접두사를 사용하거나 접두사 없이 프라이빗 리포지토리를 생성할지 여부를 선택합니다. 접두사를 사용하도록 선택한 경우 캐시 리포지토리 접두사에 접두사 이름을 지정합니다.

  2. 업스트림 네임스페이스 패널에서 특정 리포지토리 접두사를 사용하거나 접두사 없이 업스트림 리포지토리에서 가져올지 여부를 선택합니다. 접두사를 사용하도록 선택한 경우 Upstream 리포지토리 접두사에 접두사 이름을 지정합니다.

    네임스페이스 예제 패널에는 예제 풀 요청, 업스트림 URL 및 생성된 캐시 리포지토리의 URL이 표시됩니다.

  3. 다음(Next)을 선택합니다.

  4. 구성을 검토하고 생성을 선택하여 규칙을 생성합니다.

를 사용하여 풀스루 캐시 규칙 생성 AWS CLI

Amazon ECR create-pull-through-cache-rule 명령을 사용하여 풀스루 캐시 규칙을 생성합니다. 인증이 필요한 업스트림 레지스트리의 경우 보안 인증 정보를 Secrets Manager 보안 암호에 저장합니다.

다음 예제에서는 지원되는 각 업스트림 레지스트리에 대한 규칙을 생성하는 방법을 보여줍니다.

Amazon ECR Public

다음 예제에서는 Amazon ECR 퍼블릭 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 로 지정ecr-public하므로 규칙이 생성하는 각 리포지토리는 이름 지정 체계를 사용합니다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

다음 예제에서는 Kubernetes 퍼블릭 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 로 지정kubernetes하므로 규칙이 생성하는 각 리포지토리는 이름 지정 체계를 사용합니다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

다음 예제에서는 Quay 퍼블릭 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 로 지정quay하므로 규칙이 생성하는 각 리포지토리는 이름 지정 체계를 사용합니다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

다음 예제에서는 Docker Hub 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 로 지정docker-hub하므로 규칙이 생성하는 각 리포지토리는 이름 지정 체계를 사용합니다docker-hub/upstream-repository-name. Docker Hub 보안 인증 정보가 포함된 보안 암호의 전체 Amazon 리소스 이름(ARN)을 지정해야 합니다.

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

다음 예제에서는 GitHub 컨테이너 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 로 지정github하므로 규칙이 생성하는 각 리포지토리는 이름 지정 체계를 사용합니다github/upstream-repository-name. GitHub 컨테이너 레지스트리 보안 인증 정보가 포함된 보안 암호의 전체 Amazon 리소스 이름(ARN)을 지정해야 합니다.

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

다음 예제에서는 Microsoft Azure 컨테이너 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 로 지정azure하므로 규칙이 생성하는 각 리포지토리는 이름 지정 체계를 사용합니다azure/upstream-repository-name. Microsoft Azure 컨테이너 레지스트리 보안 인증 정보가 포함된 보안 암호의 전체 Amazon 리소스 이름(ARN)을 지정해야 합니다.

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

다음 예제에서는 GitLab 컨테이너 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 로 지정gitlab하므로 규칙이 생성하는 각 리포지토리는 이름 지정 체계를 사용합니다gitlab/upstream-repository-name. GitLab 컨테이너 레지스트리 보안 인증 정보가 포함된 보안 암호의 전체 Amazon 리소스 이름(ARN)을 지정해야 합니다.

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

get-run-task AWS CLI 명령을 사용하여 특정 작업에 사용되는 컨테이너 이미지에 대한 정보를 검색할 수 있습니다.

aws omics get-run-task --id run-id --task-id task-id

출력에는 컨테이너 이미지에 대한 다음 정보가 포함됩니다.

"imageDetails": {
    "image": "string",
    "imageDigest": "string",
    "sourceImage": "string",
    ...
}

2단계: 업스트림 레지스트리에 대한 권한 설정

레지스트리 권한을 사용하여 HealthOmics가 풀스루 캐시를 사용하고 컨테이너 이미지를 Amazon ECR 프라이빗 레지스트리로 가져올 수 있도록 허용합니다. 실행에 사용되는 컨테이너를 제공하는 Amazon ECR 레지스트리 정책을 레지스트리에 추가합니다.

다음 정책은 HealthOmics 서비스가 지정된 풀스루 캐시 접두사를 사용하여 리포지토리를 생성하고 이러한 리포지토리로 업스트림 풀을 시작할 수 있는 권한을 부여합니다.

레지스트리 정책은 자체 리전 및 계정에만 적용되므로가 생성한 모든 캐시 리포지토리 접두사를 Resource 포함하는지 확인하고 각 리포지토리 ARN AWS 계정 의 리전 및를 구성 중인 레지스트리로 설정합니다.

  1. Amazon ECR 콘솔을 엽니다.

  2. 탐색 창의 프라이빗 레지스트리에서 레지스트리 권한을 확장한 다음 명령문 생성을 선택합니다.

  3. 오른쪽 상단에서 JSON을 선택합니다. 다음과 유사한 정책을 입력합니다.

    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/*"
            ] 
        }
    ]
}

  4. 정책을 저장합니다.

AWS CLI 대신를 사용하여 정책을 연결하려면 파일에 저장한 다음 Amazon ECR put-registry-policy 명령을 사용합니다.

aws ecr put-registry-policy \
     --policy-text file://registry-policy-file.json \
     --region region
중요

put-registry-policy는 전체 레지스트리 정책을 대체합니다. 레지스트리에 이미 정책이 있는 경우를 사용하여 정책을 검색하고 HealthOmics 문을 get-registry-policy추가한 다음 결합된 정책을 다시 넣습니다.

Amazon ECR 풀스루 캐시 정책에 대한 자세한 내용은 섹션을 참조하세요Amazon ECR 풀스루 캐시에 대한 정책.

3단계: 리포지토리 템플릿 생성

HealthOmics에서 풀스루 캐싱을 사용하려면 Amazon ECR 리포지토리에 리포지토리 생성 템플릿이 있어야 합니다. 템플릿은 사용자 또는 Amazon ECR이 업스트림 레지스트리에 대한 프라이빗 리포지토리를 생성할 때에 대한 구성 설정을 정의합니다.

각 템플릿에는 Amazon ECR이 새 리포지토리를 특정 템플릿과 일치시키는 데 사용하는 리포지토리 네임스페이스 접두사가 포함되어 있습니다. 템플릿은 리소스 기반 액세스 정책, 태그 불변성, 암호화 및 수명 주기 정책을 포함한 모든 리포지토리 설정에 대한 구성을 지정합니다.

자세한 내용은 Amazon Elastic Container Registry 사용 설명서의 리포지토리 생성 템플릿을 참조하세요.

참고

접두사를 사용하는 첫 번째 실행 전에 템플릿을 생성합니다. 자체 템플릿이 없고 ROOT 템플릿이 없는 접두사는 리포지토리 정책을 가져오지 않으므로 HealthOmics는 캐시된 이미지를 가져올 수 없습니다. 업스트림 태그가 변경될 때 Amazon ECR이 캐시된 이미지를 새로 고칠 수 MUTABLE있도록 태그 변경 가능성을에 둡니다. 이미 존재하는 리포지토리는 섹션을 참조하세요템플릿 이전에 생성된 리포지토리 업데이트.

리포지토리 생성 템플릿을 생성하려면 Amazon ECR 콘솔을 사용하여 다음 단계를 따릅니다.

1부: 템플릿 정의

  1. Amazon ECR 콘솔을 엽니다.

  2. 탐색 창의 프라이빗 레지스트리에서 기능 및 설정을 확장한 다음 리포지토리 생성 템플릿을 선택합니다.

  3. 템플릿 생성을 선택합니다.

  4. 템플릿 세부 정보에서 풀스루 캐시를 선택합니다.

  5. 이 템플릿을 특정 접두사에 적용할지 아니면 다른 템플릿과 일치하지 않는 모든 리포지토리에 적용할지 선택합니다.

    특정 접두사를 선택하는 경우 접두사에 네임스페이스 접두사 값을 입력합니다. 풀스루 캐시 규칙을 생성할 때이 접두사를 지정했습니다.

  6. 다음(Next)을 선택합니다.

2부: 리포지토리 생성 구성 추가

  1. 리포지토리 생성 구성 추가 페이지의 리포지토리 권한에 샘플 정책 설명 중 하나를 사용하거나 다음 예제와 유사한 명령문을 입력합니다.

    JSON
    {
    "Version":"2012-10-17",
    "Statement": [
        {
            "Sid": "PTCRepoCreationTemplate",
            "Effect": "Allow",
            "Principal": {
                "Service": "omics.amazonaws.com"
            },
            "Action": [
                "ecr:BatchGetImage",
                "ecr:GetDownloadUrlForLayer"
            ],
            "Resource": "*"
        }
    ]
}

  2. (선택 사항) 수명 주기 정책 및 태그와 같은 리포지토리 설정을 추가합니다. Amazon ECR은 지정된 접두사를 사용하는 풀스루 캐시용으로 생성된 모든 컨테이너 이미지에 이러한 규칙을 적용합니다.

  3. 다음(Next)을 선택합니다.

  4. 구성을 검토하고 생성을 선택하여 템플릿을 생성합니다.

AWS CLI 대신를 사용하여 템플릿을 생성하려면 이전 절차의 리포지토리 정책을 파일에 저장한 다음 풀스루 캐시 규칙에서가 캐시 리포지토리 접두사로 --prefix 설정된 Amazon ECR create-repository-creation-template 명령을 사용합니다. 설명은 선택 사항입니다.

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

접두사에 대한 템플릿이 이미 있는 경우 TemplateAlreadyExistsException에서가 create-repository-creation-template 실패합니다. 대신 기존 템플릿을 업데이트합니다.

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
중요

update-repository-creation-template는 전달하는 각 값을 대체하므로 기존 목록과 정책을 병합하는 대신 --applied-for --repository-policy 덮어씁니다. 를 사용하여 현재 템플릿을 검색하고describe-repository-creation-templates, 변경 사항을 병합하고, 전체 값을 전달합니다.

Amazon ECR이 구성되었지만 HealthOmics 구성이 완료되지 않았습니다. 워크플로 정의에서 업스트림 이미지 URIs 사용하는 경우 로 계속 진행합니다4단계: 컨테이너 레지스트리 맵 추가(워크플로에서 업스트림 URIs 사용하는 경우). 컨테이너 레지스트리 맵이 없으면 실행이 시작된 후 실패합니다. 그렇지 않은 경우 5단계: 풀스루 캐시 구성 확인를 계속 진행합니다.

4단계: 컨테이너 레지스트리 맵 추가(워크플로에서 업스트림 URIs 사용하는 경우)

워크플로 정의의 이미지 URIs에 따라 컨테이너 레지스트리 맵이 필요한지 여부가 결정됩니다.

워크플로 정의의 이미지 URIs 레지스트리 맵

양식의 업스트림 URIs upstream-registry-url/upstream-repository-name:tag

맵을 추가합니다. 맵은 HealthOmics가 풀스루 캐시 규칙을 읽지 않기 때문에 어떤 캐시 리포지토리 접두사가 어떤 업스트림 레지스트리에 속하는지 HealthOmics에 알려줍니다.

캐시 리포지토리의 Amazon ECR 프라이빗 URIs, 형식 account-id.dkr.ecr.region.amazonaws.com/ecr-repository-prefix/upstream-repository-name:tag

맵이 필요하지 않습니다. HealthOmics는 지정된 대로 각 URI를 사용합니다.

레지스트리 호스트 없이 작성된 이미지 이름은 업스트림 URI로 간주되고 맵이 필요한 Docker Hub 짧은 이름입니다.

정의에서 두 종류의 URI를 모두 사용하는 경우 업스트림 URIs를 사용하는 이미지에 대한 맵을 추가합니다.

중요

업스트림 URIs를 사용하면 맵이 없거나 이미지의 업스트림 레지스트리에 대한 매핑이 없는 경우에도가 StartRun 성공합니다. HealthOmics는 이미지를 사용하는 작업을 생성할 때 각 이미지를 검증하므로 실행이 시작된 후 실패합니다. 두 경우 모두 실패 이유를 INVALID_ECR_IMAGE_URI로 지정하고 실행 상태 메시지가 이를 구분합니다. 대신 존재하지 않는 캐시 리포지토리로 이미지를 확인하는 매핑은 ECR_REPOSITORY_NOT_FOUND를 제공합니다.

매핑에서 풀스루 캐시 규칙 미러링: upstreamRegistryUrl 규칙의 업스트림 레지스트리 URL, ecrRepositoryPrefix 캐시 리포지토리 접두사, 규칙이 이를 사용하는 경우 업스트림 리포지토리 접두사upstreamRepositoryPrefix로 설정합니다.

캐시 리포지토리가 워크플로 AWS 계정 와 다른에 있는 경우 ecrAccountId를 캐시 리포지토리를 소유한 계정으로 설정하고에 설명된 교차 계정 정책을 추가합니다교차 계정 Amazon ECR 액세스 정책.는 ecrAccountId 기본적으로 워크플로의 자체 계정으로 설정됩니다.

참고

Docker Hub의 경우의 값registry-1.docker.io인 upstreamRegistryUrl로 설정합니다사전 조건. HealthOmics는 registry-1.docker.io 및를 동일한 호스트docker.io로 취급하므로 하나의 매핑은 로 작성된 이미지 URIs도 포함합니다docker.io.

또한 HealthOmics는 매핑과 일치하기 전에 짧은 Docker Hub 이름을 확장합니다. ubuntu:22.04는이 되고 docker.io/library/ubuntu:22.04myorg/image:tag는이 됩니다docker.io/myorg/image:tag. HealthOmics는 정의의 이미지 이름에 슬래시가 없는 library/ 경우에만를 삽입합니다. 확장된 이름은 캐시 리포지토리 경로도 결정하므로 프라이빗 레지스트리ecr-repository-prefix/library/ubuntu:22.04에서가 로 ubuntu:22.04 확인됩니다.

워크플로 또는 워크플로 버전을 생성할 때 맵을 제공합니다. 맵 형식과 워크플로에 필요한 매핑을 결정하는 규칙은 섹션을 참조하세요레지스트리 매핑. 이미지 매핑은 섹션을 참조하세요이미지 매핑. 맵을 추가한 후 로 계속 진행합니다5단계: 풀스루 캐시 구성 확인.

5단계: 풀스루 캐시 구성 확인

get-registry-policy 및는 describe-repository-creation-templates 항상 호출 계정의 레지스트리를 읽고 워크플로를 소유한 계정에서 aws ecr 명령을 실행하기 때문에 캐시 리포지토리를 소유한 계정에서 aws omics 명령을 실행합니다. 두 가지 모두에 대해 워크플로를 실행하는 리전을 사용합니다. 다음 절차의 세 가지 검사는 독립적이므로 문제를 수정하기 전에 모든 검사를 실행하고 모든 문제를 수집합니다. 에 설명된 대로 워크플로 또는 워크플로 버전을 생성한 후 절차 후 레지스트리 맵 검사가 적용됩니다워크플로 생성 중 프라이빗 또는 타사 컨테이너 추가. 또한 시작된 실행이 필요한 end-to-end 검사입니다.

  1. 풀스루 캐시 규칙이 존재하고 예상 업스트림 레지스트리를 가리키는지 확인합니다.

    aws ecr describe-pull-through-cache-rules \
     --region region

    생성한 각 규칙은 ecrRepositoryPrefix 및와 함께 표시됩니다upstreamRegistryUrl. 업스트림 리포지토리 접두사를 설정하는 규칙에는 도 표시되고upstreamRepositoryPrefix, 자격 증명을 사용하는 규칙에는 도 표시됩니다. 규칙이 설정하지 않으면 credentialArnAmazon ECR은 각 필드를 생략합니다. 빈 pullThroughCacheRules 목록은이 리전에 규칙이 없음을 의미합니다. 1단계: 풀스루 캐시 규칙 생성으로 돌아갑니다.

    규칙이 자격 증명을 사용하는 경우 Amazon ECR이 보안 암호를 읽고 업스트림 레지스트리에 로그인할 수 있는지도 확인합니다.

    aws ecr validate-pull-through-cache-rule \
     --ecr-repository-prefix ecr-repository-prefix \
     --region region

    출력에는 인증이 성공한 "isValid": true 시기가 포함되며, 그렇지 않으면에서 이유의 이름을 지정합니다failure. PullThroughCacheRuleNotFoundException에서 명령이 실패하면 해당 접두사를 사용하는 규칙이 없습니다. AccessDeniedException은 호출자에게 ecr:ValidatePullThroughCacheRule 권한이 없음을 의미하며, 읽기 전용 정책에는 규칙이 잘못되었다는 것이 아니라 항상 포함되지 않습니다. 자세한 내용은 Amazon Elastic Container Registry 사용 설명서의 풀스루 캐시 규칙 검증을 참조하세요.

  2. 레지스트리 정책이 HealthOmics 액세스 권한을 부여하는지 확인합니다.

    aws ecr get-registry-policy \
     --region region

    Amazon ECR이 JSON 이스케이프를 반환하는 출력의 policyText 값에는 및를 omics.amazonaws.com 모두 ecr:BatchImportUpstreamImage개별적으로 또는 와일드카드를 통해 2단계: 업스트림 레지스트리에 대한 권한 설정부여하고 생성한 모든 캐시 ecr:CreateRepository 리포지토리 접두사를 포함하는의 문이 포함되어야 합니다. 접두사는 접두사로 끝나는 리포지토리 ARN 뒤에 , /* 단독으로 끝나는 리포지토리 ARN 또는 Resource의와 같이 그 아래의 캐시 리포지/*토리와 일치하는 Resource 항목에 포함됩니다*. 가 없는 접두사 자체로 끝나는 ARN은 아무것도 /*다루지 않습니다. 캐시 리포지토리 이름에는 항상 접두사 아래에 경로가 있습니다. 이 레지스트리 자체가 AWS 계정 아닌 리전 또는의 이름을 지정하는 ARN은에 설명된 대로 아무것도 다루지 않습니다2단계: 업스트림 레지스트리에 대한 권한 설정. 접두사를 포함하는 문이 없거나 명령이 RegistryPolicyNotFoundException에서 실패하는 경우 로 돌아가서 정책을 저장했는지 2단계: 업스트림 레지스트리에 대한 권한 설정 확인합니다.

  3. 각 캐시 리포지토리 접두사에 대한 리포지토리 생성 템플릿이 있는지 확인합니다. 생성한 모든 접두사를 전달합니다.

    aws ecr describe-repository-creation-templates \
     --prefixes ecr-repository-prefix-1 ecr-repository-prefix-2 \
     --region region

    각 접두사에 대해 다음 단락에서 식별된 Amazon ECR이 캐시 리포지토리에 적용하는 템플릿은 PULL_THROUGH_CACHE에 appliedFor , 및 3단계: 리포지토리 템플릿 생성 ecr:BatchGetImage에서 omics.amazonaws.com 풀 작업을 repositoryPolicy 부여하는가 있어야 합니다ecr:GetDownloadUrlForLayer. 비어 있지 않은 정책으로는 충분하지 않습니다. 보안 주체와 작업을 확인합니다.

    Amazon ECR은 접두사가 리포지토리의 가장 긴 일치인 템플릿을 적용하거나 접두사가 일치하지 않는 경우 ROOT 템플릿을 적용합니다. 는 경로가 아닌 각 접두사를 정확히 --prefixes 일치시키므로 모든 템플릿을 보--prefixes지 않고 명령을 실행합니다. 따라서 ROOT 템플릿이나 더 긴 접두사의 템플릿은 필터링된 출력에 표시되지 않습니다. 해당 템플릿이 누락되었거나 요구 사항에 실패한 접두사에 대해 해당 단계로 돌아갑니다. imageTagMutability는 HealthOmics가 이미지를 가져올 수 있는지 여부에 영향을 주지 않지만,에 설명된 대로 업스트림 태그가 이동할 때이 템플릿을 이외의 다른 항목으로 설정하면 Amazon ECR이 캐시된 이미지 새로 고침을 MUTABLE 중지합니다3단계: 리포지토리 템플릿 생성.

    템플릿을 생성하기 전에 캐시 리포지토리가 있는 경우에 설명된 대로 각 리포지토리에 대한 리포지토리 정책도 확인합니다템플릿 이전에 생성된 리포지토리 업데이트.

정의에서 업스트림 URIs 사용하는 경우에 추가한 레지스트리 맵을 확인합니다4단계: 컨테이너 레지스트리 맵 추가(워크플로에서 업스트림 URIs 사용하는 경우). 맵은 워크플로 또는 해당 맵을 제공한 워크플로 버전에 속하므로 실행에서 사용하는 버전, 즉 --workflow-version-name에 전달하는 버전 start-run또는 실행에 이름이 지정되지 않은 경우 워크플로를 확인합니다. 이미 존재하는 실행의 경우 get-run 출력workflowVersionName에서 해당 버전의 이름을 지정합니다.

워크플로의 경우:

aws omics get-workflow \
     --id workflow-id \
     --region region

워크플로 버전의 경우:

aws omics get-workflow-version \
     --workflow-id workflow-id \
     --version-name version-name \
     --region region

출력의 containerRegistryMap 값을 확인합니다. 맵이 없는 경우 응답은 필드를 생략합니다. status가 인지 확인합니다ACTIVE. 여전히 인 경우 기CREATING다렸다가 다시 시도하고 인 경우 FAILED이유는에 있습니다statusMessage. 맵을 변경할 수 없으므로 맵이 없거나 잘못된 경우에 설명된 대로 새 워크플로 버전을 생성합니다구성 재실행.

실행에서 캐시된 이미지를 사용했는지 end-to-end로 확인하려면 캐시를 사용하는 실행의 결과를 읽습니다. 실패한 실행을 포함하여 이미 완료된 실행은 작동하지만 취소된 실행은 이미지를 해결하지 못할 수 있습니다. 아직 실행이 없는 경우에만 실행을 시작합니다.

aws omics get-run \
     --id run-id \
     --region region

출력의 resourceDigests 필드는 실행이 하나를 보고할 때 컨테이너 이미지를 포함하여 실행이 해결된 리소스를 기록합니다. 키가 캐시 리포지토리 접두사 아래의 Amazon ECR 프라이빗 URI이고 다이sha256제스트가 값으로 있는 항목은 실행이 해당 이미지를 캐시로 확인했음을 확인합니다. 이는 가장 빠른 검사이며 관련이 없는 이유로 실패한 실행에서도 작동합니다.

실행이 성공하지 않고 중지된 경우 failureReason와 statusMessage 함께이 구성이 관련되어 있는지 여부를 알려줍니다. 이미지에서 실패한 실행은 태스크를 전혀 생성하지 않을 수 있으므로 실행의 태스크를 살펴보기 전에 다음 사항을 확인하세요.

  • 캐시 리포지토리 접두사 중 하나의 이미지 URI에 대한 ECR_REPOSITORY_NOT_FOUND, ECR_IMAGE_NOT_FOUND 또는 ECR_PERMISSION_ERROR - 로 계속 진행합니다풀스루 캐시 문제 해결. 접두사 중 하나에 속하지 않는 URI의 이유 중 하나는 캐시 규칙이 적용되지 않기 때문에 풀스루 캐시 문제가 아닌 해당 리포지토리의 Amazon ECR 문제입니다. Amazon ECR에서 직접 관리하는 리포지토리의 경우에 설명된 대로 리포지토리 정책을 사용하여 HealthOmics에 액세스 권한을 부여합니다Amazon ECR 리포지토리에 대한 리소스 정책 생성.

  • INVALID_ECR_IMAGE_URI - 레지스트리 맵이 누락되었거나, 이미지의 업스트림 레지스트리에 대한 매핑이 없거나, 이미지 경로를 포함하지 upstreamRepositoryPrefix 않거나, 이미지 URI가 유효하지 않습니다. 상태 메시지를 읽고 이를 구분하여 알리고 맵을 변경하기 전에 URI를 확인합니다. 4단계: 컨테이너 레지스트리 맵 추가(워크플로에서 업스트림 URIs 사용하는 경우) 섹션을 참조하세요.

  • 접두사 중 하나 아래의 이미지 URI에 대한 CANNOT_START_CONTAINER_ERROR 또는 IMAGE_VERIFICATION_FAILURE - 이미지가 캐시 리포지토리에 도달했지만 작업이 이를 사용할 수 없습니다. 캐시 규칙을 변경하거나 다시 생성한 경우 오래된 캐시 이미지로 인해이 문제가 발생할 수 있습니다. 섹션을 참조하세요실행이 활성 상태인 동안 캐시 규칙 변경. 그렇지 않으면 캐시된 이미지 자체가이 구성이 아닌 문제이고, 이를 사용하는 업스트림 이미지 또는 작업이 찾아야 할 위치입니다.

  • 다른 모든 실패 이유 또는 취소된 실행 보고서로 전혀 표시되지 않음 -이 구성과 관련이 없는 이유로 실행이 중지되었습니다. 실행 상태 및 기타 실패 이유는 실행 정보 가져오기 및 단원을 참조하십시오실행 실패 이유.

모든 실행이를 보고하는 것은 아니며 resourceDigests이미지를 아직 확인하지 않은 실행에는 해당 항목에 대한 항목이 없습니다. 필드 또는 항목이 없거나 개별 작업이 가져온 이미지를 확인하려면 실행의 작업을 나열합니다.

aws omics list-run-tasks \
     --id run-id \
     --region region

아직 진행 중인 실행의 빈 items 목록은 HealthOmics가 아직 작업을 생성하지 않았음을 의미하므로 기다렸다가 다시 나열합니다. 중지된 실행에서는 작업이 생성되지 않았음을 의미합니다. 실패한 실행의 경우 이전 실패 이유가 이유를 설명하고, 실행이 시작되기 전에 취소된 실행에는 확인할 사항이 없으므로 다른 실행을 사용합니다. 그렇지 않으면 taskId 이전 출력의를 사용하여 작업 중 하나에 대한 이미지 세부 정보를 검색합니다.

aws omics get-run-task \
     --id run-id \
     --task-id task-id \
     --region region \
     --query imageDetails

에서 imageDetailssourceImage는 워크플로 정의의 이미지 URI이고 image는 작업이 가져온 Amazon ECR 프라이빗 URI입니다. 캐시 리포지토리 접두사 아래의 image 값으로,에 표시된 프라이빗 URI 형식4단계: 컨테이너 레지스트리 맵 추가(워크플로에서 업스트림 URIs 사용하는 경우)이며 이미지 다이제스트가 추가된 경우 작업은 풀스루 캐시를 사용했음을 확인합니다.는 아직 이미지를 가져오지 않은 작업과 이미 완료된 일부 작업의 경우 비어 있을 imageDetails 수 있습니다. 이미지 세부 정보가 기록되지 않은 작업도 실행 매니페스트 로그에 없으므로 동일한 실행의 다른 작업을 확인합니다. 완료된 실행에 기록된 작업이 없는 경우에도에 설명된 대로 이미지가 캐시되었는지 확인할 수 있습니다누락되거나 불완전한 레지스트리 정책 해결. 이전 실행에서 캐시가 채워졌을 수 있으므로 특정 작업을 가져온 이미지가 아닌 구성을 확인합니다.

실행이 완료되면 실행 매니페스트 로그가이 이미지 정보를 반복하므로 각 이미지에 get-run-task 대해를 호출하는 대신 실행의 작업을 한 번에 확인할 수 있습니다. 각 작업의 레코드에서 라는 필드는 sourceImage 여기에 originalImage 해당하며 위와 동일한 값image입니다. 로그를 찾을 수 있는 위치는 섹션을 참조하고CloudWatch Logs를 사용하여 HealthOmics 모니터링, 작업 레코드의 나머지 부분은 섹션을 참조하세요실행 정보 가져오기.

풀스루 캐시를 구성한 후 새 워크플로 또는 워크플로 버전을 생성하여 구성된 레지스트리의 컨테이너를 사용할 수 있습니다. 자세한 내용은 워크플로 생성 중 프라이빗 또는 타사 컨테이너 추가 섹션을 참조하세요.

구성 재실행

접두사를 추가하거나 정책을 수정하는 등이 단계를 반복할 수 있습니다. 생성 명령은 리소스가 이미 존재하는 경우 변경하지 않고 0이 아닌 종료 코드로 실패합니다. put-registry-policy는 실패하지 않지만에 설명된 대로 전체 레지스트리 정책을 대체합니다2단계: 업스트림 레지스트리에 대한 권한 설정.

  • 풀스루 캐시 규칙 - PullThroughCacheRuleAlreadyExistsException에서 create-pull-through-cache-rule 실패합니다. 추가하려는 레지스트리에 인증이 필요한 경우에 설명된 대로 Secrets Manager 보안 암호를 먼저 생성합니다사전 조건.

  • 레지스트리 권한 정책 -에 설명된 대로 각 새 캐시 리포지토리 접두사에 대한 Resource 항목을 추가합니다. 접두사를 개별적으로 열거하는 2단계: 업스트림 레지스트리에 대한 권한 설정정책은 새 접두사를 다루지 않습니다. 에 설명된 get-registry-policy대로를 사용하여 적용 범위를 확인합니다5단계: 풀스루 캐시 구성 확인.

  • 리포지토리 생성 템플릿 -에 설명된 대로 캐시 리포지토리 접두사가 없는 접두사에 대한 템플릿을 생성하고 기존 템플릿을 업데이트하여 이미 접두사가 있는 접두사를 변경합니다3단계: 리포지토리 템플릿 생성. 다른 접두사의 템플릿에 대해 업데이트를 실행하면 해당 템플릿을 덮어씁니다. Amazon ECR이 이미 생성한 리포지토리를 최신 상태로 유지하려면 섹션을 참조하세요템플릿 이전에 생성된 리포지토리 업데이트.

  • 컨테이너 레지스트리 맵 - 워크플로 또는 워크플로 버전을 생성할 때 맵을 제공하며 변경할 update-workflow update-workflow-version 수 없습니다. 버전을 생성하기 전에 전체 맵을 준비하세요. 새 버전은 이전 버전의 맵을 상속하지 않으므로 새 맵뿐만 아니라 워크플로에 여전히 필요한 모든 매핑을 나열합니다. create-workflow-version는 맵뿐만 아니라 전체 버전을 사용하므로에 설명된 대로 워크플로 정의와 버전의 다른 파라미터도 필요합니다워크플로 버전 생성. 그런 다음에 설명된 대로 업데이트된 맵으로 버전을 4단계: 컨테이너 레지스트리 맵 추가(워크플로에서 업스트림 URIs 사용하는 경우)생성하고 해당 버전에 대해 실행을 시작합니다. 버전의 이름을 지정하지 않는 실행은 워크플로의 기본 버전을 사용하며,이 기본 버전은 생성된 맵을 유지하므로 이전과 동일한 방식으로 실패합니다. 자세한 내용은 기본 워크플로 버전 섹션을 참조하세요.

풀스루 캐시 문제 해결

풀스루 캐시의 컨테이너를 사용할 때 다음 구성 문제로 인해 실행이 실패합니다. 워크플로 정의가 업스트림 이미지 URIs 사용하고 INVALID_ECR_IMAGE_URI로 실행이 실패하는 경우에 설명된 대로 레지스트리 맵으로 시작합니다4단계: 컨테이너 레지스트리 맵 추가(워크플로에서 업스트림 URIs 사용하는 경우). 다른 실행 실패 이유는 섹션을 참조하세요실행 실패 이유.

에서와 동일한 계정에서이 섹션의 aws ecr 명령을 실행5단계: 풀스루 캐시 구성 확인하거나를 전달합니다--registry-id ecr-account-id. 리포지토리 이름을 describe-repositories 반환하는 그대로 사용합니다. 캐시 리포지토리 이름은 캐시 리포지토리 접두사 뒤에 업스트림 리포지토리 경로이며, Docker Hub의 경우 짧은 이름에는에 설명된 library/ 세그먼트가 포함됩니다4단계: 컨테이너 레지스트리 맵 추가(워크플로에서 업스트림 URIs 사용하는 경우).

누락되거나 불완전한 레지스트리 정책 해결

증상 - 다음 실패 이유 중 하나와 함께 이미지 URI에 대한 실행이 실패합니다.

  • ECR_REPOSITORY_NOT_FOUND - 캐시 리포지토리가 프라이빗 레지스트리에 존재하지 않습니다.

  • ECR_IMAGE_NOT_FOUND - 캐시 리포지토리가 존재하지만 이미지를 가져온 적이 없습니다.

  • ECR_PERMISSION_ERROR – Amazon ECR은 액세스를 거부합니다.

캐시 리포지토리가 누락된 경우 다음 명령은 접두사에 대한 리포지토리를 반환하지 않습니다.

aws ecr describe-repositories \
     --region region \
     --query "repositories[?starts_with(repositoryName, 'ecr-repository-prefix/')]"

아직 아무것도 가져오지 않은 접두사의 빈 결과는 예상되며 그 자체로 구성 문제가 아닙니다. 이미지 URI에 대한 실행이 실패하면 일반적으로 누락된 리포지토리가 Amazon ECR이 이를 생성할 수 없음을 의미합니다. 리포지토리가 있는 경우 이미지가 리포지토리에 도달했는지 확인합니다.

aws ecr describe-images \
     --repository-name cache-repository-name \
     --image-ids imageTag=tag \
     --region region

반환된 이미지는 태그가 캐시되었음을 의미합니다. ImageNotFoundException은 리포지토리가 존재하지만 태그가 해당 리포지토리에 없음을 의미하고, RepositoryNotFoundException은 리포지토리 이름이 잘못되었거나 접두사를 통해 아직 아무것도 가져오지 않았음을 의미합니다. 전달--image-ids: 명령이 없으면 리포지토리의 모든 태그를 보고하므로 실행에 필요한 태그에 대해 다른 태그의 존재가 성공한 것처럼 보일 수 있습니다.

원인 - 레지스트리 정책은 필요한 것을 HealthOmics에 부여하지 않습니다. 즉, 정책이 없거나, 정책이 작업이 없거나, Resource 목록에이 캐시 접두사가 포함되지 않습니다.

해결 방법 -에 설명된 대로 레지스트리 정책을 추가하거나 수정하고 2단계: 업스트림 레지스트리에 대한 권한 설정에 설명된 대로 확인합니다5단계: 풀스루 캐시 구성 확인. 레지스트리 정책이 이미 캐시 리포지토리 접두사를 포함하는 경우 레지스트리 정책은 문제가 되지 않습니다. 리포지토리가 있지만 이미지가 도착하지 않은 ECR_IMAGE_NOT_FOUND의 경우 업스트림 가져오기가 실패했습니다.에 설명된 validate-pull-through-cache-rule대로를 사용하여 규칙의 자격 증명을 확인합니다5단계: 풀스루 캐시 구성 확인. 존재하는 리포지토리에 있는 ECR_PERMISSION_ERROR의 경우 로 계속 진행합니다누락된 리포지토리 생성 템플릿 또는 리포지토리 정책 해결. 그런 다음 실행을 다시 시작합니다.

누락된 리포지토리 생성 템플릿 또는 리포지토리 정책 해결

증상 - 가져온 이미지와 함께 캐시 리포지토리가 존재하고 이미지 URI에 대한 ECR_PERMISSION_ERROR에서 실행이 여전히 실패합니다.

원인 - 캐시 리포지토리 접두사와 일치하는 리포지토리 생성 템플릿이 없거나, 템플릿이 PULL_THROUGH_CACHE에 포함되지 않거나appliedFor, 템플릿에 리포지토리 정책이 없습니다. 따라서 리포지토리에는 HealthOmics가 리포지토리에서 가져올 수 있도록 허용하는 정책이 없습니다.

솔루션 -에 설명된 대로 템플릿을 생성하거나 업데이트합니다3단계: 리포지토리 템플릿 생성. 리포지토리가 이미 존재하므로에 설명된 대로 리포지토리에도 정책을 적용합니다템플릿 이전에 생성된 리포지토리 업데이트.

템플릿 이전에 생성된 리포지토리 업데이트

증상 - 리포지토리 생성 템플릿을 생성 또는 수정하고 이를 올바른 것으로 describe-repository-creation-templates 표시하며 동일한 이미지에 대한 Amazon ECR 액세스 오류와 함께 실행이 여전히 실패합니다. 영향을 받는 리포지토리에서 누락된 정책을 확인합니다.

aws ecr get-repository-policy \
     --repository-name cache-repository-name \
     --region region

policyText 값은 omics.amazonaws.com 최소한 템플릿의 리포지토리 정책이 부여하는 작업을 부여해야 합니다. 리포지토리에 정책이 전혀 없는 경우 RepositoryPolicyNotFoundException에서 명령이 실패합니다. RepositoryNotFoundException에서 실패하면 리포지토리 이름이 잘못되었거나 리포지토리가 아직 존재하지 않습니다.

원인 - 템플릿은 Amazon ECR이 리포지토리를 생성할 때만 적용되므로 템플릿을 추가하기 전에 생성된 리포지토리에는 HealthOmics에 대한 리포지토리 정책이 없습니다.

솔루션 - 다음 방법 중 하나로 기존 리포지토리를 최신 상태로 유지합니다.

주의

리포지토리를 삭제하면 캐시된 모든 이미지도 삭제되며 실행 취소할 수 없습니다. 실행에서 리포지토리를 사용하는 동안에는 리포지토리를 삭제하지 마십시오.

  • 기존 리포지토리마다 정책을 직접 설정합니다. 템플릿의 리포지토리 정책을 파일에 저장한 다음 영향을 받는 각 리포지토리에 대해 다음 명령을 실행합니다.

    aws ecr set-repository-policy \
     --repository-name cache-repository-name \
     --policy-text file://repository-policy-file.json \
     --region region

  • 영향을 받는 각 리포지토리를 삭제합니다. 풀스루 캐시는 작업에서 이미지를 가져올 때 템플릿에서 다시 생성하므로 풀이 완료될 때까지 캐시된 이미지를 사용할 수 없습니다.

    aws ecr delete-repository \
     --repository-name cache-repository-name \
     --force \
     --region region

실행이 활성 상태인 동안 캐시 규칙 변경

증상 - 풀스루 캐시 규칙을 변경하거나 다시 생성한 후 영향을 받는 리포지토리를 이미 사용하고 있는 실행은 CANNOT_START_CONTAINER_ERROR 또는 IMAGE_VERIFICATION_FAILURE로 실패하거나 예상치 못한 이미지를 사용하여 완료할 수 있습니다.

원인 - 캐시 리포지토리 접두사는 이제 다른 업스트림 리포지토리로 확인되지만 실행은 이미 이전 규칙이 생성한 리포지토리에서 가져오고 있습니다.

해결 방법 -의 설명과 같이 규칙을 변경하기 전에 활성 실행이 완료될 때까지 기다립니다1단계: 풀스루 캐시 규칙 생성. 작업이 실제로 사용한 이미지를 확인하려면 imageDetails에 설명된 대로 get-run-task 출력을 확인합니다5단계: 풀스루 캐시 구성 확인. 실행에서 오래된 캐시된 이미지를 사용한 경우 캐시 리포지토리에서 해당 이미지를 삭제하여 다음 풀이 업스트림 레지스트리에서 이미지를 새로 고칩니다.