네임스페이스와 마운트 경로 모범 사례

네임스페이스는 기능적으로 "Vault 안의 Vault"를 만드는 격리된 환경입니다. 별도의 로그인 경로가 있으며, 자신의 네임스페이스로 격리된 데이터를 생성·관리할 수 있습니다. 이 기능을 통해 Vault를 테넌트에게 서비스로 제공할 수 있습니다.

이 가이드는 조직 구조와 사용 사례가 주어졌을 때 Vault 네임스페이스와 마운트 경로를 구조화하는 권장 접근 방식과, 네임스페이스·경로 구조화에 대한 결정을 내리는 방법에 대한 지침을 제공합니다.

출처: 문서

본문

왜 이 주제가 중요한가요?

Vault의 모든 것은 경로 기반(path-based) 입니다. 각 경로는 Vault의 작업 또는 시크릿에 해당하며, Vault API 엔드포인트는 이러한 경로에 매핑됩니다. 따라서 정책을 작성하는 것은 특정 시크릿 경로에 허용된 작업을 구성하는 것입니다. 예를 들어 루트 네임스페이스에서 토큰 관리 접근을 부여하려면 정책 경로는 auth/token/*입니다. education 네임스페이스의 토큰을 관리하려면 정규화된 경로는 기능적으로 education/auth/token/*이 됩니다.

아래 다이어그램은 인증 메서드와 시크릿 엔진이 활성화된 위치에 따른 API 경로를 보여줍니다.

각 Vault 클라이언트 전용 네임스페이스 또는 마운트로 시크릿을 격리할 수 있습니다. 예를 들어 각 격리된 테넌트마다 네임스페이스를 만들고, 그들이 자신의 네임스페이스 아래의 리소스를 관리하도록 책임질 수 있습니다. 또는 조직 내 각 팀 전용 경로에 전용 시크릿 엔진을 마운트할 수 있습니다.

시크릿을 격리하는 방식에 따라 누가 그 시크릿을 관리할 책임이 있는지, 그리고 더 중요한 것은 그 시크릿과 관련된 정책을 누가 관리하는지가 결정됩니다.

참고: 네임스페이스 생성은 각 조직·팀·애플리케이션에 대해 격리된 환경을 설정하기 위해, root 같은 높은 권한 토큰을 가진 사용자가 수행해야 합니다.

배포 고려사항

Vault 네임스페이스, 인증 메서드 경로, 시크릿 엔진 경로를 계획·설계하려면 조직을 위해 Vault의 논리적 개체를 가장 잘 구조화하는 방법을 고려해야 합니다.

요구사항	고려할 사항
조직 구조	조직 구조는 무엇인가요? LOB(사업부), 부서, 팀, 서비스, 앱에 걸쳐 Vault의 최종 설계에 반영해야 할 세분화 수준은 어느 정도인가요?
셀프서비스 요구사항	조직 구조가 주어졌을 때 필요한 셀프서비스 수준은 어느 정도인가요? Vault 정책은 어떻게 관리되나요? 팀이 자신의 책임 범위에 대한 정책을 직접 관리해야 하나요? 아니면 정책·패턴이 템플릿화되는 추상화 계층을 통해 Vault와 상호작용하나요? 예: configuration by code, Git 흐름, Terraform Vault provider, 사용자 지정 온보딩 계층, 또는 이들의 조합.
감사 요구사항	조직 내 Vault 사용 감사에 대한 요구사항은 무엇인가요? 시크릿에 대한 접근을 정기적으로 인증(certify)할 필요가 있나요? 오래된 시크릿이나 인증 역할을 검토·폐기할 필요가 있나요? 내부 고객에 대한 차지백(chargeback) 금액을 결정할 필요가 있나요?
시크릿 엔진 요구사항	어떤 유형의 시크릿 엔진을 사용할 것인가요(KV, database, AD, PKI 등)? 대규모 조직의 경우 각각 다른 구조화 패턴이 필요할 수 있습니다. 예를 들어 KV 시크릿 엔진에서는 각 팀이 전용 KV 마운트를 가질 수 있습니다. 그러나 AD 시크릿 엔진은 본질적으로 공유 유형의 마운트이므로, 같은 연결 구성을 공유하는 여러 마운트를 두는 대신 역할 수준에서 접근을 관리하게 됩니다.

Chroot 네임스페이스

Vault 버전: chroot 리스너 기능을 사용하려면 Vault Enterprise 1.15 이상을 실행해야 합니다.

Vault 클라이언트(사용자, 애플리케이션 등)는 요청을 보낼 네임스페이스를 알고 있어야 하며, -namespace 플래그, X-Vault-Namespace HTTP 헤더, 또는 VAULT_NAMESPACE 환경 변수로 대상 네임스페이스를 설정해야 합니다. 대상 네임스페이스가 제대로 설정되지 않으면 요청이 실패합니다. 이는 번거로울 수 있습니다.

이를 단순화하기 위해 Vault 운영자는 구성 파일에 추가 리스너 스탠자를 지정하고, 대체 최상위 네임스페이스를 지정하는 chroot_namespace를 정의할 수 있습니다.

예시 (vault-config.hcl):

ui            = true
cluster_addr  = "https://127.0.0.1:8201"
api_addr      = "https://127.0.0.1:8200"
disable_mlock = true

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_1"
}

listener "tcp" {
  address       = "127.0.0.1:8200"
  tls_cert_file = "/path/to/full-chain.pem"
  tls_key_file  = "/path/to/private-key.pem"
}

listener "tcp" {
   address          = "127.0.0.1:8300"
   chroot_namespace = "usa-hq"
   tls_cert_file = "/path/to/full-chain.pem"
   tls_key_file  = "/path/to/private-key.pem"
   telemetry {
      unauthenticated_metrics_access = true
  }
}

telemetry {
  statsite_address = "127.0.0.1:8125"
  disable_hostname = true
}

chroot_namespace는 리스너 https://127.0.0.1:8300에 대한 대체 최상위 네임스페이스를 지정합니다.

예시 요청:

$ curl --header "X-Vault-Namespace: team_1" \
   --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data '{"type": "kv-v2"}' \
   https://127.0.0.1:8300/v1/sys/mounts/team-secret

리스너 주소 127.0.0.1:8300의 최상위 네임스페이스가 usa-hq로 설정되어 있으므로 이 요청은 usa-hq/team_1 네임스페이스에서 작동합니다. https://127.0.0.1:8200의 최상위 네임스페이스는 root입니다.

일반 지침

적절한 네임스페이스 또는 마운트 경로 구조를 안내하는 데 다음 원칙을 사용해야 합니다.

네임스페이스를 절약해서 사용하기
Vault ID 활용하기
Vault의 마운트 포인트 이해하기
경로의 세분화
표준화된 온보딩 과정

네임스페이스를 절약해서 사용하기

네임스페이스의 주요 목적은 관리 경계를 구분하는 것입니다. 조직 단위를 자체 네임스페이스로 캡슐화하는 주요 결정 요인은, 해당 단위가 정책을 직접 관리할 수 있어야 하는지 여부입니다. 그러나 많은 조직은 특히 Vault 소비자에게 "셀프서비스"를 제공하고 싶다면 배포 요구사항이 더 미묘하다는 것을 알게 됩니다.

Vault를 셀프서비스로 설정할 때 먼저 "셀프서비스"가 조직에 실제로 무엇을 의미하는지 물어봐야 합니다.

팀이 Vault를 직접 관리할 것인가요?
팀이 상호작용할 온보딩 과정/계층이 있을 것인가요?

가능하면 HashiCorp는 Vault를 직접 통해서가 아니라 온보딩 계층을 구현해 셀프서비스 기능을 제공하는 것을 권장합니다. 온보딩 계층은 표준 명명 규칙, 시크릿 경로 구조, 템플릿화된 정책을 강제할 수 있습니다. 이 경우 관리 경계는 조직 단위 수준이 아니라 온보딩 계층에 있습니다. 따라서 이 사용 사례는 팀을 위한 별도 네임스페이스가 필요하지 않습니다.

그러나 이러한 팀은 특정 플랫폼 팀이나 LOB에 집약될 수 있으며, 그 LOB 내 모든 팀에서 정책 구조화, 인증 방법, 시크릿 사용 사례가 공통적일 수 있습니다. 이 경우 상위 수준의 조직 단위가 자체 네임스페이스를 가지는 것이 합리적입니다.

또한 많은 경우 원하는 격리 수준의 대부분은 ACL 정책으로 강제할 수 있습니다.

전체 네임스페이스 목록은 Vault에서 단일 스토리지 항목에 들어가야 하며, 각 네임스페이스는 스토리지 공간도 필요로 하는 최소 두 개의 시크릿 엔진을 만듭니다. 네임스페이스 계획에는 스토리지 항목 크기가 허용하는 최대 네임스페이스 수 검토가 포함되어야 합니다.

Vault ID 활용하기

ACL 템플릿을 사용하려면 ID를 이해하는 것도 중요하며, 이는 정책 관리를 쉽게 해줍니다.

Vault는 엔티티를 여러 인증 메서드에 매핑하고 그룹화 기능을 제공하는 데 사용할 수 있는 내부 ID 관리 계층을 제공합니다. 이를 통해 더 강력한 정책 할당 옵션이 가능해집니다.

팁: 템플릿화된 ACL 정책 구성에 대해 알아보려면 identity alias name table 문서 페이지를 방문하세요.

인증 메서드에서 제공하는 특정 정보를 기반으로 한 엔티티 별칭(alias)은 사용자가 만드는 ID 엔티티에 매핑됩니다. 정책 템플릿과 시크릿 경로·역할의 명명 규칙 결정의 일부로 별칭·엔티티에 대해 생성된 기본 이름과 관련 메타데이터를 사용할 수 있습니다. 이를 통해 특정 패턴을 널리 따르는 사용 사례에 대해 하드코딩된 정책을 피할 수 있습니다.

공통 권한을 가져야 하는 엔티티를 연결하기 위해 ID 그룹을 정의하고, 엔티티·별칭만큼 정책 템플릿에서 그 그룹을 참조할 수 있습니다. 사용되는 인증 메서드에 따라 이러한 그룹이 자동으로 생성될 수도 있습니다.

ACL 정책 템플릿 예시:

path "kvv1-{{identity.entity.metadata.team_name}}/*" {
   capabilities = [ "create", "read", "update", "delete", "list" ]
}

path "transit/encrypt/{{identity.entity.aliases.auth_approle_b2560218.name}}" {
   capabilities = [ "update" ]
}

이 템플릿화된 값은 요청자의 엔티티 토큰 메타데이터를 기반으로 동적으로 해석됩니다.

1행의 {{identity.entity.metadata.team_name}} 값은 엔티티의 메타데이터에 설정된 team_name 값을 가져옵니다. 마찬가지로 5행의 {{identity.entity.aliases.auth_approle_b2560218.name}} 값은 요청 클라이언트의 Role ID를 반환합니다. 이를 통해 정책이 덜 정적일 수 있습니다.

참고: Vault가 보고·라이선싱 목적의 활성 클라이언트 수를 결정하는 방식이 ID 엔티티 수입니다. 자세한 내용은 Client Count 문서를 참고하세요.

팁: 템플릿화된 정책에 익숙하지 않다면 ACL Policy Path Templating 튜토리얼을 읽어보세요.

Vault의 마운트 포인트 이해하기

인증 메서드와 시크릿 엔진은 두 가지 유형으로 분류할 수 있습니다.

전용 (Dedicated): 특정 조직 단위에 직접 관리·매핑될 수 있는 인증 메서드와 시크릿 엔진. 예를 들어 app-1을 관리하는 팀은 다른 팀의 마운트에 영향을 줄 수 없으면서 자신의 AppRole 및/또는 KV 마운트를 활용할 수 있습니다.
공유 (Shared): Kubernetes 인증 메서드와 Active Directory(AD) 시크릿 엔진처럼 회사 수준에서 공유·관리되는 조직 수준의 리소스. 따라서 회사 수준 네임스페이스에 마운트됩니다.

Vault의 마운트 크기 제한을 이해하는 것이 중요합니다. 모든 시크릿 엔진·인증 메서드 마운트 포인트는 각각 단일 스토리지 항목에 들어가야 합니다. Consul의 경우 스토리지 한도는 512KB입니다. 통합 스토리지의 경우 한도는 1MB입니다.

마운트를 설명하는 각 JSON 개체는 ~500바이트를 사용하지만, 압축된 형태로는 ~75바이트입니다. 인증 마운트, 시크릿 엔진 마운트 포인트, 로컬 전용 인증 메서드, 로컬 전용 시크릿 엔진 마운트는 별도로 저장되므로 한도는 각각에 독립적으로 적용됩니다.

기본적으로 각 네임스페이스는 토큰 인증 마운트(/auth/), ID 마운트(/identity/), 시스템 마운트(/sys/)로 생성됩니다. 즉 각 네임스페이스는 세 개의 다른 마운트가 필요하고 여기에 사용자 지정 마운트를 추가합니다. 여기에 수천을 곱하면 마운트 테이블이 기하급수적으로 커집니다.

경로의 세분화

Vault의 논리적 구조를 생각할 때, 필요한 다양한 마운트와 마운트 내 정의된 역할 사이에서 올바른 세분화 균형을 찾아야 합니다.

팀 간 마운트 공유에는 이점과 위험이 있습니다. 필요한 다양한 마운트와 마운트 내 정의된 역할 사이의 올바른 세분화 균형을 찾는 것은 사용자의 몫입니다. 아래에 이점과 위험이 있는 몇 가지 사용 사례가 있습니다.

같은 마운트 내에서 모든 팀에 하위 경로를 두고 단일 KV 마운트를 만듭니다.

이점: 마운트 테이블 한도에 도달할 가능성을 줄입니다.
위험: KV 마운트가 실수로 삭제되면 그 시크릿 엔진의 모든 사용자가 영향을 받습니다.

LOB별 고유 마운트를 만듭니다.

이점: 다른 팀을 위한 하위 경로를 제공하고 잘못된 변경의 폭발 반경(blast-radius)을 단일 마운트로 제한할 수 있습니다.
위험: 팀별 고유 KV 마운트는 마운트 관리 관점에서 비효율적이 됩니다.

표준화된 온보딩 과정

Vault를 대규모로 배포할 때는 소비자 경험을 고려하는 것이 Vault 도입에 중요합니다. 구체적으로, Vault 소비의 마찰 수준을 줄이는 것이 중요합니다. 환경에 Vault를 빠르게 배치하고 직접 상호작용하는 것은 빠를 수 있지만, 소비자가 Vault를 어떻게 온보딩하고 서비스를 소비할지 의도적으로 매핑하는 것이 중요합니다.

HashiCorp의 핵심 기둥 중 하나는 코드화를 통한 자동화(automation through codification) 입니다. 많은 HashiCorp 사용자가 온프레미스와 클라우드의 인프라 관리를 위해 Terraform을 사용하고 있습니다. Terraform은 네임스페이스·정책·마운트 생성 같은 Vault 구성 작업을 코드화하는 데도 사용할 수 있습니다. 이를 통해 Vault 운영자는 생산성을 높이고, 더 빠르게 움직이며, 반복 가능한 과정을 촉진하고, 사람의 실수를 줄일 수 있습니다.

튜토리얼

더 알아보려면 다음 튜토리얼을 검토하세요.

Secure multi-tenancy with namespaces
Manage secrets across namespaces

네임스페이스와 마운트 경로 모범 사례