원격 서비스 발견 프로토콜 레퍼런스

원격 서비스 발견 프로토콜 레퍼런스 (Remote Service Discovery Protocol Reference)

이 주제는 Terraform의 원격 서비스 발견(remote service discovery) 프로토콜에 대한 레퍼런스 정보를 제공해요.

출처: 문서

본문

소개 (Introduction)

Terraform은 많은 기능을 원격 서비스로 구현해요. 그중 일부는 Terraform이 원격 서비스 발견 프로토콜로 상호작용하는 네이티브 서비스예요.

사용자 대상 호스트 이름 (User-facing Hostname)

Terraform은 사람이 읽을 수 있는 호스트 이름에 네이티브 서비스를 제공해요. 이 호스트 이름은 구성과 필요한 인증 자격 증명의 핵심이에요.

발견 프로토콜의 목적은 사용자가 제공한 호스트 이름을 특정 서비스의 기본 URL로 매핑하는 거예요. 각 호스트는 서로 다른 서비스 조합을 제공할 수 있을 뿐 아니라 아예 서비스가 없을 수도 있어요! 그래서 발견 프로토콜은 주어진 호스트 이름에 대해 어떤 서비스가 유효한지 Terraform이 식별하게 하는 보조 목적도 가져요.

예를 들어 모듈 소스 문자열은 첫 번째 세그먼트로 모듈 레지스트리 호스트 이름을 포함할 수 있어요(example.com/namespace/name/provider처럼). Terraform은 서비스 발견을 사용해 example.com이 모듈 레지스트리를 가지고 있는지, 있다면 그 API가 어디에 있는지 판단해요.

사용자 대상 호스트 이름은 유니코드 형태로 표현된 완전히 지정된 국제화 도메인 이름이며(대응하는 "punycode" 형태는 허용되지 않아요), DNS에서 포트 443에 HTTPS 서버가 실행 중인 주소로 해석될 수 있어야 해요.

사용자 대상 호스트 이름은 내부 비교를 위해 표준 유니코드 Nameprep 알고리즘으로 정규화돼요. 여기에는 모든 문자를 소문자로 변환하는 것, 가능한 곳에서 결합 악센트를 미리 구성된 형태로 정규화하는 것, 그리고 다양한 기타 정규화 단계가 포함돼요.

발견 프로세스 (Discovery Process)

호스트 이름이 주어지면 발견은 그 호스트 이름을 https: 스키마와 고정 경로 /.well-known/terraform.json으로 사용해 초기 발견 URL을 구성하면서 시작해요.

예를 들어 호스트 이름 example.com이 주어지면 초기 발견 URL은 https://example.com/.well-known/terraform.json이 돼요.

그런 다음 Terraform은 이 발견 URL에 GET 요청을 보내고 JSON 응답을 기대해요. 응답이 상태 200이 아니거나, 미디어 타입이 application/json이 아니거나, 본문을 JSON 객체로 파싱할 수 없으면 발견은 실패하고 Terraform은 해당 호스트가 어떠한 Terraform 네이티브 서비스도 지원하지 않는다고 간주해요.

응답이 HTTP 리다이렉트라면 Terraform은 새 위치를 발견 URL로 삼아 이 단계를 반복해요. Terraform은 최소한 하나의 리다이렉트를 따라가는 것이 보장되지만, 중첩된 리다이렉트는 보장도 권장도 되지 않아요.

응답이 유효한 JSON 객체라면 그 키들은 서비스 타입 이름과 버전 문자열을 마침표로 구분한, Terraform 네이티브 서비스 식별자예요. 예를 들어 모듈 레지스트리 프로토콜 버전 1의 서비스 식별자는 modules.v1이에요.

각 객체 요소의 값은 해당 서비스의 기본 URL이에요. 이 URL은 절대 경로일 수도 상대 경로일 수도 있으며, 상대 경로라면 (리다이렉트를 따른 후의) 최종 발견 URL에 대해 해석돼요.

다음은 모듈 레지스트리 프로토콜 버전 1을 지원함을 선언하는 발견 문서 예시예요.

{
  "modules.v1": "https://modules.example.com/v1/"
}

지원되는 서비스 (Supported Services)

현재 사용 중인 서비스 식별자는 다음과 같아요.

인증 (Authentication)

주어진 호스트 이름에 대한 자격 증명이 CLI 구성에 credentials_helper를 통해 또는 호스트별 환경 변수로 사용 가능하다면, 발견 문서에 대한 요청에 포함돼요.

자격 증명은 해당 서비스의 요구사항에 따라 발견 문서에 선언된 엔드포인트에도 제공될 수 있어요.

사용자 대상 호스트 이름의 비표준 포트 (Non-standard Ports in User-facing Hostnames)

호스트 이름의 발견 문서를 표준 HTTPS 포트 443에 제공하는 것이 강력히 권장돼요. 하지만 개발 환경에서는 항상 가능하거나 편리하지는 않으므로, Terraform은 호스트 이름이 콜론 다음에 하나 이상의 십진 숫자로 구성된 포트 지정으로 끝나는 것을 허용해요.

사용자 지정 포트 번호가 있으면 해당 포트의 서비스는 HTTPS를 구현하고 같은 고정 발견 경로에 응답할 것으로 기대돼요.

일상적인 사용에서는 이 메커니즘에 의존하지 말고 표준 포트에 발견 문서를 제공할 것을 강력히 권장해요. 그래야 가장 사용자 친화적인 호스트 이름 형태를 사용할 수 있기 때문이에요.

더 알아보기 (Learn more)