플러그인 설치

플러그인 설치 (Install Plugins)

참고

2025년 8월 1일부터 많은 공식 HashiCorp 관리 Packer 플러그인의 소스가 GitHub releases에서 공식 HashiCorp 릴리스 사이트인 releases.hashicorp.com으로 이동해요. 자세한 내용은 Install HashiCorp-maintained plugins 를 참고하세요.

이 문서는 Packer용 외부 플러그인을 설치하는 방법을 설명해요. 플러그인에 대한 추가 정보는 Packer Plugins Overview 를 참고하세요.

출처: Packer 공식 문서

본문

Overview (개요)

Packer 템플릿에 하나 이상의 필수 플러그인을 지정하고 초기화 커맨드를 실행해요. 초기화 중에 Packer는 호스트 운영체제의 버전 제약과 일치하는 템플릿에 지정된 플러그인을 소스 저장소에서 조회해요. Packer는 템플릿에 지정된 플러그인과 기타 의존성을 다운로드해 설치해요.

플러그인을 배포하는 GitHub의 원격 프로젝트나 다른 호스트를 지정해서 Packer가 거기서 플러그인을 설치하게 할 수 있어요. 원격 소스에서 플러그인을 설치하는 방법에 대한 추가 정보는 Requirements 를 참고하세요.

Packer 템플릿을 실행하면 Packer는 먼저 템플릿에 지정된 버전 요구 사항과 일치하는 설치된 플러그인이 디렉터리에 있는지 확인해요. 적합한 버전의 플러그인이 설치되어 있지 않으면 Packer는 오류를 출력해요. Packer는 source 구성에서 필요한 버전을 다운로드해요.

Manual installation method (수동 설치 방법)

HCL 템플릿 파일에 플러그인을 지정할 수 없다면 플러그인을 수동으로 설치할 수 있어요. 플러그인이 아직 개발 중이라면 수동 플러그인 설치 방법을 사용해야 할 수 있어요.

packer plugins install 커맨드로 플러그인을 수동 설치해요. 로컬 또는 원격 플러그인 소스를 지정하고, Packer 빌드 중에 플러그인을 로드하는 데 필요한 SHA256SUM 파일을 생성하기 위해 바이너리 경로를 포함해요. 원격 소스에서 플러그인을 설치하는 방법에 대한 추가 정보는 Requirements 를 참고하세요.

참고로 Packer는 템플릿으로 아티팩트를 빌드할 때 플러그인 설치 디렉터리를 템플릿의 required_plugins 블록과 대조해 확인해요. 수동으로 설치된 템플릿에 지정된 플러그인도 템플릿에 설정된 버전 제약을 지켜야 해요.

Installation directory (설치 디렉터리)

기본적으로 Packer는 Unix에서 $HOME/.config/packer/plugins 디렉터리에, Windows에서는 %APPDATA%\packer.d\plugins 에 플러그인을 설치해요. 하지만 PACKER_PLUGIN_PATH 환경 변수로 다른 디렉터리를 지정할 수 있어요.

참고

플러그인 설치는 TMPDIR 아래의 임시 파일 접근이 필요해요. 시스템의 임시 디렉터리가 쓰기 불가하거나 실행 불가하면 TMPDIR를 사용해 Packer가 사용하는 임시 파일 저장소의 위치를 덮어써요. 추가 정보는 Packer configuration reference 를 참고하세요.

Requirements (요구 사항)

GitHub에서 플러그인을 설치하려면 플러그인이 다음 요구 사항을 충족해야 해요.

저장소 이름이 packer-plugin-<name> 이어야 해요.
프로젝트에 다음 형식의 시맨틱 버전 태그가 있어야 해요: v<major>.<minor>.<patch>.
태그에 연결된 릴리스에 릴리스에 어떤 파일이 있는지 나타내는 shasums 파일이 있어야 해요.

github.com 이 아닌 다른 호스트에서 플러그인을 설치하려면, 해당 호스트가 Host your own plugin source 에 설명된 디렉터리 구조로 HTTPS를 통해 플러그인 파일을 제공해야 해요.

GitHub API token (GitHub API 토큰)

GitHub의 공개 API는 단일 IP 주소에서 시간당 인증되지 않은 요청 수를 제한해요. 추가 정보는 GitHub rate limits 문서를 참고하세요.

요청 속도 제한을 초과할 것으로 예상된다면 GitHub API 토큰을 사용해 요청을 인증하고 속도 제한을 넘을 수 있어요. CI(지속적 통합) 서버에서 Packer를 실행할 때는 잠재적인 속도 제한 오류를 피하기 위해 GitHub API 토큰을 설정할 것을 권장해요. 설정 방법은 Authenticate requests to the GitHub API 를 참고하세요.

Install a plugin (플러그인 설치)

Packer 템플릿 파일에서 packer 블록에 required_plugins 블록을 추가해요.
플러그인의 이름과 version, source 파라미터를 지정해요. 올바른 버전 제약 문자열을 설정하는 것은 빌드 재현성(reproducibility)을 위해 플러그인 버전을 고정(pinning)하는 데 중요해요. 추가 정보는 packer 블록 구성 참조를 참고하세요.

다음 예시는 Packer가 happycloud 라는 플러그인을 설치하도록 구성해요. 템플릿이 초기화되면 Packer는 GitHub에서 플러그인 버전 2.7.0 이상을 다운로드해요.

packer {
  required_plugins {
    happycloud = {
      version = ">= 2.7.0"
      source = "github.com/hashicorp/happycloud"
    }
  }
}

packer init 커맨드를 실행해요. Packer는 설치된 모든 플러그인을 나열한 다음, required_plugins 블록에 지정된 버전 제약과 일치하는 최신 플러그인 버전을 설치해요. 추가 정보는 init 커맨드 참조를 참고하세요.

Install HashiCorp-maintained plugins (HashiCorp 관리 플러그인 설치)

HashiCorp는 이제 다음 공식 HashiCorp 관리 플러그인을 HashiCorp 릴리스 사이트를 통해 제공해요.

이 플러그인들에는 다음이 포함돼요.

Amazon
Ansible
Azure
Docker
Google Cloud Platform
QEMU
Vagrant
VirtualBox

Packer 1.14.0부터 Packer는 이 플러그인을 새 릴리스 소스에서 자동으로 설치하며, Packer 템플릿을 변경할 필요가 없어요. 이 플러그인들의 업데이트를 계속 자동으로 받으려면 Packer 1.14.0 이상으로 업그레이드해야 해요. Packer 버전을 업그레이드할 수 없다면 이 플러그인들의 새 버전을 수동으로 설치할 수 있어요. 자세한 내용은 Manually install plugins using the CLI 를 참고하세요.

Host your own plugin source (자체 플러그인 소스 호스팅)

내부 미러나 아티팩트 저장소처럼 관리하는 인프라에서 플러그인을 설치할 수 있어요. 플러그인의 source 주소에 호스트와 경로를 지정해요. 예를 들어 plugins.example.com/mirror/hashicorp/happycloud 처럼요. 호스트는 HTTPS를 통해 소스의 경로 아래에 다음 디렉터리 구조를 제공해야 해요.

packer-plugin-happycloud/index.json
packer-plugin-happycloud/<version>/packer-plugin-happycloud_<version>_SHA256SUMS
packer-plugin-happycloud/<version>/<the zip files listed in the SHA256SUMS file>

이것은 releases.hashicorp.com이 제공하는 것과 같은 디렉터리 구조예요. Packer는 index.json 을 가져와 사용 가능한 버전을 발견하고, 템플릿의 제약과 일치하는 버전을 선택한 뒤, 호스트 플랫폼용 플러그인 zip을 다운로드해 해당 버전의 SHA256SUMS 파일과 대조 검증해요.

버전 디렉터리 이름에는 v 접두사가 포함되지 않아요. 버전 디렉터리의 zip 파일 이름에 플러그인 프로토콜 버전이 포함되지 않는 경우(예: packer-plugin-happycloud_1.0.0_linux_amd64.zip), 디렉터리에는 releases.hashicorp.com에 게시된 것과 같은 버전의 packer-plugin-happycloud_1.0.0_manifest.json 파일도 포함해야 해요. 매니페스트는 파일 이름에서 생략된 프로토콜 버전을 제공해요.

Mirror a plugin from releases.hashicorp.com (releases.hashicorp.com에서 플러그인 미러링)

예를 들어 wget --mirror 또는 rsync 로 releases.hashicorp.com에서 플러그인의 디렉터리 트리를 수정 없이 복사해요. SHA256SUMS 파일, 서명, 각 버전의 manifest.json 을 포함한 모든 검증 아티팩트는 HashiCorp가 게시한 파일과 바이트 단위로 동일하게 유지돼요.

Mirror a plugin published as GitHub release assets (GitHub 릴리스 자산으로 게시된 플러그인 미러링)

제공하려는 플러그인의 각 버전에 대해 다음 단계를 완료해요.

v 접두사가 없는 버전 디렉터리를 만들어요. 예: packer-plugin-happycloud/1.0.0/.
GitHub 릴리스의 zip 파일을 디렉터리로 복사해요.
릴리스의 SHA256SUMS 파일을 디렉터리로 복사하고, 파일 이름에서 버전의 v 접두사를 제거해요. 예를 들어 packer-plugin-happycloud_v1.0.0_SHA256SUMS 는 packer-plugin-happycloud_1.0.0_SHA256SUMS 가 돼요. 파일 내용은 수정하지 마세요.
버전을 플러그인의 index.json 파일에 추가해요. 버전 키만 필요해요.

{
  "versions": {
    "1.0.0": {},
    "1.0.1": {}
  }
}

GitHub 릴리스 자산 이름에는 플러그인 프로토콜 버전이 포함되므로, 이 버전들은 manifest.json 파일이 필요하지 않아요. 단일 호스트가 releases.hashicorp.com에서 미러링한 콘텐츠와 GitHub 릴리스에서 미러링한 콘텐츠를 나란히 제공할 수 있으며, 같은 플러그인의 다른 버전도 포함해요.

Limitations (제한 사항)

플러그인 소스는 항상 HTTPS로 가져와요. 일반 HTTP는 지원되지 않아요.
호스트의 인증서는 운영체제의 신뢰 저장소에 있는 인증 기관(certificate authority)으로 체인이 이어져야 해요. 내부 CA가 발급한 인증서는 시스템이 CA를 신뢰하면 추가 Packer 구성이 필요 없어요.
plugins.example.com:8443 같은 포트 번호가 있는 호스트명은 소스 주소에서 지원되지 않아요.
Packer는 플러그인 소스에 인증하지 않아요.

Manually install plugins using the CLI (CLI로 플러그인 수동 설치)

packer plugins install 커맨드를 사용해 플러그인 바이너리를 수동 설치할 수 있어요. --path 플래그를 사용해 로컬 소스를 지정해요. 그러면 Packer가 자동으로 SHA256SUM 파일을 계산하고 파일을 Packer 플러그인 디렉터리에 설치해요.

$ packer plugins install --path <path-to-downloaded-extracted-binary> <hostname>/<namespace>/<plugin-name>

다음 예시는 로컬 소스 바이너리에서 happycloud 플러그인을 설치해요.

$ unzip packer-plugin-happycloud.zip
$ ls -l
-rwxr-xr-x [...] happycloud
$ packer plugins install --path happycloud github.com/hashicorp/happycloud

추가 정보는 packer plugins install 참조를 참고하세요.

Upgrade plugins (플러그인 업그레이드)

이미 설치된 플러그인을 업그레이드하려면 --upgrade 플래그로 packer init 를 실행해요. Packer는 템플릿 구성에 지정된 설치된 플러그인의 최신 버전을 가져와요.

다음 예시는 현재 디렉터리의 템플릿에 따라 플러그인을 업그레이드해요.

$ packer init --upgrade .

추가 정보는 packer init 커맨드를 참고하세요.

Use a plugin under development (개발 중인 플러그인 사용)

개발 바이너리(예: 수동으로 빌드된 바이너리)가 지정된 소스에서 사용 가능하면, 그것이 설치된 호환 버전 중 가장 높고 같은 버전 번호의 최종 플러그인 버전이 옆에 설치되어 있지 않은 경우, Packer는 빌드에서 이를 사용해요.

다음 예시에서는 버전 1.1.0 이상이 필요해요.

packer = {
    required_plugins = {
        amazon = {
            source = "github.com/hashicorp/amazon"
            version = ">= 1.1.0"
        }
    }

. . .

}

다음 바이너리가 사용 가능하면 Packer는 Amazon 플러그인의 -dev 버전을 사용해요.

/Users/dev/.packer.d/plugins
└─ github.com
   └─ hashicorp
        └── amazon
          ├── packer-plugin-amazon_v1.1.0_x5.0_darwin_arm64
          ├── packer-plugin-amazon_v1.1.0_x5.0_darwin_arm64_SHA256SUM
          ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64
          └── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64_SHA256SUM

비개발 버전의 1.1.1이 사용 가능해지면 그 바이너리가 개발 바이너리보다 우선해요.

/Users/dev/.packer.d/plugins
└─ github.com
   └─ hashicorp
        └── amazon
          ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64
          ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64_SHA256SUM
          ├── packer-plugin-amazon_v1.1.1_x5.0_darwin_arm64
          └── packer-plugin-amazon_v1.1.1_x5.0_darwin_arm64_SHA256SUM

Example Docker plugin (예시: Docker 플러그인)

예시로 Docker 플러그인의 사용자 정의 버전을 빌드하고 설치하려면 다음 단계를 완료해요.

플러그인의 GitHub 저장소를 복제해요.

$ git clone https://github.com/hashicorp/packer-plugin-docker.git

플러그인 디렉터리 루트로 이동하고 go build 커맨드를 실행해 플러그인을 개발 바이너리로 빌드해요.

$ cd packer-plugin-docker
$ go build -ldflags="-X github.com/hashicorp/packer-plugin-docker/version.VersionPrerelease=dev" -o packer-plugin-docker-dev

릴리스 버전을 검증해요.

$ ./packer-plugin-docker-dev describe
{"version":"1.0.10-dev","sdk_version":"0.5.2","api_version":"x5.0","builders":["-packer-default-plugin-name-"],"post_processors":["import","push","save","tag"],"provisioners":[],"datasources":[]}

packer plugins install 커맨드를 사용해 개발 바이너리를 설치해요.

packer plugins install --path packer-plugin-docker-dev github.com/hashicorp/docker
Successfully installed plugin github.com/hashicorp/docker from $HOME/Development/packer-plugin-docker/packer-plugin-docker-dev to ~/github.com/hashicorp/docker/packer-plugin-docker_v1.0.10-dev_x5.0_darwin_arm64

새로 설치된 플러그인으로 packer build 를 실행해요.

$ packer build .

편의를 위해 Packer 플러그인 스캐폴딩 저장소의 makefile이 make dev 로 개발 바이너리를 빌드·설치해요. 추가 정보는 Packer plugin scaffolding 저장소의 문서를 참고하세요.

Authenticate requests to the GitHub API (GitHub API 요청 인증)

PACKER_GITHUB_API_TOKEN 환경 변수를 설정하면 GitHub API가 부과하는 한도보다 시간당 더 많은 요청을 보낼 수 있어요.

개인 액세스 토큰 페이지로 가서 새 토큰을 생성해요.
PACKER_GITHUB_API_TOKEN 환경 변수를 토큰 값으로 설정해요.

$ export PACKER_GITHUB_API_TOKEN=<token>

더 알아보기 (Learn more)

이 페이지는 Packer 공식 문서에서 가져왔어요.