다음을 통해 공유

Azure Key Vault의 비밀을 대체하려면 Data API 작성기에서 @akv()를 사용하세요.

DAB(데이터 API 작성기)를 사용하면 데이터베이스 연결 문자열과 같은 비밀을 로드 시 대체하여 런타임 구성 파일에서 유지할 수 있습니다. 원래 이 작업은 환경 변수 에 @env() 대한 함수 를 사용하여 수행되었습니다. 버전 1.6부터 DAB는 함수를 통해 @akv() Azure Key Vault에 대한 지원을 추가합니다.

수행되는 기능 @akv()

구성 JSON에서 직접 Azure Key Vault에 저장된 비밀을 참조할 수 있습니다.

{
  "data-source": {
    "connection-string": "@akv('my-connection-secret')"
  }
}

구성 로드 시 DAB는 플레이스홀더를 확인하고 이를 @env('VAR_NAME')와 유사하게 비밀 값으로 바꿉니다. 비밀을 검색할 수 없으면 구성 로드가 실패합니다. 오류에는 누락된 비밀 또는 권한 부여 실패가 포함됩니다.

구성 구조

구성의 루트 수준에서 azure-key-vault 섹션을 추가합니다.

{
  "azure-key-vault": {
    "endpoint": "https://my-vault-name.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  }
}

속성

재산 필수 유형 Description
endpoint Key Vault를 사용하는 경우 예 문자열 전체 Key Vault 엔드포인트 URL
retry-policy 아니오 객체 Key Vault를 호출할 때 재시도 동작을 재정의

정책 개체 다시 시도

분야 Default 비고
mode exponential 허용되는 값: fixed 또는 exponential
max-count 3 0보다 커야 합니다.
delay-seconds 1 0보다 커야 합니다.
max-delay-seconds 60 지수 백오프의 경우 최대값인 0보다 커야 합니다.
network-timeout-seconds 60 0보다 커야 합니다.

정책 모드 다시 시도

Mode 행동
fixed 다음까지 시도 사이에 일정한 대기 시간 delay-seconds 대기합니다 max-count
exponential 도달할 때까지 지연 시간을 max-delay-seconds 또는 max-count까지 두 배로 늘립니다.

로컬 개발: .akv 파일

Azure Key Vault가 없는 개발의 경우 .akv 파일을 사용하여 비밀을 시뮬레이션합니다. 형식은 name=value 줄당입니다.

my-connection-secret=Server=.;Database=AppDb;User Id=app;Password=local-dev;
api-key=dev-api-key-123

비고

개발을 위해 로컬 .akv 파일을 제공하는 경우 해당 항목은 Azure Key Vault에 대한 네트워크 호출 없이 'secret-name') 조회를 충족 @akv(하는 데 사용됩니다.

지침:

  • .akv을(를) 소스 제어에서 제외하세요
  • 비밀 이름은 에 사용된 이름과 일치해야 합니다. @akv('name')

CLI를 사용하여 Azure Key Vault 설정 추가

CLI를 사용하여 Key Vault 설정을 구성할 수 있습니다.

dab configure \
  --azure-key-vault.endpoint "https://my-vault.vault.azure.net/" \
  --azure-key-vault.retry-policy.mode exponential \
  --azure-key-vault.retry-policy.max-count 5 \
  --azure-key-vault.retry-policy.delay-seconds 2 \
  --azure-key-vault.retry-policy.max-delay-seconds 30 \
  --azure-key-vault.retry-policy.network-timeout-seconds 45 \
  --config dab-config.json

유효성 검사:

  • 엔드포인트가 없는 재시도 정책 필드로 인해 유효성 검사 실패가 발생합니다.
  • 선택적 재시도 매개 변수는 양의 정수여야 합니다.

구성에서 @akv() 사용하기

기본 대체

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  }
}

@env()와 혼합된

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@akv('sql-connection')"
  },
  "runtime": {
    "rest": { "enabled": true }
  }
}

비고

시작 시 @env() 대체는 @akv() 대체 전에 발생합니다.

저장 프로시저 매개 변수

{
  "entities": {
    "RunJob": {
      "source": {
        "object": "dbo.RunJob",
        "type": "stored-procedure",
        "parameters": {
          "apiKey": "@akv('job-runner-apikey')"
        }
      },
      "permissions": [
        { "role": "anonymous", "actions": [ "execute" ] }
      ]
    }
  }
}

Troubleshooting

증상 Steps
비밀을 찾을 수 없음 이름 확인, 볼트 내 존재 확인 및 ID 권한 확인
잘못된 다시 시도 값 양의 정수를 사용하거나 제거하여 기본값을 사용하십시오.
구성 업데이트 실패 로그에서 유효성 검증 오류를 확인하십시오
@akv() 대체되지 않음 엔드포인트, 비밀 이름 및 비밀 해제가 사용되도록 설정되어 있는지 확인합니다.
Key Vault에서 401/403 ID 할당 및 사용 권한 확인

전체 예제 구성

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  },
  "azure-key-vault": {
    "endpoint": "https://my-vault.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  },
  "runtime": {
    "rest": { "enabled": true }
  },
  "entities": {
    "Books": {
      "source": "dbo.Books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

예제 .akv 파일:

primary-sql-connection=Server=localhost;Database=BooksDb;User Id=app;Password=password;

중요합니다

비밀이 포함된 파일을 커밋 .akv 하지 마세요. |

빠른 참조

Item 요약
Syntax @akv('secret-name')
엔드포인트 필요 Yes
시뮬레이션 파일 .akv name=value 선과 함께
@env()와(과) 혼합하기 Supported.

검토

Azure Key Vault에서 비밀을 확인하는 데 사용합니다 @akv() . 안정성을 위해 재시도 정책을 구성하고 .akv 파일을 사용하여 개발 중에 비밀을 시뮬레이션합니다. 이렇게 하면 일관된 개발 및 프로덕션 워크플로를 지원하면서 중요한 값이 구성 파일에서 제외됩니다.

  • Last updated on