Compartilhar via

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

  • Artigo

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:

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

Atualizações na versão 3.0+

A versão 3.0+ de extensão da VM do Key Vault 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 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 existente para uma versão mais recente.

  • Se você preferir atualizar para uma versão mais recente, precisará excluir a versão anterior primeiro e 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 “--versão 3.0” é opcional porque a versão mais recente é instalada por padrão.

  • Se a VM tiver certificados baixados pela versão anterior, a exclusão da extensão da VM não exclui os certificados baixados. Depois de instalar a versão mais recente, 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": "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".>
        }>
       }
      }
    }

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
publisher Microsoft.Azure.KeyVault string
type KeyVaultForLinux string
typeHandlerVersion 3.0 INT
pollingIntervalInS 3600 string
certificateStoreName É ignorado no Linux string
linkOnRenewal false booleano
requireInitialSync true booleano
aclEnabled true 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 "fluentd" string
loggingSettings/endpoint "tcp://localhost:24224" string
loggingSettings/format "forward" string
loggingSettings/servicename "akvvm_service" 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": "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">
          }
        } 
      }
    }

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:

A extensão da VM do Azure Key Vault pode ser implantada com o Azure PowerShell. Salve as configurações de extensão da 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 da VM do Key Vault 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 dimensionamento de máquinas virtuais:
    # 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

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:

A extensão da VM do Azure Key Vault pode ser implantada usando a CLI do Azure. Salve as configurações de extensão da 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 da VM do Key Vault 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 dimensionamento de máquinas virtuais:
    # 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"

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

  • Restrições de Key Vault:
    • Ele deve existir no momento da implantação
    • A função de Usuário de Segredos do Key Vault deve ser atribuída ao Key Vault para a identidade da VM

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 existem localmente na VM e são mais informativos quando se trata de solucionar problemas. Você pode usar a seção de registro em log opcional para se integrar ao provedor de log por meio de fluentd

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

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.