Extensão de máquina virtual Key Vault para Linux

  • Artigo

A extensão de VM do Cofre da Chave fornece atualização automática de certificados armazenados em um cofre de chaves do Azure. Especificamente, a extensão monitora uma lista de certificados observados armazenados em cofres de chaves. A extensão recupera e instala os certificados correspondentes depois de detetar uma alteração. Este documento detalha as plataformas, configurações e opções de implantação suportadas para a extensão Key Vault VM para Linux.

Sistema operativo

A extensão Key Vault VM suporta estas distribuições Linux:

Nota

A Extensão de VM do Cofre da Chave baixa os certificados no local padrão ou para o local fornecido pela propriedade "certStoreLocation" nas configurações da Extensão da VM. A Extensão de VM do Cofre de Chaves atualiza a permissão de pasta para 700 (drwx------), permitindo permissão de leitura, gravação e execução apenas para o proprietário da pasta

Tipos de conteúdo de certificado suportados

  • PKCS #12
  • PEM

Pré-requisitos

Versão da extensão Key Vault VM

  • Os usuários podem optar por atualizar sua versão de extensão vm do Cofre da Chave para V2.0 usar o recurso de download da cadeia de certificados completa. Os certificados do emissor (intermediário e raiz) são incluídos com o certificado folha no arquivo PEM.

  • Se você preferir atualizar para v2.0o , você precisaria excluir v1.0 primeiro e, em seguida, instalar o 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

O sinalizador --version 2.0 é opcional porque a versão mais recente é instalada por padrão.

  • Se a VM tiver certificados baixados pela v1.0, excluir a extensão AKVVM v1.0 não excluirá os certificados baixados. Depois de instalar a v2.0, os certificados existentes não são modificados. Você precisaria excluir os arquivos de certificado ou sobrepor o certificado para obter o arquivo PEM com cadeia completa na VM.

Esquema de extensão

O JSON a seguir mostra o esquema para a extensão de VM do Cofre da Chave. A extensão não requer configurações protegidas - todas as suas configurações são consideradas informações sem impacto na segurança. A extensão requer uma lista de segredos monitorados, frequência de sondagem e o armazenamento de certificados de destino. Especificamente:

    {
      "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".>
        }
       }
      }
    }

Nota

Os URLs dos certificados observados devem ter o formato https://myVaultName.vault.azure.net/secrets/myCertName.

Isso ocorre porque o /secrets caminho retorna o certificado completo, incluindo a chave privada, enquanto o /certificates caminho não. Mais informações sobre certificados podem ser encontradas aqui: Key Vault Certificates

Importante

A propriedade 'authenticationSettings' é necessária para VMs com identidades atribuídas ao usuário. Mesmo se você quiser usar uma identidade atribuída ao sistema, isso ainda é necessário, caso contrário, a extensão da VM não sabe qual identidade usar. Sem essa seção, uma VM com identidades atribuídas ao usuário resultará na falha da extensão do Cofre de Chaves e na impossibilidade de baixar certificados. Defina msiClientId como a identidade que será autenticada no Cofre da Chave.

Também necessário para VMs habilitadas para Azure Arc. Defina msiEndpoint como http://localhost:40342/metadata/identity.

Valores de propriedade

Nome Valor / Exemplo Tipo de Dados
apiVersion 2022-07-01 data
editora Microsoft.Azure.KeyVault string
tipo KeyVaultForLinux string
typeHandlerVersion 2.0 número inteiro
pollingIntervalInS 3600 string
certificateStoreName É ignorado no Linux string
linkOnRenewal false boolean
certificateStoreLocalização /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
requireInitialSync verdadeiro boolean
observedCertificados ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"] matriz de cadeia de caracteres
msiPonto final http://169.254.169.254/metadata/identity string
msiClientId C7373AE5-91C2-4165-8AB6-7381D6E75619 string

Implementação de modelos

As extensões de VM do Azure podem ser implantadas com modelos do Azure Resource Manager. Os modelos são ideais ao implantar uma ou mais máquinas virtuais que exigem atualização pós-implantação de certificados. A extensão pode ser implantada em VMs individuais ou conjuntos de dimensionamento de máquinas virtuais. O esquema e a configuração são comuns a ambos os tipos de modelo.

A configuração JSON para uma extensão de máquina virtual deve ser aninhada dentro do fragmento de recurso de máquina virtual do modelo, especificamente "resources": [] objeto para o modelo de máquina virtual e para uma escala de máquina virtual definida como "virtualMachineProfile":"extensionProfile":{"extensions" :[] objeto.

Nota

A extensão da VM exigiria que a identidade gerenciada pelo sistema ou pelo usuário fosse atribuída para autenticar no Cofre da chave. Consulte Como autenticar no Cofre da Chave e atribuir uma política de acesso ao Cofre da Chave.

    {
      "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"
        }
      }
      }
    }

Ordenação de dependência de extensão

A extensão Key Vault VM suporta ordenação de extensão, se configurada. Por padrão, a extensão relata o início bem-sucedido assim que a sondagem começa. No entanto, você pode configurá-lo para aguardar até que ele baixe com êxito a lista completa de certificados antes de relatar um início bem-sucedido. Se outras extensões dependerem de certificados instalados antes de serem iniciadas, habilitar essa configuração permitirá que essas extensões declarem uma dependência na extensão do Cofre da Chave. Isso impedirá que essas extensões sejam iniciadas até que todos os certificados dos quais dependem tenham sido instalados. A extensão tentará novamente o download inicial indefinidamente e permanecerá em um Transitioning estado.

Para ativar a dependência de extensão, defina o seguinte:

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

Nota

O uso desse recurso não é compatível com um modelo ARM que cria uma identidade atribuída ao sistema e atualiza uma política de acesso ao Cofre da Chave com essa identidade. Isso resultará em um impasse, pois a política de acesso ao cofre não pode ser atualizada até que todas as extensões tenham começado. Em vez disso, você deve usar uma identidade MSI atribuída a um único usuário e pré-ACL seus cofres com essa identidade antes de implantar.

Implantação do Azure PowerShell

Aviso

Os clientes do PowerShell geralmente adicionam \ no " settings.json o que causará akvvm_service falha com erro: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

O Azure PowerShell pode ser usado para implantar a extensão de VM do Cofre da Chave em uma máquina virtual existente ou em um conjunto de dimensionamento de máquina virtual.

  • Para implantar a extensão em uma 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

  • Para implantar a extensão em um conjunto de escala de máquina virtual:

    
    # 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

Implementação da CLI do Azure

A CLI do Azure pode ser usada para implantar a extensão de VM do Cofre da Chave em uma máquina virtual existente ou em um conjunto de dimensionamento de máquina virtual.

  • Para implantar a extensão em uma 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> \"] }}'

  • Para implantar a extensão em um conjunto de escala de máquina virtual:

          # 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> \"] }}'

Tenha em atenção as seguintes restrições/requisitos:

  • Restrições do Cofre da Chave:

Solução de problemas e suporte

Os dados sobre o estado das implantações de extensão podem ser recuperados do portal do Azure e usando o Azure PowerShell. Para ver o estado de implantação das extensões de uma determinada VM, execute o seguinte comando usando o Azure PowerShell.

Azure PowerShell

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

CLI do Azure

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

A CLI do Azure pode ser executada em vários ambientes de shell, mas com pequenas variações de formato. Se você tiver resultados inesperados com os comandos da CLI do Azure, consulte Como usar a CLI do Azure com êxito.

Logs e configuração

Os logs de extensão da VM do Cofre da Chave só existem localmente na VM e são mais informativos quando se trata de solução de problemas.

Localização Description
/var/log/waagent.log Mostra quando ocorreu uma atualização para a extensão.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Examine os logs do serviço Key Vault VM Extension para determinar o status do serviço akvvm_service e do download do certificado. Você pode encontrar o local de download de arquivos PEM em arquivos com uma entrada chamada nome de arquivo de certificado. Se certificateStoreLocation não for especificado, o padrão será /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-versão<> mais recente/config/* A configuração e os binários para o serviço Key Vault VM Extension.

Links simbólicos ou Symlinks são atalhos avançados. Para evitar o monitoramento da pasta e obter o certificado mais recente automaticamente, você pode usar este link ([VaultName].[CertificateName]) simbólico para obter a versão mais recente do certificado no Linux.

Perguntas Mais Frequentes

  • Há um limite para o número de observedCertificates que você pode configurar? Não, a Extensão de VM do Cofre de Chaves não tem limite para o número de observedCertificates.

Suporte

Se precisar de mais ajuda em qualquer ponto deste artigo, entre em contato com os especialistas do Azure nos fóruns MSDN Azure e Stack Overflow. Como alternativa, você pode registrar um incidente de suporte do Azure. Vá para o site de suporte do Azure e selecione Obter suporte. Para obter informações sobre como usar o Suporte do Azure, leia as Perguntas frequentes de suporte do Microsoft Azure.