Extensión de máquina virtual de Key Vault para Linux

La extensión de máquina virtual de Key Vault proporciona la actualización automática de certificados almacenados en un almacén de claves de Azure. En concreto, la extensión supervisa la lista de certificados observados almacenados en los almacenes de claves. Al detectar un cambio, la extensión recupera e instala los certificados correspondientes. En este documento se especifican las plataformas compatibles, configuraciones y opciones de implementación de la extensión de máquina virtual de Key Vault para Linux.

Sistema operativo

La extensión de máquina virtual de Key Vault admite:

• Ubuntu 22.04 y versiones posteriores
• Azure Linux

Tipos de contenido de certificado admitidos

• PKCS n.º 12
• PEM

Características

La extensión de máquina virtual de Key Vault para Linux versión 3.0+ admite:

• Adición de permisos de ACL para certificados descargados para proporcionar acceso de lectura a usuarios y grupos
• Configuración de la ubicación de instalación del certificado
• Compatibilidad con nombres simbólicos personalizados
• Compatibilidad con la integración del registro de extensiones de máquina virtual a través de Fluentd

Requisitos previos

• Instancia de Key Vault con certificado. Consulte Creación de un almacén de claves.

• Identidad administrada asignada en máquinas virtuales o conjuntos de escalado de máquinas virtuales.

• El rol Usuario de secretos de Key Vault en el ámbito de Key Vault para las máquinas virtuales y la identidad administrada de Azure Virtual Machine Scale Sets. Este rol recupera la parte de un secreto de un certificado. Para más información, consulte los siguientes artículos.

  • Autenticación de Azure Key Vault
  • Uso de los permisos de secretos, claves y certificados de Azure RBAC con Azure Key Vault
  • Asignación de roles del ámbito de Key Vault

• Los conjuntos de escalado de máquinas virtuales deben tener la siguiente configuración de identidad: "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }

• La extensión AKV debe tener este valor: "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Actualización de la extensión de máquina virtual de Key Vault

• Si necesita actualizar desde una versión anterior a la versión 3.0 o posterior, primero tendría que eliminar la versión anterior y, a continuación, instalar la versión 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

• Si la máquina virtual tiene certificados descargados por la versión anterior, la eliminación de la extensión de máquina virtual no elimina los certificados descargados. Después de instalar la versión más reciente, los certificados existentes no se modifican. Tendrá que eliminar los archivos de certificado o revertir el certificado para obtener el archivo PEM con la cadena completa de la máquina virtual.

Esquema de extensión

El siguiente JSON proporciona el esquema para la extensión de máquina virtual de Key Vault. Todas las configuraciones se especifican como configuraciones sin protección, ya que ninguna se considera confidencial. Para configurar la extensión, debe especificar una lista de certificados para supervisar, la frecuencia con la que sondear actualizaciones y la ruta de acceso de destino para almacenar certificados. Concretamente:

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

Implementación de plantilla

Las extensiones de VM de Azure pueden implementarse con plantillas de Azure Resource Manager. Las plantillas son ideales al implementar una o varias máquinas virtuales que requieren la actualización de los certificados tras la implementación. La extensión se puede implementar en máquinas virtuales individuales o en conjuntos de escalado de máquinas virtuales. El esquema y la configuración son comunes para ambos tipos de plantilla.

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

Orden de las dependencias de la extensión

La extensión de máquina virtual de Key Vault admite el orden de las extensiones si está configurado. De forma predeterminada, los informes de extensión se inician correctamente en cuanto se inicia el sondeo. Sin embargo, puede configurarlo para esperar hasta que descargue correctamente la lista completa de certificados antes de notificar un inicio correcto. Si otras extensiones dependen de los certificados instalados antes de que se inicien, la habilitación de esta configuración permitirá que esas extensiones declaren una dependencia de la extensión de Key Vault. Esto evitará que se inicien esas extensiones hasta que se hayan instalado todos los certificados de los que dependen.

La extensión reintentará la descarga inicial hasta 25 veces con períodos de espera crecientes, durante los cuales permanece en estado Transitioning. Si se agotan los reintentos, la extensión notificará un estado Error.

Para activar la dependencia de extensión, establezca lo siguiente:

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

Implementación de Azure PowerShell

Azure PowerShell puede usarse para implementar la extensión de máquina virtual de Key Vault en una máquina virtual o un conjunto de escalado de máquinas virtuales.

• Para implementar la extensión en una máquina virtual:

La extensión de máquina virtual de Azure Key Vault se puede implementar con Azure PowerShell. Guarde la configuración de la extensión de la máquina virtual de Key Vault en un archivo JSON (settings.json).

Los siguientes fragmentos de código JSON proporcionan una configuración de ejemplo para implementar la extensión de máquina virtual de Key Vault con 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 implementar la extensión en una 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 implementar la extensión en un conjunto de escalado de máquinas virtuales:

    # 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 

Implementación de la CLI de Azure

La CLI de Azure puede usarse para implementar la extensión de máquina virtual de Key Vault en una máquina virtual o un conjunto de escalado de máquinas virtuales.

• Para implementar la extensión en una máquina virtual:

La extensión de máquina virtual de Azure Key Vault se puede implementar mediante la CLI de Azure. Guarde la configuración de la extensión de la máquina virtual de Key Vault en un archivo JSON (settings.json).

Los siguientes fragmentos de código JSON proporcionan una configuración de ejemplo para implementar la extensión de máquina virtual de Key Vault con la CLI de 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 implementar la extensión en una 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 implementar la extensión en un conjunto de escalado de máquinas virtuales:

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

Tenga en cuenta las restricciones y los requisitos siguientes:

• Restricciones de Key Vault:
  • Debe existir en el momento de la implementación.
  • El rol de usuario secretos de Key Vault debe asignarse a Key Vault para la identidad de máquina virtual

Solución de problemas y asistencia

Los datos sobre el estado de las implementaciones de extensiones pueden recuperarse desde Azure Portal y mediante Azure PowerShell. Para ver el estado de implementación de las extensiones de una máquina virtual determinada, ejecute el comando siguiente con Azure PowerShell.

Azure PowerShell

Get-AzVMExtension -VMName <vmName> -ResourceGroupname <resource group name>

CLI de Azure

 az vm get-instance-view --resource-group <resource group name> --name  <vmName> --query "instanceView.extensions"

La CLI de Azure se puede ejecutar en varios entornos de shell, pero con ligeras variaciones de formato. Si tiene resultados inesperados con comandos de la CLI de Azure, consulte Uso correcto de la CLI de Azure.

Registros y configuración

Los registros de extensión de máquina virtual de Key Vault existen localmente en la máquina virtual y son más informativos cuando se trata de solucionar problemas. Puede usar la sección de registro opcional para integrarse con el proveedor de registro a través de fluentd

Uso de vínculos simbólicos

Los vínculos simbólicos o Symlinks son métodos abreviados avanzados. Para evitar supervisar la carpeta y obtener el certificado más reciente automáticamente, puede usar este vínculo simbólico ([VaultName].[CertificateName]) para obtener la versión más reciente del certificado en Linux.

Instalación de certificados en Linux

La extensión de máquina virtual de Key Vault para Linux instala certificados como archivos PEM con la cadena de certificados completa incluida. Cuando se descarga un certificado desde Key Vault, la extensión:

1. Crea una carpeta de almacenamiento basada en la certificateStoreLocation configuración (el valor predeterminado es /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ si no se especifica).
2. Instala la cadena de certificados completa y la clave privada en un archivo PEM después de la sección 7.4.2 de RFC 5246 en este orden específico:
   • El certificado hoja (certificado de entidad final) viene primero
   • Los certificados intermedios siguen en orden, donde cada certificado certifica directamente el anterior.
   • Certificado raíz, si está presente (aunque no es necesario para la validación si ya confía en el sistema)
   • La clave privada, correspondiente al certificado de hoja, se coloca al final del archivo.
3. Crea automáticamente un vínculo simbólico denominado [VaultName].[CertificateName] que apunta a la versión más reciente del certificado.

Este enfoque garantiza que:

• Las aplicaciones siempre tienen acceso a la cadena de certificados completa necesaria para la validación
• La cadena de certificados se ordena correctamente para los protocolos de enlace TLS según los estándares RFC
• La clave privada está disponible para su uso por parte del servicio.
• Las aplicaciones pueden hacer referencia a una ruta de acceso de vínculo simbólico estable que se actualiza automáticamente cuando se renuevan los certificados.
• No se necesita reconfiguración de aplicaciones cuando se rotan o renuevan los certificados.

Estructura de ruta de acceso para certificados de ejemplo

Para un certificado de exampleVault.vault.azure.net con el nombre myCertificate, la estructura de directorios tendría el siguiente aspecto:

/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)

Las aplicaciones deben configurarse para usar la ruta de acceso de vínculo simbólico (/var/lib/waagent/Microsoft.Azure.KeyVault.Store/exampleVault.myCertificate) para asegurarse de que siempre acceden a la versión de certificado más reciente.

Cuando se usan ubicaciones de almacén de certificados personalizadas y la customSymbolicLinkName configuración, la estructura sigue este patrón:

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

Preguntas más frecuentes

• ¿Hay un límite en el número de certificados observados que puede configurar? No, la extensión de máquina virtual de Key Vault no tiene límite en el número de certificados observados.

Soporte técnico

Si necesita más ayuda con cualquier aspecto de este artículo, puede ponerse en contacto con los expertos de Azure en los foros de MSDN Azure o Stack Overflow. Como alternativa, puede registrar un incidente de soporte técnico de Azure. Vaya al sitio de soporte técnico de Azure y seleccione Obtener soporte. Para obtener información sobre el uso del soporte técnico, lea las Preguntas más frecuentes de soporte técnico de Microsoft Azure.