자격 증명 헬퍼 만들기

자격 증명 헬퍼 만들기 (Create Credentials Helpers)

이 주제는 Terraform이 자격 증명을 얻는 방식을 사용자 지정할 수 있도록 자격 증명 헬퍼(credentials helper)를 작성하고 설치하는 방법을 설명해요. 이미 설치된 자격 증명 헬퍼를 구성하는 방법은 Terraform CLI 문서의 자격 증명 헬퍼를 참고하세요.

출처: 문서

본문

소개 (Introduction)

모듈 레지스트리와 원격 작업처럼 원격 네트워크 서비스와 상호작용하는 Terraform 특화 기능의 경우, Terraform은 기본적으로 CLI 구성에서 이러한 호출에 사용할 API 자격 증명을 찾아요.

자격 증명 헬퍼는 외부 프로그램을 사용해 Terraform이 자격 증명을 얻는 방식을 사용자 지정할 수 있게 하는 대안적인 접근 방식이에요. 이 프로그램은 조직의 기존 시크릿 관리 시스템에 직접 접근할 수 있어요.

Terraform이 자격 증명 헬퍼를 찾는 방법 (How Terraform finds Credentials Helpers)

자격 증명 헬퍼는 특정 위치에 설치되고 특정 명명 규칙을 따르는 일반 실행 프로그램이에요.

예를 들어 "credstore"라는 자격 증명 헬퍼는 terraform-credentials-credstore라는 이름의 실행 프로그램(Windows에서는 .exe 확장자)으로 구현되고 기본 플러그인 검색 위치 중 하나에 설치돼요.

Terraform이 자격 증명 헬퍼를 실행하는 방법 (How Terraform runs Credentials Helpers)

Terraform은 구성된 자격 증명 헬퍼를 찾으면, CLI 구성의 credentials 블록으로 충족할 수 없는 각 자격 증명 요청에 대해 헬퍼를 한 번씩 실행해요.

다음 예시에서는 다음과 같이 구성된 "credstore" 자격 증명 헬퍼를 가정해요.

credentials_helper "credstore" {
  args = ["--host=credstore.example.com"]
}

Terraform은 args에 주어진 각 인자 뒤에 동사(verb), 그리고 동사가 적용될 호스트 이름을 붙여 헬퍼 프로그램을 실행해요. 현재 동사 집합은 다음과 같아요.

get: 주어진 호스트 이름에 대한 자격 증명을 가져오기
store: 주어진 호스트 이름에 대한 새 자격 증명을 저장하기
forget: 주어진 호스트 이름에 대해 저장된 자격 증명을 삭제하기

자격 증명을 나타내기 위해 자격 증명 헬퍼 프로토콜은 CLI 구성의 credentials 블록 내용에 대응하는 내용을 가진 JSON 객체를 사용해요. API 토큰을 나타내려면 객체에 "token"이라는 속성을 포함하고 그 값이 토큰 문자열이에요.

{
  "token": "example-token-value"
}

다음 섹션들은 세 동사 각각에 대한 구체적인 기대 동작을 설명해요.

`get`: 주어진 호스트 이름의 자격 증명 가져오기

app.terraform.io의 자격 증명을 가져오기 위해 Terraform은 "credstore" 헬퍼를 다음과 같이 실행해요.

terraform-credentials-credstore --host=credstore.example.com get app.terraform.io

자격 증명 헬퍼가 주어진 호스트에 대한 자격 증명을 제공할 수 있으면 stdout 스트림에 JSON 자격 증명 객체를 출력하고 성공을 나타내는 상태 코드 0으로 종료해야 해요.

자격 증명 헬퍼가 주어진 호스트에 대한 자격 증명이 확실히 없다면 stdout에 빈 JSON 객체를 출력하고 상태 0으로 종료해야 해요.

자격 증명 헬퍼가 어떤 다른 이유로 요청된 자격 증명을 제공할 수 없다면, 최종 사용자 대상의 평문 텍스트 오류 메시지를 stderr 스트림에 출력하고 0이 아닌 상태 코드로 종료해야 해요.

`store`: 주어진 호스트 이름의 새 자격 증명 저장하기

app.terraform.io에 대한 새 자격 증명을 저장하기 위해 Terraform은 "credstore" 헬퍼를 다음과 같이 실행해요.

terraform-credentials-credstore --host=credstore.example.com store app.terraform.io

그런 다음 Terraform은 JSON 자격 증명 객체를 헬퍼 프로그램의 stdin 스트림에 써요. 헬퍼가 주어진 자격 증명을 저장할 수 있으면 저장한 다음 상태 코드 0으로 종료하고 stdout·stderr에 아무 출력도 하지 않아 성공을 나타내야 해요.

어떤 이유로든 주어진 자격 증명을 저장할 수 없으면, stdin을 EOF까지 완전히 읽은 다음에 최종 사용자 대상의 평문 텍스트 오류 메시지를 stderr 스트림에 출력하고 0이 아닌 상태 코드로 종료해야 해요.

새 자격 증명은 주어진 호스트 이름에 대해 저장된 기존 자격 증명을 완전히 대체해야 해요.

`forget`: 주어진 호스트 이름의 저장된 자격 증명 삭제하기

app.terraform.io에 대한 기존 자격 증명을 잊기 위해 Terraform은 "credstore" 헬퍼를 다음과 같이 실행해요.

terraform-credentials-credstore --host=credstore.example.com forget app.terraform.io

forget 동사에는 JSON 자격 증명 객체가 사용되지 않아요.

헬퍼 프로그램이 주어진 호스트 이름에 대해 저장된 자격 증명을 삭제할 수 있거나 이미 저장된 자격 증명이 없다면, 상태 코드 0으로 종료하고 stdout·stderr에 아무 출력도 하지 않아야 해요.

어떤 이유로든 저장된 자격 증명을 잊을 수 없고, 특히 자격 증명이 더 이상 검색되지 않는다고 확신할 수 없다면, 헬퍼 프로그램은 최종 사용자 대상의 평문 텍스트 오류 메시지를 stderr 스트림에 출력하고 0이 아닌 상태 코드로 종료해야 해요.

다른 명령 처리 (Handling Other Commands)

자격 증명 헬퍼 프로토콜은 향후 추가 동사로 확장될 수 있으므로, 향후 호환성을 위해 자격 증명 헬퍼는 지원하지 않는 동사에 최종 사용자 대상의 평문 텍스트 오류 메시지를 stderr 스트림에 출력하고 0이 아닌 상태 코드로 종료함으로써 응답해야 해요.

지원되지 않는 자격 증명 객체 속성 처리 (Handling Unsupported Credentials Object Properties)

Terraform은 JSON 자격 증명 객체 내에서 token 속성만 정의해요.

자격 증명 헬퍼가 token 이외의 속성을 가진 객체를 저장하도록 요청받고 그것을 충실히 보존할 수 없다면, 객체를 저장 불가능한 것으로 간주하고 오류를 반환해야 해요. 자격 증명 객체의 의미를 바꿀 수 있으므로 token 값을 단독으로 저장하고 다른 속성을 조용히 버려서는 안 돼요.

대상 시스템의 제약 안에서 기술적으로 가능하다면, 자격 증명 헬퍼는 나중에 검색할 수 있도록 전체 JSON 객체를 있는 그대로 저장하는 것을 선호해야 해요. 더 제약이 심한 시스템에서는 다른 속성을 포함한 객체를 위에서 설명한 대로 거부하는 한, token 문자열만 저장하는 것도 허용돼요.

자격 증명 헬퍼 설치 (Installing a Credentials Helper)

Terraform에는 자격 증명 헬퍼의 자동 설치 메커니즘이 없어요. 대신 사용자가 헬퍼 프로그램 실행 파일을 기본 플러그인 검색 위치 중 하나에 직접 풀어 넣어야 해요.

배포용으로 자격 증명 헬퍼를 패키징한다면, 기대되는 명명 체계(terraform-credentials-example)로 이름을 지정하고, 포함하는 아카이브 포맷이 지원하고 대상 운영 체제에 의미가 있다면 파일을 실행 가능으로 표시해서 추출 직후 바로 작동할 가능성을 높여요.

Terraform은 자격 증명 헬퍼를 검색할 때 terraform init에 대한 -plugin-dir 인자를 존중하지 않아요. 이는 자격 증명이 terraform init 이전에 실행될 수 있는 다른 명령에서도 사용되기 때문이에요. 기본 검색 위치만 지원돼요.

자격 증명 헬퍼 만들기