다음을 통해 공유

Linux용 Key Vault 가상 머신 확장

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

운영 체제

Key Vault VM 확장은 다음을 지원합니다.

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

  • PKCS #12
  • PEM

기능

Linux 버전 3.0 이상용 Key Vault VM 확장은 다음을 지원합니다.

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

필수 조건

  • 인증서를 사용하는 Key Vault 인스턴스. Key Vault 만들기를 참조하세요.

  • 가상 머신/가상 머신 확장 집합에 할당된 관리 ID 입니다.

  • 키 자격 증명 모음 비밀 사용자 역할은 VM 및 Azure Virtual Machine Scale Sets 관리 ID에 대한 Key Vault 범위 수준에서 할당되어야 합니다. 이 역할은 인증서의 비밀 부분을 검색합니다. 자세한 내용은 다음 문서를 참조하세요.

  • 가상 머신 확장 집합에는 다음 ID 설정이 있어야 합니다. "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }

  • AKV 확장에는 다음 설정이 있어야 합니다. "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Key Vault VM 확장 업그레이드

  • 이전 버전에서 버전 3.0 이상으로 업그레이드해야 하는 경우 먼저 이전 버전을 삭제한 다음 버전 3.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 3.0
  • VM에 이전 버전에서 다운로드한 인증서가 있는 경우 VM 확장을 삭제해도 다운로드한 인증서가 삭제되지 않습니다. 최신 버전을 설치한 후에는 기존 인증서가 수정되지 않습니다. VM에서 전체 체인으로 PEM 파일을 가져오려면 인증서 파일을 삭제하거나 인증서를 롤오버해야 합니다.

확장 스키마

다음 JSON은 Key Vault VM 확장에 대한 스키마를 제공합니다. 모든 설정은 일반(보호되지 않음) 설정으로 지정됩니다. 중요한 설정은 없습니다. 확장을 구성하려면 모니터링할 인증서 목록, 업데이트를 폴링하는 빈도 및 인증서 저장 대상 경로를 지정해야 합니다. 특히:

    {
      "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.: "00001111-aaaa-2222-bbbb-3333cccc4444".>
        }>
       }
      }
    }

비고

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

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

중요합니다

'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 문자열
type KeyVaultForLinux 문자열
typeHandlerVersion 3.0 정수 (int)
pollingIntervalInS 3600 문자열
certificateStoreName Linux에서 무시됨 문자열
linkOnRenewal 거짓 불리언
requireInitialSync 맞다 불리언
aclEnabled 맞다 불리언
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store 문자열
observedCertificates [{...}, {...}] 문자열 배열
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" 문자열
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" 문자열
observedCertificates/customSymbolicLinkName(선택 사항) app1Cert1 문자열
observedCertificates/acls(선택 사항) {...}, {...} 문자열 배열
authenticationSettings(선택 사항) {...} 객체
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity 문자열
authenticationSettings/msiClientId 00001111-aaaa-2222-bbbb-3333cccc44444 문자열
loggingSettings(선택 사항) {...} 객체
loggingSettings/logger fluentd 문자열
loggingSettings/endpoint "tcp://localhost:24224" 문자열
loggingSettings/format 전진 문자열
loggingSettings/servicename "akvvm_service" 문자열

템플릿 배포

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

비고

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.: "00001111-aaaa-2222-bbbb-3333cccc4444">
          }
        } 
      }
    }

확장 종속성 순서 지정

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

확장은 대기 시간이 증가하는 동안 초기 다운로드를 최대 25번까지 다시 시도하며, 이 기간 동안 Transitioning 상태에 머무릅니다. 재시도를 모두 사용한 경우, 확장이 Error 상태를 보고합니다.

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

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

비고

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

Azure PowerShell 배포

경고

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-<최신 버전>/config/* Key Vault VM 확장 서비스의 구성과 이진 파일입니다.

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

Linux에서 인증서 설치

Linux용 Key Vault VM 확장은 인증서를 전체 인증서 체인이 포함된 PEM 파일로 설치합니다. Key Vault에서 인증서를 다운로드하면 확장은 다음과 같습니다.

  1. certificateStoreLocation 설정에 따라 스토리지 폴더를 생성합니다(지정되지 않은 경우 기본값은 /var/lib/waagent/Microsoft.Azure.KeyVault.Store/).
  2. 다음 특정 순서로 RFC 5246 섹션 7.4.2 에 따라 PEM 파일에 전체 인증서 체인 및 프라이빗 키를 설치합니다.
    • 리프 인증서(최종 엔터티 인증서)가 우선적으로 제공됩니다.
    • 중간 인증서는 순서대로 수행됩니다. 여기서 각 인증서는 그 전에 인증서를 직접 인증합니다.
    • 루트 인증서가 있는 경우(시스템에서 이미 신뢰할 수 있는 경우 유효성 검사에 필요하지는 않지만)
    • 리프 인증서에 해당하는 프라이빗 키는 파일의 끝에 배치됩니다.
  3. 인증서의 최신 버전을 가리키는 기호 [VaultName].[CertificateName] 링크를 자동으로 만듭니다.

이 방법은 다음을 보장합니다.

  • 애플리케이션은 항상 유효성 검사에 필요한 전체 인증서 체인에 액세스할 수 있습니다.
  • RFC 표준에 따라 TLS 핸드셰이크에 대해 인증서 체인이 올바르게 정렬됩니다.
  • 프라이빗 키는 서비스에서 사용할 수 있습니다.
  • 애플리케이션은 인증서가 갱신될 때 자동으로 업데이트되는 안정적인 기호 링크 경로를 참조할 수 있습니다.
  • 인증서를 회전하거나 갱신할 때 애플리케이션 재구성이 필요하지 않습니다.

인증서 경로 구조 예제

이름이 myCertificate있는 인증서 exampleVault.vault.azure.net 의 경우 디렉터리 구조는 다음과 같습니다.

/var/lib/waagent/Microsoft.Azure.KeyVault.Store/
├── exampleVault.myCertificate -> exampleVault.myCertificate.1234567890abcdef
├── exampleVault.myCertificate.1234567890abcdef    # Full chain PEM file (current version)
└── exampleVault.myCertificate.0987654321fedcba    # Previous version (if exists)

애플리케이션은 항상 최신 인증서 버전에 액세스하도록 기호화된 링크 경로(/var/lib/waagent/Microsoft.Azure.KeyVault.Store/exampleVault.myCertificate)를 사용하도록 구성해야 합니다.

사용자 지정 인증서 저장소 위치 및 customSymbolicLinkName 설정을 사용하는 경우 구조는 다음 패턴을 따릅니다.

/path/to/custom/store/
├── customLinkName -> exampleVault.myCertificate.1234567890abcdef
└── exampleVault.myCertificate.1234567890abcdef    # Full chain PEM file

자주 묻는 질문

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

지원

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