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

A extensão Azure Key Vault virtual machine (VM) atualiza automaticamente os certificados armazenados num Azure Key vault. A extensão monitora uma lista de certificados observados armazenados em cofres de chaves. Quando a extensão deteta uma alteração, recupera e instala os certificados correspondentes. Este artigo descreve as plataformas, configurações e opções de implementação suportadas para a extensão Key Vault VM para Linux.

Sistemas operativos

A extensão Key Vault VM para Linux suporta as seguintes distribuições, tanto em AMD64 como em ARM64:

• Ubuntu 24,04
• Azure Linux 3.0 e 4.0
• Red Hat Enterprise Linux (RHEL) 9

Tipos de conteúdo de certificado suportados

A extensão de VM do Cofre de Chaves suporta os seguintes tipos de conteúdos de certificados:

• PKCS #12
• PEM

Caraterísticas

A extensão Key Vault VM para Linux versão 4.x:

• Instala as duas versões mais recentes de cada certificado.
• Instala cada certificado como ficheiros divididos: um ficheiro de cadeia .pem completa e um ficheiro de chave privada separado .keyid , cada um escrito como um ficheiro versionado com uma ligação simbólica estável que aponta para a versão mais recente.
• Realiza a validação da cadeia de certificados antes de instalar qualquer certificado que contenha o TLS Server Authentication Extended Key Usage (EKU). A validação é fail-open: um certificado ainda é instalado se a validação não conseguir ser concluída devido a problemas transitórios da rede. Certificados sem a EKU de Autenticação do Servidor não estão sujeitos a esta verificação.
• Aplica ACLs POSIX para conceder a utilizadores e grupos configurados acesso de leitura à chave privada. A aplicação do LCA está sempre ativa.
• Suporta uma substituição opcional da autenticação ao nível do certificado, que permite que cada um dos certificados observados se autentique no Key Vault com uma identidade gerida diferente da identidade gerida predefinida da extensão. Para mais informações, consulte Esquema de extensão.
• Suporta integração de registo de extensões de VM através do Fluentd. Para mais informações, consulte Registo com Fluentd.

Atualização da versão 3.0

Se estiver a atualizar a partir da 3.0, as seguintes funcionalidades são alteradas ou removidas.

Alterações gerais de última hora:

• pollingIntervalInS está agora limitado a entre 5 e 60 minutos. Por predefinição, a extensão verifica uma vez por hora.
• requireInitialSync é removido. A extensão só reporta sucesso se instalar todos os certificados configurados.
• Já não pode configurar uma versão específica de um certificado. Os URLs dos certificados observados devem ser sem versão.
• O esquema legado, onde observedCertificates há uma lista de cadeias de URL, já não é suportado. Cada entrada deve ser um objeto com uma url propriedade.

Alterações específicas de Linux:

• A cadeia de certificados e a chave privada são agora escritas em ficheiros separados. Na 3.0, a cadeia completa e a chave privada eram combinadas num único ficheiro PEM. Na versão 4.x, a extensão escreve a cadeia completa em <vaultname>.<certname>.pem e a chave privada num ficheiro <vaultname>.<certname>.keyid separado. Esta alteração está a quebrar: as aplicações que esperam a chave e cadeia num ficheiro têm de ser atualizadas para ler a cadeia do .pem ficheiro e a chave privada do .keyid ficheiro. O .luma ficheiro é atualizado após as ligações simbólicas serem atualizadas, pelo que as aplicações devem monitorizar as alterações a este ficheiro de metadados.
• customSymbolicLinkName é removido. A extensão utiliza sempre o nome predefinido da ligação simbólica <vaultname>.<certname>.
• aclEnabled é removido. A funcionalidade ACL está agora sempre ativada.
• certificateStoreName é ignorado no Linux e não tem efeito.

Pré-requisitos

Revise os seguintes pré-requisitos para usar a extensão Key Vault VM para Linux:

• Uma instância do Azure Key Vault com um certificado. Para obter mais informações, consulte Criar um cofre de chaves usando o portal do Azure.

• Uma VM com uma identidade gerenciada atribuída.

• Atribua o papel Utilizador de Segredos do Key Vault ao nível do âmbito do Key Vault à identidade gerida da VM ou dos Conjuntos de Dimensionamento de Máquinas Virtuais do Azure. Esta função recupera a parte secreta de um certificado. Para obter mais informações, consulte os seguintes artigos:

  • Autenticação em Azure Key Vault
  • Utilize permissões de segredo, chave e certificado do Azure RBAC com o Azure Key Vault
  • Atribuição de função no âmbito do Key Vault

• Configure os Conjuntos de Dimensionamento de Máquinas Virtuais utilizando a seguinte identity configuração:

  "identity": {
      "type": "UserAssigned",
      "userAssignedIdentities": {
         "[parameters('userAssignedIdentityResourceId')]": {}
      }
  }
  

• Configure a extensão da VM Key Vault com a seguinte authenticationSettings configuração:

  "authenticationSettings": {
      "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]",
      "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]"
  }
  

Esquema de extensão

O JSON a seguir mostra o esquema da extensão de VM do Key Vault. Antes de considerar as opções de implementação do esquema, revise as seguintes observações importantes.

• A extensão não requer configurações protegidas. Todas as definições são informação pública.

• Os URLs de certificados observados devem usar o formulário https://myVaultName.vault.azure.net/secrets/myCertName.

  Este formulário é obrigatório porque o /secrets path devolve o certificado completo, incluindo a chave privada, mas o /certificates path não. Para obter mais informações sobre certificados, consulte Visão geral de chaves, segredos e certificados do Azure Key Vault. Não podes especificar uma versão específica do certificado.

• O host URL deve ser um host reconhecido do Azure Key Vault.

• A authenticationSettings propriedade é necessária para VMs com identidades atribuídas pelo utilizador e para VMs com Azure Arc.

  Omita esta propriedade quando usares uma identidade atribuída pelo sistema. Para VMs habilitadas pelo Azure Arc, defina msiEndpoint para http://localhost:40342/metadata/identity.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KVVMExtensionForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": <Optional. Polling interval in seconds, between 300 (5 min) and 3600 (60 min). Example: "3600">,
             "certificateStoreLocation": <Optional. Default disk path where certificates are stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
             "observedCertificates": <An array of Key Vault URIs that represent monitored certificates, including per-certificate store location and ACL permissions on the 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 disk path where the certificate is stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app1">,
                    "acls": <Optional. An array of users and groups to grant read access to the certificate private key. Example:
                    [
                       { "user": "app1", "group": "appGroup1" },
                       { "user": "service1" }
                    ]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreLocation": <Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app2">,
                    "authenticationOverride": <Optional. Overrides authenticationSettings for this certificate only, so it can authenticate with a different managed identity. Example: {"msiClientId": "11112222-bbbb-3333-cccc-4444dddd5555"}>
                }
             ]>
         },
         "authenticationSettings": {
             "msiEndpoint":  <Required when the msiClientId property is used. Specifies the MSI endpoint. Example for most Azure VMs: "http://169.254.169.254/metadata/identity">,
             "msiClientId":  <Required when the VM has any user assigned identities. Specifies the MSI identity. Example: "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

Valores de propriedade

O esquema JSON inclui as seguintes propriedades.

Implementação de modelos

Implemente extensões VM do Azure utilizando templates do Azure Resource Manager (ARM). Os modelos são ideais quando implementa uma ou mais máquinas virtuais que requerem uma atualização pós-implementação dos certificados. Pode implementar a extensão em VMs individuais ou instâncias do 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 do cofre de chaves está inserida dentro do modelo de VM ou Conjuntos de Escala de Máquina Virtual. Para uma extensão de recurso de VM, a configuração é aninhada dentro do objeto de máquina virtual "resources": []. Para uma extensão de instância do Conjuntos de Dimensionamento de Máquinas Virtuais, a configuração é aninhada sob o "virtualMachineProfile":"extensionProfile":{"extensions" :[] objeto.

O seguinte excerto JSON fornece exemplos de definições para a implementação de um template ARM da extensão VM Key Vault.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KeyVaultForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": "3600",
             "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
             "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"
                }
             ]
         },
         "authenticationSettings": {
            "msiEndpoint":  "http://169.254.169.254/metadata/identity",
            "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
         }
      }
   }
}

Atualização automática de extensão

A extensão VM Key Vault suporta a atualização automática de extensões para máquinas virtuais e conjuntos de escala no Azure. O Azure mantém a extensão atualizada automaticamente quando defines as autoUpgradeMinorVersion propriedades e enableAutomaticUpgrade nos exemplos anteriores como true.

Ordenação de dependências de extensões

A extensão VM Key Vault suporta ordenação de dependências de extensão. A extensão reporta um arranque bem-sucedido após descarregar e instalar todos os certificados.

Se usares outras extensões que exijam a instalação de certificados antes de começarem, podes usar a ordem de dependência de extensões para declarar uma dependência na extensão VM do Key Vault.

No arranque, a extensão VM Key Vault tenta descarregar e instalar certificados até 25 vezes, com períodos de recuo crescentes, durante os quais permanece num estado Transição. Se as tentativas forem esgotadas, a extensão reporta um estado de Erro . Depois que todos os certificados forem instalados com êxito, a extensão de VM do Cofre da Chave relatará um início bem-sucedido.

Para mais informações sobre a configuração de dependências entre extensões, consulte Provisão de extensões de sequência em Conjuntos de Dimensionamento de Máquinas Virtuais.

Implantação do Azure PowerShell

Implemente a extensão VM do Azure Key Vault usando Azure PowerShell. Salve as configurações de extensão de VM do Key Vault em um arquivo JSON (settings.json).

O seguinte excerto JSON fornece exemplos de definições para implementar a extensão VM Key Vault usando PowerShell.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "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"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

Implantar em uma VM

# Build settings
$settings = (Get-Content -Raw ".\settings.json")
$extName =  "KeyVaultForLinux"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForLinux"

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

Implantar em uma instância de Conjuntos de Dimensionamento de Máquina Virtual

# 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 "4.0" -Setting $settings

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

Implementação do CLI do Azure

Implemente a extensão VM do Azure Key Vault usando a CLI do Azure. Salve as configurações de extensão de VM do Key Vault em um arquivo JSON (settings.json).

O seguinte excerto JSON fornece exemplos de definições para implementar a extensão VM Key Vault usando a CLI do Azure.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "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"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

Implantar em uma VM

# Start the deployment
az vm extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vm-name "<vmName>" \
  --version "4.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

Implantar em uma instância de Conjuntos de Dimensionamento de Máquina Virtual

# Start the deployment
az vmss extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vmss-name "<vmssName>" \
  --version "4.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

az vm extension delete --name "KeyVaultForLinux" --resource-group "<resourcegroup>" --vm-name "<vmName>"

Registo com o Fluentd

A extensão VM Key Vault pode encaminhar os seus registos para um coletor de registos Fluentd. Certifica-te de que o teu coletor de registos está a correr e a ouvir no endpoint que especificas nas definições.

Adicione a seguinte secção às suas definições de extensão:

"loggingSettings": {
   "logger": "fluentd",
   "endpoint": "unix:///var/run/azuremonitoragent/sometenant/default_fluent.socket",
   "format": "forward",
   "servicename": "akvvm_service"
}

Solucionar problemas

Use estas sugestões para resolver problemas de implementação.

Consulte as perguntas frequentes

Existe um limite para o número de certificados observados?

Não. A extensão Key Vault VM não limita o número de certificados observados (observedCertificates).

Qual é o local padrão onde os certificados são instalados?

Se não especificares certificateStoreLocation, a extensão escreve certificados para /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.

Como posso forçar a extensão a obter um novo certificado?

Reinicie o akvvm_service serviço (nome de exibição Key Vault VM Extension).

Como posso usar uma identidade diferente para um certificado específico?

Adicione à entrada desse certificado em observedCertificates um objeto authenticationOverride com o alvo msiClientId. Certificados sem exceção utilizam o elemento de nível superior authenticationSettings.

Ver estado da extensão

Verifique o estado da implementação da sua extensão no portal do Azure, ou usando o PowerShell ou a CLI do Azure.

Para ver o estado de implantação das extensões de uma determinada VM, execute os seguintes comandos.

• Azure PowerShell:

  Get-AzVMExtension -ResourceGroupName <myResourceGroup> -VMName <myVM> -Name <myExtensionName>
  

• CLI do Azure:

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

A CLI do Azure pode correr em vários ambientes de shell, mas com ligeiras variações de formato. Se tiveres resultados inesperados com CLI do Azure comandos, vê Como usar o CLI do Azure com sucesso.

Revisar registros e configuração

Os registos de extensão da VM do Key Vault existem apenas localmente na VM. Reveja os detalhes do registo para ajudar na resolução de problemas.

Instalação de certificados no Linux

A extensão Key Vault VM para Linux instala certificados como ficheiros PEM. Quando a extensão descarrega um certificado do Key Vault, ela:

1. Cria uma pasta de armazenamento com base na certificateStoreLocation definição. Se não especificar esta definição, a localização por defeito é /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.
2. Escreve a cadeia de certificados (folha, depois intermediários e, em seguida, o certificado de raiz, caso esteja presente no Key Vault) num ficheiro full-chain .pem versionado e escreve a chave privada correspondente num ficheiro .keyid versionado.
3. Aplica ACLs POSIX à chave privada com base no acls especificado na configuração, o que concede acesso de leitura aos utilizadores e grupos listados. Os ficheiros só podem ser acedidos pelo proprietário.
4. Cria ou atualiza uma ligação simbólica estável (<vaultname>.<certname>.pem e <vaultname>.<certname>.keyid) que aponta para a versão mais recente do certificado. A ligação ocorre sempre.

Localização padrão do armazenamento de certificados

Se não especificar uma localização, a extensão instala certificados sob /var/lib/waagent/Microsoft.Azure.KeyVault.Store/. A extensão ignora certificateStoreName no Linux.

Ficheiros de saída de certificados

Para vault mykv e secreto server-tls, uma sincronização bem-sucedida produz:

/var/lib/waagent/Microsoft.Azure.KeyVault.Store/
├── mykv.server-tls.pem -> mykv.server-tls.<version>.pem.<timestamp>     # symlink to latest full chain
├── mykv.server-tls.keyid -> mykv.server-tls.<version>.keyid.<timestamp> # symlink to latest private key
├── mykv.server-tls.<version>.pem.<timestamp>                            # full chain PEM (mode 600)
├── mykv.server-tls.<version>.keyid.<timestamp>                          # private key (mode 600)
└── mykv.server-tls.luma                                                 # certificate management metadata (mode 644)

Configure as aplicações para referenciarem o caminho da ligação simbólica estável (por exemplo, /var/lib/waagent/Microsoft.Azure.KeyVault.Store/mykv.server-tls.pem) para que leiam sempre a versão mais recente do certificado sem necessidade de reconfiguração na renovação.

Controlo de acesso a certificados

Por defeito, os ficheiros de certificados e chaves privadas são legíveis apenas pelo seu proprietário. Conceder acesso de leitura a utilizadores e grupos adicionais utilizando o acls array na configuração do certificado:

"acls": [
   { "user": "app1", "group": "appGroup1" },
   { "user": "service1" }
]

Cada entrada pode especificar um utilizador, um grupo ou ambos. A aplicação do ACL está sempre ativada e atualmente concede acesso de leitura.

Renovação do certificado

Quando os certificados são renovados no Key Vault, a extensão executa automaticamente as seguintes ações na próxima sondagem:

1. Descarrega a nova versão do certificado.
2. Escreve a nova versão .pem e .keyid arquivos.
3. Atualiza a ligação simbólica estável para apontar para a nova versão, de modo a que os caminhos existentes das aplicações continuem a ser resolvidos para o certificado mais recente.

Obtenha suporte

A Microsoft oferece suporte apenas para a versão principal 3.0 e posteriores da extensão VM Key Vault. Se estiveres a usar a versão 1.0, atualiza para a versão mais recente antes de pedir suporte.

Use estas outras opções para ajudar a resolver problemas de implementação:

• Para assistência, contacte os especialistas Azure em Microsoft Q& A.

• Se não encontrar uma resposta no site, pode publicar uma pergunta para obter contributos da Microsoft ou de outros membros da comunidade.

• Também pode contactar o Suporte da Microsoft. Para informações sobre a utilização de suporte do Azure, veja Como criar um pedido de suporte do Azure.