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

A extensão de VM do Cofre de Chaves proporciona atualização automática de certificados armazenados num 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:

• Ubuntu 22.04 e posterior
• Azure Linux

Tipos de conteúdo de certificado suportados

• PKCS #12
• PEM

Caraterísticas

A extensão Key Vault VM para Linux versão 3.0+ suporta:

• 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 registos de extensões de máquina virtual através do Fluentd

Pré-requisitos

• Instância do Cofre de Chaves com certificado. Consulte Criar um cofre de chaves

• Identidade gerenciada atribuída em máquinas virtuais/conjuntos de dimensionamento de máquinas virtuais.

• A função Utilizador de Segredos do Cofre de Chaves no nível de escopo do Cofre de Chaves para identidades geridas de VMs e Conjuntos de Escala de Máquinas Virtuais Azure. Esta função recupera parte de um segredo de um certificado. Para obter mais informações, consulte os seguintes artigos:

  • Autenticação no Cofre da Chave do Azure
  • Utilizar permissões de segredo, chave e certificado do Controlo de Acesso Baseado em Funções (RBAC) do Azure com o Azure Key Vault
  • Atribuição de função no escopo do Key Vault

• Os conjuntos de dimensionamento de máquinas virtuais devem ter a seguinte configuração de identidade: "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }

• A extensão AKV deve ter esta configuração: "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Atualizando a extensão de VM do Key Vault

• Se você precisar atualizar de uma versão mais antiga para a versão 3.0+, você precisaria excluir a versão anterior primeiro e, em seguida, instalar a versão 3.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 3.0

• 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 seguinte JSON fornece o esquema para a extensão de máquina virtual do Key Vault. Todas as configurações são especificadas como configurações simples (desprotegidas), pois nenhuma é considerada sensível. Para configurar a extensão, você deve especificar uma lista de certificados a serem monitorados, a frequência de pesquisa de atualizações e o caminho de destino para armazenar certificados. Mais 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.: "00001111-aaaa-2222-bbbb-3333cccc4444".>
        }>
       }
      }
    }

Valores de propriedade

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.

   {
      "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.: "00001111-aaaa-2222-bbbb-3333cccc4444">
          }
        } 
      }
    }

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 voltará a tentar o download inicial até 25 vezes com intervalos de espera crescente, durante os quais a extensão permanece num estado Transitioning. Se as novas tentativas estiverem esgotadas, a extensão informará um Error estado.

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

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

Implantação do Azure PowerShell

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 da VM do Azure 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 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 Azure 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 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 Utilizador de Segredos do Cofre de Chaves deve ser atribuída ao Cofre de Chaves 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 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>

Azure CLI

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

Usando o Symlink

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.

Instalação de certificado no Linux

A extensão Key Vault VM para Linux instala certificados como arquivos PEM com a cadeia de certificados completa incluída. Quando um certificado é baixado do Cofre de Chaves, a extensão:

1. Cria uma pasta de armazenamento com base na certificateStoreLocation configuração (o padrão é /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ se não for especificado)
2. Instala a cadeia de certificados completa e a chave privada em um arquivo PEM seguindo a seção 7.4.2 da RFC 5246 nesta ordem específica:
   • O certificado Leaf (certificado de entidade final) vem em primeiro lugar
   • O(s) certificado(s) intermédio(s) segue(m) por ordem, em que cada certificado certifica diretamente o certificado anterior
   • Certificado raiz, se presente (embora não seja necessário para validação se já for confiável pelo sistema)
   • A chave privada, correspondente ao certificado de folha, é colocada no final do ficheiro
3. Cria automaticamente um link simbólico chamado [VaultName].[CertificateName] que aponta para a versão mais recente do certificado

Esta abordagem garante que:

• Os aplicativos sempre têm acesso à cadeia de certificados completa necessária para a validação
• A cadeia de certificados é ordenada corretamente para apertos de mão TLS de acordo com os padrões RFC
• A chave privada está disponível para uso pelo serviço
• Os aplicativos podem fazer referência a um caminho de link simbólico estável que é atualizado automaticamente quando os certificados são renovados
• Nenhuma reconfiguração de aplicativo é necessária quando os certificados são alternados ou renovados

Exemplo de estrutura de caminho de certificado

Para um certificado de exampleVault.vault.azure.net com o nome myCertificate, a estrutura de diretórios seria semelhante a:

/var/lib/waagent/Microsoft.Azure.KeyVault.Store/
├── exampleVault.myCertificate -> exampleVault.myCertificate.1234567890abcdef
├── exampleVault.myCertificate.1234567890abcdef    # Full chain PEM file (current version)
└── exampleVault.myCertificate.0987654321fedcba    # Previous version (if exists)

Os aplicativos devem ser configurados para usar o caminho de link simbólico (/var/lib/waagent/Microsoft.Azure.KeyVault.Store/exampleVault.myCertificate) para garantir que sempre acessem a versão de certificado mais atual.

Quando você usa locais de armazenamento de certificados personalizados e a customSymbolicLinkName configuração, a estrutura segue este padrão:

/path/to/custom/store/
├── customLinkName -> exampleVault.myCertificate.1234567890abcdef
└── exampleVault.myCertificate.1234567890abcdef    # Full chain PEM file

Perguntas Frequentes

• Há um limite para o número de observedCertificates que você pode configurar? Não, a Extensão de Máquina Virtual do Azure Key Vault não tem limite para o número de certificados observados.

Apoio

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.