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 de Extensão da VM (versão 1/2) ou nas configurações de certificado individuais (versão 3). 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

Atualizações na versão 3.0+

A versão 3.0+ da extensão Key Vault VM para Linux adiciona suporte para os seguintes recursos:

  • Adicionar permissões de ACL para certificados baixados para fornecer acesso de leitura para usuários e grupos
  • Configuração do local de instalação do certificado
  • Suporte a nomes simbólicos personalizados
  • Suporte à integração de log de extensão de VM por meio do Fluentd

Pré-requisitos

Versão da extensão Key Vault VM

  • Os usuários podem optar por atualizar sua versão de extensão existente do Key Vault VM para a versão mais recente.

  • Se você preferir atualizar para a versão mais recente, você precisaria excluir a versão anterior primeiro e, em seguida, instalar a versão mais recente.

  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

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

  • Se a VM tiver certificados baixados pela versão anterior, excluir a extensão da VM não excluirá os certificados baixados. Depois de instalar a versão mais recente, 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": "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.: "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
publisher Microsoft.Azure.KeyVault string
type KeyVaultForLinux string
typeHandlerVersion 3.0 número inteiro
pollingIntervalInS 3600 string
certificateStoreName É ignorado no Linux string
linkOnRenewal false boolean
requireInitialSync verdadeiro boolean
aclEnabled verdadeiro boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
observedCertificates [{...}, {...}] matriz de cadeia de caracteres
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" string
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" string
observedCertificates/customSymbolicLinkName (opcional) "app1Cert1" string
observedCertificates/acls (opcional) "{...}, {...}" matriz de cadeia de caracteres
authenticationSettings (opcional) {...} objeto
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity string
authenticationSettings/msiClientId C7373AE5-91C2-4165-8AB6-7381D6E75619 string
loggingSettings (opcional) {...} objeto
loggingSettings/logger "Fluente" string
loggingSettings/endpoint "tcp://localhost:24224" string
loggingSettings/format "Avante" string
loggingSettings/servicename "akvvm_service" 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": "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.: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
          }
        } 
      }
    }

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:

A extensão de VM do Azure Key Vault pode ser implantada com o Azure PowerShell. Salve as configurações de extensão de VM do Key Vault em um arquivo JSON (settings.json).

Os trechos JSON a seguir fornecem configurações de exemplo para implantar a extensão de VM do Cofre da Chave com o PowerShell.

{
   "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"
   }      
}
  • Para implantar a extensão em uma máquina virtual:
# 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
  • Para implantar a extensão em um conjunto de escala 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 "3.0" -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:

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

Os trechos JSON a seguir fornecem configurações de exemplo para implantar a extensão de VM do Cofre da Chave com a CLI do Azure.

{
   "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"
   }      
}
  • Para implantar a extensão em uma máquina virtual

    # 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"
  • 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 3.0 `
    --enable-auto-upgrade true `
    --settings "@settings.json"

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

  • Restrições do Cofre da Chave:
    • Ele deve existir no momento da implantação
    • A função Usuário dos Segredos do Cofre da Chave deve ser atribuída à identidade do Cofre da Chave para VM

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 existem localmente na VM e são mais informativos quando se trata de solução de problemas. Pode utilizar a secção de registo opcional para se integrar com o fornecedor de registo através de fluentd

Location 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.