HCP Packer 레지스트리 연결하기

JSON 및 HCL2 템플릿을 HCP Packer 레지스트리에 연결하는 방법의 개요와 HCP Packer 환경 변수의 전체 목록을 정리한 문서예요. 설정 상세와 예시는 HCP Packer 문서의 Packer Template Configuration 페이지를 참고하세요.

출처: Packer 공식 문서

본문

소개 (Introduction)

HCP Packer 레지스트리는 아티팩트 팩토리와 아티팩트 배포 사이의 간극을 메워 줘요. 개발팀과 보안팀이 중앙화된 방식으로 아티팩트를 만들고 관리하고 소비하기 위해 함께 협업할 수 있게 해줍니다.

HCP Packer 레지스트리는 아티팩트에 대한 메타데이터를 저장해요. 언제 만들어졌는지, 외부 플랫폼에서 아티팩트가 어디에 존재하는지, 그리고 빌드와 연관된 git 커밋이 있다면 무엇인지 같은 정보를 담습니다. 이 레지스트리를 사용해 Packer 빌드가 만드는 아티팩트에 대한 정보를 추적하고, 테스트 및 프로덕션 환경에 적합한 아티팩트를 명확히 지정하며, Packer와 Terraform 구성에서 사용할 올바른 아티팩트를 조회할 수 있어요.

HCP Packer는 JSON 템플릿과 HCL2 템플릿 모두에서 사용할 수 있습니다. JSON 템플릿을 사용한다면 HCP Packer 환경 변수로 시작한 뒤 가능하면 HCL로 마이그레이션하는 것을 권장해요.

요구사항 (Requirements)

HCP_PROJECT_ID 환경 변수를 사용하려면 Packer 버전 1.9.1 이상이 필요해요. 이 변수는 Packer가 HCP의 특정 프로젝트에 연결할 수 있게 해줍니다. 1.9.1보다 오래된 Packer 버전으로 multi-project 메타데이터를 보내도록 구성하면 빌드가 실패할 거예요.

HCP Packer 환경 변수

다음 환경 변수들은 템플릿을 바꾸지 않고도 Packer가 활성 레지스트리에 아티팩트 메타데이터를 푸시하도록 구성할 수 있게 해줘요. 환경 변수는 JSON 템플릿과 HCL2 템플릿 모두에서 사용할 수 있습니다. 완전한 안내와 예시는 HCP Packer 문서의 Basic Configuration With Environment Variables를 참고하세요.

HCP Packer에 연결하려면 인증 환경 변수를 설정해야 해요. 클라이언트 ID와 시크릿을 직접 설정하거나 (Packer 1.14.2 이상 버전에서는) HCP 인증서 파일을 사용할 수 있습니다.

클라이언트 ID와 시크릿의 경우 다음 환경 변수를 설정해요.

HCP_CLIENT_ID - Packer가 HCP Packer 레지스트리에 인증하는 데 사용할 수 있는 HashiCorp Cloud Platform 서비스 원칙(service principal)의 HCP 클라이언트 ID
HCP_CLIENT_SECRET - Packer가 HCP Packer 레지스트리에 인증하는 데 사용할 수 있는 HashiCorp Cloud Platform 서비스 원칙의 HCP 클라이언트 시크릿

인증서 기반 인증의 경우 유효한 HCP 인증서 파일의 위치를 HCP_CRED_FILE 환경 변수에 지정하거나, HCP SDK의 기본 위치인 ~/.config/hcp/cred_file.json에 넣으면 돼요.

Workload Identity Federation과 인증서 인증에 대한 자세한 내용은 다음 HCP 문서를 참고하세요.

HCP_PACKER_BUCKET_NAME - HCP Packer가 템플릿과 연관된 빌드의 아티팩트 메타데이터를 저장할 HCP Packer Bucket의 이름. HCP Packer는 버킷이 아직 없으면 자동으로 생성해 줘요. HCL2 템플릿에 hcp_packer_registry 블록이 포함되어 있으면, 구성에 지정된 버킷 이름은 이 환경 변수로 덮어써집니다.

메타데이터가 레지스트리로 푸시되는 방식을 제어하는 추가 환경 변수도 설정할 수 있어요.

HCP_PACKER_BUILD_FINGERPRINT - 각 버전에 할당되는 고유 식별자. 기존의 불완전한 버전과 연관된 fingerprint를 재사용하려면 이 환경 변수를 설정해야 해요. 사용법은 Version Fingerprinting을 참고하세요.
HCP_PACKER_REGISTRY - 설정되면 Packer는 그 외에 구성된 템플릿에서 HCP Packer로 아티팩트 메타데이터를 푸시하지 않아요. 허용되는 값은 [0|OFF]입니다.
HCP_ORGANIZATION_ID - 서비스 원칙에 연결된 HCP 조직의 ID. 이 환경 변수는 필수가 아니며, HCP SDK 인증 옵션과 패리티를 유지하기 위한 목적만을 위해 존재해요. 사용 방식은 향후 릴리스에서 바뀔 수 있습니다.
HCP_PROJECT_ID - 사용할 HCP 프로젝트의 ID. 서비스 원칙이 여러 프로젝트에 접근할 수 있을 때 유용한데, 기본적으로 Packer는 처음 생성된 프로젝트를 대상으로 고르기 때문이에요.

Note: 프로젝트 레벨 서비스 원칙으로 인증한다면 HCP_PROJECT_ID 환경 변수를 반드시 설정해야 해요. 그렇지 않으면 Packer가 조직의 프로젝트 목록을 가져오려다 프로젝트 레벨 서비스 원칙의 권한 부족으로 오류가 발생합니다. 이 기능은 Packer 1.9.3부터 지원되며, 그보다 오래된 버전은 프로젝트 레벨 서비스 원칙 사용을 지원하지 않아요.

HCP Packer 레지스트리 블록

기본 구성으로 Packer가 템플릿에서 유추할 수 있는 메타데이터는 빌드 이름과 빌드 fingerprint뿐이에요. HCL2 템플릿에서는 hcp_packer_registry 블록을 템플릿에 추가해서 Packer가 레지스트리로 보내는 메타데이터를 커스터마이즈하는 것을 권장합니다.

hcp_packer_registry 블록은 HCL2 Packer 템플릿에서만 사용할 수 있어요. JSON에는 이에 해당하는 PACKER_CONFIG가 없습니다.

전체 구성 인자 목록은 hcp_packer_registry를 참고하세요. 아티팩트 메타데이터를 커스터마이즈하는 방법과 예시는 HCP Packer 문서의 Custom Configuration을 참고하세요.

버전 fingerprinting

Packer는 버전과 연관된 빌드의 완료를 추적하기 위해 고유한 fingerprint를 사용해요. HCP_PACKER_BUILD_FINGERPRINT 환경 변수로 fingerprint를 수동으로 제공하지 않는 한, 기본적으로 packer build를 호출할 때마다 Packer가 자동으로 fingerprint를 생성합니다.

1.9.0 이전 버전에서는 이 fingerprint가 템플릿이 저장된 현재 HEAD의 Git SHA로 계산됐어요. Git으로 관리되지 않는 템플릿으로 빌드를 실행한다면 packer build를 호출하기 전에 HCP_PACKER_BUILD_FINGERPRINT 환경 변수를 설정해야 했습니다. Packer 1.9.0부터 fingerprint 생성은 Git에 전혀 의존하지 않고, Packer는 이제 packer build 호출마다 접두사 정렬이 가능한 고유 식별자(ULID)를 fingerprint로 생성합니다.

Fingerprint와 불완전한 버전

Packer로 템플릿을 빌드할 때는 네트워크 문제, 프로비저닝 실패, 또는 어떤 상위 오류 때문에 빌드가 성공하지 못할 가능성이 항상 있어요. 그런 경우 Packer는 불완전한 버전과 연관된 생성된 fingerprint를 출력해서, HCP_PACKER_BUILD_FINGERPRINT 환경 변수로 그 버전의 빌드를 재개할 수 있게 해줍니다. 버전은 완료로 표시되기 전까지 재개될 수 있어요. 이 환경 변수는 불완전한 버전을 재개하기 위해 필요하며, 그렇지 않으면 Packer가 빌드를 위해 새 버전을 만들게 됩니다.

자신만의 fingerprint를 언제 어떻게 설정할지에 대한 두 가지 대안이 있어요.

이 템플릿에 처음 packer build를 호출하기 전에 설정할 수 있어요. 이 경우 fingerprint는 고유해야 하며, 그렇지 않으면 Packer가 같은 fingerprint의 버전을 계속하려 시도할 거예요.
템플릿에 packer build를 호출하고, 실패하면 커맨드 출력에서 fingerprint를 가져와 이후 실행을 위해 설정할 수 있어요. 그러면 Packer가 이 버전의 빌드를 계속합니다.

첫 번째 대안은 CI 환경에 권장돼요. CI의 환경 변수를 사용해 고유하고 결정적인 fingerprint를 생성하고, 어떤 이유로든 스텝이 실패하면 이를 재사용할 수 있기 때문이에요. 이렇게 하면 매 호출마다 새 버전을 만들지 않고 같은 버전의 빌드를 계속할 수 있습니다.

두 번째 대안은 로컬 빌드에 좋아요. 빌드 환경과 직접 상호작용할 수 있으므로, 실패 시 Packer가 제공한 fingerprint를 설정해 버전의 빌드를 계속할지 직접 결정할 수 있기 때문입니다.

모든 경우에서 버전은 아직 완료되지 않은 경우에만 계속될 수 있다는 점을 유의하세요. 버전이 완료되면 수정할 수 없고 새로 만들어야 합니다.