HCP Terraform 시크릿 엔진
HCP Terraform 시크릿 엔진
Vault용 HCP Terraform 시크릿 엔진은 Organizations, Teams, Users에 대해 HCP Terraform API 토큰을 동적으로 생성해요.
이 페이지에서는 이 백엔드의 빠른 시작을 보여 드릴게요. 모든 경로에 대한 자세한 문서는 백엔드를 마운트한 후 vault path-help를 사용하세요.
Terraform Enterprise 지원: 이 시크릿 엔진은 Terraform Cloud(app.terraform.io)와 온프레미스 Terraform Enterprise를 모두 지원해요. 버전 요구 사항은 그 버전을 요구하는 기능과 함께 문서화될 거예요(있다면).
출처: 문서
본문
빠른 시작 (Quick start)
대부분의 시크릿 엔진은 본래 기능을 수행하기 전에 미리 설정을 해 둬야 해요. 운영자나 설정 관리 도구가 보통 이 단계들을 수행해요.
1. HCP Terraform 시크릿 엔진을 활성화합니다.
$ vault secrets enable terraform
Success! Enabled the terraform secrets engine at: terraform/
기본적으로 시크릿 엔진은 엔진 이름과 같은 경로에 마운트돼요. 다른 경로에 활성화하려면 -path 인자를 사용하면 됩니다.
2. Vault가 HCP Terraform에 연결하고 인증하도록 구성합니다.
$ vault write terraform/config \
token=<user | team | org token>
Success! Data written to: terraform/config
Terraform Enterprise를 구성할 때 기본값 https://app.terraform.io를 재정의하려면 address 파라미터를 지정하세요.
$ vault write terraform/config \
address="https://tfe.example.com" \
token=<user | team | org token>
Success! Data written to: terraform/config
Terraform 플러그인과 함께 사용할 적절한 API 토큰을 결정하려면 HCP Terraform의 API 토큰 문서를 참고하세요. 의도한 범위와 일치하는 토큰을 선택하세요. 추가 고려 사항은 조직, 레거시 팀, 팀, 사용자 역할 섹션을 참고하세요.
3. HCP Terraform 팀에 대한 역할을 구성합니다.
Vault는 Terraform 시크릿 역할을 기존 HCP Terraform 팀에 매핑해 동적 API 토큰을 발급해요. Vault는 API 토큰 수명 주기도 관리하며 역할의 ttl과 max_ttl 설정에 따라 토큰을 자동으로 만료시켜요.
해당 클라이언트에 대한 API 토큰을 생성하려면 Terraform 팀 ID나 사용자 ID를 알아야 해요.
- 팀 ID를 찾으려면 HCP Terraform Teams API를 사용하거나 HCP Terraform GUI의 Teams 섹션으로 이동해요.
- 사용자 ID를 찾으려면 Account Details API를 사용하거나 HCP Terraform GUI에서 사용자 프로필을 확인해요.
$ vault write terraform/role/my-team-role \
team_id=team-12345abcde \
credential_type=team \
description="CI/CD automation token" \
ttl=300 \
max_ttl=1800
Success! Data written to: terraform/role/my-team-role
사용법 (Usage)
시크릿 엔진이 설정되면 적절한 권한을 가진 Vault 토큰이 단기 Team API 토큰을 생성할 수 있어요.
역할 이름으로 /creds 엔드포인트를 호출해 새 토큰을 생성해요.
$ vault read terraform/creds/my-team-role
Key Value
--- -----
lease_id terraform/creds/my-team-role/A_LEASE_ID_abc123
lease_duration 300s
lease_renewable true
token tftk.abcdef1234567890
token_id at-456defghi789
description CI/CD automation token(42)
expired_at 2025-11-08T21:30:00Z
조직, 레거시 팀, 팀, 사용자 역할
HCP Terraform은 네 가지 유형의 API 토큰을 지원해요: Organizations, Teams, Legacy Team Tokens, Users. 각 토큰 유형은 뚜렷한 접근 수준과 생성 워크플로를 가져요. 주어진 Vault 역할은 한 번에 지원되는 유형 중 하나를 관리할 수 있지만, 알아야 할 중요한 차이점이 있어요.
Terraform 플러그인의 앵커 크레덴셜을 선택할 때는 항상 의도한 사용 사례와 일치하는 범위의 토큰을 선택하세요. 사용자 토큰은 그 사용자가 소유한 리소스를 관리할 권한만 가져야 해요. 팀 토큰은 그 팀이 소유한 팀 수준 리소스를 관리할 권한만 가져야 해요. 더 좁게 정의된 범위가 Vault가 적절한 토큰을 발급하는 것을 막거나 의도한 워크플로를 방해할 때만 팀 간 권한이 있는 토큰을 만들어야 해요.
조직 역할 (Organization roles)
Vault에서 크레덴셜을 읽거나 다른 방법으로 app.terraform.io에서 생성해 새 Organization API 토큰을 생성하면, 그 Organization의 기존 API 토큰을 효과적으로 폐기해요.
이 동작 때문에 Vault가 만든 Organization API 토큰은 크레덴셜이 회전될 때까지 저장되고 이후 요청에서 반환돼요. 이는 현재 사용 중인 토큰의 의도치 않은 폐기를 막기 위해서예요.
다음은 Organization API 토큰을 관리하는 Vault 역할을 만들고 토큰을 회전하는 예시예요.
$ vault write terraform/role/testing \
organization="${TF_ORGANIZATION}" \
credential_type=organization
Success! Data written to: terraform/role/testing
$ vault write -f terraform/rotate-role/testing
Success! Data written to: terraform/rotate-role/testing
API 토큰은 역할의 크레덴셜을 읽어 얻어요.
$ vault read terraform/creds/testing
Key Value
--- -----
organization hashicorp-vault-testing
role testing
token <example token>
token_id at-fqvtdTQ5kQWcjUfG
사용자 역할 (User roles)
전통적으로 Vault 시크릿 엔진은 동적 사용자와 그 사용자에 대한 크레덴셜을 만들어요. HCP Terraform API는 동적 사용자 생성을 지원하지 않으므로, Terraform 플러그인은 기존 HCP Terraform 사용자를 관리하도록 Vault 역할을 구성해 동적 User API 토큰을 발급해요. Vault는 사용자 토큰의 수명 주기를 관리하고 역할의 ttl과 max_ttl 값에 따라 자동으로 만료시켜요. Vault는 User API 토큰을 개별 사용자 계정으로 범위를 제한해요. 결과적으로 관련 계정은 다른 사용자를 위한 토큰을 만들거나 관리할 수 없어요. 팀 간에 작동하거나 자동화 워크플로를 지원하는 토큰을 Vault가 발급해야 한다면 팀 API 토큰을 사용하세요.
terraform/role/{user} 엔드포인트는 User API 토큰을 관리하는 Vault 역할을 만들 수 있어요. 예를 들어:
$ vault write terraform/role/user-testing \
user_id="${TF_USER_ID}"
Success! Data written to: terraform/role/user-testing
역할의 크레덴셜을 읽어 API 토큰을 얻어요.
$ vault read terraform/creds/user-testing
Key Value
--- -----
role user-testing
token <example token>
token_id at-fqvtdTQ5kQWcjUfG
팀 역할 (Team roles)
HCP Terraform 시크릿 엔진은 기존 HCP Terraform 팀을 관리하도록 Vault 역할을 구성해 동적 Team API 토큰을 만들어요. 이 토큰들의 수명 주기는 Vault 및/또는 HCP Terraform이 관리해요. 일반적으로 Vault는 ttl과 max_ttl 설정에 따라 폐기 작업을 취해 외부 API의 토큰을 관리하는 것을 목표로 해요. 그 동작 외에 max_ttl을 사용하면 Vault가 HCP Terraform에 ExpiredAt 날짜를 설정해, 토큰이 max_ttl 시간에 만료되도록 보장하고 Vault가 토큰을 폐기할 수 없는 경우에도 Team 토큰이 max_ttl을 넘어 살지 않게 해요. max_ttl을 생략하면 Vault의 시스템 max_ttl이 기본값이 돼요.
HCP Terraform에서 팀 토큰은 일치하는 설명을 가질 수 없어요. 충돌을 피하기 위해 시크릿 엔진은 설명에 무작위 문자열을 접미사로 생성해요. 추가 설명을 설정하는 것을 강력히 권장해요.
예를 들어 Team API 토큰을 관리하는 Vault 역할을 만들 때 설명을 설정하려면 description 파라미터를 사용하세요.
$ vault write terraform/role/team-testing \
team_id="${TF_TEAM_ID}" \
credential_type=team \
description="testing token" \
ttl=200 \
max_ttl=600
Success! Data written to: terraform/role/team-testing
API 토큰은 역할의 크레덴셜을 읽어 얻어요.
$ vault read terraform/creds/team-testing
Key Value
--- -----
lease_id terraform/creds/team-testing/4oNxB4X0x77IrP51lBMJBiJi
lease_duration 3m20s
lease_renewable true
description testing token(74)
expired_at 2025-05-01T20:10:55Z
token <example token>
token_id at-GDMeMTvn3NhUernt
레거시 팀 역할 (Deprecated)
HCP Terraform API는 레거시 팀 역할을 주어진 시점에 활성 토큰 하나로 제한해요. Vault에서 크레덴셜을 읽거나 다른 방법으로 app.terraform.io에서 생성해 새 Legacy Team API 토큰을 생성하면, 그 Team의 기존 API 토큰을 효과적으로 폐기해요.
이 동작 때문에 Vault가 만든 Legacy Team API 토큰은 크레덴셜이 회전될 때까지 저장되고 이후 요청에서 반환돼요. 이는 현재 사용 중인 토큰의 의도치 않은 폐기를 막기 위해서예요.
다음은 Legacy Team API 토큰을 관리하는 Vault 역할을 만들고 토큰을 회전하는 예시예요.
$ vault write terraform/role/legacy-team \
team_id="${TF_TEAM_ID}" \
credential_type=team_legacy
Success! Data written to: terraform/role/legacy-team
$ vault write -f terraform/rotate-role/legacy-team
Success! Data written to: terraform/rotate-role/legacy-team
API 토큰은 역할의 크레덴셜을 읽어 얻어요.
$ vault read terraform/creds/legacy-team
Key Value
--- -----
organization n/a
role legacy-team
team_id team-<id>
token <example token>
token_id at-fqvtdTQ5kQWcjUfG
더 알아보기 (Learn more)
- Vault HCP Terraform 시크릿 엔진 전체 API는 Terraform API 문서를 참고하세요.
- Terraform 플러그인 사용에 대한 자세한 내용은 HCP Terraform 문서를 참고하세요.