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

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:

• Ubuntu 22.04 e posterior
• Azure Linux

Tipos suportados de conteúdo de certificado

• PKCS #12
• PEM

Features

A extensão de VM do Key Vault para Linux versão 3.0+ dá suporte a:

• 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

• Instância Key Vault com certificado. Ver Criar um Key Vault

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

• A função de Usuário de Segredos do Key Vault no nível de escopo do Key Vault para VMs e a identidade gerenciada dos Conjuntos de Dimensionamento de Máquinas Virtuais do Azure. Essa função recupera uma parte secreta de um certificado. Para obter mais informações, consulte os seguintes artigos:

  • Autenticação do 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

• 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 essa 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+, precisará excluir a versão anterior primeiro e 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, 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 serã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 fornece o esquema para a extensão de VM do Key Vault. Todas as configurações são especificadas como configurações simples (desprotegidas), pois nenhuma é considerada confidencial. Para configurar a extensão, você deve especificar uma lista de certificados a serem monitorados, com que frequência pesquisar atualizações e o caminho de destino para armazenar certificados. 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

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.

   {
      "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">
          }
        } 
      }
    }

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 executar download inicial até 25 vezes, com intervalos de espera crescentes, durante os quais permanecerá em um estado Transitioning. Se as novas tentativas estiverem esgotadas, a extensão relatará o estado Error.

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

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

Implantação do Azure PowerShell

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

Usando symlink

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.

Instalação de certificado no Linux

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

1. Cria uma pasta de armazenamento com base na configuração certificateStoreLocation (o padrão é /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ se não especificado)
2. Instala a cadeia de certificados completa e a chave privada em um arquivo PEM seguindo a seção RFC 5246 7.4.2 nesta ordem específica:
   • O certificado de folha (certificado de entidade final) vem primeiro
   • Os certificados intermediários seguem em ordem, em que cada certificado certifica diretamente aquele antes dele
   • 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 final, é colocada no final do arquivo.
3. Cria automaticamente um link simbólico chamado [VaultName].[CertificateName] que aponta para a versão mais recente do certificado

Essa abordagem garante que:

• Os aplicativos sempre têm acesso à cadeia de certificados completa necessária para validação
• A cadeia de certificados é ordenada corretamente para handshakes TLS de acordo com os padrões RFC
• A chave privada está disponível para uso pelo serviço
• Os aplicativos podem referenciar 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 girados ou renovados

Exemplo de estrutura de caminho de certificado

Para um certificado exampleVault.vault.azure.net com o nome myCertificate, a estrutura do diretório teria a seguinte aparência:

/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 eles sempre acessem a versão de certificado mais atual.

Quando você usa locais personalizados do repositório de certificados e a configuração customSymbolicLinkName, 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 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 MSDN e do 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 saber mais sobre como usar o Suporte do Azure, leia as Perguntas frequentes sobre o suporte do Microsoft Azure.