모듈 레지스트리 프로토콜 레퍼런스

모듈 레지스트리 프로토콜 레퍼런스 (Module Registry Protocol Reference)

이 주제는 모듈 레지스트리 프로토콜에 대한 레퍼런스 정보를 제공해요.

출처: 문서

본문

타사 모듈 레지스트리는 Terraform CLI 0.11 이상에서만 지원돼요. 이전 버전은 이 프로토콜을 지원하지 않아요.

소개 (Introduction)

Terraform CLI는 모듈 레지스트리 프로토콜을 사용해 설치할 수 있는 모듈에 대한 메타데이터를 발견하고, 선택된 모듈의 배포 패키지를 찾아요.

이 프로토콜의 주요 구현체는 registry.terraform.io의 공개 Terraform 레지스트리예요. 이 프로토콜의 자체 구현을 작성하고 배포하면, 공개 Terraform 레지스트리에 게시하는 대신 자체 모듈을 배포할 별도의 레지스트리를 만들 수 있어요.

공개 Terraform 레지스트리는 레지스트리 UI에서 사용하는 추가 정보를 담기 위해 이 페이지에서 설명하는 API의 상위 집합(superset)을 구현해요. 그 확장에 대한 정보는 Terraform 레지스트리 HTTP API를 참고하세요. 타사 레지스트리 구현은 원한다면 그 확장을 구현할 수 있지만, Terraform CLI 자체는 사용하지 않아요.

모듈 주소 (Module Addresses)

각 Terraform 모듈에는 연관된 주소가 있어요. 모듈 주소는 hostname/namespace/name/system 문법을 가져요. 여기서:

• hostname은 이 모듈을 제공하는 모듈 레지스트리의 호스트 이름이에요.
• namespace는 특정 호스트 이름에서 고유한 네임스페이스의 이름으로, 어떤 식으로든 관련된 하나 이상의 모듈을 담을 수 있어요. 공개 Terraform 레지스트리에서 "namespace"는 모듈을 패키징하고 배포하는 조직을 나타내요.
• name은 모듈 이름으로, 일반적으로 모듈이 만들고자 하는 추상화의 이름이에요.
• system은 모듈이 주로 대상으로 하는 원격 시스템의 이름이에요. 멀티 클라우드 추상화의 경우, 추상화의 프로바이더별 구현을 반영해 "system"만 다른 주소를 가진 여러 모듈이 있을 수 있어요. 예를 들어 registry.terraform.io/hashicorp/consul/aws와 registry.terraform.io/hashicorp/consul/azurerm 같은 식이에요. 시스템 이름은 보통 공식 프로바이더 주소의 타입 부분(위 예시의 aws 또는 azurerm)과 일치하지만, 그럴 필요는 없으므로 특정 레지스트리 구성에 맞는 시스템 키워드를 사용할 수 있어요.

모듈 주소의 hostname/ 부분(슬래시 구분자 포함)은 선택이며, 생략하면 registry.terraform.io/로 기본 설정돼요.

예를 들어:

• hashicorp/consul/aws는 registry.terraform.io/hashicorp/consul/aws의 축약형으로, Amazon Web Services에서 Consul 클러스터를 배포하기 위한 공개 레지스트리의 모듈이에요.
• example.com/awesomecorp/consul/happycloud는 타사 레지스트리에 게시된 가상의 모듈이에요.

모든 Terraform 사용자가 쓸 수 있도록 개발한 모듈을 공유하려면, 발견 가능성을 높이기 위해 공개 Terraform 레지스트리에 게시하는 것을 고려해 보세요. 당신이 통제하는 다른 호스트 이름을 포함하는 주소로 모듈을 게시하려는 경우에만 이 모듈 레지스트리 프로토콜을 구현하면 돼요.

각각의 고유한 모듈 주소에는 버전 집합이 연관되어 있고, 각 버전은 연관된 버전 번호를 가져요. Terraform은 버전 번호가 시맨틱 버저닝 2.0 규칙을 따르며, 사용자가 보는 모듈의 동작이 "공개 API" 역할을 한다고 가정해요.

각 module 블록은 여러 블록이 같은 소스 주소를 가지더라도 모듈의 서로 다른 버전을 선택할 수 있어요.

서비스 발견 (Service Discovery)

모듈 레지스트리 프로토콜은 Terraform CLI가 Terraform의 원격 서비스 발견 프로토콜을 사용하는 것으로 시작하며, 모듈 주소의 호스트 이름이 "사용자 대상 호스트 이름" 역할을 해요.

모듈 레지스트리 프로토콜의 서비스 식별자는 modules.v1이에요. 연관된 문자열 값은 다음 섹션에서 정의하는 상대 URL의 기본 URL이에요.

예를 들어 오직 모듈 레지스트리 프로토콜만 구현하는 호스트의 서비스 발견 문서는 다음을 포함할 수 있어요.

{
  "modules.v1": "/terraform/modules/v1/"
}

주어진 URL이 상대 URL이라면 Terraform은 발견 문서 자체에 대해 상대적으로 해석해요. 특정 모듈 레지스트리 프로토콜 엔드포인트는 주어진 기본 URL에 대해 상대적인 URL로 정의되므로, 지정된 기본 URL은 일반적으로 슬래시로 끝나서 상대 경로가 예상대로 해석되도록 해야 해요.

다음 섹션들은 모듈 레지스트리가 Terraform CLI의 모듈 설치 프로그램과 호환되기 위해 구현해야 하는 다양한 작업을 설명해요. 표시된 URL은 모두 위에서 설명한 서비스 발견으로 얻은 URL에 대해 상대적이에요. 호출자가 이미 registry.terraform.io에서 서비스 발견을 수행해 기본 URL을 알아냈다고 가정하고, Terraform 레지스트리의 현재 URL을 작업 예시로 사용해요.

URL은 콜론 : 접두사가 있는 경로 부분이 동적으로 선택되는 값의 자리 표시자이고, 다른 모든 경로 부분은 리터럴이라는 규칙으로 표시돼요. 예를 들어 :namespace/:type/versions에서 처음 두 경로 부분은 자리 표시자이고 세 번째는 문자 그대로 문자열 "versions"예요.

특정 모듈의 사용 가능한 버전 목록 (List Available Versions for a Specific Module)

이것은 모듈 소스를 해석하는 주요 엔드포인트로, 주어진 전체 자격(fully-qualified) 모듈에 대한 사용 가능한 버전을 반환해요.

• 메서드: GET
• 경로: :namespace/:name/:system/versions
• 생성물: application/json

매개변수 (Parameters)

• namespace (string: required): 모듈을 소유한 사용자 또는 조직. 필수이며 URL 경로의 일부로 지정돼요.
• name (string: required): 모듈의 이름. 필수이며 URL 경로의 일부로 지정돼요.
• system (string: required): 대상 시스템의 이름. 필수이며 URL 경로의 일부로 지정돼요.

샘플 요청 (Sample Request)

$ curl 'https://registry.terraform.io/v1/modules/hashicorp/consul/aws/versions'

샘플 응답 (Sample Response)

응답의 modules 배열은 항상 요청된 모듈을 첫 번째 요소로 포함해요.

Terraform은 이 목록의 다른 요소는 사용하지 않아요. 그러나 타사 구현은 향후 호환성을 위해 항상 단일 요소 목록을 사용해야 해요.

반환된 각 모듈은 사용 가능한 버전 배열을 가지며, Terraform은 이를 구성에 주어진 버전 제약 조건과 대조해요.

{
   "modules": [
      {
         "versions": [
            {"version": "1.0.0"},
            {"version": "1.1.0"},
            {"version": "2.0.0"}
         ]
      }
   ]
}

요청된 네임스페이스, 이름, 대상 시스템으로 사용 가능한 모듈이 없음을 나타내려면 404 Not Found를 반환해요.

특정 모듈 버전의 소스 코드 다운로드 (Download Source Code for a Specific Module Version)

이 엔드포인트는 단일 대상 시스템에 대해 모듈의 지정된 버전을 다운로드해요.

• 메서드: GET
• 경로: :namespace/:name/:system/:version/download
• 생성물: application/json

매개변수 (Parameters)

• namespace (string: required): 모듈을 소유한 사용자. 필수이며 URL 경로의 일부로 지정돼요.
• name (string: required): 모듈의 이름. 필수이며 URL 경로의 일부로 지정돼요.
• system (string: required): 대상 시스템의 이름. 필수이며 URL 경로의 일부로 지정돼요.
• version (string: required): 모듈의 버전. 필수이며 URL 경로의 일부로 지정돼요.

샘플 요청 (Sample Request)

$ curl -i 'https://registry.terraform.io/v1/modules/hashicorp/consul/aws/0.0.1/download'

샘플 응답 (Sample Response)

HTTP/1.1 204 No Content
Content-Length: 0
X-Terraform-Get: https://api.github.com/repos/hashicorp/terraform-aws-consul/tarball/v0.0.1//*?archive=tar.gz

성공적인 응답에는 본문이 없으며, X-Terraform-Get 헤더에 모듈 버전의 소스를 다운로드할 위치가 포함돼요. 이 헤더의 값은 Module Sources에 설명된 대로 Terraform 구성의 module 블록에 있는 source 인자가 받아들이는 값과 동일한 값을 받아들이지만, 다른 모듈 레지스트리 주소를 재귀적으로 참조할 수는 없어요.

X-Terraform-Get의 값은 대신 /, ./, ../로 시작하는 상대 URL일 수도 있는데, 이 경우 다운로드 엔드포인트의 전체 URL에 대해 상대적으로 해석되어 HTTP URL 모듈 소스를 만들어요.

더 알아보기 (Learn more)

• 원격 서비스 발견 프로토콜
• Terraform 레지스트리 — 공개 모듈 레지스트리
• 모듈 소스 — module 블록의 source 문법