지문을 사용하여 패키지 버전 ID 확인

아티팩트 지문을 사용하여 Artifact Registry 저장소의 패키지를 고유하게 식별할 수 있습니다.

패키지를 저장소에 푸시하면 Artifact Registry에서 해당 패키지 버전의 지문을 계산합니다. 지문은 Compute Engine 및 Cloud Build와 같은 Google Cloud시스템 간에 이동할 때 패키지가 수정되지 않았음을 검증하는 데 사용할 수 있는 암호화 방식으로 변경할 수 없는 참조입니다. 패키지의 지문을 가져온 후에는 특정 Artifact Registry API 요청 중에 패키지가 유효한지 확인하는 데 사용할 수 있습니다. 로컬 지문을 수동으로 계산하고 저장소의 지문과 비교하여 동일한 패키지의 로컬 인스턴스와 저장소 인스턴스를 검증할 수도 있습니다.

시작하기 전에

Artifact Registry API 사용 설정 및 Google Cloud CLI 설치를 포함하여 Artifact Registry를 사용 설정합니다.
(선택사항) gcloud 명령어의 기본값을 구성합니다.

필요한 역할

Artifact Registry 저장소에서 패키지 버전 지문을 보는 데 필요한 권한을 얻으려면 관리자에게 Google Cloud 프로젝트에 대한 Artifact Registry 리더 (roles/artifactregistry.reader) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

저장소에서 패키지 버전의 디지털 지문 가져오기

지문은 다음과 같은 구조를 갖습니다.

VERSION@DIRSUM_SHA256:HASH_VALUE

Artifact Registry 저장소에서 패키지 버전의 지문을 가져오려면 Google Cloud CLI에 다음을 입력합니다.

gcloud artifacts versions describe VERSION --repository=REPOSITORY --location=LOCATION --package=PACKAGE_NAME

각 항목의 의미는 다음과 같습니다.

VERSION은 패키지 버전입니다(예: 1.0543).
REPOSITORY은 평가할 패키지가 포함된 저장소입니다.
LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다. 기본 위치를 설정하는 경우 이 플래그를 생략할 수 있습니다.
PACKAGE_NAME는 패키지의 이름입니다.

응답은 다음과 같습니다.

fingerprints:
- type: DIRSUM_SHA256
  value: 7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04
name: projects/test-project/locations/us-west1/repositories/test-repo/packages/test-pkg/versions/v1
updateTime: '2025-08-15T00:03:41.809228Z'

지문의 전체 주소는 패키지 버전, 지문 유형, 해시 값 순입니다. 이 예시에서 지문 주소는 VERSION@DIRSUM_SHA256:7c07b910c6dd6df6984a5591d00ad0074fe24cd81145d2c681cdfda3b3d65a04입니다.

Artifact Registry API에서 지문을 변경할 수 없는 참조로 검증

특정 Artifact Registry API 요청은 패키지의 지문이 다음과 같이 형식이 지정된 경우 저장소의 패키지를 검증합니다.

VERSION@DIRSUM_SHA256:HASH_VALUE

예를 들어 저장소의 패키지에 첨부파일을 만들려고 합니다. 다음 명령어에서 target에 정의된 패키지는 Artifact Registry에서도 패키지의 지문을 검증하도록 형식이 지정됩니다.

  gcloud artifacts attachments create my-attachment --target='projects/test-project/locations/us-west1/repositories/test-repo/packages/test-pkg/versions/v1@dirsum_sha256:30330c6b65a26ebf1a13e1b9ded4068b4c36d72ed3b62226e3243b5bee18fd31' --attachment-type="application/vnd.in-toto+json" --attachment-namespace="mynamespace.com" --files=att.txt

제공된 지문이 현재 버전의 지문과 일치하지 않으면 Artifact Registry에서 API 요청을 거부하고 failed_precondition 오류를 표시합니다.

다음 요청은 API 라이브러리, Google Cloud CLI, curl를 사용하여 전달될 때 제공된 지문을 검증합니다.

다음 요청은 API 라이브러리와 curl를 사용하여 전달될 때 지문을 검증합니다.

ListAttachments

패키지의 로컬 인스턴스와 저장소 인스턴스가 동일한지 확인

Google Cloud 시스템 간에 이동하는 동안 패키지가 수정되지 않았는지 확인하려면 저장소 외부에서 해당 패키지 인스턴스의 지문을 수동으로 계산합니다.

지문을 수동으로 계산하려면 다음 단계를 따르세요.

저장소에서 패키지의 지문 보기에 설명된 대로 Artifact Registry에서 패키지의 지문을 찾습니다.
외부 패키지의 지문을 수동으로 계산합니다.
1. 패키지에 있는 각 파일의 짧은 파일 이름과 개별 SHA256 해시를 가져옵니다.
  1. Google Cloud 콘솔에서 저장소 페이지를 엽니다.
    
    저장소 페이지 열기
  2. 저장소를 선택한 다음 검증하려는 패키지 버전이 포함된 이미지를 선택합니다.
  3. 파일 탭을 클릭합니다.
  4. 페이지에 표시된 각 파일의 짧은 파일 이름과 SHA256 해시를 식별합니다. 짧은 파일 이름은 파일 위치 뒤에 오는 마지막 문자열입니다. 예를 들어 다음 스크린샷은 Maven 저장소에 있는 패키지의 Version 5.0 파일 6개를 보여줍니다. 각 파일 이름은 my-app-5.0로 시작합니다. 각 파일의 해시 값은 Hashes 열 아래에 표시됩니다.
2. 짧은 파일 이름의 알파벳순으로 파일을 정렬합니다.
3. 정렬된 각 파일 항목에 대해 파일 정보를 다음 단축된 문자열로 결합하고 해시 값과 파일 이름 사이에 공백 두 개를 추가하고 null 바이트로 끝납니다.
  
  HASH_VALUE FILE_NAME/0
4. 단축된 각 문자열을 가져와 각 문자열 사이에 공백이나 문자가 없는 하나의 전체 시퀀스로 결합합니다.
5. 전체 시퀀스의 SHA256 해시 값을 계산합니다. 최종 SHA256 해시 값은 외부 패키지의 dirsum_sha256입니다.
수동으로 계산한 지문과 저장소에 있는 패키지의 지문을 비교합니다. 두 지문이 동일하면 저장소의 패키지 인스턴스가 수정되지 않은 것입니다.