본문 바로가기
WIKI 기술 지식 베이스

시크릿 관리 (Secrets Management)

원문 보기 위키 갱신

Datadog Agent가 AWS Secrets Manager, HashiCorp Vault, Kubernetes Secrets 같은 다양한 시크릿 관리 솔루션과 연동해 민감 정보를 안전하게 관리하고, 설정에서 시크릿을 동적으로 참조하는 방법을 알려드릴게요.

출처: 문서

본문

개요 (Overview)

Datadog Agent는 다음 시크릿 관리 솔루션과의 연동을 통해 시크릿을 안전하게 관리하도록 도와줘요:

  • AWS Secrets Manager
  • AWS SSM
  • Azure KeyVault
  • GCP Secret Manager
  • HashiCorp Vault
  • Kubernetes Secrets
  • Docker Secrets
  • File Text
  • File JSON
  • File YAML
  • Windows Registry Key

API 키나 비밀번호 같은 민감한 값을 설정 파일에 평문으로 하드코딩하는 대신, Agent가 런타임에 동적으로 가져올 수 있어요. 설정에서 시크릿을 참조하려면 ENC[<secret_id>] 표기법을 사용하세요. 시크릿은 가져와서 메모리에 로드되지만 디스크에 기록되거나 Datadog 백엔드로 전송되지는 않아요.

참고: secret_backend_command 같은 secret_* 설정에서는 ENC[] 구문을 사용할 수 없어요.

시크릿 조회 옵션 (Options for retrieving secrets)

옵션 1: 시크릿 조회를 위한 네이티브 Agent 지원 사용

참고:

  • Agent 7.70+: 네이티브 시크릿 관리 지원 도입.
  • Agent 7.76+: FIPS 활성화 Agent에서 네이티브 시크릿 관리 사용 가능.
  • Agent 7.77+: Cluster Agent는 컨테이너 환경에서 Agent 7.77 이상이 필요해요. 이전 버전은 옵션 2나 옵션 3을 대신 사용하세요.
  • Agent 7.80+: 여러 백엔드 지원.

단일 백엔드 (Single backend)

datadog.yaml에서 secret_backend_type과 secret_backend_config를 사용해 단일 시크릿 백엔드를 구성하세요:

# datadog.yaml

secret_backend_type: <backend_type>
secret_backend_config:
  <KEY_1>: <VALUE_1>

더 구체적인 설정 지침은 사용하는 백엔드 유형에 따라 달라져요. 자세한 내용은 아래 해당 섹션을 참고하세요:

AWS 시크릿 (AWS Secrets)

다음 AWS 서비스가 지원돼요:

secret_backend_type 값 AWS 서비스
aws.secrets AWS Secrets Manager
인스턴스 프로필 설정하기

Datadog은 인스턴스 프로필 방식으로 시크릿을 조회할 것을 권장해요. AWS가 모든 환경 변수와 세션 프로필을 처리해 주기 때문이에요. 이에 대한 더 자세한 지침은 공식 AWS Secrets Manager 문서에서 확인할 수 있어요.

구성 예시

Agent YAML 파일 — 다음 구성을 사용해 Datadog Agent가 AWS Secrets로 시크릿을 해석하도록 구성하세요:

# datadog.yaml
secret_backend_type: aws.secrets
secret_backend_config:
  aws_session:
    aws_region: {regionName}

환경 변수를 사용하면 구성을 다음과 같이 JSON으로 변환해요:

DD_SECRET_BACKEND_TYPE="aws.secrets"
DD_SECRET_BACKEND_CONFIG='{"aws_session":{"aws_region":"<AWS_REGION>"}}'

Agent가 AWS Secrets를 사용하도록 구성한 뒤에는 설정에서 ENC[secretId;secretKey]로 시크릿을 참조할 수 있어요.

ENC 표기법은 다음으로 구성돼요:

  • secretId: 시크릿의 "친숙한 이름"(예: /DatadogAgent/Production) 또는 ARN(예: arn:aws:secretsmanager:us-east-1:123456789012:secret:/DatadogAgent/Production-FOga1K).
    • 참고: AWS 자격 증명이나 sts:AssumeRole 자격 증명이 정의된 다른 계정에서 시크릿에 접근할 때는 전체 ARN 형식이 필요해요.
  • secretKey: 사용하려는 AWS 시크릿의 JSON 키.

AWS Secrets Manager는 단일 시크릿 안에 여러 키-값 쌍을 저장할 수 있어요. Secrets Manager를 사용하는 백엔드 구성은 시크릿에 정의된 모든 키에 접근할 수 있어요.

예를 들어 시크릿 ID My-Secrets가 다음 3개 값을 포함한다고 가정해요:

{
    "prodApiKey": "datadog api key to use",
    "anotherSecret1": "value2",
    "anotherSecret2": "value3",
}

다음은 AWS Secrets를 사용해 My-Secrets에서 API 키를 가져오는 datadog.yaml 구성 파일의 전체 예시예요:

api_key: ENC[My-Secrets;prodApiKey]

secret_backend_type: aws.secrets
secret_backend_config:
  aws_session:
    aws_region: us-east-1
모든 aws_session 옵션

다음 aws_session 필드는 Agent가 AWS에 인증하는 방식을 구성해요. 모든 필드는 선택 사항이며, 아무것도 설정하지 않으면 Agent는 기본 자격 증명 체인(인스턴스 프로필, 환경 변수, 공유 구성 파일 등)을 사용해요.

필드 설명
aws_region AWS 리전 (예: us-east-1).
aws_access_key_id 정적 AWS 액세스 키 ID. aws_secret_access_key와 함께 사용.
aws_secret_access_key 정적 AWS 시크릿 액세스 키. aws_access_key_id와 함께 사용.
aws_profile 공유 AWS Config 파일(~/.aws/config)의 명명된 프로필.
aws_role_arn sts:AssumeRole로 가정할 IAM 역할 ARN.
aws_external_id 크로스 계정 역할을 가정할 때 전달할 External ID.
force_string 옵션

secret_backend_config의 최상위에서 force_string: true를 설정하면 원시 시크릿 문자열을 JSON으로 파싱하지 않고 반환해요. 시크릿이 JSON 객체가 아니라 평문으로 저장된 경우 유용해요.

secret_backend_type: aws.secrets
secret_backend_config:
  force_string: true
  aws_session:
    aws_region: us-east-1

Helm — 다음 구성을 사용해 Helm에서 Datadog Agent가 AWS Secrets로 시크릿을 해석하도록 구성하세요:

통합 체크 (Integration check)
datadog:
  secretBackend:
    type: "aws.secrets"
    config:
      aws_session:
        aws_region: "<AWS_REGION>"
  confd:
  # This is an example
    <INTEGRATION_NAME>.yaml: |-
      ad_identifiers:
        - <SHORT_IMAGE>
      instances:
        - [...]
          password: "ENC[secretId;secretKey]"
agents:
  rbac:
    # IAM role ARN required to grant the Agent permissions to access the AWS secret
    serviceAccountAnnotations:
      eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>

Agent가 AWS 시크릿에 접근할 수 있는 권한을 부여하려면 serviceAccountAnnotations를 포함해야 해요.

클러스터 체크: 클러스터 체크 러너 미활성화 시
datadog:
  secretBackend:
    type: "aws.secrets"
    config:
      aws_session:
        aws_region: "<AWS_REGION>"
agents:
  rbac:
    # IAM role ARN required to grant the Agent permissions to access the AWS secret
    serviceAccountAnnotations:
      eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>
clusterAgent:
  confd:
    # This is an example
    <INTEGRATION_NAME>.yaml: |-
      cluster_check: true
      instances:
        - [...]
          password: "ENC[secretId;secretKey]"
클러스터 체크: 클러스터 체크 러너 활성화 시
datadog:
  secretBackend:
    type: "aws.secrets"
    config:
      aws_session:
        aws_region: "<AWS_REGION>"
clusterAgent:
  confd:
  # This is an example
    <INTEGRATION_NAME>.yaml: |-
      cluster_check: true
      instances:
        - [...]
          password: "ENC[secretId;secretKey]"
clusterChecksRunner:
  enabled: true
  rbac:
    # IAM role ARN required to grant the Agent permissions to access the AWS secret
    serviceAccountAnnotations:
      eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>

Operator — 다음 구성을 사용해 Datadog Operator로 Datadog Agent가 AWS Secrets로 시크릿을 해석하도록 구성하세요:

참고: 네이티브 secretBackend 필드에는 Datadog Operator v1.29.0+가 필요해요.

통합 체크 (Integration check)
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "aws.secrets"
      config:
        aws_session:
          aws_region: <AWS_REGION>
  override:
    nodeAgent:
      # IAM role ARN is required to grant the Agent permissions to access the AWS secret
      serviceAccountAnnotations:
        eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            ad_identifiers:
              - <SHORT_IMAGE>
            instances:
              - [...]
                 password: "ENC[secretId;secretKey]"

Agent가 AWS 시크릿에 접근할 수 있는 권한을 부여하려면 serviceAccountAnnotations를 포함해야 해요.

클러스터 체크: 클러스터 체크 러너 미활성화 시
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "aws.secrets"
      config:
        aws_session:
          aws_region: <AWS_REGION>
  override:
    nodeAgent:
      # IAM role ARN required to grant the Agent permissions to access the AWS secret
      serviceAccountAnnotations:
        eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>
    clusterAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            cluster_check: true
            instances:
              - [...]
                password: "ENC[secretId;secretKey]"
클러스터 체크: 클러스터 체크 러너 활성화 시
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "aws.secrets"
      config:
        aws_session:
          aws_region: <AWS_REGION>
  features:
    clusterChecks:
      useClusterChecksRunners: true
  override:
    [...]
    clusterChecksRunner:
      # IAM role ARN required to grant the Agent permissions to access the AWS secret
      serviceAccountAnnotations:
        eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>
    clusterAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            cluster_check: true
            instances:
              - [...]
                password: "ENC[secretId;secretKey]"

또는, 네이티브 spec.global.secretBackend.type 및 spec.global.secretBackend.config 필드 대신 DD_SECRET_BACKEND_TYPE과 DD_SECRET_BACKEND_CONFIG 환경 변수를 사용할 수 있어요. 예: DD_SECRET_BACKEND_TYPE="aws.secrets" 및 DD_SECRET_BACKEND_CONFIG='{"aws_session":{"aws_region":"<AWS_REGION>"}}'.

AWS SSM

다음 AWS 서비스가 지원돼요:

secret_backend_type 값 AWS 서비스
aws.ssm AWS Systems Manager Parameter Store
인스턴스 프로필 설정하기

Datadog은 인스턴스 프로필 방식으로 시크릿을 조회할 것을 권장해요. AWS가 모든 환경 변수와 세션 프로필을 처리해 주기 때문이에요. 이에 대한 더 자세한 지침은 공식 AWS Secrets Manager 문서에서 확인할 수 있어요.

구성 예시

Agent YAML 파일 — AWS System Manager Parameter Store는 계층 구조 모델을 지원해요. 예를 들어 다음 AWS System Manager Parameter Store 경로를 가정해요:

/DatadogAgent/Production/ApiKey = <your_api_key>
/DatadogAgent/Production/ParameterKey2 = ParameterStringValue2
/DatadogAgent/Production/ParameterKey3 = ParameterStringValue3

파라미터는 다음과 같이 가져올 수 있어요:

# datadog.yaml
secret_backend_type: aws.ssm
secret_backend_config:
  aws_session:
    aws_region: us-east-1

api_key: "ENC[/DatadogAgent/Production/ApiKey]"
property1: "ENC[/DatadogAgent/Production/ParameterKey1]"
property2: "ENC[/DatadogAgent/Production/ParameterKey2]"
모든 aws_session 옵션

다음 aws_session 필드는 Agent가 AWS에 인증하는 방식을 구성해요. 모든 필드는 선택 사항이며, 아무것도 설정하지 않으면 Agent는 기본 자격 증명 체인(인스턴스 프로필, 환경 변수, 공유 구성 파일 등)을 사용해요.

필드 설명
aws_region AWS 리전 (예: us-east-1).
aws_access_key_id 정적 AWS 액세스 키 ID. aws_secret_access_key와 함께 사용.
aws_secret_access_key 정적 AWS 시크릿 액세스 키. aws_access_key_id와 함께 사용.
aws_profile 공유 AWS Config 파일(~/.aws/config)의 명명된 프로필.
aws_role_arn sts:AssumeRole로 가정할 IAM 역할 ARN.
aws_external_id 크로스 계정 역할을 가정할 때 전달할 External ID.

Helm — 다음 구성을 사용해 Helm에서 Datadog Agent가 AWS SSM으로 시크릿을 해석하도록 구성하세요:

통합 체크 (Integration check)
datadog:
  secretBackend:
    type: "aws.ssm"
    config:
      aws_session:
        aws_region: "<AWS_REGION>"
    enableGlobalPermissions: true
  confd:
  # This is an example
    <INTEGRATION_NAME>.yaml: |-
      ad_identifiers:
        - <SHORT_IMAGE>
      instances:
        - [...]
          password: "ENC[/DatadogAgent/Production/ParameterKey]"
agents:
  rbac:
    # IAM role ARN required to grant the Agent permissions to access the AWS SSM parameter
    serviceAccountAnnotations:
      eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>

Agent가 AWS SSM 파라미터에 접근할 수 있는 권한을 부여하려면 serviceAccountAnnotations를 포함해야 해요.

클러스터 체크: 클러스터 체크 러너 미활성화 시
datadog:
  secretBackend:
    type: "aws.ssm"
    config:
      aws_session:
        aws_region: "<AWS_REGION>"
    enableGlobalPermissions: true
agents:
  rbac:
    # IAM role ARN required to grant the Agent permissions to access the AWS SSM parameter
    serviceAccountAnnotations:
      eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>
clusterAgent:
  confd:
    # This is an example
    <INTEGRATION_NAME>.yaml: |-
      cluster_check: true
      instances:
        - [...]
          password: "ENC[/DatadogAgent/Production/ParameterKey]"
클러스터 체크: 클러스터 체크 러너 활성화 시
datadog:
  secretBackend:
    type: "aws.ssm"
    config:
      aws_session:
        aws_region: "<AWS_REGION>"
    enableGlobalPermissions: true
clusterAgent:
  confd:
  # This is an example
    <INTEGRATION_NAME>.yaml: |-
      cluster_check: true
      instances:
        - [...]
          password: "ENC[/DatadogAgent/Production/ParameterKey]"
clusterChecksRunner:
  enabled: true
  rbac:
    # IAM role ARN required to grant the Agent permissions to access the AWS SSM parameter
    serviceAccountAnnotations:
      eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>

Operator — 다음 구성을 사용해 Datadog Operator로 Datadog Agent가 AWS SSM으로 시크릿을 해석하도록 구성하세요:

참고: 네이티브 secretBackend 필드에는 Datadog Operator v1.29.0+가 필요해요.

통합 체크 (Integration check)
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "aws.ssm"
      config:
        aws_session:
          aws_region: <AWS_REGION>
  override:
    nodeAgent:
      # IAM role ARN is required to grant the Agent permissions to access the AWS SSM parameter
      serviceAccountAnnotations:
        eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            ad_identifiers:
              - <SHORT_IMAGE>
            instances:
              - [...]
                password: "ENC[/DatadogAgent/Production/ParameterKey]"

Agent가 AWS SSM 파라미터에 접근할 수 있는 권한을 부여하려면 serviceAccountAnnotations를 포함해야 해요.

클러스터 체크: 클러스터 체크 러너 미활성화 시
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "aws.ssm"
      config:
        aws_session:
          aws_region: <AWS_REGION>
  override:
    nodeAgent:
      # IAM role ARN required to grant the Agent permissions to access the AWS SSM parameter
      serviceAccountAnnotations:
        eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>
    clusterAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            cluster_check: true
            instances:
              - [...]
                password: "ENC[/DatadogAgent/Production/ParameterKey]"
클러스터 체크: 클러스터 체크 러너 활성화 시
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "aws.ssm"
      config:
        aws_session:
          aws_region: <AWS_REGION>
  features:
    clusterChecks:
      useClusterChecksRunners: true
  override:
    [...]
    clusterChecksRunner:
      # IAM role ARN required to grant the Agent permissions to access the AWS SSM parameter
      serviceAccountAnnotations:
        eks.amazonaws.com/role-arn: <IAM_ROLE_ARN>
    clusterAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            cluster_check: true
            instances:
              - [...]
                password: "ENC[/DatadogAgent/Production/ParameterKey]"

또는, 네이티브 spec.global.secretBackend.type 및 spec.global.secretBackend.config 필드 대신 DD_SECRET_BACKEND_TYPE과 DD_SECRET_BACKEND_CONFIG 환경 변수를 사용할 수 있어요. 예: DD_SECRET_BACKEND_TYPE="aws.ssm" 및 DD_SECRET_BACKEND_CONFIG='{"aws_session":{"aws_region":"<AWS_REGION>"}}'.

Azure Keyvault 백엔드

다음 Azure 서비스가 지원돼요:

secret_backend_type 값 Azure 서비스
azure.keyvault Azure Keyvault
Azure 인증

Datadog은 Azure 인증에 Managed Identities 사용을 권장해요. 이렇게 하면 클라우드 리소스를 AMI 계정과 연결할 수 있고 datadog.yaml 구성 파일에 민감한 정보를 넣을 필요가 없어져요.

관리 ID (Managed identity)

Key Vault에 접근하려면 Managed Identity를 만들고 Virtual Machine에 할당하세요. 그런 다음 Key Vault에 적절한 역할 할당을 구성해 해당 ID가 시크릿에 접근할 수 있게 하세요.

구성 예시

Agent YAML 파일 — Azure Key Vault 시크릿의 백엔드 구성은 다음 스키마를 따르는 YAML로 구조화돼요:

# datadog.yaml
secret_backend_type: azure.keyvault
secret_backend_config:
  keyvaulturl: {keyVaultURL}
  azure_session:
    azure_client_id: {clientID}  # User-assigned managed identity client ID; omit this field for system-assigned

환경 변수를 사용하면 구성을 JSON으로 변환해요:

DD_SECRET_BACKEND_TYPE="azure.keyvault"
DD_SECRET_BACKEND_CONFIG='{"keyvaulturl": "<keyVaultURL>", "azure_session": {"azure_client_id": "<CLIENT_ID>"}}'

백엔드 시크릿은 Datadog Agent 구성 파일에서 ENC[ ]로 참조돼요. 다음은 평문 시크릿을 가져와야 하는 예시예요:

# datadog.yaml

api_key: "ENC[secretKeyNameInKeyVault]"
모든 azure_session 옵션

다음 azure_session 필드는 Agent가 Azure에 인증하는 방식을 제어해요. 모든 필드는 선택 사항이며, 아무것도 설정하지 않으면 Agent는 Default Azure Credential(환경 변수, Workload Identity, 시스템 할당 Managed Identity, Azure CLI 등)로 폴백해요.

필드 설명
azure_client_id 사용자 할당 Managed Identity 또는 서비스 주체의 Client ID.
azure_tenant_id 서비스 주체 인증을 위한 Tenant ID. azure_client_id와 클라이언트 시크릿 또는 인증서와 함께 필요.
azure_client_secret 서비스 주체 인증을 위한 클라이언트 시크릿.
azure_client_certificate_path 서비스 주체 인증서 인증을 위한 PEM 또는 PKCS12 인증서 파일 경로.
azure_client_certificate_password 인증서 파일의 비밀번호(비밀번호로 보호되는 경우).
azure_client_send_certificate_chain 인증서 인증 시 전체 인증서 체인을 보내려면 true로 설정.

인증은 제공된 필드를 기반으로 선택돼요:

  • 시크릿이 있는 서비스 주체: azure_tenant_id + azure_client_id + azure_client_secret
  • 인증서가 있는 서비스 주체: azure_tenant_id + azure_client_id + azure_client_certificate_path
  • 사용자 할당 Managed Identity: azure_client_id만
  • Default Azure Credential (권장): 모든 azure_session 필드 생략

Helm — 다음 구성을 사용해 Helm에서 Datadog Agent가 Azure Key Vault로 시크릿을 해석하도록 구성하세요:

통합 체크 (Integration check)
datadog:
  secretBackend:
    type: "azure.keyvault"
    config:
      keyvaulturl: "<keyVaultURL>"
      azure_session:
        azure_client_id: "<CLIENT_ID>"
  confd:
  # This is an example
    <INTEGRATION_NAME>.yaml: |-
      ad_identifiers:
        - <SHORT_IMAGE>
      instances:
        - [...]
          password: "ENC[secretKeyNameInKeyVault]"
클러스터 체크: 클러스터 체크 러너 미활성화 시
datadog:
  secretBackend:
    type: "azure.keyvault"
    config:
      keyvaulturl: "<keyVaultURL>"
      azure_session:
        azure_client_id: "<CLIENT_ID>"
clusterAgent:
  confd:
    # This is an example
    <INTEGRATION_NAME>.yaml: |-
      cluster_check: true
      instances:
        - [...]
          password: "ENC[secretKeyNameInKeyVault]"
클러스터 체크: 클러스터 체크 러너 활성화 시
datadog:
  secretBackend:
    type: "azure.keyvault"
    config:
      keyvaulturl: "<keyVaultURL>"
      azure_session:
        azure_client_id: "<CLIENT_ID>"
clusterAgent:
  confd:
  # This is an example
    <INTEGRATION_NAME>.yaml: |-
      cluster_check: true
      instances:
        - [...]
          password: "ENC[secretKeyNameInKeyVault]"
clusterChecksRunner:
  enabled: true

Operator — 다음 구성을 사용해 Datadog Operator로 Datadog Agent가 Azure Key Vault로 시크릿을 해석하도록 구성하세요:

참고: 네이티브 secretBackend 필드에는 Datadog Operator v1.29.0+가 필요해요.

통합 체크 (Integration check)
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "azure.keyvault"
      config:
        keyvaulturl: <KEY_VAULT_URL>
        azure_session:
          azure_client_id: <CLIENT_ID>
  override:
    nodeAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            ad_identifiers:
              - <SHORT_IMAGE>
            instances:
              - [...]
                 password: "ENC[secretKeyNameInKeyVault]"
클러스터 체크: 클러스터 체크 러너 미활성화 시
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "azure.keyvault"
      config:
        keyvaulturl: <KEY_VAULT_URL>
        azure_session:
          azure_client_id: <CLIENT_ID>
  override:
    clusterAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            cluster_check: true
            instances:
              - [...]
                password: "ENC[secretKeyNameInKeyVault]"
클러스터 체크: 클러스터 체크 러너 활성화 시
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "azure.keyvault"
      config:
        keyvaulturl: <KEY_VAULT_URL>
        azure_session:
          azure_client_id: <CLIENT_ID>
  features:
    clusterChecks:
      useClusterChecksRunners: true
  override:
    clusterAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            cluster_check: true
            instances:
              - [...]
                password: "ENC[secretKeyNameInKeyVault]"

또는, 네이티브 spec.global.secretBackend.type 및 spec.global.secretBackend.config 필드 대신 DD_SECRET_BACKEND_TYPE과 DD_SECRET_BACKEND_CONFIG 환경 변수를 사용할 수 있어요.

GCP Secret Manager

Agent 7.74+ 버전에서 사용 가능

다음 GCP 서비스가 지원돼요:

secret_backend_type 값 GCP 서비스
gcp.secretmanager GCP Secret Manager
GCP 인증 및 액세스 정책

GCP Secret Manager 구현은 Google 인증에 Application Default Credentials (ADC)를 사용해요.

GCP Secret Manager와 상호작용하려면 Datadog Agent가 사용하는 서비스 계정(VM의 서비스 계정, workload identity, 로컬에서 활성화된 자격 증명 등)에 secretmanager.versions.access 권한이 필요해요.

이 권한은 사전 정의된 역할 Secret Manager Secret Accessor(roles/secretmanager.secretAccessor) 또는 동등한 액세스 권한이 있는 커스텀 역할로 부여할 수 있어요.

GCE 또는 GKE 런타임에서 ADC는 인스턴스 또는 pod에 연결된 서비스 계정을 통해 자동으로 구성돼요. 연결된 서비스 계정은 GCP Secret Manager에 접근할 수 있는 적절한 역할을 가져야 해요. 또한 GCE 또는 GKE 런타임에는 cloud-platform OAuth 액세스 범위가 필요해요.

GCP 구성 예시

Agent YAML 파일 — 다음 구성을 사용해 Datadog Agent가 GCP Secret Manager로 시크릿을 해석하도록 구성하세요:

# datadog.yaml
secret_backend_type: gcp.secretmanager
secret_backend_config:
  gcp_session:
    project_id: <PROJECT_ID>

환경 변수를 사용하면 구성을 JSON으로 변환해요:

DD_SECRET_BACKEND_TYPE="gcp.secretmanager"
DD_SECRET_BACKEND_CONFIG='{"gcp_session":{"project_id":"<PROJECT_ID>"}}'

Agent가 GCP Secret Manager를 사용하도록 구성한 뒤에는 ENC[secret-name] 또는 ENC[secret-name;key;version;]로 설정에서 시크릿을 참조하세요.

ENC 표기법은 다음으로 구성돼요:

  • secret: GCP Secret Manager의 시크릿 이름 (예: datadog-api-key).
  • key: (선택) JSON 형식 시크릿에서 추출할 키. 평문 시크릿을 사용한다면 생략할 수 있어요 (예: ENC[secret-name;;version]).
  • version: (선택) 시크릿 버전 번호. 지정하지 않으면 latest 버전이 사용돼요.
    • 버전 구문 예시:
      • secret-key - 암시적 latest 버전
      • secret-key;;latest - 명시적 latest 버전
      • secret-key;;1 - 특정 버전 번호

예를 들어 두 버전을 가진 datadog-api-key와 datadog-app-key라는 GCP 시크릿을 가정해요:

# datadog.yaml
api_key: ENC[datadog-api-key;;1] # specify the first version of the api key
app_key: ENC[datadog-app-key] # latest version

secret_backend_type: gcp.secretmanager
secret_backend_config:
  gcp_session:
    project_id: <PROJECT_ID>

JSON 형식 시크릿의 경우 datadog-keys라는 시크릿이 다음을 포함한다고 가정해요:

{
  "api_key": "your_api_key_value",
  "app_key": "your_app_key_value"
}

특정 키를 다음과 같이 참조하세요:

# datadog.yaml
api_key: ENC[datadog-keys;api_key;1] # specify the first version of the api key 
app_key: ENC[datadog-keys;app_key] # latest

secret_backend_type: gcp.secretmanager
secret_backend_config:
  gcp_session:
    project_id: <PROJECT_ID>

Helm — 다음 구성을 사용해 Helm에서 Datadog Agent가 GCP Secret Manager로 시크릿을 해석하도록 구성하세요:

통합 체크 (Integration check)
datadog:
  secretBackend:
    type: "gcp.secretmanager"
    config:
      gcp_session:
        project_id: "<PROJECT_ID>"
  confd:
  # This is an example
    <INTEGRATION_NAME>.yaml: |-
      ad_identifiers:
        - <SHORT_IMAGE>
      instances:
        - [...]
          password: "ENC[secret-name]"
클러스터 체크: 클러스터 체크 러너 미활성화 시
datadog:
  secretBackend:
    type: "gcp.secretmanager"
    config:
      gcp_session:
        project_id: "<PROJECT_ID>"
clusterAgent:
  confd:
    # This is an example
    <INTEGRATION_NAME>.yaml: |-
      cluster_check: true
      instances:
        - [...]
          password: "ENC[secret-name]"
클러스터 체크: 클러스터 체크 러너 활성화 시
datadog:
  secretBackend:
    type: "gcp.secretmanager"
    config:
      gcp_session:
        project_id: "<PROJECT_ID>"
clusterAgent:
  confd:
  # This is an example
    <INTEGRATION_NAME>.yaml: |-
      cluster_check: true
      instances:
        - [...]
          password: "ENC[secret-name]"
clusterChecksRunner:
  enabled: true

Operator — 다음 구성을 사용해 Datadog Operator로 Datadog Agent가 GCP Secret Manager로 시크릿을 해석하도록 구성하세요:

참고: 네이티브 secretBackend 필드에는 Datadog Operator v1.29.0+가 필요해요.

통합 체크 (Integration check)
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "gcp.secretmanager"
      config:
        gcp_session:
          project_id: <PROJECT_ID>
  override:
    nodeAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            ad_identifiers:
              - <SHORT_IMAGE>
            instances:
              - [...]
                 password: "ENC[secret-name]"
클러스터 체크: 클러스터 체크 러너 미활성화 시
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "gcp.secretmanager"
      config:
        gcp_session:
          project_id: <PROJECT_ID>
  override:
    clusterAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            cluster_check: true
            instances:
              - [...]
                password: "ENC[secret-name]"
클러스터 체크: 클러스터 체크 러너 활성화 시
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "gcp.secretmanager"
      config:
        gcp_session:
          project_id: <PROJECT_ID>
  features:
    clusterChecks:
      useClusterChecksRunners: true
  override:
    clusterAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            cluster_check: true
            instances:
              - [...]
                password: "ENC[secret-name]"

또는, 네이티브 spec.global.secretBackend.type 및 spec.global.secretBackend.config 필드 대신 DD_SECRET_BACKEND_TYPE과 DD_SECRET_BACKEND_CONFIG 환경 변수를 사용할 수 있어요.

시크릿 버전 관리 (Secret versioning)

GCP Secret Manager는 시크릿 버전을 지원해요. Agent 구현도 ; 구분자를 사용한 시크릿 버전 관리를 지원해요. 버전을 지정하지 않으면 latest 버전이 사용돼요.

JSON 시크릿 지원

Datadog Agent는 ; 구분자를 사용해 JSON 형식 시크릿에서 특정 키를 추출하는 것을 지원해요:

  • datadog;api_key - 암시적 latest 버전으로 datadog 시크릿에서 api_key 필드 추출

  • datadog;api_key;1 - 버전 1에서 datadog 시크릿의 api_key 필드 추출

HashiCorp Vault 백엔드

다음 HashiCorp 서비스가 지원돼요:

secret_backend_type 값 HashiCorp 서비스
hashicorp.vault HashiCorp Vault (Secrets Engine 버전 1 및 2)
HashiCorp Vault 설정 방법
  1. HashiCorp Vault를 실행하세요. 자세한 내용은 공식 HashiCorp Vault 문서를 참고하세요.
  2. 볼트에서 시크릿을 가져올 권한을 주는 정책(policy)을 작성하세요. *.hcl 파일을 만들고 Secrets Engine 버전 1을 사용한다면 다음 권한을 포함하세요:
path "<your mount path>/<additional subpath>" {
  capabilities = ["read"]
}

Secrets Engine 버전 2를 사용한다면 다음 권한이 필요해요:

path "<your_mount_path>/data/<additional_subpath>" {
  capabilities = ["read"]
}

/*
Datadog needs access to mount information to check the Secrets Engine version
number. If access isn't granted, version 1 is assumed.
*/
path "sys/mounts" {
  capabilities = ["read"]
}

vault policy write <policy_name> <path_to_*.hcl_file>을 실행하세요.

볼트에 인증할 방법을 선택하세요. AWS 인스턴스 프로필 방법을 사용한다면 vault auth enable aws를 실행하세요. Helm이나 Datadog Operator로 배포한다면 대신 Kubernetes 인증 방법을 사용하세요.

AWS 인스턴스 프로필 지침

AWS 연결 머신에서 HashiCorp Vault를 실행 중이라면 인스턴스 프로필 방식으로 인증할 것을 권장해요.

이 설정을 마친 뒤 인증별 볼트 정책을 작성하세요.

Kubernetes 인증 방법 지침

사전 요구 사항: Vault의 kubernetes 인증 방법은 Kubernetes TokenReview API를 호출해 Agent의 ServiceAccount 토큰을 검증해요. Vault가 이 호출에 사용하는 ID(기본적으로 자체 ServiceAccount 또는 token_reviewer_jwt로 설정된 ID)에는 system:auth-delegator ClusterRole이 바인딩되어 있어야 해요:

kubectl create clusterrolebinding vault-tokenreview-binding \
    --clusterrole=system:auth-delegator \
    --serviceaccount=<VAULT_NAMESPACE>:<VAULT_SERVICE_ACCOUNT>

공식 Vault Helm 차트로 Vault를 설치했다면 이미 구성되어 있어요.

Agent pod의 Kubernetes ServiceAccount 토큰으로 인증하려면(Helm 및 Operator 구성 예시가 사용하는 방법) Vault에서 kubernetes 인증 방법을 활성화하세요:

vault auth enable kubernetes

vault write auth/kubernetes/config \
    kubernetes_host="https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT"

그런 다음 2단계의 정책을 Agent의 ServiceAccount 이름과 네임스페이스에 바인딩하는 역할을 만드세요:

vault write auth/kubernetes/role/<VAULT_ROLE> \
    bound_service_account_names=<AGENT_SERVICE_ACCOUNT_NAME> \
    bound_service_account_namespaces=<AGENT_NAMESPACE> \
    policies=<policy_name> \
    ttl=1h

이 <VAULT_ROLE> 값을 Helm 및 Operator 구성 예시의 vault_kubernetes_role에 사용하세요.

구성 예시

Agent YAML 파일 — 다음 예시에서 HashiCorp Vault 시크릿 경로 접두사가 키 apikey와 함께 /Datadog/Production이라고 가정해요:

/DatadogAgent/Production/apikey: *** "<your_api_key>"

다음 예시는 AWS를 인증에 활용해 HashiCorp Vault에서 API 키 값을 가져와요:

# datadog.yaml
api_key: "ENC[/Datadog/Production;apikey]"

secret_backend_type: hashicorp.vault
secret_backend_config:
  vault_address: http://myvaultaddress.net
  vault_session:
    vault_auth_type: aws
    vault_aws_role: Name-of-IAM-role-attached-to-machine
    aws_region: us-east-1  # optional, defaults to us-east-1 if not set
모든 vault_session 옵션

다음 vault_session 필드는 Agent가 Vault에 인증하는 방식을 제어해요.

필드 설명
vault_auth_type 인증 방법. 지원 값: aws, kubernetes. 설정하지 않으면 제공된 자격 증명에 따라 AppRole, userpass 또는 LDAP가 사용됨.
vault_role_id AppRole 역할 ID. vault_secret_id와 함께 사용.
vault_secret_id AppRole 시크릿 ID. vault_role_id와 함께 사용.
vault_username userpass 인증용 사용자 이름. vault_password와 함께 사용.
vault_password userpass 인증용 비밀번호. vault_username과 함께 사용.
vault_ldap_username LDAP 인증용 사용자 이름. vault_ldap_password와 함께 사용.
vault_ldap_password LDAP 인증용 비밀번호. vault_ldap_username과 함께 사용.
vault_aws_role AWS IAM 인증용 Vault 역할 이름. vault_auth_type: aws일 때 필수.
vault_aws_iam_server_id 재생 공격을 방지하기 위한 X-Vault-AWS-IAM-Server-ID 헤더 값.
aws_region IAM 인증 요청을 위한 AWS 리전. 기본값은 us-east-1.
vault_kubernetes_role Kubernetes 인증용 Vault 역할 이름. vault_auth_type: kubernetes일 때 필수.
vault_kubernetes_jwt 문자열로 된 Kubernetes 서비스 계정 JWT 토큰.
vault_kubernetes_jwt_path Kubernetes JWT 토큰 파일의 경로. 기본값은 /var/run/secrets/kubernetes.io/serviceaccount/token.
vault_kubernetes_mount_path Kubernetes 인증 방법의 Vault 마운트 경로.
implicit_auth 인증을 건너뛰고 Vault 클라이언트 환경에 이미 설정된 토큰(예: VAULT_TOKEN)을 사용하려면 true로 설정.
Vault용 기타 secret_backend_config 옵션

다음 최상위 secret_backend_config 필드도 적용돼요:

필드 설명
vault_address Vault 서버 주소 (예: http://myvaultaddress.net). VAULT_ADDR 환경 변수로도 설정할 수 있음.
vault_token 정적 Vault 토큰. 인증 방법에 의존하지 않을 때 사용.
vault_namespace Vault Enterprise 환경용 Vault 네임스페이스.
TLS 구성 (vault_tls_config)

상호 TLS나 커스텀 CA를 활성화하려면 vault_tls_config 블록을 추가하세요:

secret_backend_type: hashicorp.vault
secret_backend_config:
  vault_address: https://myvaultaddress.net
  vault_tls_config:
    ca_cert: /path/to/ca.pem
    client_cert: /path/to/client.pem
    client_key: /path/to/client-key.pem
    insecure: false
필드 설명
ca_cert PEM 인코딩 CA 인증서 파일의 경로.
ca_path PEM 인코딩 CA 인증서 파일 디렉터리의 경로.
client_cert mTLS용 PEM 인코딩 클라이언트 인증서 파일의 경로.
client_key 클라이언트 인증서의 프라이빗 키 파일 경로.
tls_server TLS SNI 검증을 위한 예상 서버 이름.
insecure TLS 인증서 검증을 비활성화하려면 true로 설정. 프로덕션에서 사용하지 마세요.

Helm — 다음 구성을 사용해 Helm에서 Datadog Agent가 HashiCorp Vault로 시크릿을 해석하도록 구성하세요. 이는 Agent에 자동으로 마운트된 ServiceAccount 토큰에 의존하는 Vault의 kubernetes 인증 방법을 사용하므로 Agent에 추가 Kubernetes RBAC나 어노테이션이 필요하지 않아요. Vault 자체에는 해당 토큰을 검증할 RBAC 권한이 필요해요. 위의 Kubernetes 인증 방법 지침을 참고하세요.

참고: Vault 서버에서 kubernetes 인증 방법을 활성화하고 vault_kubernetes_role을 Agent의 ServiceAccount 이름과 네임스페이스에 바인딩하세요. 자세한 내용은 위의 Kubernetes 인증 방법 지침과 공식 HashiCorp Vault Kubernetes 인증 방법 문서를 참고하세요.

통합 체크 (Integration check)
datadog:
  secretBackend:
    type: "hashicorp.vault"
    config:
      vault_address: "https://myvaultaddress.net"
      vault_session:
        vault_auth_type: kubernetes
        vault_kubernetes_role: "<VAULT_ROLE>"
        vault_kubernetes_mount_path: "auth/kubernetes/login"
    enableGlobalPermissions: true
  confd:
  # This is an example
    <INTEGRATION_NAME>.yaml: |-
      ad_identifiers:
        - <SHORT_IMAGE>
      instances:
        - [...]
          password: "ENC[/Datadog/Production;apikey]"
클러스터 체크: 클러스터 체크 러너 미활성화 시
datadog:
  secretBackend:
    type: "hashicorp.vault"
    config:
      vault_address: "https://myvaultaddress.net"
      vault_session:
        vault_auth_type: kubernetes
        vault_kubernetes_role: "<VAULT_ROLE>"
        vault_kubernetes_mount_path: "auth/kubernetes/login"
    enableGlobalPermissions: true
clusterAgent:
  confd:
    # This is an example
    <INTEGRATION_NAME>.yaml: |-
      cluster_check: true
      instances:
        - [...]
          password: "ENC[/Datadog/Production;apikey]"
클러스터 체크: 클러스터 체크 러너 활성화 시
datadog:
  secretBackend:
    type: "hashicorp.vault"
    config:
      vault_address: "https://myvaultaddress.net"
      vault_session:
        vault_auth_type: kubernetes
        vault_kubernetes_role: "<VAULT_ROLE>"
        vault_kubernetes_mount_path: "auth/kubernetes/login"
    enableGlobalPermissions: true
clusterAgent:
  confd:
  # This is an example
    <INTEGRATION_NAME>.yaml: |-
      cluster_check: true
      instances:
        - [...]
          password: "ENC[/Datadog/Production;apikey]"
clusterChecksRunner:
  enabled: true

Operator — 다음 구성을 사용해 Datadog Operator로 Datadog Agent가 HashiCorp Vault로 시크릿을 해석하도록 구성하세요. 이는 Agent에 자동으로 마운트된 ServiceAccount 토큰에 의존하는 Vault의 kubernetes 인증 방법을 사용하므로 Agent에 추가 Kubernetes RBAC나 어노테이션이 필요하지 않아요. Vault 자체에는 해당 토큰을 검증할 RBAC 권한이 필요해요. 위의 Kubernetes 인증 방법 지침을 참고하세요.

참고: 네이티브 secretBackend 필드에는 Datadog Operator v1.29.0+가 필요해요. Vault 서버에서 kubernetes 인증 방법을 활성화하고 vault_kubernetes_role을 Agent의 ServiceAccount 이름과 네임스페이스에 바인딩하세요. 자세한 내용은 위의 Kubernetes 인증 방법 지침과 공식 HashiCorp Vault Kubernetes 인증 방법 문서를 참고하세요.

통합 체크 (Integration check)
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "hashicorp.vault"
      config:
        vault_address: "https://myvaultaddress.net"
        vault_session:
          vault_auth_type: kubernetes
          vault_kubernetes_role: "<VAULT_ROLE>"
          vault_kubernetes_mount_path: "auth/kubernetes/login"
  override:
    nodeAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            ad_identifiers:
              - <SHORT_IMAGE>
            instances:
              - [...]
                password: "ENC[/Datadog/Production;apikey]"
클러스터 체크: 클러스터 체크 러너 미활성화 시
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "hashicorp.vault"
      config:
        vault_address: "https://myvaultaddress.net"
        vault_session:
          vault_auth_type: kubernetes
          vault_kubernetes_role: "<VAULT_ROLE>"
          vault_kubernetes_mount_path: "auth/kubernetes/login"
  override:
    clusterAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            cluster_check: true
            instances:
              - [...]
                password: "ENC[/Datadog/Production;apikey]"
클러스터 체크: 클러스터 체크 러너 활성화 시
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  [...]
  global:
    secretBackend:
      type: "hashicorp.vault"
      config:
        vault_address: "https://myvaultaddress.net"
        vault_session:
          vault_auth_type: kubernetes
          vault_kubernetes_role: "<VAULT_ROLE>"
          vault_kubernetes_mount_path: "auth/kubernetes/login"
  features:
    clusterChecks:
      useClusterChecksRunners: true
  override:
    clusterAgent:
      extraConfd:
        configDataMap:
        # This is an example
          <INTEGRATION_NAME>.yaml: |-
            cluster_check: true
            instances:
              - [...]
                password: "ENC[/Datadog/Production;apikey]"

또는, 네이티브 spec.global.secretBackend.type 및 spec.global.secretBackend.config 필드 대신 DD_SECRET_BACKEND_TYPE과 DD_SECRET_BACKEND_CONFIG 환경 변수를 사용할 수 있어요. 예: DD_SECRET_BACKEND_TYPE="hashicorp.vault" 및 DD_SECRET_BACKEND_CONFIG='{"vault_address":"https://myvaultaddress.net","vault_session":{"vault_auth_type":"kubernetes","vault_kubernetes_role":"<VAULT_ROLE>","vault_kubernetes_mount_path":"auth/kubernetes/login"}}'.

Kubernetes Secrets

Agent 7.75+ 버전에서 사용 가능

다음 Kubernetes 서비스가 지원돼요:

secret_backend_type 값 서비스
k8s.secrets Kubernetes Secrets
사전 요구 사항 (Prerequisites)

Kubernetes 시크릿 백엔드에는 다음이 필요해요:

  • ServiceAccount 자격 증명: 기본적으로 자동 마운트된 ServiceAccount 토큰(automountServiceAccountToken: true, 참고: Kubernetes 문서)을 사용해요. 필요하면 커스텀 경로를 구성할 수 있어요.
  • RBAC 권한: Agent의 ServiceAccount가 대상 네임스페이스의 시크릿을 읽을 권한이 있어야 해요
  • 네트워크 접근: Agent pod가 Kubernetes API 서버에 도달할 수 있어야 해요
RBAC 설정

시크릿이 들어 있는 각 네임스페이스에 대해 올바른 네임스페이스 이름을 사용해 다음 예시로 Role과 RoleBinding을 만들세요:

# Role: grants permission to read secrets
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: datadog-secret-reader
  namespace: <target namepace> # Namespace with secrets
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get"]
---
# RoleBinding: grants permission to Agent's ServiceAccount
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: datadog-secret-access
  namespace: <target namespace>  # Namespace with secrets
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: datadog-secret-reader
subjects:
- kind: ServiceAccount
  name: <serviceaccount name>  # datadog is typically the default ServiceAccount name
  namespace: datadog  # Where Agent runs
구성 예시

Agent YAML 파일 — 다음 구성을 사용해 Datadog Agent가 Kubernetes Secrets를 사용하도록 구성하세요:

# datadog.yaml
secret_backend_type: k8s.secrets

# Reference secrets using namespace/secret-name;key format
api_key: "ENC[secrets-prod/dd-api-key;api_key]"
app_key: "ENC[secrets-prod/dd-api-key;app_key]"

ENC 표기법 형식은 namespace/secret-name;key예요:

  • namespace: 시크릿이 들어 있는 Kubernetes 네임스페이스
  • secret-name: Secret 리소스의 이름
  • key: Secret의 data 필드에서 추출할 특정 키

예시: 네임스페이스 secrets-ns에 다음 Secret이 있다고 가정해요:

apiVersion: v1
kind: Secret
metadata:
  name: dd-api-key
  namespace: secrets-ns
data:
  api_key: <base64-encoded-value>
  app_key: <base64-encoded-value>

개별 키를 참조할 수 있어요:

api_key: "ENC[secrets-ns/dd-api-key;api_key]"
app_key: "ENC[secrets-ns/dd-api-key;app_key]"

멀티 네임스페이스 지원: 각 시크릿 참조는 다른 네임스페이스를 지정할 수 있어요 (각 네임스페이스에 RBAC를 구성해야 함):

api_key: "ENC[secrets-ns/dd-keys;api_key]"
db_password: "ENC[secrets-shared/db-creds;password]"

Helm — Helm으로 Datadog Agent가 Kubernetes Secrets를 사용하도록 구성하세요:

# values.yaml
datadog:
  apiKey: "place...den"

  secretBackend:
    type: "k8s.secrets"

  env:
  - name: DD_API_KEY
    value: "ENC[secrets-ns/dd-api-key;api_key]"

참고: 시크릿 백엔드로 API 키를 해석할 때 Helm 차트 검증에는 플레이스홀더 apiKey가 필요해요. DD_API_KEY 환경 변수가 이를 덮어써요. 시크릿이 들어 있는 각 네임스페이스에 RBAC(Role + RoleBinding)를 수동으로 생성해야 해요. 자세한 내용은 RBAC 설정 섹션을 참고하세요.

또는, 네이티브 datadog.secretBackend.type 필드 대신 DD_SECRET_BACKEND_TYPE 환경 변수를 사용할 수 있어요.

Operator — Datadog Operator로 Datadog Agent가 Kubernetes Secrets를 사용하도록 구성하세요:

참고: 네이티브 secretBackend 필드에는 Datadog Operator v1.25.0+가 필요해요.

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    credentials:
      apiKey: "place...den"
    secretBackend:
      type: "k8s.secrets"

  override:
    nodeAgent:
      env:
      - name: DD_API_KEY
        value: "ENC[secrets-ns/dd-api-key;api_key]"

참고: 시크릿 백엔드로 API 키를 해석할 때 플레이스홀더 API 키가 Operator 검증을 충족해요. DD_API_KEY 환경 변수가 이를 덮어써요. 시크릿이 들어 있는 각 네임스페이스에 RBAC(Role + RoleBinding)를 수동으로 생성해야 해요. 자세한 내용은 RBAC 설정 섹션을 참고하세요.

또는, 네이티브 spec.global.secretBackend.type 필드 대신 DD_SECRET_BACKEND_TYPE 환경 변수를 사용할 수 있어요.

커스텀 경로 구성

설정이 ServiceAccount 기반 인증의 기본 위치를 따르지 않는다면 대신 token_path와 ca_path를 지정할 수 있어요.

Agent YAML

secret_backend_type: k8s.secrets
secret_backend_config:
  token_path: /custom/path/to/token
  ca_path: /custom/path/to/ca.crt

Helm

참고: 네이티브 secretBackend 필드에는 Helm 차트 v3.171.0+가 필요해요.

datadog:
  secretBackend:
    type: "k8s.secrets"
    config:
      token_path: /custom/path/to/token
      ca_path: /custom/path/to/ca.crt
    enableGlobalPermissions: true

또는, 네이티브 datadog.secretBackend.type 및 datadog.secretBackend.config 필드 대신 DD_SECRET_BACKEND_TYPE과 DD_SECRET_BACKEND_CONFIG 환경 변수를 사용할 수 있어요.

Operator

참고: 네이티브 secretBackend 필드에는 Datadog Operator v1.25.0+가 필요해요.

spec:
  global:
    secretBackend:
      type: "k8s.secrets"
      config:
        token_path: /custom/path/to/token
        ca_path: /custom/path/to/ca.crt

또는, 네이티브 spec.global.secretBackend.type 및 spec.global.secretBackend.config 필드 대신 DD_SECRET_BACKEND_TYPE과 DD_SECRET_BACKEND_CONFIG 환경 변수를 사용할 수 있어요.

커스텀 API 서버 구성

설정이 기본 KUBERNETES_SERVICE_HOST와 KUBERNETES_SERVICE_PORT 환경 변수를 노출하지 않는다면 Kubernetes REST API와 상호작용하기 위해 api_server URL을 제공할 수 있어요.

Agent YAML

secret_backend_type: k8s.secrets
secret_backend_config:
  api_server: https://{KUBERNETES_SERVICE_HOST}:{KUBERNETES_SERVICE_PORT}

Helm

참고: 네이티브 secretBackend 필드에는 Helm 차트 v3.171.0+가 필요해요.

datadog:
  secretBackend:
    type: "k8s.secrets"
    config:
      api_server: https://{KUBERNETES_SERVICE_HOST}:{KUBERNETES_SERVICE_PORT}
    enableGlobalPermissions: true

또는, 네이티브 datadog.secretBackend.type 및 datadog.secretBackend.config 필드 대신 DD_SECRET_BACKEND_TYPE과 DD_SECRET_BACKEND_CONFIG 환경 변수를 사용할 수 있어요.

Operator

참고: 네이티브 secretBackend 필드에는 Datadog Operator v1.25.0+가 필요해요.

spec:
  global:
    secretBackend:
      type: "k8s.secrets"
      config:
        api_server: https://{KUBERNETES_SERVICE_HOST}:{KUBERNETES_SERVICE_PORT}

또는, 네이티브 spec.global.secretBackend.type 및 spec.global.secretBackend.config 필드 대신 DD_SECRET_BACKEND_TYPE과 DD_SECRET_BACKEND_CONFIG 환경 변수를 사용할 수 있어요.

Docker Secrets

Agent 7.75+ 버전에서 사용 가능

다음 Docker 서비스가 지원돼요:

secret_backend_type 값 서비스
docker.secrets Docker Secrets
사전 요구 사항 (Prerequisites)

Docker 시크릿 백엔드는 Docker Swarm 시크릿과 Docker Compose 시크릿을 모두 지원해요. 기본적으로 Swarm과 Compose 모두 컨테이너 내의 /run/secrets(Linux) 또는 C:\ProgramData\Docker\secrets(Windows)에 시크릿을 파일로 자동 마운트해요.

참고: Compose 시크릿은 파일 기반(로컬 파일을 가리킴)이거나 외부(기존 Swarm 시크릿 참조)일 수 있어요.

구성 예시

다음 구성을 사용해 Datadog Agent가 Docker Secrets를 사용하도록 구성하세요:

# datadog.yaml
secret_backend_type: docker.secrets

# Reference secrets using the secret name (filename in /run/secrets)
api_key: "ENC[dd_api_key]"

ENC 표기법 형식은 /run/secrets/의 파일 이름에 해당하는 시크릿 이름이에요:

  • ENC[api_key]는 /run/secrets/api_key(Linux) 또는 C:\ProgramData\Docker\secrets\api_key(Windows)에서 읽어요

커스텀 시크릿 경로: Docker Swarm이나 Compose가 시크릿을 다른 위치에 마운트하도록 구성된 경우 다음과 같이 지정할 수 있어요:

secret_backend_type: docker.secrets
secret_backend_config:
  secrets_path: /custom/secrets/path
Docker Swarm 예시

Docker Swarm 시크릿을 생성하고 사용하세요:

# Create the secret
echo "<api_key_value>" | docker secret create dd_api_key -

# Deploy Agent with secret mounted
docker service create \
  --name datadog-agent \
  --secret dd_api_key \
  --env DD_API_KEY="ENC[dd_api_key]" \
  --env DD_SECRET_BACKEND_TYPE="docker.secrets" \
  --env DD_SITE="datadoghq.com" \
  --env DD_HOSTNAME="dd-agent" \
  registry.datadoghq.com/agent:latest

시크릿 dd_api_key는 /run/secrets/dd_api_key에 자동으로 마운트되고 Agent는 docker.secrets 백엔드로 읽어요.

Docker Compose 예시

파일 기반 시크릿으로 docker-compose.yml을 생성하세요:

version: '3.8'

services:
  datadog:
    image: registry.datadoghq.com/agent:latest
    environment:
      - DD_API_KEY=ENC[dd_api_key]
      - DD_SECRET_BACKEND_TYPE=docker.secrets
      - DD_SITE=datadoghq.com
      - DD_HOSTNAME=dd-agent
    secrets:
      - dd_api_key

secrets:
  dd_api_key:
    file: ./secrets/api_key.txt

시크릿 파일 ./secrets/api_key.txt는 컨테이너의 /run/secrets/dd_api_key에 마운트돼요.

JSON, YAML 또는 TEXT 파일 시크릿 백엔드
secret_backend_type 값 파일 서비스
file.json JSON
file.yaml YAML
file.text TEXT
파일 권한

파일 백엔드는 구성된 JSON, YAML 또는 TEXT 파일에 대한 읽기 권한만 필요해요. 이 권한은 로컬 Datadog Agent 사용자(Linux의 dd-agent, Windows의 ddagentuser)에 부여해야 해요.

JSON 파일 백엔드

참고: JSON 깊이 한 레벨만 지원돼요 (예: {"key": "value"}).

구성 예시

JSON 파일을 사용해 시크릿을 로컬에 저장할 수 있어요.

예를 들어 다음을 포함하는 /path/to/secret.json JSON 파일이 있다고 가정해요:

{
  "datadog_api_key": "your_api_key"
}

이 구성을 사용해 시크릿을 가져올 수 있어요:

# datadog.yaml
api_key: "ENC[datadog_api_key]"

secret_backend_type: file.json
secret_backend_config:
  file_path: /path/to/secret.json

YAML 파일 백엔드

참고: YAML 깊이 한 레벨만 지원돼요 (예: key: value).

구성 예시

YAML 파일을 사용해 시크릿을 로컬에 저장할 수 있어요.

예를 들어 다음을 포함하는 /path/to/secret.yaml YAML 파일이 있다고 가정해요:

datadog_api_key: your api key

다음 구성을 사용해 여기서 시크릿을 가져올 수 있어요:

# datadog.yaml
api_key: "ENC[datadog_api_key]"
secret_backend_type: file.yaml
secret_backend_config:
  file_path: /path/to/secret.yaml

TEXT 파일 백엔드

Agent 7.75+ 버전에서 사용 가능

참고: 각 시크릿은 자체 개별 텍스트 파일에 저장해야 해요.

구성 예시

개별 텍스트 파일을 사용해 시크릿을 로컬에 저장할 수 있어요.

예를 들어 /path/to/secrets/에 텍스트 파일이 있다고 가정해요:

/path/to/secrets/dd_api_key에 다음을 포함:

your_api_key_value

/path/to/secrets/dd_app_key에 다음을 포함:

your_app_key_value

다음 구성을 사용해 여기서 시크릿을 가져올 수 있어요:

# datadog.yaml
api_key: "ENC[dd_api_key]"
app_key: "ENC[dd_app_key]"

secret_backend_type: file.text
secret_backend_config:
  secrets_path: /path/to/secrets
경로 보안:
  • ENC[]의 상대 경로는 secrets_path를 기준으로 해석돼요 (예: secret_path: /path/to/secrets와 함께 ENC[dd_api_key]는 /path/to/secrets/dd_api_key로 해석)
  • ENC[]의 절대 경로는 secrets_path 안에 있어야 해요 (예: secret_path: /path/to/secrets와 함께 ENC[/path/to/secrets/dd_api_key]는 동작)
  • 경로 탐색 시도(예: ENC[../etc/passwd])는 차단되고 "path outside allowed directory"로 실패해요

참고: 일부 도구는 시크릿을 파일로 내보낼 때 자동으로 줄바꿈을 추가해요. 처리 방법은 Remove trailing line breaks를 참고하세요.

Helm 또는 Datadog Operator로 배포하기

Helm 또는 Datadog Operator로 파일 기반 시크릿 백엔드(file.json, file.yaml, file.text)를 사용하려면 시크릿 파일을 이를 해석하는 모든 Agent 구성 요소에 마운트하세요. 다음 예시는 node Agent에만 마운트해요. Cluster Agent나 Cluster Checks Runner에 ENC[] 값이 있으면 같은 볼륨을 해당 구성 요소에도 마운트하세요. 필요에 따라 file.yaml 또는 file.text와 해당 구성 키(file_path 또는 secrets_path)로 바꾸세요.

Helm

datadog:
  secretBackend:
    type: "file.json"
    config:
      file_path: /etc/secret-volume/secret.json
    enableGlobalPermissions: true
agents:
  volumes:
    - name: secret-volume
      secret:
        secretName: <SECRET_NAME>
  volumeMounts:
    - name: secret-volume
      mountPath: /etc/secret-volume
      readOnly: true

또는, 네이티브 datadog.secretBackend.type 및 datadog.secretBackend.config 필드 대신 DD_SECRET_BACKEND_TYPE과 DD_SECRET_BACKEND_CONFIG 환경 변수를 사용할 수 있어요.

Operator

참고: 네이티브 secretBackend 필드에는 Datadog Operator v1.25.0+가 필요해요.

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    secretBackend:
      type: "file.json"
      config:
        file_path: /etc/secret-volume/secret.json
  override:
    nodeAgent:
      volumes:
        - name: secret-volume
          secret:
            secretName: <SECRET_NAME>
      containers:
        agent:
          volumeMounts:
            - name: secret-volume
              mountPath: /etc/secret-volume
              readOnly: true

또는, 네이티브 spec.global.secretBackend.type 및 spec.global.secretBackend.config 필드 대신 DD_SECRET_BACKEND_TYPE과 DD_SECRET_BACKEND_CONFIG 환경 변수를 사용할 수 있어요.

Windows Registry Key

Agent 7.82+ 버전에서 사용 가능

다음 Windows 서비스가 지원돼요:

secret_backend_type 값 서비스
windows.regkey Windows Registry
사전 요구 사항 (Prerequisites)

이 백엔드는 Windows에서만 지원돼요. 레지스트리 키는 Datadog Agent가 실행되는 계정(기본적으로 ddagentuser)이 읽을 수 있어야 해요. HKLM 아래의 키는 기본적으로 모든 로컬 사용자가 읽을 수 있어요. Datadog은 ddagentuser와 SYSTEM만 키를 읽도록 ACL을 제한할 것을 권장해요.

구성 예시

다음 구성을 사용해 Datadog Agent가 Windows Registry Key 백엔드를 사용하도록 구성하세요:

# datadog.yaml
secret_backend_type: windows.regkey

api_key: 'ENC[SOFTWARE\Datadog\secrets:api_key]'

ENC[<registry-path>:<value-name>] 형식으로 시크릿을 참조하세요. 여기서 registry-path는 루트 키 아래의 하위 경로이고 value-name은 읽을 레지스트리 값이에요.

기본적으로 루트 키는 HKLM이에요. 다른 하이브를 사용하려면 root_key를 설정하세요. 다음 값만 허용되며 (다른 값은 오류를 반환해요):

HKLM, HKCU, HKCR, HKU, HKCC (HKEY_LOCAL_MACHINE 같은 긴 형식도 지원됨)

secret_backend_type: windows.regkey
secret_backend_config:
  root_key: HKCU
레지스트리 키 설정

이 예시 PowerShell 스크립트는 레지스트리 설정 방법을 보여줘요 (설치 후 Administrator로 실행):

# Create the key and set the secret value
New-Item -Path "HKLM:\SOFTWARE\Datadog\secrets" -Force
Set-ItemProperty -Path "HKLM:\SOFTWARE\Datadog\secrets" -Name "api_key" -Value "<YOUR_API_KEY>"

# Restrict read access to ddagentuser and SYSTEM (recommended)
$acl = Get-Acl "HKLM:\SOFTWARE\Datadog\secrets"
$acl.SetAccessRuleProtection($true, $false)
$acl.SetAccessRule((New-Object System.Security.AccessControl.RegistryAccessRule -ArgumentList "SYSTEM", "ReadKey", "Allow"))
$acl.SetAccessRule((New-Object System.Security.AccessControl.RegistryAccessRule -ArgumentList "ddagentuser", "ReadKey", "Allow"))
$acl.SetAccessRule((New-Object System.Security.AccessControl.RegistryAccessRule -ArgumentList "Administrators", "FullControl", "Allow"))
Set-Acl "HKLM:\SOFTWARE\Datadog\secrets" $acl

여러 백엔드 (Multiple backends)

Agent 7.80+ 버전에서 사용 가능

단일 secret_backend_type 대신 multi_secret_backends 아래에 명명된 여러 백엔드를 선언할 수 있어요. 각 백엔드는 자체 type과 config를 가지며, 시크릿은 ENC[] 핸들에 backendName; 접두사를 사용해 특정 백엔드로 라우팅돼요.

다음 중 둘 이상이 설정되면 우선순위가 가장 높은 설정이 적용되고 나머지는 경고와 함께 무시돼요:

  1. secret_backend_command
  2. secret_backend_type
  3. multi_secret_backends
구성 (Configuration)
# datadog.yaml

multi_secret_backends:
  <backend_name>:
    type: <backend_type>
    config:
      <KEY_1>: <VALUE_1>

각 <backend_name>은 사용자가 선택하는 임의의 식별자예요. ENC[] 핸들의 구분자로 사용되므로 세미콜론을 포함할 수 없어요. type과 config 필드는 해당 백엔드의 secret_backend_type 및 secret_backend_config와 같은 스키마를 따라요.

ENC[] 표기법

multi_secret_backends가 활성화되면 ENC[] 핸들 앞에 백엔드 이름과 세미콜론을 붙이세요:

ENC[<backend_name>;<secret_key>]

첫 번째 세미콜론만 백엔드 구분자로 취급돼요. 자체에 세미콜론이 포함된 시크릿 키(예: Kubernetes 스타일 namespace/secret-name;key)는 계속 동작해요.

예시 (Example)

다음 구성은 두 파일 백엔드에서 동시에 시크릿을 읽어요:

# datadog.yaml
multi_secret_backends:
  yaml_secrets:
    type: file.yaml
    config:
      file_path: /etc/datadog-agent/secrets.yaml
  aws_secrets:
    type: aws.secrets
    config:
      aws_session:
        aws_region: us-east-1

백엔드 이름을 접두사로 붙여 시크릿을 참조하세요:

# datadog.yaml
api_key: ENC[yaml_secrets;api_key]
app_key: ENC[aws_secrets;My-Secrets;appKey]
secret_backend_type에서 마이그레이션

단일 secret_backend_type에서 multi_secret_backends로 전환하려면:

  1. secret_backend_type과 secret_backend_config를 multi_secret_backends 아래의 명명된 항목으로 이동하세요.
  2. 최상위에서 secret_backend_type과 secret_backend_config를 제거하세요.
  3. 모든 ENC[secretKey] 핸들을 ENC[backendName;secretKey]로 업데이트하세요.
# Before
secret_backend_type: file.yaml
secret_backend_config:
  file_path: /etc/datadog-agent/secrets.yaml

api_key: ENC[api_key]

# After
multi_secret_backends:
  my_yaml:
    type: file.yaml
    config:
      file_path: /etc/datadog-agent/secrets.yaml

api_key: ENC[my_yaml;api_key]

옵션 2: Kubernetes 및 Docker용 내장 스크립트 사용

Agent 7.32+ 버전에서 사용 가능

컨테이너 환경의 경우 Datadog Agent 컨테이너 이미지에는 내장 스크립트 /readsecret_multiple_providers.sh가 포함돼 있어요. 이 스크립트는 다음에서 시크릿을 읽는 것을 지원해요:

  • 파일: ENC[file@/path/to/file] 사용
  • Kubernetes Secrets: ENC[k8s_secret@namespace/secret-name/key] 사용

Datadog Operator — 이 실행 파일을 Datadog Operator와 함께 사용하려면 다음과 같이 구성하세요:

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    secretBackend:
      command: "/readsecret_multiple_providers.sh"

Helm — 이 실행 파일을 Helm 차트와 함께 사용하려면 다음과 같이 설정하세요:

datadog:
  [...]
  secretBackend:
    command: "/readsecret_multiple_providers.sh"

DaemonSet — 이 실행 파일을 사용하려면 DD_SECRET_BACKEND_COMMAND 환경 변수를 다음과 같이 설정하세요:

DD_SECRET_BACKEND_COMMAND=/readsecret_multiple_providers.sh

예시: 마운트된 파일에서 읽기

Kubernetes는 시크릿을 파일로 노출하는 것을 지원하며, Agent가 시크릿을 해석하기 위해 읽을 수 있어요.

Kubernetes에서 시크릿을 볼륨으로 마운트할 수 있어요:

  containers:
    - name: agent
      #(...)
      volumeMounts:
        - name: secret-volume
          mountPath: /etc/secret-volume
  #(...)
  volumes:
    - name: secret-volume
      secret:
        secretName: test-secret

그런 다음 이렇게 시크릿을 참조할 수 있어요:

password: ENC[file@/etc/secret-volume/password]

참고:

  • Secret은 마운트되는 pod와 같은 네임스페이스에 존재해야 해요.
  • 스크립트는 민감한 /var/run/secrets/kubernetes.io/serviceaccount/token을 포함한 모든 하위 폴더에 접근할 수 있어요. 따라서 Datadog은 /var/run/secrets 대신 전용 폴더를 사용할 것을 권장해요.

Docker swarm 시크릿은 /run/secrets 폴더에 마운트돼요. 예를 들어 Docker 시크릿 db_prod_passsword는 Agent 컨테이너의 /run/secrets/db_prod_password에 있어요. 이는 구성에서 ENC[file@/run/secrets/db_prod_password]로 참조돼요.

예시: 다른 네임스페이스에서 Kubernetes 시크릿 읽기

Agent가 다른 네임스페이스의 Secret을 읽게 하려면 k8s_secret@ 접두사를 사용하세요. 예:

password: ENC[k8s_secret@database/database-secret/password]

Agent의 Service Account가 시크릿을 읽을 수 있도록 RBAC를 구성하세요. 다음 Role은 database 네임스페이스의 database-secret Secret에 대한 읽기 권한을 부여해요:

Datadog Operator

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    secretBackend:
      command: "/readsecret_multiple_providers.sh"
      roles:
      - namespace: database
        secrets:
        - "database-secret"

참고: roles 목록의 각 네임스페이스는 Datadog Operator 배포의 WATCH_NAMESPACE 또는 DD_AGENT_WATCH_NAMESPACE 환경 변수에도 구성해야 해요.

Helm

datadog:
  (...)
  secretBackend:
    command: "/readsecret_multiple_providers.sh"
    roles:
      - namespace: database
        secrets:
          - database-secret

또는 RBAC 리소스를 직접 정의할 수 있어요:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: datadog-secret-reader
  namespace: database
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    resourceNames: ["database-secret"]
    verbs: ["get", "watch", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: datadog-read-secrets
  namespace: database
subjects:
  - kind: ServiceAccount
    name: datadog-agent
    apiGroup: ""
    namespace: default
roleRef:
  kind: Role
  name: datadog-secret-reader
  apiGroup: ""

이 Role은 Namespace: database의 Secret: database-secret에 대한 접근을 부여해요. RoleBinding은 이 권한을 Namespace: default의 ServiceAccount: datadog-agent에 연결해요. 이는 배포된 리소스를 기준으로 클러스터에 수동으로 추가해야 해요.

옵션 3: 커스텀 실행 파일 만들기

시크릿을 조회하기 위해 Agent는 사용자가 제공하는 외부 실행 파일을 사용해요. 이 실행 파일은 새 시크릿이 발견될 때 사용되며 Agent의 수명 동안 캐시돼요. 시크릿을 업데이트하거나 로테이션해야 한다면 다시 로드하려면 Agent를 재시작해야 해요.

이렇게 하면 어떤 시크릿 관리 솔루션이든 사용할 수 있고 Agent가 시크릿에 접근하는 방식을 완전히 제어할 수 있어요.

Agent는 이 실행 파일에 해석할 시크릿 핸들 목록이 포함된 JSON 페이로드를 표준 입력으로 보내요. 그런 다음 실행 파일이 각 시크릿을 가져와 표준 출력을 통해 JSON 형식으로 반환해요.

다음 예시는 Agent가 STDIN으로 실행 파일에 보내는 내용을 보여줘요:

{
  "version": "1.0",
  "secrets": ["secret1", "secret2"]
}
  • version (string): 형식 버전.
  • secrets (string 목록): 각 문자열은 가져올 시크릿의 핸들이에요.

실행 파일은 다음과 같은 STDOUT 출력으로 응답해요:

{
  "secret1": {"value": "decrypted_value", "error": null},
  "secret2": {"value": null, "error": "could not fetch the secret"}
}
  • value (string): 설정에 사용할 시크릿 값. 오류가 발생한 경우 null일 수 있어요.
  • error (string): 오류 메시지 또는 null.

시크릿 해석에 실패하면(0이 아닌 종료 코드나 null이 아닌 오류 반환으로) 관련 구성은 Agent에 의해 무시돼요.

stderr에 민감한 정보를 절대 출력하지 마세요. 바이너리가 0과 다른 상태 코드로 종료되면 Agent는 문제 해결을 위해 실행 파일의 표준 오류 출력을 기록해요.

어떤 언어로든 자체 시크릿 조회 실행 파일을 만들 수 있어요. 유일한 요구 사항은 앞서 설명한 입출력 형식을 따르는 것이에요.

다음은 더미 시크릿을 반환하는 Go 예시예요:

package main

import (
  "encoding/json"
  "fmt"
  "io/ioutil"
  "os"
)

type secretsPayload struct {
  Secrets []string `json:secrets`
  Version int      `json:version`
}

func main() {
  data, err := ioutil.ReadAll(os.Stdin)

  if err != nil {
    fmt.Fprintf(os.Stderr, "Could not read from stdin: %s", err)
    os.Exit(1)
  }
  secrets := secretsPayload{}
  json.Unmarshal(data, &secrets)

  res := map[string]map[string]string{}
  for _, handle := range secrets.Secrets {
    res[handle] = map[string]string{
      "value": "decrypted_" + handle,
    }
  }

  output, err := json.Marshal(res)
  if err != nil {
    fmt.Fprintf(os.Stderr, "could not serialize res: %s", err)
    os.Exit(1)
  }
  fmt.Printf(string(output))
}

이렇게 하면 다음 구성이:

instances:
  - server: db_prod
    user: ENC[db_prod_user]
    password: ENC[db_prod_password]

메모리에서 이렇게 변환돼요:

instances:
  - server: db_prod
    user: decrypted_db_prod_user
    password: decrypted_db_prod_password

다음을 추가해 Agent가 시크릿 해석에 이 바이너리를 사용하도록 구성할 수 있어요:

secret_backend_command: /path/to/binary

Agent 보안 요구 사항 (Agent security requirements)

Agent는 제공된 실행 파일을 하위 프로세스로 실행해요. 실행 패턴은 Linux와 Windows에서 다르게 나타나요.

Linux — Linux에서 실행 파일은 다음을 충족해야 해요:

  • Agent를 실행하는 동일한 사용자(기본적으로 dd-agent, 컨테이너 내에서는 root)가 소유해야 해요.
  • group이나 other에 대한 권한이 없어야 해요.
  • 소유자에 대한 실행 권한이 최소한 있어야 해요.

Windows — Windows에서 실행 파일은 다음을 충족해야 해요:

  • ddagentuser(Agent를 실행하는 사용자)에 대한 읽기 또는 실행 권한이 있어야 해요.
  • Administrators 그룹, 기본 제공 Local System 계정, Agent 사용자 컨텍스트(기본적으로 ddagentuser) 외의 다른 사용자나 그룹에 대한 권한이 없어야 해요.
  • Agent가 실행할 수 있도록 유효한 Win32 애플리케이션이어야 해요 (예: PowerShell이나 Python 스크립트는 동작하지 않음).

참고: 실행 파일은 Agent와 동일한 환경 변수를 공유해요.

런타임에서 시크릿 새로고침 (Refreshing secrets at runtime)

Agent 7.67+ 버전에서 사용 가능

재시작 없이 해석된 시크릿을 새로고침하도록 Agent를 구성할 수 있어요.

새로고침 간격을 설정하세요:

secret_refresh_interval: 3600  # refresh every hour

또는 수동으로 새로고침을 트리거하세요:

datadog-agent secret refresh

API/APP 키 새로고침

시크릿으로 가져온 API/APP 키는 런타임 새로고침을 지원해요.

datadog.yaml에서 secret_refresh_interval(초)을 설정해 활성화할 수 있어요:

api_key: ENC[<secret_handle>]

secret_refresh_interval: 3600  # refresh every hour

기본적으로 Agent는 Agent 플릿이 동시에 새로고침하지 않도록 secret_refresh_interval 창 내에서 초기 새로고침을 무작위화해요. 키는 시작 시 해석되고 첫 번째 간격 내에 한 번, 이후 매 간격마다 새로고침돼요.

다운타임을 방지하려면 전체 플릿이 업데이트된 키를 가져온 후에만 이전 키를 무효화하세요. Fleet Management 페이지에서 키 사용량을 추적할 수 있어요.

다음을 설정해 이 동작을 비활성화할 수 있어요:

secret_refresh_scatter: false

Autodiscovery 체크 시크릿 새로고침

Agent 7.76+ 버전에서 사용 가능

템플릿이 ENC[] 구문을 사용하면 예약된 Autodiscovery 체크가 런타임에 시크릿을 새로고침할 수 있어요.

labels:
  tags.datadoghq.com/redis.env: "prod"
  tags.datadoghq.com/redis.service: "my-redis"
  tags.datadoghq.com/redis.version: "6.0.3"
annotations:
  ad.datadoghq.com/redis.checks: |
    {
      "redisdb": {
        "init_config": {},
        "instances": [
          {
            "host": "%%host%%",
            "port":"6379",
            "password":"ENC[<secret_handle>]"
          }
        ]
      }
    }

그러면 Agent는 secret_refresh_interval에 설정된 간격 또는 수동으로 datadog-agent secret refresh로 시크릿 새로고침을 트리거할 수 있어요.

API 키 실패 / 무효화 시 자동 시크릿 새로고침

Agent 7.74+ 버전에서 사용 가능

Agent는 잘못된 API 키를 감지하면 시크릿을 자동으로 새로고침할 수 있어요. 이는 Agent가 Datadog으로부터 403 Forbidden 응답을 받거나 주기적 상태 확인이 잘못되었거나 만료된 API 키를 감지할 때 발생해요.

이 기능을 활성화하려면 datadog.yaml 파일에서 secret_refresh_on_api_key_failure_interval을 분 단위 간격으로 설정하세요. 비활성화하려면 0으로 설정하세요(기본값).

이 간격은 잘못된 API 키가 감지될 때 시크릿 관리 솔루션을 스팸하지 않도록 두 새로고침 사이의 최소 시간이에요.

api_key: ENC[<secret_handle>]

secret_refresh_on_api_key_failure_interval: 10

이 설정은 secret_refresh_interval과 호환돼요.

DDOT collector 새로고침 활성화

DDOT collector를 사용 중이고 API/APP 새로고침을 활성화하려면 datadog.yaml 파일에 다음 추가 구성을 넣어야 해요:

agent_ipc:
  port: 5051
  config_refresh_interval: 3600

이렇게 하면 시크릿이 새로고침된 후 DDOT collector가 Agent와 동기화 상태를 유지해요. Agent가 주기적으로 구성 상태를 검증하는 것처럼 DDOT collector는 이 설정을 사용해 Agent의 업데이트된 값을 정기적으로 확인해요.

문제 해결 (Troubleshooting)

감지된 시크릿 나열하기

Agent CLI의 secret 명령어는 설정과 관련된 오류를 보여줘요. 예를 들어 실행 파일 권한이 잘못된 경우처럼요. 발견된 모든 핸들과 위치도 나열해요.

Linux에서 이 명령어는 실행 파일의 파일 모드, 소유자, 그룹을 출력해요. Windows에서는 ACL 권한이 나열돼요.

Linux

Linux 예시:

datadog-agent secret
=== Checking executable rights ===
Executable path: /path/to/you/executable
Check Rights: OK, the executable has the correct rights

Rights Detail:
file mode: 100700
Owner username: dd-agent
Group name: dd-agent

=== Secrets stats ===
Number of secrets decrypted: 3
Secrets handle decrypted:
- api_key: from datadog.yaml
- db_prod_user: from postgres.yaml
- db_prod_password: from postgres.yaml

Windows

Windows 예시 (Administrator PowerShell에서):

PS C:\> & "$env:ProgramFiles\Datadog\Datadog Agent\bin\agent.exe" secret
=== Checking executable rights ===
Executable path: C:\path\to\you\executable.exe
Check Rights: OK, the executable has the correct rights

Rights Detail:
Acl list:
stdout:

Path   : Microsoft.PowerShell.Core\FileSystem::C:\path\to\you\executable.exe
Owner  : BUILTIN\Administrators
Group  : WIN-ITODMBAT8RG\None
Access : NT AUTHORITY\SYSTEM Allow  FullControl
         BUILTIN\Administrators Allow  FullControl
         WIN-ITODMBAT8RG\ddagentuser Allow  ReadAndExecute, Synchronize
Audit  :
Sddl   : O:BAG:S-1-5-21-2685101404-2783901971-939297808-513D:PAI(A;;FA;;;SY)(A;;FA;;;BA)(A;;0x1200
         a9;;;S-1-5-21-2685101404-2783901971-939297808-1001)

=== Secrets stats ===
Number of secrets decrypted: 3
Secrets handle decrypted:
- api_key: from datadog.yaml
- db_prod_user: from sqlserver.yaml
- db_prod_password: from sqlserver.yaml

시크릿 주입 후 구성을 보기

체크 구성이 어떻게 해석되는지 빠르게 보려면 configcheck 명령어를 사용할 수 있어요:

sudo -u dd-agent -- datadog-agent configcheck

=== a check ===
Source: File Configuration Provider
Instance 1:
host: <decrypted_host>
port: <decrypted_port>
password: <obfuscated_password>
~
===

=== another check ===
Source: File Configuration Provider
Instance 1:
host: <decrypted_host2>
port: <decrypted_port2>
password: <obfuscated_password2>
~
===

참고: 구성 파일의 변경 사항을 적용하려면 Agent를 재시작해야 해요.

secret_backend_command 디버깅

Agent 외부에서 테스트하거나 디버깅하려면 Agent가 실행하는 방식을 모방할 수 있어요:

Linux

sudo -u dd-agent bash -c "echo '{\"version\": \"1.0\", \"secrets\": [\"secret1\", \"secret2\"]}' | /path/to/the/secret_backend_command"

dd-agent 사용자는 Datadog Agent를 설치할 때 생성돼요.

Windows

권한 관련 오류

다음 오류는 설정에 뭔가 빠진 것을 나타내요.

  1. 실행 파일에 필요한 것 외의 다른 그룹이나 사용자에게 권한이 있으면 다음 유사 오류가 기록돼요:

    error while decrypting secrets in an instance: Invalid executable 'C:\decrypt.exe': other users/groups than LOCAL_SYSTEM, Administrators or ddagentuser have rights on it

  2. ddagentuser가 파일에 대한 읽기 및 실행 권한이 없으면 다음 유사 오류가 기록돼요:

    error while decrypting secrets in an instance: could not query ACLs for C:\decrypt.exe

  3. 실행 파일은 유효한 Win32 애플리케이션이어야 해요. 그렇지 않으면 다음 오류가 기록돼요:

    error while running 'C:\decrypt.py': fork/exec C:\decrypt.py: %1 is not a valid Win32 application.

Datadog은 실행 파일에 올바른 권한을 설정하도록 도와주는 Powershell 스크립트를 제공해요. 사용 예시:

.\Set-SecretPermissions.ps1 -SecretBinaryPath C:\secrets\decrypt_secrets.exe
ddagentuser SID: S-1-5-21-3139760116-144564943-2741514060-1076
=== Checking executable permissions ===
Executable path: C:\secrets\decrypt_secrets.exe
Executable permissions: OK, the executable has the correct permissions

Permissions Detail:

stdout:
Path   : Microsoft.PowerShell.Core\FileSystem::C:\secrets\decrypt_secrets.exe
Owner  : BUILTIN\Administrators
Group  : BUILTIN\Administrators
Access : NT AUTHORITY\SYSTEM Allow  FullControl
         BUILTIN\Administrators Allow  FullControl
         DESKTOP-V03BB2P\ddagentuser Allow  ReadAndExecute, Synchronize
Audit  :
Sddl   : O:BAG:BAD:PAI(A;;FA;;;SY)(A;;FA;;;BA)(A;;0x1200a9;;;S-1-5-21-3139760116-144564943-2741514
         060-1076)
stderr:


=== Secrets stats ===
Number of secrets resolved: 0
Secrets handle resolved:
실행 파일 테스트

실행 파일은 시크릿을 가져올 때 Agent에 의해 실행돼요. Datadog Agent는 ddagentuser로 실행돼요. 이 사용자는 특정 권한이 없지만 Performance Monitor Users 그룹의 일부예요. 이 사용자의 비밀번호는 설치 시 무작위로 생성되며 어디에도 저장되지 않아요.

즉 실행 파일은 기본 사용자나 개발 사용자에서 작동할 수 있지만, ddagentuser는 더 제한된 권한을 가지므로 Agent가 실행할 때는 작동하지 않을 수 있어요.

Agent와 같은 조건에서 실행 파일을 테스트하려면 개발 머신에서 ddagentuser의 비밀번호를 업데이트하세요. 이렇게 하면 ddagentuser로 인증해 Agent가 실행할 것과 같은 컨텍스트에서 실행 파일을 실행할 수 있어요.

이렇게 하려면 다음 단계를 따르세요:

  1. Local Security Policy의 Local Policies/User Rights Assignement/Deny Log on locally 목록에서 ddagentuser를 제거하세요.
  2. ddagentuser에 새 비밀번호를 설정하세요(설치 시 생성된 것은 어디에도 저장되지 않으므로). PowerShell에서 다음을 실행하세요: 
    $user = [ADSI]"WinNT://./ddagentuser";
$user.SetPassword("a_new_password")
  3. Service Control Manager에서 DatadogAgent 서비스가 사용할 비밀번호를 업데이트하세요. PowerShell에서 다음을 실행하세요: 
    sc.exe config DatadogAgent password= "a_new_password"

이제 ddagentuser로 로그인해 실행 파일을 테스트할 수 있어요. Datadog은 다른 사용자로 실행 파일을 테스트하도록 도와주는 Powershell 스크립트를 제공해요. 이 스크립트는 사용자 컨텍스트를 전환하고 Agent가 실행 파일을 실행하는 방식을 모방해요.

사용 예시:

.\secrets_tester.ps1 -user ddagentuser -password a_new_password -executable C:\path\to\your\executable.exe -payload '{"version": "1.0", "secrets": ["secret_ID_1", "secret_ID_2"]}'
Creating new Process with C:\path\to\your\executable.exe
Waiting a second for the process to be up and running
Writing the payload to Stdin
Waiting a second so the process can fetch the secrets
stdout:
{"secret_ID_1":{"value":"secret1"},"secret_ID_2":{"value":"secret2"}}
stderr: None
exit code:
0

Agent 시작 거부 (Agent refusing to start)

Agent가 시작 시 가장 먼저 하는 일은 datadog.yaml을 로드하고 그 안의 시크릿을 해석하는 것이에요. 이는 로깅 설정 전에 이뤄져요. 따라서 Windows 같은 플랫폼에서는 datadog.yaml을 로드할 때 발생하는 오류가 로그가 아닌 stderr에 기록돼요. 이는 시크릿용으로 Agent에 제공된 실행 파일이 오류를 반환할 때 발생할 수 있어요.

datadog.yaml에 시크릿이 있고 Agent가 시작을 거부한다면:

  • stderr를 볼 수 있도록 Agent를 수동으로 시작해 보세요.
  • datadog.yaml에서 시크릿을 제거하고 먼저 체크 구성 파일의 시크릿으로 테스트하세요.

Kubernetes 권한 테스트

Kubernetes에서 직접 시크릿을 읽을 때 kubectl auth 명령어로 권한을 다시 확인할 수 있어요. 일반적인 형식은 다음과 같아요:

kubectl auth can-i get secret/<SECRET_NAME> -n <SECRET_NAMESPACE> --as system:serviceaccount:<AGENT_NAMESPACE>:<AGENT_SERVICE_ACCOUNT>

앞서의 Kubernetes Secrets 예시에서 Namespace: database에 Secret:database-secret이 있고 Namespace: default에 ServiceAccount:datadog-agent가 있다고 가정해요.

이 경우 다음 명령어를 사용하세요:

kubectl auth can-i get secret/database-secret -n database --as system:serviceaccount:default:datadog-agent

이 명령어는 Agent가 이 Secret을 볼 권한이 유효한지 반환해요.

끝에 있는 줄바꿈 제거

일부 시크릿 관리 도구는 시크릿을 파일로 내보낼 때 자동으로 줄바꿈을 추가해요. datadog.yaml 구성 파일에서 secret_backend_remove_trailing_line_break: true를 설정해 이러한 줄바꿈을 제거할 수 있어요. 또는 환경 변수 DD_SECRET_BACKEND_REMOVE_TRAILING_LINE_BREAK를 사용해 동일하게 할 수 있으며, 특히 컨테이너 환경에서 유용해요.

시크릿 핸들의 Autodiscovery 변수

시크릿 핸들에 Autodiscovery 변수를 사용하는 것도 가능해요. Agent는 시크릿을 해석하기 전에 이 변수들을 해석해요. 예:

instances:
  - server: %%host%%
    user: ENC[db_prod_user_%%host%%]
    password: ENC[db_prod_password_%%host%%]

더 알아보기 (Learn more)

도움이 되는 추가 문서, 링크, 글: