기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
프라이빗 워크플로용 컨테이너 이미지
HealthOmics는 Amazon ECR 프라이빗 리포지토리에서 호스팅되는 컨테이너 이미지를 지원합니다. 컨테이너 이미지를 생성하여 프라이빗 리포지토리에 업로드할 수 있습니다. Amazon ECR 프라이빗 레지스트리를 풀스루 캐시로 사용하여 업스트림 레지스트리의 콘텐츠를 동기화할 수도 있습니다.
Amazon ECR 리포지토리는 서비스를 호출하는 계정과 동일한 AWS 리전에 있어야 합니다. 소스 이미지 리포지토리가 적절한 권한을 제공하는 한 다른가 컨테이너 이미지를 소유할 AWS 계정 수 있습니다. 자세한 내용은 교차 계정 Amazon ECR 액세스에 대한 정책 단원을 참조하십시오.
실행이 시작되기 전에 액세스를 확인할 수 있도록 Amazon ECR 컨테이너 이미지 URIs를 워크플로의 파라미터로 정의하는 것이 좋습니다. 또한 리전 파라미터를 변경하여 새 리전에서 워크플로를 더 쉽게 실행할 수 있습니다.
참고
HealthOmics는 ARM 컨테이너를 지원하지 않으며 퍼블릭 리포지토리에 대한 액세스를 지원하지 않습니다.
HealthOmics가 Amazon ECR에 액세스하도록 IAM 권한을 구성하는 방법에 대한 자세한 내용은 섹션을 참조하세요HealthOmics 리소스 권한.
주제
타사 컨테이너 레지스트리와 동기화
Amazon ECR 풀스루 캐시 규칙을 사용하여 지원되는 업스트림 레지스트리의 리포지토리를 Amazon ECR 프라이빗 리포지토리와 동기화할 수 있습니다. 자세한 내용은 Amazon ECR 사용 설명서의 업스트림 레지스트리 동기화를 참조하세요.
풀스루 캐시는 캐시를 생성할 때 프라이빗 레지스트리에 이미지 리포지토리를 자동으로 생성하고 업스트림 이미지가 변경될 때 캐시된 이미지와 자동으로 동기화됩니다.
HealthOmics는 다음 업스트림 레지스트리에 대한 풀스루 캐시를 지원합니다.
Amazon ECR 퍼블릭
Kubernetes 컨테이너 이미지 레지스트리
Quay
Docker Hub
Microsoft Azure 컨테이너 레지스트리
GitHub 컨테이너 레지스트리
GitLab 컨테이너 레지스트리
HealthOmics는 업스트림 Amazon ECR 프라이빗 리포지토리에 대한 풀스루 캐시를 지원하지 않습니다.
Amazon ECR 풀스루 캐시 사용의 이점은 다음과 같습니다.
-
컨테이너 이미지를 Amazon ECR로 수동으로 마이그레이션하거나 타사 리포지토리에서 업데이트를 동기화할 필요가 없습니다.
-
워크플로는 프라이빗 리포지토리의 동기화된 컨테이너 이미지에 액세스하며, 이는 퍼블릭 레지스트리에서 런타임에 콘텐츠를 다운로드하는 것보다 더 안정적입니다.
-
Amazon ECR 풀스루 캐시는 예측 가능한 URI 구조를 사용하므로 HealthOmics 서비스는 Amazon ECR 프라이빗 URI를 업스트림 레지스트리 URI와 자동으로 매핑할 수 있습니다. 워크플로 정의에서 URI 값을 업데이트하고 바꿀 필요는 없습니다.
풀스루 캐시 구성
Amazon ECR은 각 리전 AWS 계정 에서에 대한 레지스트리를 제공합니다. 워크플로를 실행하려는 리전과 동일한 리전에서 Amazon ECR 구성을 생성해야 합니다.
다음 섹션에서는 풀스루 캐시의 구성 작업에 대해 설명합니다.
풀스루 캐시 규칙 생성
캐시하려는 이미지가 있는 각 업스트림 레지스트리에 대해 Amazon ECR 풀스루 캐시 규칙을 생성합니다. 규칙은 업스트림 레지스트리와 Amazon ECR 프라이빗 리포지토리 간의 매핑을 지정합니다.
인증이 필요한 업스트림 레지스트리의 경우 AWS Secrets Manager를 사용하여 자격 증명을 제공합니다.
참고
활성 실행이 프라이빗 리포지토리를 사용하는 동안에는 풀스루 캐시 규칙을 변경하지 마십시오. 실행이 실패하거나 더 심각하게는 예상치 못한 이미지를 사용하는 파이프라인이 발생할 수 있습니다.
자세한 내용은 Amazon Elastic Container Registry 사용 설명서의 풀스루 캐시 규칙 생성을 참조하세요.
콘솔을 사용하여 풀스루 캐시 규칙 생성
풀스루 캐시를 구성하려면 Amazon ECR 콘솔을 사용하여 다음 단계를 따릅니다.
-
Amazon ECR 콘솔 열기: https://console.aws.amazon.com/ecr
-
왼쪽 메뉴의 프라이빗 레지스트리에서 기능 및 설정을 확장한 다음 캐시 풀스루를 선택합니다.
-
풀스루 캐시 페이지에서 규칙 추가를 선택합니다.
-
업스트림 레지스트리 패널에서 프라이빗 레지스트리와 동기화할 업스트림 레지스트리를 선택한 후 다음을 선택합니다.
-
업스트림 레지스트리에 인증이 필요한 경우 보안 인증 정보가 포함된 SageMaker AI 보안 암호를 지정하는 새 페이지가 콘솔에 열립니다. 다음을 선택합니다.
-
네임스페이스 지정의 캐시 네임스페이스 패널에서 특정 리포지토리 접두사를 사용하거나 접두사 없이 프라이빗 리포지토리를 생성할지 여부를 선택합니다. 접두사를 사용하도록 선택한 경우 캐시 리포지토리 접두사에 접두사 이름을 지정합니다.
-
업스트림 네임스페이스 패널에서 특정 리포지토리 접두사를 사용하거나 접두사 없이 업스트림 리포지토리에서 가져올지 여부를 선택합니다. 접두사를 사용하도록 선택한 경우 Upstream 리포지토리 접두사에 접두사 이름을 지정합니다.
네임스페이스 예제 패널에는 풀 요청 예제, 업스트림 URL 및 생성된 캐시 리포지토리의 URL이 표시됩니다.
-
다음을 선택합니다.
-
구성을 검토하고 생성을 선택하여 규칙을 생성합니다.
자세한 내용은 풀스루 캐시 규칙 생성(AWS 관리 콘솔)을 참조하세요.
CLI를 사용하여 풀스루 캐시 규칙 생성
Amazon ECR create-pull-through-cache-rule 명령을 사용하여 풀스루 캐시 규칙을 생성합니다. 인증이 필요한 업스트림 레지스트리의 경우 Secrets Manager 보안 암호에 자격 증명을 저장합니다.
다음 섹션에서는 지원되는 각 업스트림 레지스트리의 예를 제공합니다.
다음 예제에서는 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 \ --regionus-east-1
다음 예제에서는 Kubernetes 퍼블릭 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 kubernetes
으로 지정합니다. 이렇게 하면 풀스루 캐시 규칙을 통해 생성한 각 리포지토리가 kubernetes/
의 명명 체계를 사용하게 됩니다.upstream-repository-name
aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix
kubernetes
\ --upstream-registry-url registry.k8s.io \ --regionus-east-1
다음 예제에서는 Quay 퍼블릭 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 quay
로 지정합니다. 이렇게 하면 풀스루 캐시 규칙을 통해 생성한 각 리포지토리가 quay/
의 명명 체계를 사용하게 됩니다.upstream-repository-name
aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix
quay
\ --upstream-registry-url quay.io \ --regionus-east-1
다음 예제에서는 Docker Hub 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 docker-hub
으로 지정합니다. 이렇게 하면 풀스루 캐시 규칙을 통해 생성한 각 리포지토리가 docker-hub/
의 명명 체계를 사용하게 됩니다. Docker Hub 보안 인증 정보가 포함된 보안 암호의 전체 Amazon 리소스 이름(ARN)을 지정해야 합니다.upstream-repository-name
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
\ --regionus-east-1
다음 예제에서는 GitHub 컨테이너 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 github
으로 지정합니다. 이렇게 하면 풀스루 캐시 규칙을 통해 생성한 각 리포지토리가 github/
의 명명 체계를 사용하게 됩니다. GitHub 컨테이너 레지스트리 보안 인증 정보가 포함된 보안 암호의 전체 Amazon 리소스 이름(ARN)을 지정해야 합니다.upstream-repository-name
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
\ --regionus-east-1
다음 예제에서는 Microsoft Azure 컨테이너 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 azure
으로 지정합니다. 이렇게 하면 풀스루 캐시 규칙을 통해 생성한 각 리포지토리가 azure/
의 명명 체계를 사용하게 됩니다. Microsoft Azure 컨테이너 레지스트리 보안 인증 정보가 포함된 보안 암호의 전체 Amazon 리소스 이름(ARN)을 지정해야 합니다.upstream-repository-name
aws ecr create-pull-through-cache-rule \ --ecr-repository-prefix
azure
\ --upstream-registry-urlmyregistry
.azurecr.io \ --credential-arn arn:aws:secretsmanager:us-east-1
:111122223333
:secret:ecr-pullthroughcache/example1234
\ --regionus-east-1
다음 예제에서는 GitLab 컨테이너 레지스트리에 대한 풀스루 캐시 규칙을 생성합니다. 리포지토리 접두사를 gitlab
으로 지정합니다. 이렇게 하면 풀스루 캐시 규칙을 통해 생성한 각 리포지토리가 gitlab/
의 명명 체계를 사용하게 됩니다. GitLab 컨테이너 레지스트리 보안 인증 정보가 포함된 보안 암호의 전체 Amazon 리소스 이름(ARN)을 지정해야 합니다.upstream-repository-name
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
\ --regionus-east-1
자세한 내용은 Amazon ECR 사용 설명서의 풀스루 캐시 규칙(CLI) 생성을 참조하세요.
get-run-task CLI 명령을 사용하여 특정 작업에 사용되는 컨테이너 이미지에 대한 정보를 검색할 수 있습니다.
aws omics get-run-task --id 1234567 --task-id <task_id>
출력에는 컨테이너 이미지에 대한 다음 정보가 포함됩니다.
"imageDetails": { "image": "string", "imageDigest": "string", "sourceImage": "string", ... }
업스트림 레지스트리에 대한 레지스트리 권한
레지스트리 권한을 사용하여 HealthOmics가 풀스루 캐시를 사용하고 컨테이너 이미지를 Amazon ECR 프라이빗 레지스트리로 가져올 수 있도록 허용합니다. 실행에 사용되는 컨테이너를 제공하는 레지스트리에 Amazon ECR 레지스트리 정책을 추가합니다.
다음 정책은 HealthOmics 서비스가 지정된 풀스루 캐시 접두사(들)로 리포지토리를 생성하고 이러한 리포지토리로 업스트림 풀을 시작할 수 있는 권한을 부여합니다.
-
Amazon ECR 콘솔에서 왼쪽 메뉴를 열고 프라이빗 레지스트리에서 레지스트리 권한을 확장한 다음 명령문 생성을 선택합니다.
-
오른쪽 상단에서 JSON을 선택합니다. 다음과 유사한 정책을 입력합니다.
리포지토리 생성 템플릿
HealthOmics에서 풀스루 캐싱을 사용하려면 Amazon ECR 리포지토리에 리포지토리 생성 템플릿이 있어야 합니다. 템플릿은 사용자 또는 Amazon ECR이 업스트림 레지스트리에 대한 프라이빗 리포지토리를 생성할 때에 대한 구성 설정을 정의합니다.
각 템플릿에는 Amazon ECR이 새 리포지토리를 특정 템플릿과 일치시키는 데 사용하는 리포지토리 네임스페이스 접두사가 포함되어 있습니다. 템플릿은 리소스 기반 액세스 정책, 태그 불변성, 암호화 및 수명 주기 정책을 포함한 모든 리포지토리 설정에 대한 구성을 지정합니다.
자세한 내용은 Amazon Elastic Container Registry 사용 설명서의 리포지토리 생성 템플릿을 참조하세요.
리포지토리 생성 템플릿을 생성하는 방법:
-
Amazon ECR 콘솔에서 왼쪽 메뉴를 열고 프라이빗 레지스트리에서 기능 및 설정을 확장한 다음 리포지토리 생성 템플릿을 선택합니다.
-
템플릿 생성을 선택합니다.
-
템플릿 세부 정보에서 풀스루 캐시를 선택합니다.
-
이 템플릿을 특정 접두사에 적용할지 아니면 다른 템플릿과 일치하지 않는 모든 리포지토리에 적용할지 선택합니다.
특정 접두사를 선택하는 경우 접두사에 네임스페이스 접두사 값을 입력합니다. PTC 규칙을 생성할 때이 접두사를 지정했습니다.
-
다음을 선택합니다.
-
리포지토리 생성 구성 추가 페이지에서 리포지토리 권한을 입력합니다. 샘플 정책 설명 중 하나를 사용하거나 다음 예제와 유사한 명령문을 입력합니다.
-
선택적으로 수명 주기 정책 및 태그와 같은 리포지토리 설정을 추가할 수 있습니다. Amazon ECR은 지정된 접두사를 사용하는 풀스루 캐시용으로 생성된 모든 컨테이너 이미지에 이러한 규칙을 적용합니다.
-
다음을 선택합니다.
-
구성을 검토하고 다음을 선택합니다.
워크플로 생성
새 워크플로 또는 워크플로 버전을 생성할 때 레지스트리 매핑을 검토하고 필요한 경우 업데이트합니다. 자세한 내용은 프라이빗 워크플로 생성을 참조하세요.
레지스트리 매핑
프라이빗 Amazon ECR 레지스트리의 접두사와 업스트림 레지스트리 이름 간에 매핑하도록 레지스트리 매핑을 정의합니다.
Amazon ECR 레지스트리 매핑에 대한 자세한 내용은 Amazon ECR에서 풀스루 캐시 규칙 생성을 참조하세요.
다음 예제에서는 Docker Hub, Quay 및 Amazon ECR Public에 대한 레지스트리 매핑을 보여줍니다.
{ "registryMappings": [ { "upstreamRegistryUrl": "registry-1.docker.io", "ecrRepositoryPrefix": "docker-hub" }, { "upstreamRegistryUrl": "quay.io", "ecrRepositoryPrefix": "quay" }, { "upstreamRegistryUrl": "public.ecr.aws", "ecrRepositoryPrefix": "ecr-public" } ] }
이미지 매핑
프라이빗 Amazon ECR 워크플로에 정의된 이미지 이름과 업스트림 레지스트리의 이미지 이름 간에 매핑하도록 이미지 매핑을 정의합니다.
풀스루 캐시를 지원하는 레지스트리에서 이미지 매핑을 사용할 수 있습니다. HealthOmics 않는 업스트림 레지스트리에서 이미지 매핑을 사용할 수도 있습니다. 업스트림 레지스트리를 프라이빗 리포지토리와 수동으로 동기화해야 합니다.
Amazon ECR 이미지 매핑에 대한 자세한 내용은 Amazon ECR에서 풀스루 캐시 규칙 생성을 참조하세요.
다음 예제에서는 프라이빗 Amazon ECR 이미지에서 퍼블릭 게놈 이미지 및 최신 Ubuntu 이미지로의 매핑을 보여줍니다.
{ "imageMappings": [ { "sourceImage": "public.ecr.aws/aws-genomics/broadinstitute/gatk:4.6.0.2", "destinationImage": "123456789012.dkr.ecr.us-east-1.amazonaws.com/broadinstitute/gatk:4.6.0.2" }, { "sourceImage": "ubuntu:latest", "destinationImage": "123456789012.dkr.ecr.us-east-1.amazonaws.com/custom/ubuntu:latest", } ] }
Amazon ECR 컨테이너 이미지에 대한 일반 고려 사항
-
아키텍처
HealthOmics는 x86_64 컨테이너를 지원합니다. 로컬 시스템이 Apple Mac과 같은 ARM 기반인 경우 다음과 같은 명령을 사용하여 x86_64 컨테이너 이미지를 빌드합니다.
docker build --platform amd64 -t my_tool:latest .
-
진입점 및 쉘
HealthOmics 워크플로 엔진은 워크플로 작업에 사용되는 컨테이너 이미지에 대한 명령 재정의로 bash 스크립트를 삽입합니다. 따라서 컨테이너 이미지는 bash 쉘이 기본값이 되도록 지정된 ENTRYPOINT 없이 빌드해야 합니다.
-
탑재된 경로
공유 파일 시스템은 /tmp에서 컨테이너 작업에 마운트됩니다. 이 위치의 컨테이너 이미지에 내장된 모든 데이터 또는 도구는 재정의됩니다.
워크플로 정의는 /mnt/workflow의 읽기 전용 탑재를 통해 태스크에 사용할 수 있습니다.
-
이미지 크기
최대 컨테이너 이미지 크기는 HealthOmics 워크플로 고정 크기 할당량 섹션을 참조하세요.
HealthOmics 워크플로의 환경 변수
HealthOmics는 컨테이너에서 실행되는 워크플로에 대한 정보가 있는 환경 변수를 제공합니다. 워크플로 작업의 로직에서 이러한 변수의 값을 사용할 수 있습니다.
모든 HealthOmics 워크플로 변수는 AWS_WORKFLOW_
접두사로 시작합니다. 이 접두사는 보호된 환경 변수 접두사입니다. 워크플로 컨테이너의 자체 변수에는이 접두사를 사용하지 마십시오.
HealthOmics는 다음과 같은 워크플로 환경 변수를 제공합니다.
- AWS_REGION
-
이 변수는 컨테이너가 실행 중인 리전입니다.
- AWS_WORKFLOW_RUN
-
이 변수는 현재 실행의 이름입니다.
- AWS_WORKFLOW_RUN_ID
-
이 변수는 현재 실행의 실행 식별자입니다.
- AWS_WORKFLOW_RUN_UUID
-
이 변수는 현재 실행의 실행 UUID입니다.
- AWS_WORKFLOW_TASK
-
이 변수는 현재 작업의 이름입니다.
- AWS_WORKFLOW_TASK_ID
-
이 변수는 현재 작업의 작업 식별자입니다.
- AWS_WORKFLOW_TASK_UUID
-
이 변수는 현재 작업의 작업 UUID입니다.
다음 예제에서는 각 환경 변수의 일반적인 값을 보여줍니다.
AWS Region: us-east-1 Workflow Run: arn:aws:omics:us-east-1:123456789012:run/6470304 Workflow Run ID: 6470304 Workflow Run UUID: f4d9ed47-192e-760e-f3a8-13afedbd4937 Workflow Task: arn:aws:omics:us-east-1:123456789012:task/4192063 Workflow Task ID: 4192063 Workflow Task UUID: f0c9ed49-652c-4a38-7646-60ad835e0a2e
Amazon ECR 컨테이너 이미지에서 Java 사용
워크플로 태스크가 GATK와 같은 Java 애플리케이션을 사용하는 경우 컨테이너에 대한 다음 메모리 요구 사항을 고려하세요.
-
Java 애플리케이션은 스택 메모리와 힙 메모리를 사용합니다. 기본적으로 최대 힙 메모리는 컨테이너에서 사용 가능한 총 메모리의 백분율입니다. 이 기본값은 특정 JVM 배포 및 JVM 버전에 따라 달라지므로 JVM 관련 설명서를 참조하거나 Java 명령줄 옵션(예: `-Xmx`)을 사용하여 힙 메모리 최대값을 명시적으로 설정합니다.
-
JVM 스택에는 메모리도 필요하므로 최대 힙 메모리를 컨테이너 메모리 할당의 100%로 설정하지 마세요. 메모리는 JVM 가비지 수집기 및 컨테이너에서 실행되는 기타 운영 체제 프로세스에도 필요합니다.
-
GATK와 같은 일부 Java 애플리케이션은 기본 메서드 호출 또는 메모리 매핑 파일과 같은 기타 최적화를 사용할 수 있습니다. 이러한 기법에는 JVM 최대 힙 파라미터로 제어되지 않는 "오프 힙"으로 수행되는 메모리 할당이 필요합니다.
Java 애플리케이션이 오프 힙 메모리를 할당한다는 것을 알고 있는 경우(또는 의심하는 경우) 태스크 메모리 할당에 오프 힙 메모리 요구 사항이 포함되어 있는지 확인합니다.
이러한 오프 힙 할당으로 인해 컨테이너의 메모리가 부족해지는 경우 일반적으로 JVM이이 메모리를 제어하지 않기 때문에 Java OutOfMemory 오류가 표시되지 않습니다.
Amazon ECR 컨테이너 이미지에 작업 입력 추가
워크플로 작업을 실행하는 데 필요한 모든 실행 파일, 라이브러리 및 스크립트를 작업을 실행하는 데 사용되는 Amazon ECR 이미지에 추가합니다.
작업 컨테이너 이미지 외부에 있는 스크립트, 바이너리 및 라이브러리를 사용하지 않는 것이 좋습니다. 이는 bin
디렉터리를 nf-core
워크플로 패키지의 일부로 사용하는 워크플로를 사용할 때 특히 중요합니다. 이 디렉터리는 워크플로 작업에 사용할 수 있지만 읽기 전용 디렉터리로 마운트됩니다. 이 디렉터리의 필수 리소스는 작업 이미지에 복사하여 런타임 시 또는 작업에 사용되는 컨테이너 이미지를 빌드할 때 사용할 수 있어야 합니다.
HealthOmics가 지원하는 컨테이너 이미지의 최대 크기는 HealthOmics 워크플로 고정 크기 할당량 섹션을 참조하세요. HealthOmics