서비스 주체

서비스 주체 (Service principals)

HCP(HashiCorp Cloud Platform)에서 애플리케이션, 호스팅 서비스, 자동화 도구의 서비스 요청을 인증하기 위해 서비스 주체(service principal)를 사용하는 방법을 설명해 드릴게요.

서비스 주체는 하나의 조직에만 연결할 수 있고, 서비스 주체에 역할 기반 권한을 할당해 HCP에서 특정 작업을 수행할 수 있게 할 수 있어요. 자세한 내용은 user permissions 문서를 참고하세요.

출처: 문서

본문

서비스 주체 유형 (Types of service principals)

서비스 주체는 조직 수준(organization-level) 또는 프로젝트 수준(project-level)으로 만들 수 있어요. 이 섹션에서는 두 유형에 대한 개요, 각 유형을 만드는 방법, 각 유형을 삭제하는 방법을 설명할게요.

서비스 주체를 사용하려면 해당하는 서비스 주체 키(service principal key)도 함께 만들어야 해요. 자세한 내용은 service principal keys 문서를 참고하세요.

조직 수준 서비스 주체 (Organization-level service principals)

조직 수준 서비스 주체는 조직 내의 모든 리소스와 프로젝트와 상호작용하도록 범위가 정해져요. 예를 들어 viewer 권한이 있는 조직 수준 서비스 주체는 조직 내 모든 프로젝트의 모든 리소스를 볼 수 있어요.

조직 수준에서 역할을 할당해 조직 수준 서비스 주체에 추가 권한을 부여할 수 있어요. 이렇게 하면 단일 조직 수준 서비스 주체가 여러 프로젝트에 걸쳐 리소스를 관리하거나 새 프로젝트 생성 같은 조직 전체 작업까지 수행할 수 있어요.

프로젝트 수준 서비스 주체 (Project-level service principals)

프로젝트 수준 서비스 주체는 조직에서 특정 프로젝트 내의 리소스와 상호작용하도록 설계돼요. 기본적으로 만들어진 프로젝트의 리소스에만 접근할 수 있어요.

다른 프로젝트나 조직 수준에서 역할을 할당해 프로젝트 수준 서비스 주체에 추가 권한을 부여할 수 있어요. 이렇게 하면 단일 프로젝트 수준 서비스 주체가 여러 프로젝트에 걸쳐 리소스를 관리하거나 새 프로젝트 생성 같은 조직 전체 작업까지 수행할 수 있어요.

이 기능은 프로젝트 수준 서비스 주체를 요구하는 워크로드 아이덴티티 페더레이션(workload identity federation)을 사용하는 자동화 워크플로에서 특히 중요해요. 프로젝트 수준 서비스 주체에 조직 수준 역할(Project Creator 또는 Group Admin 등)을 할당하면, 장기(long-lived) 조직 수준 정적 키 없이도 전체 HCP 인프라를 자동화할 수 있어요.

예시:

Dev-Infra 프로젝트에 만들어진 automation-sp라는 프로젝트 수준 서비스 주체를 상상해 보세요.

• 자신의 홈 프로젝트인 Dev-Infra에서는 Contributor 역할을 가질 수 있어요.
• Prod-Infra 프로젝트에서는 Viewer 역할을 할당받아 프로덕션 리소스를 변경하지 않고 읽을 수 있어요 (교차 프로젝트 역할 할당을 통해).
• 조직 수준의 Project Creator 역할을 할당받아 워크로드 아이덴티티 페더레이션을 사용하는 자동화 스크립트로 개발 팀용 새 프로젝트를 프로비저닝할 수 있어요.

이 시나리오에서 단일 프로젝트 수준 서비스 주체가 최소 권한(least privilege) 원칙을 지키면서 조직 전체에 걸쳐 유연한 권한 조합을 갖게 돼요.

워크로드 아이덴티티 페더레이션을 구성할 때는 반드시 프로젝트 수준 서비스 주체를 사용해야 해요.

서비스 주체 만들기

조직 수준과 프로젝트 수준 서비스 주체를 만드는 단계는 비슷해요.

조직 수준 서비스 주체

HCP UI / HCP CLI / Terraform

1. https://portal.cloud.hashicorp.com에 로그인하고 조직을 선택해요.
2. Access control (IAM) 을 클릭해요.
3. Service principals를 클릭해요.
4. Create service principal을 클릭해요.
5. 서비스 주체 이름을 입력하고 원하는 scope와 역할을 선택해요.
6. Create service principal을 클릭해요.

hcp iam service-principals create 명령을 사용해 서비스 주체를 만들어요. 다음 예시는 example-sp라는 서비스 주체를 만들어요.

$ hcp iam service-principals create iam/organization/d3e891e7-35c5-4ffb-a192-567e02ec566f/service-principal/example-sp

hcp_service_principal 리소스를 사용해요.

data "hcp_organization" "my_org" {
}

resource "hcp_service_principal" "example" {
  name   = "workload-sp"
  parent = data.hcp_organization.my_org.resource_name
}

프로젝트 수준 서비스 주체

HCP UI / HCP CLI / Terraform

1. https://portal.cloud.hashicorp.com에 로그인하고 조직을 선택해요.
2. Projects를 클릭한 다음 서비스 주체를 만들 프로젝트를 선택해요.
3. Access control (IAM) 을 클릭해요.
4. Service principals를 클릭해요.
5. Create service principal을 클릭해요.
6. 서비스 주체 이름을 입력하고 원하는 scope와 역할을 선택해요.
7. Create service principal을 클릭해요.

hcp iam service-principals create 명령을 사용해 서비스 주체를 만들어요. 다음 예시는 example-sp라는 프로젝트 수준 서비스 주체를 만들어요.

$ hcp iam service-principals create iam/project/d3e891e7-35c5-4ffb-a192-567e02ec566f/service-principal/example-sp

hcp_service_principal 리소스를 사용해요.

resource "hcp_project" "my_proj" {
  name = "platform-dev"
}

resource "hcp_service_principal" "example" {
  name   = "workload-sp"
  parent = hcp_project.my_proj.resource_name
}

교차 프로젝트 서비스 주체 (Cross project service principals)

HCP UI / Terraform

1. 위에서 보여준 대로 프로젝트에 서비스 주체를 만들어요.
2. 서비스 주체에게 접근 권한을 주려는 다른 프로젝트를 선택해요.
3. Access control (IAM) 을 클릭해요.
4. Add new assignment를 클릭해요.
5. 검색 상자에서 이름 또는 ID로 서비스 주체를 검색해요. 이름으로 검색하면 해당 이름을 포함하는 조직의 모든 서비스 주체와 조직 내 모든 프로젝트의 서비스 주체 드롭다운이 표시돼요.
6. 드롭다운 목록에서 서비스 주체를 선택해요.
7. Select service와 Select role(s) 두 드롭다운 목록에서 서비스 주체에게 할당할 서비스 역할을 선택해요.
8. Save를 클릭해요.
9. 서비스 주체는 역할 할당 목록에 아이콘과 함께 표시되는데, 아이콘 위에 커서를 올리면 Cross-project 태그가 보여요.

hcp_service_principal 리소스를 사용해요.

resource "hcp_project" "first_project" {
  name = "example-first-project"
}

resource "hcp_service_principal" "sp" {
  name   = "example-first-project-sp"
  parent = hcp_project.first_project.resource_name
}

resource "hcp_project" "second_project" {
  name = "example-second-project"
}

resource "hcp_project_iam_binding" "example" {
  project_id   = hcp_project.second_project.resource_id
  principal_id = hcp_service_principal.sp.resource_id
  role         = "roles/contributor"
}

서비스 주체 삭제

조직 수준과 프로젝트 수준 서비스 주체를 삭제하는 단계는 비슷해요.

서비스 주체를 삭제하려면 먼저 그와 연결된 모든 키를 삭제해야 해요.

조직 수준 서비스 주체

HCP UI / HCP CLI / Terraform

1. https://portal.cloud.hashicorp.com에 로그인하고 조직을 선택해요.
2. Access control (IAM) 을 클릭해요.
3. Service principals를 클릭해요.
4. 삭제하려는 특정 서비스 주체 옆의 드롭다운을 클릭해요.
5. Delete service principal을 클릭해요.
6. 표시된 필드에 DELETE를 입력하고 Delete를 클릭해요.

hcp iam service-principals delete 명령을 사용해 서비스 주체를 삭제해요. 다음 예시는 example-sp라는 서비스 주체를 삭제해요.

$ hcp iam service-principals delete iam/organization/d3e891e7-35c5-4ffb-a192-567e02ec566f/service-principal/example-sp

-target 플래그와 함께 terraform destroy 명령을 사용해요.

$ terraform destroy -target "hcp_service_principal.example"

프로젝트 수준 서비스 주체

HCP UI / HCP CLI / Terraform

1. https://portal.cloud.hashicorp.com에 로그인하고 조직을 선택해요.
2. Projects를 클릭하고 서비스 주체를 만들 원하는 프로젝트를 선택해요.
3. Access control (IAM) 을 클릭해요.
4. Service principals를 클릭해요.
5. 삭제하려는 특정 서비스 주체 옆의 드롭다운을 클릭해요.
6. Delete service principal을 클릭해요.
7. 표시된 필드에 DELETE를 입력하고 Delete를 클릭해요.

hcp iam service-principals delete 명령을 사용해 서비스 주체를 삭제해요. 다음 예시는 example-sp라는 프로젝트 수준 서비스 주체를 삭제해요.

$ hcp iam service-principals delete iam/project/d3e891e7-35c5-4ffb-a192-567e02ec566f/service-principal/example-sp

-target 플래그와 함께 terraform destroy 명령을 사용해요.

$ terraform destroy -target "hcp_service_principal.example"

더 알아보기 (Learn more)

• 서비스 주체 키 (Service principal key) — 서비스 주체 인증 키를 생성·삭제하는 방법을 확인해 보세요.
• 워크로드 아이덴티티 페더레이션 — 외부 IdP 워크로드를 HCP에 연결하는 방법을 알아보세요.
• 접근 관리 (Access Management) — 역할과 권한 체계를 자세히 살펴보세요.