Linux용 Key Vault 가상 머신 확장

아티클
03/07/2024

Key Vault VM 확장은 Azure Key Vault에 저장된 인증서의 자동 새로 고침을 제공합니다. 특히 확장은 Key Vault에 저장되어 있는 관찰된 인증서 목록을 모니터링합니다. 변경 사항 감지 후 확장이 해당 인증서를 검색하고 설치합니다. 이 문서에서는 Linux용 Key Vault VM 확장에 지원되는 플랫폼, 구성 및 배포 옵션에 대해 자세히 설명합니다.

운영 체제

Key Vault VM 확장은 다음 Linux 배포를 지원합니다.

Ubuntu 20.04, 22.04
Azure Linux

참고 항목

Key Vault VM 확장은 기본 위치 또는 VM 확장 설정의 "certStoreLocation" 속성에서 제공한 위치에 인증서를 다운로드합니다. Key Vault VM 확장은 폴더 권한을 700(rwx------)으로 업데이트하여 폴더 소유자에게만 읽기, 쓰기 및 실행 권한을 허용합니다

지원되는 인증서 콘텐츠 형식

PKCS #12
PEM

필수 조건

인증서를 사용하는 Key Vault 인스턴스. Key Vault 만들기를 참조하세요.
VM/VMSS에 할당된 관리 ID
키 자격 증명 모음 비밀 사용자 역할은 VM 및 Azure Virtual Machine Scale Sets 관리 ID에 대한 Key Vault 범위 수준에서 할당되어야 합니다. 이 역할은 인증서의 비밀 부분을 검색합니다. 자세한 내용은 다음 문서를 참조하세요.
VMSS에는 다음과 같은 ID 설정이 있어야 합니다. "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }
AKV 확장에는 다음 설정이 있어야 합니다. "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Key Vault VM 확장 버전

사용자는 키 자격 증명 모음 VM 확장 버전을 V2.0으로 업그레이드하여 전체 인증서 체인 다운로드 기능을 사용하도록 선택할 수 있습니다. 발급자 인증서(중간 및 루트)는 PEM 파일의 리프 인증서에 추가됩니다.
v2.0으로 업그레이드하려는 경우 먼저 v1.0을 삭제한 다음 v2.0을 설치해야 합니다.

  az vm extension delete --name KeyVaultForLinux --resource-group ${resourceGroup} --vm-name ${vmName}
  az vm extension set -n "KeyVaultForLinux" --publisher Microsoft.Azure.KeyVault --resource-group "${resourceGroup}" --vm-name "${vmName}" –settings .\akvvm.json –version 2.0

기본적으로 최신 버전이 설치되므로 플래그 --version 2.0은 선택 사항입니다.

VM에 v1.0에서 다운로드한 인증서가 있는 경우 v1.0 AKVVM 확장을 삭제해도 다운로드한 인증서는 삭제되지 않습니다. v2.0을 설치한 후에는 기존 인증서가 수정되지 않습니다. VM에서 전체 체인으로 PEM 파일을 가져오려면 인증서 파일을 삭제하거나 인증서를 롤오버해야 합니다.

확장 스키마

다음 JSON은 Key Vault VM 확장에 대한 스키마를 보여 줍니다. 확장에는 protected 설정이 필요하지 않습니다. 모든 설정은 보안의 영향을 받지 않는 정보로 간주됩니다. 확장에는 모니터링되는 비밀 목록, 폴링 빈도 및 대상 인증서 저장소가 필요합니다. 특별한 사항

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KVVMExtensionForLinux",
      "apiVersion": "2022-11-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <It's ignored on Linux>,
          "linkOnRenewal": <Not available on Linux e.g.: false>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "requireInitialSync": <initial synchronization of certificates e..g: true>,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]>
        },
        "authenticationSettings": {
          "msiEndpoint":  <Required when msiClientId is provided. MSI endpoint e.g. for most Azure VMs: "http://169.254.169.254/metadata/identity">,
          "msiClientId":  <Required when VM has any user assigned identities. MSI identity e.g.: "c7373ae5-91c2-4165-8ab6-7381d6e75619".>
        }
       }
      }
    }

참고 항목

관찰된 인증서 URL은 https://myVaultName.vault.azure.net/secrets/myCertName 형식이어야 합니다.

이는 /secrets 경로가 프라이빗 키를 포함하여 전체 인증서를 반환하지만 /certificates 경로에서는 반환하지 않기 때문입니다. 인증서에 대한 자세한 내용은 Azure Key Vault 인증서를 참조하세요.

Important

'authenticationSettings' 속성은 사용자 할당 ID가 있는 VM에 필요합니다. 시스템 할당 ID를 사용하려는 경우에도 여전히 필요합니다. 그렇지 않으면 VM 확장에서 사용할 ID를 알 수 없습니다. 이 섹션이 없으면 사용자 할당 ID가 있는 VM에서 Key Vault 확장이 실패하고 인증서를 다운로드할 수 없게 됩니다. msiClientId를 Key Vault에 인증할 ID로 설정합니다.

Azure Arc 지원 VM에도 필요합니다. msiEndpoint를 http://localhost:40342/metadata/identity로 설정합니다.

속성 값

이름	값/예제	데이터 형식
apiVersion	2022-07-01	날짜
publisher	Microsoft.Azure.KeyVault	string
type	KeyVaultForLinux	string
typeHandlerVersion	2.0	int
pollingIntervalInS	3600	string
certificateStoreName	Linux에서 무시됨	string
linkOnRenewal	false	부울 값
certificateStoreLocation	/var/lib/waagent/Microsoft.Azure.KeyVault.Store	string
requireInitialSync	true	부울 값
observedCertificates	["https://myvault.vault.azure.net/secrets/mycertificate";, "https://myvault.vault.azure.net/secrets/mycertificate2"]	문자열 배열
msiEndpoint	http://169.254.169.254/metadata/identity	string
msiClientId	c7373ae5-91c2-4165-8ab6-7381d6e75619	string

템플릿 배포

Azure Resource Manager 템플릿을 사용하여 Azure VM 확장을 배포할 수 있습니다. 배포 후에 인증서를 새로 고칠 필요가 있는 하나 이상의 가상 머신을 배포하는 경우 템플릿을 사용하는 것이 좋습니다. 확장은 개별 VM 또는 가상 머신 확장 집합에 배포할 수 있습니다. 스키마와 구성은 두 템플릿 형식 모두에 공통적으로 적용됩니다.

가상 머신 확장에 대한 JSON 구성은 템플릿의 가상 머신 리소스 조각, 특히 가상 머신 템플릿의 "resources": [] 개체 및 가상 머신 확장 집합의 "virtualMachineProfile":"extensionProfile":{"extensions" :[] 개체 내에 중첩되어야 합니다.

참고 항목

VM 확장에는 Key Vault를 인증하기 위해 할당되는 시스템 또는 사용자 관리 ID가 필요합니다. Key Vault 인증 및 Key Vault 액세스 정책 할당 방법을 참조하세요.

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KeyVaultForLinux",
      "apiVersion": "2022-11-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
          "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <ingnored on linux>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: "https://myvault.vault.azure.net/secrets/mycertificate"
        }
      }
      }
    }

확장 종속성 순서 지정

Key Vault VM 확장은 구성된 경우 확장 순서 지정을 지원합니다. 기본적으로 확장은 폴링이 시작되는 즉시 성공적인 시작을 보고합니다. 그러나 성공적인 시작을 보고하기 전에 인증서의 전체 목록이 성공적으로 다운로드될 때까지 기다리도록 구성할 수 있습니다. 다른 확장이 시작 전에 인증서가 설치되었는지에 의존하는 경우 이 설정을 사용하도록 설정하면 해당 확장이 Key Vault 확장에 대한 종속성을 선언할 수 있습니다. 이렇게 하면 해당 확장이 의존하는 모든 인증서가 설치될 때까지 해당 확장을 시작할 수 없습니다. 확장은 초기 다운로드를 무기한 다시 시도하고 Transitioning 상태로 유지됩니다.

확장 종속성을 설정하려면 다음을 설정하세요.

"secretsManagementSettings": {
    "requireInitialSync": true,
    ...
}

참고 항목

이 기능을 사용하는 것은 시스템 할당 ID를 만들고 해당 ID로 Key Vault 액세스 정책을 업데이트하는 ARM 템플릿과 호환되지 않습니다. 이렇게 하면 모든 확장이 시작될 때까지 자격 증명 모음 액세스 정책을 업데이트할 수 없으므로 교착 상태가 발생합니다. 대신 단일 사용자 할당 MSI ID를 사용하고 배포하기 전에 해당 ID를 사용하여 자격 증명 모음을 사전 ACL해야 합니다.

Azure PowerShell 배포

Warning

PowerShell 클라이언트는 종종 settings.json의 "에 \를 추가하는데 이렇게 하면 다음 오류로 인해 akvvm_service가 실패합니다. [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

Azure PowerShell은 기존 가상 머신 또는 가상 머신 확장 집합에 Key Vault VM 확장을 배포하는 데 사용할 수 있습니다.

VM에 확장을 배포하려면 다음과 같습니다.

    # Build settings
    $settings = '{"secretsManagementSettings":
    { "pollingIntervalInS": "' + <pollingInterval> +
    '", "certificateStoreName": "' + <certStoreName> +
    '", "certificateStoreLocation": "' + <certStoreLoc> +
    '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
    $extName =  "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"


    # Start the deployment
    Set-AzVmExtension -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings

가상 머신 확장 집합에 확장을 배포하려면 다음을 수행합니다.


    # Build settings
    $settings = '{"secretsManagementSettings":
    { "pollingIntervalInS": "' + <pollingInterval> +
    '", "certificateStoreName": "' + <certStoreName> +
    '", "certificateStoreLocation": "' + <certStoreLoc> +
    '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
    $extName = "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"

    # Add Extension to VMSS
    $vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
    Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -Setting $settings

    # Start the deployment
    Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss

Azure CLI 배포

Azure CLI는 기존 가상 머신 또는 가상 머신 확장 집합에 Key Vault VM 확장을 배포하는 데 사용할 수 있습니다.

VM에 확장을 배포하려면 다음과 같습니다.

   # Start the deployment
     az vm extension set -n "KeyVaultForLinux" `
     --publisher Microsoft.Azure.KeyVault `
     -g "<resourcegroup>" `
     --vm-name "<vmName>" `
     --version 2.0 `
     --enable-auto-upgrade true `
     --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

가상 머신 확장 집합에 확장을 배포하려면 다음을 수행합니다.

      # Start the deployment
      az vmss extension set -n "KeyVaultForLinux" `
      --publisher Microsoft.Azure.KeyVault `
      -g "<resourcegroup>" `
      --vmss-name "<vmssName>" `
      --version 2.0 `
      --enable-auto-upgrade true `
      --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

다음 제한 사항/요구 사항에 주의하세요.

Key Vault 제한 사항:
- 배포 시점에 있어야 합니다.
- 관리 ID를 사용하여 VM/VMSS ID에 대한 Key Vault 액세스 정책을 설정해야 합니다. Key Vault 인증 방법 및 Key Vault 액세스 정책 할당을 참조하세요.

문제 해결 및 지원

확장 배포 상태에 대한 데이터는 Azure PowerShell 또는 Azure Portal을 통해 검색할 수 있습니다. 지정된 VM에 대한 확장의 배포 상태를 보려면 Azure PowerShell을 사용하여 다음 명령을 실행합니다.

Azure PowerShell

Get-AzVMExtension -VMName <vmName> -ResourceGroupname <resource group name>

Azure CLI

 az vm get-instance-view --resource-group <resource group name> --name  <vmName> --query "instanceView.extensions"

Azure CLI는 여러 셸 환경에서 실행할 수 있지만 약간의 형식 변형이 있습니다. Azure CLI 명령으로 예기치 않은 결과가 발생하는 경우 Azure CLI를 성공적으로 사용하는 방법을 참조하세요.

로그 및 구성

Key Vault VM 확장 로그는 VM에서 로컬로 존재하며 문제 해결의 경우 가장 많은 정보를 제공합니다.

위치	설명
/var/log/waagent.log	확장에 대한 업데이트가 발생한 시간을 표시합니다.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/*	Key Vault VM 확장 서비스 로그를 검토하여 akvvm_service 서비스와 인증서 다운로드의 상태를 확인합니다. PEM 파일의 다운로드 위치는 파일에서 인증서 파일 이름이라는 항목을 사용하여 찾을 수 있습니다. certificateStoreLocation을 지정하지 않으면 기본적으로 //var/lib/waagent/Microsoft.Azure.KeyVault.Store/로 설정됩니다.
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<most recent version>/config/*	Key Vault VM 확장 서비스의 구성과 이진 파일입니다.

Symlink 사용

기호화된 링크 또는 Symlink는 고급 바로 가기입니다. 폴더 모니터링을 방지하고 최신 인증서를 자동으로 얻으려면 이 symlink ([VaultName].[CertificateName])를 사용하여 Linux에서 최신 버전의 인증서를 가져올 수 있습니다.

질문과 대답

구성할 수 있는 observedCertificates 수에 제한이 있나요? 아니요, Key Vault VM 확장은 observedCertificates 수에 제한이 없습니다.

지원

이 문서의 어디에서든 도움이 필요한 경우 MSDN Azure 및 Stack Overflow 포럼에서 Azure 전문가에게 문의할 수 있습니다. 또는 Azure 기술 지원 인시던트를 제출할 수 있습니다. Azure 지원 사이트로 가서 지원 받기를 선택합니다. Azure 지원을 사용하는 방법에 대한 자세한 내용은 Microsoft Azure 지원 FAQ를 참조하세요.

Linux용 Key Vault 가상 머신 확장

운영 체제

지원되는 인증서 콘텐츠 형식

필수 조건

Key Vault VM 확장 버전

확장 스키마

속성 값

템플릿 배포

확장 종속성 순서 지정

Azure PowerShell 배포

Azure CLI 배포

문제 해결 및 지원

로그 및 구성

Symlink 사용

질문과 대답

지원

추가 리소스