Azure Key Vault 버전이 지정된 API를 사용합니다. 애플리케이션, 스크립트 또는 인프라 템플릿이 이전 API 버전을 호출하는 경우 최신 기능을 누락하거나, 이후 버전에서 변경된 동작을 사용하거나, 더 이상 권장되지 않는 버전에 의존할 수 있습니다. 이 문서에서는 사용하는 API 버전을 확인하는 방법과 지원되는 현재 버전으로 이동하는 방법을 설명합니다.
Important
2026-02-01 이전의 모든 Key Vault 제어 평면 API 버전은 2027년 2월 27일에 사용 중지됩니다. 해당 날짜 이후에도 키 자격 증명 모음은 계속 존재하지만, 컨트롤 플레인 API 버전 2026-02-01 이상을 통해서만 관리할 수 있습니다. 이 날짜에 대한 예외 또는 확장은 없습니다. 이 사용 중지는 데이터 평면 API(키, 비밀 및 인증서를 사용하는 데 사용되는 API)에 영향을 주지 않습니다. 자세한 내용은 Key Vault 기본 액세스 제어 모델로 Azure RBAC 계획을 참조하세요.
Azure Key Vault 각각 고유한 버전이 있는 두 개의 독립적인 API 표면이 있습니다.
| API 표면 | 관리하는 내용 | 버전 구성표 | 엔드포인트 예제 |
|---|---|---|---|
| 컨트롤 플레인 (관리) | 키 자격 증명 모음 리소스 자체: 자격 증명 모음 만들기, 업데이트, 삭제 및 SKU, 네트워크 규칙 및 액세스 제어와 같은 속성을 구성합니다. | 날짜 기반({YYYY}-{MM}-{DD}) |
https://management.azure.com |
| 데이터 평면 | 자격 증명 모음 내부의 개체: 키, 비밀, 인증서 및 암호화 작업. | 날짜 기반({YYYY}-{MM}-{DD}) |
https://<vault-name>.vault.azure.net |
두 표면은 버전 관리 및 수명 주기 사례가 다릅니다. 하나를 업데이트해도 다른 업데이트는 업데이트되지 않습니다. 워크로드에서 둘 다 사용하는 경우 둘 다 검토하세요.
이 문서의 앞부분에서 설명한 대로 컨트롤 플레인 API 버전을 사용 중지할 수 있습니다.
미리 보기 데이터 평면 API 버전은 더 이상 사용되지 않을 수 있으므로 해당 수명 주기를 허용하지 않는 한 프로덕션 환경에서 미리 보기를 사용하지 마세요. 지원되는 데이터 평면 API 버전은 Azure Key Vault REST API 참조를 참조하세요.
이 문서에서는 API 버전을 식별하고 업데이트하는 데 중점을 둡니다. 컨트롤 플레인 API 버전을 업데이트해도 기존 키 자격 증명 모음을 액세스 정책에서 Azure RBAC로 마이그레이션할 필요가 없습니다. 액세스 제어를 마이그레이션하려면 액세스 정책에서 AZURE RBAC로 마이그레이션을 참조하세요. API 버전 2026-02-01 이후의 새 Key Vault에 도입된 Azure RBAC의 기본 동작에 대해서는 Key Vault의 기본 액세스 제어 모델인 Azure RBAC 계획을 참조하세요.
현재 API 버전으로 이동하는 이유
- 지원되는 기능을 사용합니다. 최신 API 버전은 기능을 추가하거나, 동작을 수정하거나, 새 서비스 기능을 지원할 수 있습니다.
- 프로덕션 워크로드를 안정적으로 유지합니다. 프로덕션 워크로드에 안정적인 현재 API 버전을 사용합니다. 미리 보기 API 버전은 평가 및 초기 테스트를 위한 것이며 Azure 지원 SLA는 이를 다루지 않을 수 있습니다. 미리 보기 버전은 더 이상 사용되지 않을 수 있습니다.
- 도구와 라이브러리의 호환성을 유지합니다. Azure CLI, Azure PowerShell, SDK, 템플릿 및 포털은 다른 API 버전을 사용할 수 있습니다. 한 클라이언트에 대한 버전을 업데이트해도 다른 클라이언트는 업데이트되지 않습니다.
현재 컨트롤 플레인 버전은 지원되는 컨트롤 플레인 API 버전을 참조하세요. 지원되는 데이터 평면 버전은 Azure Key Vault REST API 참조를 참조하세요.
사용하는 API 버전 결정
Key Vault 호출하는 방법에 따라 API 버전을 다르게 지정합니다. 워크로드에서 사용하는 각 표면을 확인합니다.
컨트롤 플레인(관리)
-
REST API: 버전은
https://management.azure.com에 대한 요청에서?api-version=<control-plane-version>쿼리 문자열 매개 변수이며, 예를 들면api-version입니다. -
ARM, Bicep 및 Terraform 템플릿: 버전은 각
Microsoft.KeyVault/vaults리소스의apiVersion속성입니다. Bicep에서는 리소스 형식 선언의 일부이며, 예를 들어resource kv 'Microsoft.KeyVault/vaults@2026-02-01'와 같습니다. - 컨트롤 플레인 관리 SDK: 패키지 버전에서 SDK가 지원하는 API 버전을 결정할 수 있지만 패키지 버전만으로는 요청에서 사용되는 API 버전을 항상 식별하지는 않습니다. 패키지 릴리스 정보와 API 참조(예를 들어 또는 의)를 확인하고, 이를 프로젝트의 의존성 매니페스트에 있는 패키지 버전과 비교하세요. 언어별 API 참조는 Azure Key Vault 클라이언트 라이브러리를 참조하세요.
-
Azure CLI 및 Azure PowerShell: Azure CLI 또는
Az모듈 버전에 따라 API 버전이 결정됩니다. az 버전 또는 Get-InstalledModule -Name Az를 사용하여 설치된 버전을 확인합니다. - Azure 포털: 포털은 요청에 대한 컨트롤 플레인 API 버전을 선택합니다. 해당 버전을 직접 설정할 수 없습니다. 포털은 템플릿, 스크립트 또는 SDK와 다른 API 버전을 사용할 수 있으므로 포털 동작을 사용하여 자동화에서 사용되는 버전을 결정하지 마세요.
- Azure Cloud Shell: Cloud Shell 현재 Azure CLI 및 Azure PowerShell 버전을 사용합니다. Cloud Shell 스크립트를 실행하는 경우 현재 지원되는 컨트롤 플레인 API 버전과 호환되는지 확인합니다.
데이터 평면
-
REST API: 버전은 예를 들어
api-version자격 증명 모음 엔드포인트에 대한 요청에 대한 쿼리 문자열 매개 변수입니다GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>. -
데이터 평면 SDK: 패키지 버전은 SDK가 지원하는 API 버전을 결정할 수 있지만 패키지 버전만으로는 요청에서 사용되는 API 버전을 항상 식별하지는 않습니다. 패키지 릴리스 정보와 API 참조(예:
Azure.Security.KeyVault.Secrets,Azure.Security.KeyVault.Keys또는Azure.Security.KeyVault.Certificates의 경우)를 확인하고 프로젝트의 종속성 매니페스트에 있는 패키지 버전과 비교합니다. 언어별 API 참조는 Azure Key Vault 클라이언트 라이브러리를 참조하세요.
API 버전 업데이트
컨트롤 플레인 API 버전 업데이트
템플릿 및 REST 호출에서 API 버전을 업데이트합니다. 모든
apiVersion정의 및 관리 요청에서api-version(ARM, Bicep, Terraform) 또는Microsoft.KeyVault/vaults쿼리 문자열 매개 변수(REST)를 현재 지원되는 제어 평면 버전으로 설정합니다.컨트롤 플레인 관리 SDK를 업데이트합니다. 선택한 컨트롤 플레인 API 버전을 지원하는 패키지 버전에 대한 패키지 릴리스 정보 및 API 참조를 확인합니다. 언어별 API 참조 및 현재 Key Vault 컨트롤 플레인 버전을 지원하는 패키지 버전은 Azure Key Vault 클라이언트 라이브러리 및 컨트롤 플레인 SDK 릴리스를 참조하세요.
참고
컨트롤 플레인 관리 SDK를 업데이트해도 데이터 평면 SDK는 업데이트되지 않습니다. 애플리케이션에서 두 API 표면을 모두 사용하는 경우 각 SDK를 개별적으로 업데이트합니다.
Azure CLI 및 Azure PowerShell을 업데이트하세요. 최신 도구 버전은 최신 API 버전을 호출합니다.
Azure CLI를 최신 버전으로 업데이트합니다. 자세한 내용은
Azure CLI 참조하세요.
- 배포하기 전에 동작 변경 내용을 검토합니다. 배포하기 전에 API 버전의 변경 로그 및 사양을 읽습니다. API 버전
2026-02-01이상에서는 새 키 보관소에 대해서만 기본 액세스 제어 모델이 변경됩니다. 자세한 내용은 Key Vault 기본 액세스 제어 모델로 Azure RBAC 계획을 참조하세요.
데이터 평면 API 버전 업데이트
REST 호출에서 API 버전을 업데이트합니다.
api-version쿼리 문자열 매개 변수를 Azure Key Vault REST API 참조에 나열된 현재 지원되는 데이터 평면 버전으로 설정합니다.데이터 평면 SDK를 업데이트합니다.
Azure.Security.KeyVault.*(또는 해당 언어에 해당하는) 패키지를 현재 안정적인 버전으로 업그레이드합니다. 패키지 릴리스 정보 및 API 참조를 확인하여 패키지에서 지원하는 데이터 평면 API 버전을 확인합니다. 언어별 API 참조 및 패키지 링크는 Azure Key Vault 클라이언트 라이브러리를 참조하세요.
안정적인 데이터 평면 API 버전은 현재 컨트롤 플레인 사용 중지의 영향을 받지 않습니다. 미리 보기 데이터 평면 API를 사용하는 경우 서비스 공지 사항 및 해당 수명 주기에 대한 API 참조를 검토합니다.
데이터 평면 REST API 호출에 대한 자세한 내용은 인증, 요청 및 응답 및Azure Key Vault REST API 참조를 참조하세요.