다음을 통해 공유

Linux용 Key Vault 가상 머신 확장

  • 아티클

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

운영 체제

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

참고 항목

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

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

  • PKCS #12
  • PEM

버전 3.0 이상에서 업데이트

Linux용 Key Vault VM 확장 버전 3.0 이상은 다음 기능에 대한 지원을 추가합니다.

  • 다운로드한 인증서에 대한 ACL 권한을 추가하여 사용자 및 그룹에 대한 읽기 액세스 권한을 제공합니다.
  • 인증서 설치 위치 구성
  • 사용자 지정 기호 이름 지원
  • Fluentd를 통한 VM 확장 로깅 통합 지원

필수 조건

  • 인증서를 사용하는 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 확장 버전

  • 사용자는 기존 Key Vault VM 확장 버전을 최신 버전으로 업그레이드하도록 선택할 수 있습니다.

  • 최신 버전으로 업그레이드하려면 먼저 이전 버전을 삭제한 다음 최신 버전을 설치해야 합니다.

  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 3.0

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

  • VM에 이전 버전에서 다운로드한 인증서가 있는 경우 VM 확장을 삭제해도 다운로드한 인증서가 삭제되지 않습니다. 최신 버전을 설치한 후에는 기존 인증서가 수정되지 않습니다. 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": "3.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
      "loggingSettings": <Optional logging settings, e.g.:
        {
              "logger": <Logger engine name. e.g.: "fluentd">,
              "endpoint": <Logger listening endpoint "tcp://localhost:24224">,
              "format": <Logging format. e.g.: "forward">,
              "servicename": <Service name used in logs. e.g.: "akvvm_service">
          }>,
        "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "linkOnRenewal": <Not available on Linux e.g.: false>,
          "requireInitialSync": <initial synchronization of certificates e..g: true>,
          "aclEnabled": <Enables ACLs for downloaded certificates, e.g.: true>,
          "observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location, ACL permission to certificate private key, and custom symbolic name. e.g.: 
             [
                {
                    "url": <A Key Vault URI to the secret portion of the certificate. e.g.: "https://myvault.vault.azure.net/secrets/mycertificate1">,
                    "certificateStoreLocation": <disk path where certificate is stored, e.g.: "/var/lib/waagent/Microsoft.Azure.KeyVault/app1">,
                    "customSymbolicLinkName": <symbolic name for the certificate. e.g.: "app1Cert1">,
                    "acls": [
                        {
                            "user": "app1",
                            "group": "appGroup1"
                        },
                        {
                            "user": "service1"
                        }
                    ]
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreLocation": <disk path where the certificate is stored, e.g.: "/var/lib/waagent/Microsoft.Azure.KeyVault/app2">,
                    "acls": [
                        {
                            "user": "app2",
                        }
                    ]
                }
             ]>
        },
        "authenticationSettings": <Optional msi settings, e.g.:
        {
          "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 date
publisher Microsoft.Azure.KeyVault string
type KeyVaultForLinux string
typeHandlerVersion 3.0 int
pollingIntervalInS 3600 string
certificateStoreName Linux에서 무시됨 string
linkOnRenewal false 부울 값
requireInitialSync true 부울 값
aclEnabled true 부울 값
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
observedCertificates [{...}, {...}] 문자열 배열
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" string
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" string
observedCertificates/customSymbolicLinkName(선택 사항) "app1Cert1" string
observedCertificates/acls(선택 사항) "{...}, {...}" 문자열 배열
authenticationSettings(선택 사항) {...} 개체
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity string
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string
loggingSettings(선택 사항) {...} 개체
loggingSettings/logger "fluentd" string
loggingSettings/endpoint "tcp://localhost:24224" string
loggingSettings/format "forward" string
loggingSettings/servicename "akvvm_service" 문자열

템플릿 배포

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": "3.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
          "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "requireInitialSync": <initial synchronization of certificates e..g: false>,
          "aclEnabled": <enables/disables acls on defined certificates e.g.: true>,
          "observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location and ACL permission to certificate private key. Example:
             [
                {
                    "url": <A Key Vault URI to the secret portion of the certificate. Example: "https://myvault.vault.azure.net/secrets/mycertificate1">,
                    "certificateStoreLocation": <The certificate store location, which currently works locally only. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
                    "acls": <Optional. An array of preferred acls with read access to certificate private keys. Example: 
                    [
                        {
                            "user": "app1",
                            "group": "appGroup1"
                        },
                        {
                            "user": "service1"
                        }
                    ]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreName": <ignored on linux>,
                    "certificateStoreLocation": <The certificate store location, which currently works locally only. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
                    "acls": <Optional. An array of preferred acls with read access to certificate private keys. Example: 
                    [
                        {
                            "user": "app2"
                        }
                    ]>
                }
               
             ]>   
          },
          "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">
          }
        } 
      }
    }

확장 종속성 순서 지정

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에 확장을 배포하려면 다음과 같습니다.

Azure Key Vault VM 확장은 Azure PowerShell을 사용하여 배포할 수 있습니다. Key Vault VM 확장 설정을 JSON 파일(settings.json)에 저장합니다.

다음 JSON 코드 조각은 PowerShell을 사용하여 Key Vault VM 확장을 배포하기 위한 예제 설정을 제공합니다.

{
   "secretsManagementSettings": {
   "pollingIntervalInS": "3600",
   "linkOnRenewal": true,
   "aclEnabled": true,
   "observedCertificates":
   [
      {
          "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate1",
          "certificateStoreLocation":  "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
          "acls": 
          [
              {
                  "user": "app1",
                  "group": "appGroup1"
              },
              {
                  "user": "service1"
              }
          ]
      },
      {
          "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate2",
          "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
          "acls": 
          [
              {
                  "user": "app2"
              }
          ]
      }
   ]},
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
      "msiClientId":  "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
   }      
}
  • 가상 머신에 확장을 배포하려면 다음을 수행합니다.
# Build settings
$settings = (get-content -raw ".\settings.json")
$extName =  "KeyVaultForLinux"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForLinux"
 
# Start the deployment
Set-AzVmExtension -TypeHandlerVersion "3.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings
  • 가상 머신 확장 집합에 확장을 배포하려면 다음을 수행합니다.
    # Build settings
    $settings = (get-content -raw ".\settings.json")
    $extName = "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"
      
    # Add extension to Virtual Machine Scale Sets
    $vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
    Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "3.0" -Setting $settings
    
    # Start the deployment
    Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss

Azure CLI 배포

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

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

Azure Key Vault VM 확장은 Azure CLI를 사용하여 배포할 수 있습니다. Key Vault VM 확장 설정을 JSON 파일(settings.json)에 저장합니다.

다음 JSON 코드 조각은 Azure CLI를 사용하여 Key Vault VM 확장을 배포하기 위한 예제 설정을 제공합니다.

{
   "secretsManagementSettings": {
   "pollingIntervalInS": "3600",
   "linkOnRenewal": true,
   "aclEnabled": true,
   "observedCertificates":
   [
      {
          "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate1",
          "certificateStoreLocation":  "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
          "acls": 
          [
              {
                  "user": "app1",
                  "group": "appGroup1"
              },
              {
                  "user": "service1"
              }
          ]
      },
      {
          "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate2",
          "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
          "acls": 
          [
              {
                  "user": "app2"
              }
          ]
      }
   ]},
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
      "msiClientId":  "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
   }      
}
  • 가상 머신에 확장을 배포하려면

    # Start the deployment
      az vm extension set -n "KeyVaultForLinux" `
      --publisher Microsoft.Azure.KeyVault `
      -g "<resourcegroup>" `
      --vm-name "<vmName>" `
      --version 3.0 `
      --enable-auto-upgrade true `
      --settings "@settings.json"
  • 가상 머신 확장 집합에 확장을 배포하려면 다음을 수행합니다.
    # Start the deployment
    az vmss extension set -n "KeyVaultForLinux" `
    --publisher Microsoft.Azure.KeyVault `
    -g "<resourcegroup>" `
    --vmss-name "<vmssName>" `
    --version 3.0 `
    --enable-auto-upgrade true `
    --settings "@settings.json"

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

  • Key Vault 제한 사항:
    • 배포 시점에 있어야 합니다.
    • Key Vault 비밀 사용자 역할은 VM ID에 대한 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에 로컬로 존재하며 문제 해결과 관련하여 가장 유익합니다. 선택적 로깅 섹션을 사용하여 로깅 공급자와 통합할 수 있습니다. fluentd

위치 설명
/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 ([VaultName].[CertificateName])를 사용하여 Linux에서 최신 버전의 인증서를 가져올 수 있습니다.

질문과 대답

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

지원

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