프로바이더 네트워크 미러 프로토콜 레퍼런스

프로바이더 네트워크 미러 프로토콜 레퍼런스 (Provider Network Mirror Protocol Reference)

이 주제는 프로바이더 네트워크 미러(network mirror) 프로토콜에 대한 레퍼런스 정보를 제공해요. 이 프로토콜을 통해 Terraform 프로바이더의 대체 설치 소스를 구현하고, 원래 레지스트리와 무관하게 그 소스를 프로바이더 네트워크 미러 프로토콜로 제공할 수 있어요.

출처: 문서

본문

프로바이더 네트워크 미러는 Terraform CLI v0.13.2 이상에서만 지원돼요. 이전 버전은 이 프로토콜을 지원하지 않아요.

소개 (Introduction)

Terraform은 CLI 구성의 provider_installation 블록에서 명시적으로 활성화한 경우에만 네트워크 미러를 사용해요. 활성화되면 네트워크 미러는 어떤 레지스트리 호스트 이름에 속한 프로바이더든 제공할 수 있어요. 따라서 조직이 사용하려는 모든 Terraform 프로바이더를 각 프로바이더의 원본 레지스트리가 아닌 내부 서버에서 제공할 수 있어요.

이 프로토콜은 Terraform 프로바이더의 원본 레지스트리(origin registry) 역할을 하려는 호스트가 구현해야 하는 프로토콜이 아니에요. 원본 레지스트리(그 호스트 이름은 해당 호스트가 호스팅하는 프로바이더의 소스 주소에 포함됨)를 제공하려면 대신 프로바이더 레지스트리 프로토콜을 구현하세요.

프로바이더 주소 (Provider Addresses)

각 Terraform 프로바이더에는 Terraform 안에서 고유하게 식별하는 연관 주소가 있어요. 프로바이더 주소는 hostname/namespace/type 문법을 가지며, 자세한 내용은 프로바이더 요구사항 문서에서 설명해요.

기본적으로 프로바이더 주소의 hostname 부분은 그 고유 식별자의 일부이자 검색할 레지스트리의 위치 역할을 모두 해요. 하지만 네트워크 미러에서 프로바이더를 설치하도록 Terraform을 구성하면 hostname은 오직 식별자로만 기능하고 더 이상 설치 소스가 아니에요. 따라서 프로바이더 미러는 registry.terraform.io의 공개 Terraform 레지스트리를 포함해 다양한 프로바이더 레지스트리 호스트 이름에 속한 프로바이더를 단일 서버에서 제공할 수 있어요.

이 문서 뒷부분의 상대 URL 패턴에서 :hostname 자리 표시자는 프로바이더 네트워크 미러가 배포된 호스트 이름이 아니라, 요청 중인 프로바이더의 주소에서 가져온 호스트 이름을 가리켜요.

프로토콜 기본 URL (Protocol Base URL)

대부분의 Terraform 네이티브 서비스는 원격 서비스 발견 프로토콜을 사용해서 엔드포인트의 물리적 위치가 식별자에 사용되는 호스트 이름과 분리될 수 있게 해요. 프로바이더 네트워크 미러 프로토콜은 서비스 발견 간접 참조를 사용하지 않아요. 네트워크 미러 위치는 물리적 위치일 뿐이며 Terraform 구성의 의존성 식별자의 일부로 사용되지 않기 때문이에요.

대신 CLI 구성의 프로바이더 설치 섹션은 기본 URL을 직접 받아들여요. 주어진 URL은 https: 스키마를 사용해야 하며, 개별 작업 엔드포인트의 상대 URL이 그 아래에서 해석되도록 일반적으로 끝에 슬래시를 붙여야 해요.

provider_installation {
  network_mirror {
    url = "https://terraform.example.com/providers/"
  }
}

Terraform은 기본 URL을 작업 엔드포인트 URL을 해석하기 위한 줄기(stem)로만 사용하므로 기본 URL에 직접 접근하지는 않아요. 따라서 원한다면 해당 URL에 네트워크 미러의 사람이 읽을 수 있는 사용법 문서를 게시할 수 있어요.

다음 섹션들은 프로바이더 네트워크 미러 서버가 Terraform CLI의 프로바이더 설치 프로그램과 호환되기 위해 구현해야 하는 다양한 작업을 설명해요. 표시된 URL은 모두 위에서 설명한 것처럼 주어진 기본 URL에 대해 상대적이에요.

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

다음 섹션의 예시 요청은 위 CLI 구성 예시의 미러 기본 URL을 가정해요.

인증 (Authentication)

CLI 구성에 네트워크 미러 기본 URL에 주어진 호스트 이름에 대한 자격 증명이 포함되어 있다면, Terraform은 아래에서 설명하는 작업에 대한 요청에 그 자격 증명을 포함해요.

주어진 URL이 비표준 포트 번호(443 이외)를 사용하면, 자격 증명은 포트 번호를 포함한 호스트 이름(예: terraform.example.com:8443)과 연결되어야 해요.

Terraform은 아래 "사용 가능한 설치 패키지 목록(List Available Installation Packages)" 응답에 주어진 URL로 아카이브를 가져올 때 자격 증명을 보내지 않아요. 특정 미러가 배포 패키지 자체를 민감한 것으로 간주한다면, 메타데이터 응답에 암호학적으로 안전하고 사용자별이며 시간 제한이 있는 URL을 사용해야 해요. 그렇게 하는 전략은 이 프로토콜 문서의 범위 밖이에요.

사용 가능한 버전 목록 (List Available Versions)

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

• 메서드: GET
• 경로: :hostname/:namespace/:type/index.json
• 생성물: application/json

매개변수 (Parameters)

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

샘플 요청 (Sample Request)

curl 'https://terraform.example.com/providers/registry.terraform.io/hashicorp/random/index.json'

샘플 응답 (Sample Response)

{
  "versions": {
    "2.0.0": {},
    "2.0.1": {}
  }
}

응답 속성 (Response Properties)

성공적인 결과는 단일 속성 versions를 포함하는 JSON 객체이며, 이는 JSON 객체여야 해요.

versions 객체의 각 속성 이름은 사용 가능한 버전 번호를 나타내요. 속성 값은 객체여야 하지만 그 객체에 대해 정의된 속성은 없어요. 향후 호환성을 위해 그 객체를 비워 두는 것을 권장해요.

미러에 주어진 주소의 프로바이더가 없음을 알리려면 404 Not Found를 반환해요.

사용 가능한 설치 패키지 목록 (List Available Installation Packages)

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

각 배포 패키지는 특정 운영 체제와 아키텍처와 연관돼 있어요. 네트워크 미러는 미러 사용자가 모두 Terraform이 지원하는 대상 플랫폼 중 일부만 사용한다고 알려진 경우, 프로바이더 버전의 사용 가능한 패키지의 일부만 호스팅할 수 있어요.

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

• 메서드: GET
• 경로: :hostname/:namespace/:type/:version.json
• 생성물: application/json

매개변수 (Parameters)

• hostname (required): 요청 중인 프로바이더 주소의 hostname 부분
• namespace (required): 요청 중인 프로바이더 주소의 namespace 부분
• type (required): 요청 중인 프로바이더 주소의 type 부분
• version (required): 다운로드하기 위해 선택된 버전. 이전 사용 가능한 버전 목록 호출에서 반환된 버전 문자열 중 하나와 정확히 일치해요.

샘플 요청 (Sample Request)

curl 'https://terraform.example.com/providers/registry.terraform.io/hashicorp/random/2.0.0.json'

샘플 응답 (Sample Response)

{
  "archives": {
    "darwin_amd64": {
      "url": "terraform-provider-random_2.0.0_darwin_amd64.zip",
      "hashes": [
        "h1:4A07+ZFc2wgJwo8YNlQpr1rVlgUDlxXHhPJciaPY5gs="
      ]
    },
    "linux_amd64": {
      "url": "terraform-provider-random_2.0.0_linux_amd64.zip",
      "hashes": [
        "h1:lCJCxf/LIowc2IGS9TPjWDyXY4nOmdGdfcwwDQCOURQ="
      ]
    }
  }
}

응답 속성 (Response Properties)

성공적인 결과는 archives라는 속성을 가진 JSON 객체이며, 이는 JSON 객체여야 해요.

archives 객체의 각 속성 이름은 대상 플랫폼 식별자로, 운영 체제와 아키텍처를 밑줄(_)로 연결한 형태예요.

archives 객체의 각 속성 값은 다시 다음 속성을 가진 중첩 객체예요.

• url (required): Terraform이 요청된 프로바이더 플러그인 버전을 담은 .zip 아카이브를 다운로드해야 하는 URL을 지정하는 문자열.
  • Terraform은 현재 JSON 문서가 반환된 URL에 대해 상대적으로 이 URL을 해석해요. 따라서 위 예시처럼 파일 이름만 포함된 경우 Terraform은 다음과 같은 URL을 구성해요.

  https://terraform.example.com/providers/registry.terraform.io/hashicorp/random/terraform-provider-random_2.0.0_darwin_amd64.zip
  

• hashes (optional): 표시된 아카이브에 대한 하나 이상의 해시 값을 담는 JSON 문자열 배열. 이 해시는 Terraform의 프로바이더 패키지 해싱 알고리즘을 사용해요. 현재 가장 쉬운 채우기 방법은 뒤에서 설명하는 terraform providers mirror 명령으로 미러의 JSON 인덱스를 만드는 것인데, 이 명령은 각 프로바이더의 계산된 해시를 포함해요.
  • 응답에 해시가 하나 이상 포함되면, Terraform은 가장 강하다고 판단하는 알고리즘의 해시를 선택하고 다운로드한 패키지가 그 해시와 일치하는지 검증해요. 응답에 hashes 속성이 없으면 Terraform은 검증 없이 표시된 아카이브를 설치해요.

Terraform CLI는 사용 가능한 버전 목록에 대한 응답에서 이전에 본 버전만 다운로드하려고 시도해요.

프로바이더 미러를 정적 웹사이트로 (Provider Mirror as a Static Website)

프로바이더 미러 프로토콜은 일반적인 정적 웹사이트 호스팅 서비스에 파일을 놓는 것만으로도 구현할 수 있도록 설계돼요. 이 전략을 사용할 때는 위에서 설명한 JSON 인덱스 응답을 적절한 중첩 하위 디렉터리에 .json 파일로 구현하고, 시스템이 .json 파일을 application/json 미디어 타입으로 제공하도록 구성해야 해요.

편의를 위해 Terraform CLI에는 terraform providers mirror 하위 명령이 포함돼 있는데, 이 명령은 현재 구성을 분석해 필요한 프로바이더를 알아내고, 그 프로바이더의 패키지를 원본 레지스트리에서 다운로드해 미러로 사용할 수 있는 로컬 디렉터리에 배치해요.

terraform providers mirror 하위 명령은 또한 index.json과 버전별 .json 파일을 생성하는데, 이것들을 정적 웹사이트 호스팅 시스템에 배치하면 프로바이더 미러 프로토콜과 호환되는 응답을 만들 수 있어요.

여러 다른 Terraform 구성에 대한 프로바이더가 있는 미러를 만들려면 각 구성에서 같은 출력 디렉터리를 지정해 terraform providers mirror를 차례로 실행하세요. 그러면 Terraform이 모든 요구사항을 단일 JSON 인덱스 집합으로 병합해요.

더 알아보기 (Learn more)

• terraform providers mirror 명령 — 로컬 미러 생성
• 프로바이더 레지스트리 프로토콜 — 원본 레지스트리 구현
• CLI 구성의 provider_installation