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

A extensão de máquina virtual (VM) do Azure Key Vault atualiza automaticamente os certificados armazenados no Azure Key Vault. A extensão monitora uma lista de certificados observados armazenados em cofres de chaves. Quando a extensão detecta uma alteração, ela recupera e instala os certificados correspondentes. Este artigo descreve as plataformas, configurações e opções de implantação com suporte para a extensão de VM Key Vault para Linux.

Sistemas operacionais

A extensão de VM Key Vault para Linux dá suporte às seguintes distribuições, tanto no AMD64 quanto no ARM64:

• Ubuntu 24.04
• Azure Linux 3.0 e 4.0
• Red Hat Enterprise Linux (RHEL) 9

Tipos suportados de conteúdo de certificado

A extensão de VM do Key Vault dá suporte aos seguintes tipos de conteúdo de certificado:

• PKCS #12
• PEM

Features

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

• Instala as duas versões mais recentes de cada certificado.
• Instala cada certificado como arquivos separados: um arquivo .pem de cadeia completa e um arquivo .keyid de chave privada separado, cada um gravado como um arquivo versionado com um link simbólico 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 uso estendido de chave (EKU) de autenticação de servidor TLS. A validação adota o modo de falha aberta: um certificado ainda será instalado se a validação não puder ser concluída devido a problemas transitórios de rede. Certificados sem a EKU de Autenticação de Servidor não estão sujeitos a essa verificação.
• Aplica ACLs POSIX para conceder aos usuários e grupos configurados acesso de leitura à chave privada. A aplicação da ACL está sempre ativa.
• Dá suporte a uma substituição opcional de autenticação por certificado, que permite que cada certificado monitorado se autentique no Key Vault com uma identidade gerenciada diferente da identidade padrão da extensão. Para obter mais informações, consulte Esquema de extensão.
• Dá suporte à integração de log de extensão de VM por meio do Fluentd. Para obter mais informações, consulte Registro em log com Fluentd.

Atualizando de 3.0

Se você estiver atualizando a partir da 3.0, os seguintes recursos serão alterados ou removidos.

Alterações da falha gerais:

• pollingIntervalInS agora está limitado a entre 5 e 60 minutos. Por padrão, a extensão vota uma vez a cada hora.
• requireInitialSync foi removido. A extensão só relatará êxito se instalar todos os certificados configurados.
• Você não pode mais configurar uma versão específica de um certificado. As URLs de certificado observadas devem estar sem versão.
• O esquema herdado em que observedCertificates há uma lista de cadeias de caracteres de URL não tem mais suporte. Cada entrada deve ser um objeto com uma url propriedade.

Alterações de falha específicas do Linux:

• A cadeia de certificados e a chave privada agora são gravadas em arquivos separados. Na versão 3.0, a cadeia completa e a chave privada foram combinadas em um único arquivo PEM. No 4.x, a extensão grava a cadeia <vaultname>.<certname>.pem completa e a chave privada em um arquivo separado <vaultname>.<certname>.keyid . Essa alteração está falhando: os aplicativos que esperam a chave e a cadeia em um arquivo devem ser atualizados para ler a cadeia do arquivo .pem e da chave privada do arquivo .keyid. O .luma arquivo é atualizado depois que os links simbólicos são atualizados, portanto, os aplicativos devem monitorar as alterações nesse arquivo de metadados.
• customSymbolicLinkName foi removido. A extensão sempre usa o nome padrão do link simbólico <vaultname>.<certname>.
• aclEnabled foi removido. A funcionalidade ACL agora fica sempre habilitada.
• certificateStoreName é ignorado no Linux e não tem efeito.

Pré-requisitos

Examine os seguintes pré-requisitos para usar a extensão de VM Key Vault 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 a função Usuário de Segredos do Key Vault no nível do escopo do Key Vault à identidade gerenciada da VM ou dos Conjuntos de Dimensionamento de Máquinas Virtuais do Azure. Essa função recupera a parte secreta de um certificado. Para obter mais informações, consulte os seguintes artigos:

  • Autenticação no Azure Key Vault
  • Use o segredo, a chave e as permissões de certificado do Azure RBAC com o Azure Key Vault
  • Atribuição de função no escopo do Key Vault

• Configure os Conjuntos de dimensionamento de máquinas virtuais com a seguinte configuração identity:

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

• Configure a extensão de 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 para a extensão da VM de Key Vault. Antes de considerar as opções de implementação de esquema, examine as notas importantes a seguir.

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

• As URLs de certificado observadas devem usar o formulário https://myVaultName.vault.azure.net/secrets/myCertName.

  Esse formulário é necessário porque o /secrets caminho retorna o certificado completo, incluindo a chave privada, mas o /certificates caminho não. Para obter mais informações sobre certificados, consulte a visão geral de chaves, segredos e certificados do Azure Key Vault. Você não pode especificar uma versão específica do certificado.

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

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

  Omita essa propriedade quando você usa uma identidade atribuída pelo sistema. Para VMs habilitadas para Azure Arc, defina msiEndpoint como 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 propriedades a seguir.

Implantação de modelo

Implante Azure extensões de VM usando modelos Azure Resource Manager (ARM). Os modelos são ideais quando você implanta uma ou mais máquinas virtuais que exigem a atualização pós-implantação de certificados. Você pode implantar a extensão em VMs individuais ou em instâncias de 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 é aninhada dentro do modelo VM ou Conjuntos de Dimensionamento de Máquinas Virtuais do Microsoft Azure. Para uma extensão de recurso da VM, a configuração "resources": [] é aninhada no objeto da máquina virtual. Para uma extensão de instância de Conjuntos de Dimensionamento de Máquinas Virtuais do Microsoft Azure, a configuração é aninhada sob o objeto "virtualMachineProfile":"extensionProfile":{"extensions" :[].

O trecho JSON a seguir fornece configurações de exemplo para uma implantação de um modelo ARM da extensão de VM do 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 de VM do Key Vault oferece suporte à atualização automática da extensão para máquinas virtuais e conjuntos de dimensionamento no Azure. O Azure mantém a extensão atualizada automaticamente quando você define as propriedades autoUpgradeMinorVersion e enableAutomaticUpgrade como true nos exemplos anteriores.

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

A extensão de VM Key Vault suporta a ordenação das dependências das extensões. A extensão relata um início bem-sucedido depois de baixar e instalar todos os certificados.

Se você usar outras extensões que exigem a instalação de certificados antes de serem iniciadas, poderá usar a ordem de dependência de extensão para declarar uma dependência na extensão de VM do Key Vault.

Na inicialização, a extensão de VM do Key Vault tenta baixar e instalar certificados até 25 vezes com períodos de retirada crescentes, durante os quais permanece em um estado Em transição. Se as novas tentativas estiverem esgotadas, a extensão relatará um estado de erro . Depois que todos os certificados forem instalados com êxito, a extensão de VM do Key Vault relatará um início bem-sucedido.

Para obter mais informações sobre como configurar dependências entre extensões, consulte o provisionamento sequencial de extensões em Conjuntos de Dimensionamento de Máquinas Virtuais.

Implantação do Azure PowerShell

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

O snippet JSON a seguir fornece configurações de exemplo para implantar a extensão de VM Key Vault usando o 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áquinas Virtuais do Microsoft Azure

# 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

Implantação da CLI do Azure

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

O snippet JSON a seguir fornece configurações de exemplo para implantar a extensão de VM Key Vault usando o 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áquinas Virtuais do Microsoft Azure

# 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>"

Registro de logs com Fluentd

A extensão de VM do Key Vault pode encaminhar seus logs para um coletor de logs Fluentd. Verifique se o coletor de logs está em execução e escutando no ponto de extremidade especificado nas configurações.

Adicione a seguinte seção às configurações de extensão:

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

Solucionar problemas

Use essas sugestões para solucionar problemas de implantação.

Verificar perguntas frequentes

Há um limite no número de certificados observados?

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

Qual é o local padrão em que os certificados são instalados?

Se você não especificar certificateStoreLocation, a extensão gravará certificados em /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.

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

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

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

Adicione um objeto authenticationOverride que tenha como destino msiClientId à entrada desse certificado em observedCertificates. Certificados sem uma substituição usam authenticationSettings de nível superior.

Exibir o status da extensão

Verifique o status da implantação da extensão no portal do Azure ou usando o PowerShell ou o CLI do Azure.

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

• Azure PowerShell:

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

• A CLI do Azure:

  az vm get-instance-view --resource-group <myResourceGroup> --name <myVM> --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.

Revisar logs e configuração

Os logs de extensão da VM do Key Vault existem apenas localmente na VM. Examine os detalhes do log para ajudar na solução de problemas.

Instalação de certificado no Linux

A extensão de VM Key Vault para Linux instala certificados como arquivos PEM. Quando a extensão baixa um certificado de Key Vault, ele:

1. Cria uma pasta de armazenamento com base na configuração certificateStoreLocation . Se você não especificar essa configuração, o local será definido como /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.
2. Grava a cadeia de certificados (certificado final, depois os intermediários e, em seguida, a raiz, se presente no Key Vault) em um arquivo .pem versionado de cadeia completa e grava a chave privada correspondente em um arquivo .keyid versionado.
3. Aplica ACLs POSIX à chave privada com base na acls especificada na configuração, que concede permissão de leitura aos usuários e grupos listados. Os arquivos, caso contrário, são acessíveis apenas ao proprietário.
4. Cria ou atualiza um link simbólico estável (<vaultname>.<certname>.pem e <vaultname>.<certname>.keyid) que aponta para a versão mais recente do certificado. A vinculação sempre ocorre.

Local padrão do repositório de certificados

Se você não especificar um local, a extensão instalará certificados em /var/lib/waagent/Microsoft.Azure.KeyVault.Store/. A extensão ignora certificateStoreName no Linux.

Arquivos de saída de certificado

Para o vault mykv e o segredo 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 aplicativos para fazer referência ao caminho de vínculo simbólico estável (por exemplo, /var/lib/waagent/Microsoft.Azure.KeyVault.Store/mykv.server-tls.pem) para que eles sempre leiam a versão de certificado mais atual sem reconfiguração na renovação.

Controle de acesso ao certificado

Por padrão, arquivos de certificado e chave privada são legíveis somente pelo proprietário. Conceda acesso de leitura a usuários e grupos adicionais usando a acls matriz na configuração do certificado:

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

Cada entrada pode especificar um usuário, um grupo ou ambos. A imposição de ACL está sempre habilitada e atualmente concede acesso de leitura.

Renovação de certificado

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

1. Baixa a nova versão do certificado.
2. Grava os novos arquivos versionados .keyid e .pem.
3. Atualiza o link simbólico estável para apontar para a nova versão, para que os caminhos da aplicação existentes continuem apontando para o certificado mais recente.

Obtenha suporte

Microsoft fornece suporte apenas para a versão principal 3.0 e posterior da extensão de VM Key Vault. Se você estiver usando a versão 1.0, atualize para a versão mais recente antes de solicitar suporte.

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

• Para obter assistência, entre em contato com os especialistas do Azure em Microsoft Q& A.

• Se você não encontrar uma resposta no site, poderá postar uma pergunta para obter informações de Microsoft ou de outros membros da comunidade.

• Você também pode entrar em contato com o Suporte da Microsoft. Para obter informações sobre como usar Suporte do Azure, consulte Como criar uma solicitação Suporte do Azure.