프로바이더 레지스트리 프로토콜 레퍼런스

프로바이더 레지스트리 프로토콜 레퍼런스 (Provider Registry Protocol Reference)

이 주제는 프로바이더 레지스트리(provider registry) 프로토콜에 대한 레퍼런스 정보를 제공해요. 이 프로토콜은 Terraform CLI가 설치 가능한 프로바이더에 대한 메타데이터를 발견하고, 선택된 프로바이더의 배포 패키지를 찾을 수 있게 해줘요.

출처: 문서

본문

소개 (Introduction)

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

이 페이지는 설치 가능한 프로바이더를 찾기 위한 프로바이더 레지스트리 프로토콜을 설명해요. 여기서는 프로바이더 플러그인 자체가 런타임에 Terraform CLI의 요청을 서비스하기 위해 구현하는 API를 설명하지 않아요. 프로바이더 API에 대한 자세한 내용은 Terraform SDK 문서를 참고하세요.

공개 Terraform 레지스트리는 레지스트리 UI에서 사용하는 추가 정보를 담기 위해 이 페이지에서 설명하는 API의 상위 집합(superset)을 구현해요. 타사 구현은 그 확장이 예고 없이 변경될 수 있으므로 포함해서는 안 돼요.

프로바이더 주소 (Provider Addresses)

각 Terraform 프로바이더에는 Terraform 안에서 고유하게 식별하는 연관 주소가 있어요. 프로바이더 주소는 hostname/namespace/type 문법을 가져요. 여기서:

hostname은 프로바이더가 유래한 레지스트리 호스트이며, CLI 구성에서 덮어쓰지 않는 한 Terraform이 프로바이더 정보를 위해 조회하는 기본 위치예요.
namespace는 특정 호스트 이름에서 고유한 네임스페이스의 이름으로, 어떤 식으로든 관련된 하나 이상의 프로바이더를 담을 수 있어요. 공개 Terraform 레지스트리에서 "namespace"는 프로바이더를 패키징하고 배포하는 조직을 나타내요.
type은 "azurerm", "aws", "google", "dns" 같은 프로바이더 타입이에요. 프로바이더 타입은 특정 호스트 이름과 네임스페이스 안에서 고유해요.

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

예를 들어:

hashicorp/aws는 registry.terraform.io/hashicorp/aws의 축약형으로, HashiCorp가 게시한 공식 AWS 프로바이더예요.
example/foo는 registry.terraform.io/example/foo의 축약형으로, 공개 Terraform 레지스트리에 게시된 가상의 타사 프로바이더예요.
example.com/bar/baz는 example.com의 타사 프로바이더 레지스트리에 게시된 가상의 타사 프로바이더예요.

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

Terraform은 (항상 호스트 이름을 포함하도록 정규화된) 전체 주소를 내부적으로 프로바이더의 전역 식별자로 사용해요. 따라서 hashicorp/azurerm 프로바이더를 다른 네임스페이스에 다시 업로드하거나 다른 호스트 이름에 게시하면 Terraform이 이를 완전히 별개의 프로바이더로 보게 되고, hashicorp/azurerm에 대한 의존성을 선언한 모듈에서 사용할 수 없게 된다는 점을 아는 것이 중요해요. 기존 프로바이더에 대한 대체 로컬 배포 소스, 즉 프로바이더의 미러를 만드는 것이 목표라면 프로바이더 설치 방법 구성을 참고하세요.

각각의 고유한 프로바이더 주소에는 버전 집합이 연관되어 있고, 각 버전은 연관된 버전 번호를 가져요. Terraform은 버전 번호가 시맨틱 버저닝 2.0 규칙을 따르고, 프로바이더의 스키마와 동작이 Terraform 최종 사용자 관점에서 문서화되어 "공개 API" 역할을 한다고 가정해요.

특정 프로바이더 주소에 대한 모든 사용 가능 버전은 Terraform이 같은 프로바이더로 간주해요. 각 Terraform 구성은 전체 구성에서 사용하기 위해 각 프로바이더의 버전 하나만 선택하므로, 버전 선택을 위해 모든 모듈의 버전 제약 조건을 함께 고려해요.

서비스 발견 (Service Discovery)

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

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

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

{
  "providers.v1": "/terraform/providers/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)

이 작업은 특정 프로바이더에 대해 현재 사용 가능한 버전을 결정해요.

메서드: GET
경로: :namespace/:type/versions
생성물: application/json

매개변수 (Parameters)

namespace (required): 요청 중인 프로바이더 주소의 namespace 부분
type (required): 요청 중인 프로바이더 주소의 type 부분

샘플 요청 (Sample Request)

curl 'https://registry.terraform.io/v1/providers/hashicorp/random/versions'

샘플 응답 (Sample Response)

{
  "versions": [
    {
      "version": "2.0.0",
      "protocols": ["4.0", "5.1"],
      "platforms": [
        {"os": "darwin", "arch": "amd64"},
        {"os": "linux", "arch": "amd64"},
        {"os": "linux", "arch": "arm"},
        {"os": "windows", "arch": "amd64"}
      ]
    },
    {
      "version": "2.0.1",
      "protocols": ["5.2"],
      "platforms": [
        {"os": "darwin", "arch": "amd64"},
        {"os": "linux", "arch": "amd64"},
        {"os": "linux", "arch": "arm"},
        {"os": "windows", "arch": "amd64"}
      ]
    }
  ]
}

응답 속성 (Response Properties)

성공적인 결과는 단일 속성 versions를 포함하는 JSON 객체예요. versions는 각각 하나의 사용 가능 버전을 설명하는 객체 배열이며, 다음 속성을 가져요.

version (required): 이 객체가 설명하는 버전 번호로, 시맨틱 버저닝 문자열 표기법을 사용해요. version은 응답의 모든 객체에서 고유해야 해요.
protocols (권장): 이 버전이 지원하는 Terraform 프로바이더 API 버전 배열로, 각각 MAJOR.MINOR 형식으로 주어지며 각 주 버전은 한 번만 나타나고 주어진 부 버전이 지원되는 가장 높은 부 버전이에요. 예를 들어 5.1은 프로바이더가 프로토콜 5.0과 5.1을 모두 지원함을 의미해요.
- Terraform은 이 정보가 있을 때, 현재 선택된 버전이 호환되지 않는 경우 사용자가 현재 Terraform 버전과 함께 작동하도록 특정 프로바이더 버전을 업그레이드 또는 다운그레이드하라는 힌트를 제공해요.
- 대부분의 프로바이더가 지원하는 API 버전은 빌드에 사용한 Terraform SDK 버전에 의해 결정돼요. 자세한 내용은 Terraform SDK 문서를 참고하세요.
- Terraform 0.13 이상만 타사 프로바이더 레지스트리를 지원하고, 그 Terraform 버전은 API 버전 5.0 이상을 요구하므로, 실제로 타사 프로바이더 레지스트리에서 주 버전 4 이하를 나열하는 것은 유용하지 않아요.
platforms (권장): 이 버전에 대해 사용 가능한 패키지가 있는 플랫폼을 설명하는 객체 배열.
- Terraform은 이 정보가 있을 때, 현재 플랫폼과의 호환성을 위해 특정 프로바이더 버전을 업그레이드 또는 다운그레이드하라는 힌트를 사용자에게 제공할 수 있어요.
- platforms 객체는 os와 arch 속성을 가지며, 그 값은 프로바이더 패키지 찾기에 대한 응답에 있는 같은 이름의 속성과 일치해요.

레지스트리에 주어진 네임스페이스와 타입의 프로바이더가 없음을 알리려면 404 Not Found를 반환해요.

프로바이더 패키지 찾기 (Find a Provider Package)

이 작업은 특정 운영 체제와 아키텍처에 대한 특정 버전의 프로바이더 배포 패키지의 다운로드 URL과 연관 메타데이터를 반환해요.

Terraform CLI는 구성된 버전 제약 조건과 일치하는 가장 새로운 사용 가능 버전을 선택한 후, 플러그인 자체를 담은 zip 아카이브를 찾기 위해 이 작업을 사용해요.

메서드: GET
경로: :namespace/:type/:version/download/:os/:arch
생성물: application/json

매개변수 (Parameters)

namespace (required): 요청 중인 프로바이더 주소의 namespace 부분
type (required): 요청 중인 프로바이더 주소의 type 부분
version (required): 다운로드하기 위해 선택된 버전. 이전 사용 가능한 버전 목록 호출에서 반환된 버전 문자열 중 하나와 정확히 일치해요.
os (required): 반환된 패키지가 호환되어야 하는 운영 체제를 식별하는 키워드 ("linux" 또는 "darwin"처럼)
arch (required): 반환된 패키지가 호환되어야 하는 CPU 아키텍처를 식별하는 키워드 ("amd64" 또는 "arm"처럼)

샘플 요청 (Sample Request)

curl 'https://registry.terraform.io/v1/providers/hashicorp/random/2.0.0/download/linux/amd64'

샘플 응답 (Sample Response)

{
  "protocols": ["4.0", "5.1"],
  "os": "linux",
  "arch": "amd64",
  "filename": "terraform-provider-random_2.0.0_linux_amd64.zip",
  "download_url": "https://releases.hashicorp.com/terraform-provider-random/2.0.0/terraform-provider-random_2.0.0_linux_amd64.zip",
  "shasums_url": "https://releases.hashicorp.com/terraform-provider-random/2.0.0/terraform-provider-random_2.0.0_SHA256SUMS",
  "shasums_signature_url": "https://releases.hashicorp.com/terraform-provider-random/2.0.0/terraform-provider-random_2.0.0_SHA256SUMS.sig",
  "shasum": "5f9c7aa76b7c34d722fc9123208e26b22d60440cb47150dd04733b9b94f4541a",
  "signing_keys": {
    "gpg_public_keys": [
      {
        "key_id": "51852D87348FFC4C",
        "ascii_armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1\n\nmQENBFMORM0BCADBRyKO1MhCirazOSVwcfTr1xUxjPvfxD3hjUwHtjsOy/bT6p9f\nW2mRPfwnq2JB5As+paL3UGDsSRDnK9KAxQb0NNF4+eVhr/EJ18s3wwXXDMjpIifq\nfIm2WyH3G+aRLTLPIpscUNKDyxFOUbsmgXAmJ46Re1fn8uKxKRHbfa39aeuEYWFA\n3drdL1WoUngvED7f+RnKBK2G6ZEpO+LDovQk19xGjiMTtPJrjMjZJ3QXqPvx5wca\nKSZLr4lMTuoTI/ZXyZy5bD4tShiZz6KcyX27cD70q2iRcEZ0poLKHyEIDAi3TM5k\nSwbbWBFd5RNPOR0qzrb/0p9ksKK48IIfH2FvABEBAAG0K0hhc2hpQ29ycCBTZWN1\ncml0eSA8c2VjdXJpdHlAaGFzaGljb3JwLmNvbT6JATgEEwECACIFAlMORM0CGwMG\nCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJEFGFLYc0j/xMyWIIAIPhcVqiQ59n\nJc07gjUX0SWBJAxEG1lKxfzS4Xp+57h2xxTpdotGQ1fZwsihaIqow337YHQI3q0i\nSqV534Ms+j/tU7X8sq11xFJIeEVG8PASRCwmryUwghFKPlHETQ8jJ+Y8+1asRydi\npsP3B/5Mjhqv/uOK+Vy3zAyIpyDOMtIpOVfjSpCplVRdtSTFWBu9Em7j5I2HMn1w\nsJZnJgXKpybpibGiiTtmnFLOwibmprSu04rsnP4ncdC2XRD4wIjoyA+4PKgX3sCO\nklEzKryWYBmLkJOMDdo52LttP3279s7XrkLEE7ia0fXa2c12EQ0f0DQ1tGUvyVEW\nWmJVccm5bq25AQ0EUw5EzQEIANaPUY04/g7AmYkOMjaCZ6iTp9hB5Rsj/4ee/ln9\nwArzRO9+3eejLWh53FoN1rO+su7tiXJA5YAzVy6tuolrqjM8DBztPxdLBbEi4V+j\n2tK0dATdBQBHEh3OJApO2UBtcjaZBT31zrG9K55D+CrcgIVEHAKY8Cb4kLBkb5wM\nskn+DrASKU0BNIV1qRsxfiUdQHZfSqtp004nrql1lbFMLFEuiY8FZrkkQ9qduixo\nmTT6f34/oiY+Jam3zCK7RDN/OjuWheIPGj/Qbx9JuNiwgX6yRj7OE1tjUx6d8g9y\n0H1fmLJbb3WZZbuuGFnK6qrE3bGeY8+AWaJAZ37wpWh1p0cAEQEAAYkBHwQYAQIA\nCQUCUw5EzQIbDAAKCRBRhS2HNI/8TJntCAClU7TOO/X053eKF1jqNW4A1qpxctVc\nz8eTcY8Om5O4f6a/rfxfNFKn9Qyja/OG1xWNobETy7MiMXYjaa8uUx5iFy6kMVaP\n0BXJ59NLZjMARGw6lVTYDTIvzqqqwLxgliSDfSnqUhubGwvykANPO+93BBx89MRG\nunNoYGXtPlhNFrAsB1VR8+EyKLv2HQtGCPSFBhrjuzH3gxGibNDDdFQLxxuJWepJ\nEK1UbTS4ms0NgZ2Uknqn1WRU1Ki7rE4sTy68iZtWpKQXZEJa0IGnuI2sSINGcXCJ\noEIgXTMyCILo34Fa/C6VCm2WBgz9zZO8/rHIiQm1J5zqz0DrDwKBUM9C\n=LYpS\n-----END PGP PUBLIC KEY BLOCK-----",
        "trust_signature": "",
        "source": "HashiCorp",
        "source_url": "https://www.hashicorp.com/security.html"
      }
    ]
  }
}

응답 속성 (Response Properties)

성공적인 결과는 다음 속성을 가진 JSON 객체예요.

protocols (required): 프로바이더가 지원하는 Terraform 프로바이더 API 버전 배열로, 사용 가능한 버전 목록과 같은 형식이에요.
- 이 속성은 사용 가능한 옵션을 나열할 때는 선택이지만, 개별 프로바이더 패키지를 설명할 때는 필수예요. 그래야 Terraform CLI가 자신과 호환되지 않는 패키지를 다운로드하는 것을 피할 수 있어요.
os (required): 요청의 os 매개변수를 되돌려보내야 해요.
arch (required): 요청의 arch 매개변수를 되돌려보내야 해요.
filename (required): "shasums" 문서에 기록된 이 프로바이더 zip 아카이브의 파일 이름. 그래야 Terraform CLI가 주어진 체크섬 중 이 특정 패키지에 어떤 것을 사용해야 하는지 결정할 수 있어요.
download_url (required): Terraform이 프로바이더 zip 아카이브를 가져올 수 있는 URL. 상대 URL이라면 포함하는 JSON 객체를 반환한 URL에 대해 상대적으로 해석돼요.
shasums_url (required): Terraform이 이 패키지와, 같은 프로바이더 버전의 다른 플랫폼에 대한 다른 패키지의 예상 SHA256 체크섬을 기록한 텍스트 문서를 가져올 수 있는 URL.
- 표시된 문서는 많은 Unix 시스템에서 사용 가능한 sha256 명령이 생성하는 형식이어야 하며, 이때 filename 속성에 주어진 파일 이름(대소문자 구분)을 기록하는 항목이 하나 있어야 해요.
shasums_signature_url (required): Terraform이 shasums_url의 문서에 대한 이진 분리 GPG 서명을 가져올 수 있는 URL로, signing_keys 속성에 표시된 키 중 하나로 서명돼 있어야 해요.
shasum (required): shasums 문서에 기록된 이 프로바이더 zip 아카이브의 SHA256 체크섬.
signing_keys (required): 이 프로바이더 패키지의 서명 키를 설명하는 객체로, 그중 하나가 shasums_signature_url의 서명을 만드는 데 사용되었어야 해요. 객체는 다음 중첩 속성을 가져요.
- gpg_public_keys (required): 각각 이 프로바이더 버전의 체크섬에 서명할 수 있는 하나의 GPG 서명 키를 설명하는 객체 배열. 최소한 하나의 요소가 포함되어야 하며, shasums_signature_url의 서명을 만든 키를 나타내요. 이 객체들은 다음 중첩 속성을 가져요.
  - key_id (required): 이 GPG 키의 대문자 16진수 형식 ID
  - ascii_armor (required): 이 GPG 키와 연관된 공개 키의 "ascii-armor" 인코딩

주어진 프로바이더 버전이 요청된 운영 체제 또는 아키텍처에 대해 사용 가능하지 않음을 알리려면 404 Not Found를 반환해요. Terraform CLI는 사용 가능한 버전 목록에 대한 응답에서 이전에 본 버전만 다운로드하려고 시도해요.

프로바이더 레지스트리 프로토콜 레퍼런스