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

Artigo
02/20/2024

A extensão de VM de Key Vault fornece a atualização automática dos certificados armazenados no 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 após detectar uma alteração. Este documento detalha as plataformas com opções de plataformas, configurações e implantação com suporte para a extensão da VM de Key Vault para Linux.

Sistema operacional

A extensão de VM do Key Vault dá suporte a essas distribuições do Linux:

Ubuntu 20.04, 22.04
Azure Linux

Observação

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

Tipos suportados de conteúdo de certificado

PKCS #12
PEM

Pré-requisitos

Instância Key Vault com certificado. Ver Criar um Key Vault
Identidade gerenciada atribuída na VM/VMSS
A função de Usuário de Segredos do Key Vault no nível de escopo do Key Vault para VMs e a identidade gerenciada dos Conjuntos de Dimensionamento de Máquinas Virtuais do Azure. Essa função recupera a parte do segredo de um certificado. Para obter mais informações, consulte os seguintes artigos:
VMSS devem ter a seguinte configuração de identidade:"identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }
A extensão AKV deve ter essa configuração: "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Versão de extensão de VM do Key Vault

Os usuários podem optar por atualizar a versão da extensão de VM do Key Vault para V2.0 para usar o recurso de download completo da cadeia de certificados. Os certificados emissores (intermediários e raiz) são incluídos com o certificado folha no arquivo PEM.
Caso você prefira atualizarv2.0, você precisará excluir v1.0 primeiro e depois instalarv2.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 “--versão 2.0” é opcional porque a versão mais recente é instalada por padrão.

Se a VM tiver certificados baixados pela v 1.0, a exclusão da extensão AKVVM v 1.0 NÃO exclui os certificados baixados. Depois de instalar a v 2.0, os certificados existentes não são modificados. Você precisará excluir os arquivos de certificado ou fazer o registro do certificado para obter o arquivo PEM com cadeia total na VM.

Esquema de extensão

O JSON a seguir mostra o esquema para a extensão da VM de Key Vault. 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 dos segredos monitorados, a frequência de sondagem e o repositório 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".>
        }
       }
      }
    }

Observação

Suas URLs de certificado observadas devem estar no formato https://myVaultName.vault.azure.net/secrets/myCertName.

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

Importante

A propriedade ' authenticationSettings ' é necessária somente para VMs com identidades atribuídas pelo usuário. Mesmo que você queira usar uma identidade atribuída pelo sistema, isso ainda será necessário. Caso contrário, a extensão da VM não saberá qual identidade usar. Sem esta seção, uma VM com identidades atribuídas pelo usuário resultará na falha da extensão do Key Vault e não poderá baixar os certificados. Defina msiClientId como a identidade que será autenticada para o Key Vault.

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

Valores de propriedade

Nome	Valor/Exemplo	Tipo de Dados
apiVersion	2022-07-01	date
publicador	Microsoft.Azure.KeyVault	string
type	KeyVaultForLinux	string
typeHandlerVersion	2,0	INT
pollingIntervalInS	3600	string
certificateStoreName	É ignorado no Linux	string
linkOnRenewal	false	booleano
certificateStoreLocation	/var/lib/waagent/Microsoft.Azure.KeyVault.Store	string
requireInitialSync	true	booleano
observedCertificates	["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]	Matriz de cadeia de caracteres
msiEndpoint	http://169.254.169.254/metadata/identity	string
msiClientId	c7373ae5-91c2-4165-8ab6-7381d6e75619	string

Implantação de modelo

Extensões de VM do Azure podem ser implantadas com modelos do Azure Resource Manager. Modelos são ideais ao implantar uma ou mais máquinas virtuais que exigem renovação de certificados pós-implantação. A extensão pode ser implantada em VMs individuais ou conjunto 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 do recurso de máquina virtual do modelo, especificamente o objeto "resources": [] para o modelo de máquina virtual e para um conjunto de dimensionamento de máquinas virtuais, no objeto "virtualMachineProfile":"extensionProfile":{"extensions" :[].

Observação

A extensão de VM exigiria que fosse atribuída a identidade gerenciada do sistema ou do usuário para autenticar no Key Vault. Consulte Como autenticar no Key Vault e atribuir uma política de acesso ao 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"
        }
      }
      }
    }

Pedido de Dependência de Extensão

A extensão de VM do Key Vault é compatível com o pedido de extensão, se configurado. Por padrão, os relatórios de extensão são iniciados com êxito assim que a sondagem é iniciada. 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 dos certificados instalados antes de serem iniciadas, a habilitação dessa configuração permitirá que essas extensões declarem uma dependência na extensão do Key Vault. 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 de forma indefinida e permanecerá em um Transitioning estado.

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

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

Observação

O uso desse recurso não é compatível com um modelo ARM que cria uma identidade atribuída pelo sistema e atualiza uma política de acesso ao Key Vault com essa identidade. Isso resultará em um deadlock, uma vez que a política de acesso do vault não pode ser atualizada até que todas as extensões sejam iniciadas. Em vez disso, você deve usar uma identidade de MSI atribuída por um único usuário e pré-listar o controle de acesso de seus cofres com essa identidade antes da implantação.

Implantação do Azure PowerShell

Aviso

Os clientes do PowerShell geralmente adicionam \ em"settings.js, o que fará com que o caakvvm_service apresente falha com o erro: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

O Azure PowerShell pode ser usado para implantar a extensão da VM do Diagnóstico de Key Vault 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 dimensionamento de máquinas virtuais:


    # 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

Implantação da CLI do Azure

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

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 dimensionamento de máquinas virtuais:

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

Por favor esteja ciente das seguintes restrições/exigências:

Restrições de Key Vault:
- Ele deve existir no momento da implantação
- A política de acesso do Key Vault deve ser definida para Identidade VM/VMSS usando uma Identidade Gerenciada. Consulte Como autenticar no Key Vault e Atribuir uma política de acesso ao Key Vault.

Solução de problemas e suporte

Os dados sobre o estado das implantações de extensão podem ser recuperados no Portal do Azure usando o Azure PowerShell. Para ver o estado da implantação das extensões de uma determinada VM, execute o comando a seguir usando o Azure PowerShell.

PowerShell do Azure

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 comandos da CLI do Azure, confira Como usar a CLI do Azure com êxito.

Logs e configuração

Os logs de extensão de VM do Key Vault só existem localmente na VM e são mais informativos quando se trata de solucionar problemas.

Location	Descrição
/var/log/waagent.log	Mostra quando acontece uma atualização da extensão.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/*	Examina os logs do serviço de extensão de VM do Key Vault para determinar o status do serviço de akvvm_service e o 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, será usado como padrão /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<most recent version>/config/*	A configuração e os binários do serviço da Extensão de VM do Key Vault.

Usando symlink

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

Perguntas frequentes

Há um limite no número de observedCertificates que você pode configurar? Não, A extensão de VM do Key Vault não tem limite no número de observedCertificates.

Suporte

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

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

Sistema operacional

Tipos suportados de conteúdo de certificado

Pré-requisitos

Versão de extensão de VM do Key Vault

Esquema de extensão

Valores de propriedade

Implantação de modelo

Pedido de Dependência de Extensão

Implantação do Azure PowerShell

Implantação da CLI do Azure

Solução de problemas e suporte

Logs e configuração

Usando symlink

Perguntas frequentes

Suporte

Recursos adicionais