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

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

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

시작하기 전에

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

필요한 역할

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

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

저장소에서 패키지 버전의 지문 검색

지문의 구조는 다음과 같습니다.

VERSION@DIRSUM_SHA256:HASH_VALUE

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

gcloud artifacts versions describe VERSION --repository=REPOSITORY --location=LOCATION --package=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을 사용하여 전달될 때 지문을 검증합니다.

패키지의 로컬 및 저장소 인스턴스가 동일한지 검증

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

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

  1. 저장소에서 패키지의 지문 보기에 설명된 대로 Artifact Registry에서 패키지의 지문을 찾습니다.

  2. 외부 패키지의 지문을 수동으로 계산합니다.

    1. 패키지에 있는 각 파일의 짧은 파일 이름과 개별 SHA256 해시를 가져옵니다.

      1. 콘솔에서 저장소 페이지를 엽니다. Google Cloud

        저장소 페이지 열기

      2. 저장소를 선택한 후 검증하려는 패키지 버전이 포함된 이미지를 선택합니다.

      3. 파일 탭을 클릭합니다.

      4. 페이지에 표시된 각 파일의 짧은 파일 이름과 SHA256 해시를 식별합니다. 짧은 파일 이름은 파일 위치 뒤에 오는 최종 문자열입니다. 예를 들어 다음 스크린샷은 Maven 저장소에 있는 패키지의 Version 5.0에 대한 6개의 파일을 보여줍니다. 각 파일 이름은 my-app-5.0으로 시작합니다. 각 파일의 해시 값은 Hashes 열 아래에 표시됩니다.

        Maven 패키지의 버전 5.0에 대한 **파일** 탭의 샘플

    2. 짧은 파일 이름으로 파일을 알파벳순으로 정렬합니다.

    3. 정렬된 각 파일 항목에 대해 해시 값과 파일 이름 사이에 공백 두 개를 추가하고 null 바이트로 끝나는 다음의 짧은 문자열로 파일 정보를 결합합니다.

      HASH_VALUE FILE_NAME/0

    4. 각 짧은 문자열을 가져와서 각 문자열 사이에 공백이나 문자가 없는 하나의 전체 시퀀스로 결합합니다.

    5. 전체 시퀀스의 SHA256 해시 값을 계산합니다. 최종 SHA256 해시 값은 외부 패키지의 dirsum_sha256입니다.

  3. 수동으로 계산한 지문과 저장소에 있는 패키지의 지문을 비교합니다. 두 지문이 동일하면 저장소에 있는 패키지 인스턴스가 수정되지 않은 것입니다.