Azure Key Vault extensión de máquina virtual para Linux

La extensión Azure Key Vault máquina virtual (VM) actualiza automáticamente los certificados almacenados en un Azure key vault. La extensión supervisa la lista de certificados observados almacenados en los almacenes de claves. Cuando la extensión detecta un cambio, recupera e instala los certificados correspondientes. En este artículo se describen las plataformas, las configuraciones y las opciones de implementación admitidas para la extensión de máquina virtual de Key Vault para Linux.

Sistemas operativos

La extensión de máquina virtual Key Vault para Linux admite las siguientes distribuciones, tanto en AMD64 como en ARM64:

• Ubuntu 24.04
• Azure Linux 3.0 y 4.0
• Red Hat Enterprise Linux (RHEL) 9

Tipos de contenido de certificado admitidos

La extensión de máquina virtual de Key Vault admite los siguientes tipos de contenido de certificado:

• PKCS n.º 12
• PEM

Características

La extensión de máquina virtual Key Vault para Linux versión 4.x:

• Instala las dos versiones más recientes de cada certificado.
• Instala cada certificado como archivos divididos: un archivo de cadena .pem completa y un archivo de clave privada independiente .keyid , cada uno escrito como un archivo con versiones con un vínculo simbólico estable que apunta a la versión más reciente.
• Realiza la validación de la cadena de certificados antes de instalar cualquier certificado que contenga el uso extendido de clave (EKU) de autenticación del servidor TLS. La validación está abierta por error: se sigue instalando un certificado si la validación no se puede completar debido a problemas de red transitorios. Los certificados sin la EKU de autenticación del servidor no están sujetos a esta comprobación.
• Aplica ACL POSIX para conceder a los usuarios y grupos configurados acceso de lectura a la clave privada. La aplicación de ACL está siempre activada.
• Admite una anulación opcional de la autenticación para cada certificado, lo que permite que cada certificado supervisado se autentique con Key Vault mediante una identidad administrada distinta de la identidad administrada predeterminada de la extensión. Para obtener más información, vea Esquema de extensión.
• Admite la integración del registro de extensiones de máquina virtual a través de Fluentd. Para obtener más información, consulte Registro con Fluentd.

Actualización desde la versión 3.0

Si va a actualizar desde la versión 3.0, se cambian o quitan las siguientes características.

Cambios importantes generales:

• pollingIntervalInS ahora está limitado a entre 5 y 60 minutos. De forma predeterminada, la extensión realiza una consulta cada hora.
• Se ha eliminado requireInitialSync. La extensión solo informa del éxito si instala todos los certificados configurados.
• Ya no puede configurar una versión específica de un certificado. Las direcciones URL de certificado observadas deben no tener versiones.
• El esquema heredado donde observedCertificates es una lista de cadenas de dirección URL ya no se admite. Cada entrada debe ser un objeto con una url propiedad .

Cambios incompatibles específicos de Linux:

• La cadena de certificados y la clave privada ahora se escriben en archivos independientes. En la versión 3.0, la cadena completa y la clave privada se combinaron en un único archivo PEM. En 4.x, la extensión escribe la cadena completa en <vaultname>.<certname>.pem y la clave privada en un archivo independiente <vaultname>.<certname>.keyid . Este cambio es incompatible: las aplicaciones que esperan que la clave y la cadena estén en un solo archivo deben actualizarse para leer la cadena del archivo .pem y la clave privada del archivo .keyid. El .luma archivo se actualiza después de actualizar los vínculos simbólicos, por lo que las aplicaciones deben supervisar los cambios en este archivo de metadatos.
• Se ha eliminado customSymbolicLinkName. La extensión siempre usa el nombre predeterminado del enlace simbólico <vaultname>.<certname>.
• Se ha eliminado aclEnabled. La funcionalidad de ACL ahora está siempre habilitada.
• certificateStoreName se omite en Linux y no tiene ningún efecto.

Requisitos previos

Revise los siguientes requisitos previos para usar la extensión de máquina virtual de Key Vault para Linux:

• Una instancia de Azure Key Vault con un certificado. Para más información, consulte Creación de un almacén de claves mediante Azure Portal.

• Una máquina virtual con una identidad administrada asignada.

• Asigne el rol Usuario de secretos de Key Vault en el nivel de ámbito de Key Vault a la identidad administrada de la máquina virtual o de los Virtual Machine Scale Sets. Este rol recupera la parte secreta de un certificado. Para más información, consulte los siguientes artículos.

  • Autenticación en Azure Key Vault
  • Utilice los permisos de secreto, clave y certificado de RBAC de Azure con Azure Key Vault
  • Asignación de roles en el ámbito de Key Vault

• Configure los conjuntos de escalado de máquinas virtuales con la siguiente identity configuración:

  "identity": {
      "type": "UserAssigned",
      "userAssignedIdentities": {
         "[parameters('userAssignedIdentityResourceId')]": {}
      }
  }
  

• Configure la extensión de máquina virtual Key Vault con la siguiente authenticationSettings configuración:

  "authenticationSettings": {
      "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]",
      "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]"
  }
  

Esquema de extensión

El siguiente JSON muestra el esquema para la extensión de máquina virtual de Key Vault. Antes de tener en cuenta las opciones de implementación del esquema, revise las siguientes notas importantes.

• La extensión no requiere una configuración protegida. Todas las configuraciones son información pública.

• Las direcciones URL de certificado observadas deben usar el formulario https://myVaultName.vault.azure.net/secrets/myCertName.

  Este formulario es necesario porque la /secrets ruta de acceso devuelve el certificado completo, incluida la clave privada, pero la /certificates ruta de acceso no. Para más información sobre los certificados, consulte Información general sobre claves, secretos y certificados de Azure Key Vault. No se puede especificar una versión específica del certificado.

• El host de dirección URL debe ser un host de Azure Key Vault reconocido.

• La authenticationSettings propiedad es necesaria para las máquinas virtuales con cualquier identidad asignada por el usuario y para máquinas virtuales habilitadas para Azure Arc.

  Omita esta propiedad cuando use una identidad asignada por el sistema. Para las máquinas virtuales habilitadas para Azure Arc, establezca msiEndpoint en http://localhost:40342/metadata/identity.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KVVMExtensionForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": <Optional. Polling interval in seconds, between 300 (5 min) and 3600 (60 min). Example: "3600">,
             "certificateStoreLocation": <Optional. Default disk path where certificates are stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
             "observedCertificates": <An array of Key Vault URIs that represent monitored certificates, including per-certificate store location and ACL permissions on the 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 disk path where the certificate is stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app1">,
                    "acls": <Optional. An array of users and groups to grant read access to the certificate private key. Example:
                    [
                       { "user": "app1", "group": "appGroup1" },
                       { "user": "service1" }
                    ]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreLocation": <Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app2">,
                    "authenticationOverride": <Optional. Overrides authenticationSettings for this certificate only, so it can authenticate with a different managed identity. Example: {"msiClientId": "11112222-bbbb-3333-cccc-4444dddd5555"}>
                }
             ]>
         },
         "authenticationSettings": {
             "msiEndpoint":  <Required when the msiClientId property is used. Specifies the MSI endpoint. Example for most Azure VMs: "http://169.254.169.254/metadata/identity">,
             "msiClientId":  <Required when the VM has any user assigned identities. Specifies the MSI identity. Example: "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

Valores de propiedad

El esquema JSON incluye las siguientes propiedades.

Implementación de plantilla

Implemente Azure extensiones de máquina virtual mediante plantillas de Azure Resource Manager (ARM). Las plantillas son ideales cuando se implementan una o varias máquinas virtuales que requieren una actualización posterior a la implementación de certificados. Puede implementar la extensión en máquinas virtuales individuales o en instancias de Virtual Machine Scale Sets. El esquema y la configuración son comunes para ambos tipos de plantilla.

La configuración JSON de una extensión de almacén de claves está anidada dentro de la plantilla VM o Virtual Machine Scale Sets. Para una extensión de recursos de máquina virtual, la configuración se anida en el objeto de máquina virtual "resources": []. Para una extensión de instancia de Virtual Machine Scale Sets, la configuración se anida bajo el "virtualMachineProfile":"extensionProfile":{"extensions" :[] objeto.

El siguiente fragmento de código JSON proporciona una configuración de ejemplo para una implementación de plantilla de ARM de la extensión de máquina virtual de Key Vault.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KeyVaultForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": "3600",
             "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
             "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"
                }
             ]
         },
         "authenticationSettings": {
            "msiEndpoint":  "http://169.254.169.254/metadata/identity",
            "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
         }
      }
   }
}

Actualización automática de extensiones

La extensión de máquina virtual Key Vault admite la actualización automática de extensiones para máquinas virtuales y conjuntos de escalado en Azure. Azure mantiene la extensión actualizada automáticamente al establecer las autoUpgradeMinorVersion propiedades y enableAutomaticUpgrade en los ejemplos anteriores en true.

Orden de las dependencias de la extensión

La extensión de máquina virtual Key Vault admite el orden de dependencias de extensión. La extensión informa de un inicio correcto después de descargar e instalar todos los certificados.

Si usa otras extensiones que requieren la instalación de certificados antes de que se inicien, puede usar el orden de dependencia de extensión para declarar una dependencia en la extensión de máquina virtual de Key Vault.

En el inicio, la extensión de máquina virtual Key Vault reintenta la descarga e instalación de certificados hasta 25 veces con períodos de retroceso crecientes, durante los cuales permanece en un estado Transitioning. Si se agotan los reintentos, la extensión notifica un estado error . Una vez instalados correctamente todos los certificados, la extensión de máquina virtual de Key Vault notifica un inicio correcto.

Para obtener más información sobre cómo configurar dependencias entre extensiones, consulte Aprovisionamiento de extensiones de secuencia en Virtual Machine Scale Sets.

Implementación de Azure PowerShell

Implemente la extensión de máquina virtual de Azure Key Vault mediante Azure PowerShell. Guarde la configuración de la extensión de la máquina virtual de Key Vault en un archivo JSON (settings.json).

El siguiente fragmento de código JSON proporciona una configuración de ejemplo para implementar la extensión de máquina virtual de Key Vault mediante PowerShell.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "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"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

Implementació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 "4.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings

Implementación en una instancia de Virtual Machine Scale Sets

# 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 "4.0" -Setting $settings

# Start the deployment
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss

Implementación de la CLI de Azure

Implemente la extensión de máquina virtual de Azure Key Vault mediante el 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).

El siguiente fragmento de código JSON proporciona una configuración de ejemplo para implementar la extensión de máquina virtual de Key Vault mediante el CLI de Azure.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "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"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

Implementación en una máquina virtual

# Start the deployment
az vm extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vm-name "<vmName>" \
  --version "4.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

Implementación en una instancia de Virtual Machine Scale Sets

# Start the deployment
az vmss extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vmss-name "<vmssName>" \
  --version "4.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

az vm extension delete --name "KeyVaultForLinux" --resource-group "<resourcegroup>" --vm-name "<vmName>"

Registro con Fluentd

La extensión de máquina virtual Key Vault puede reenviar sus registros a un recopilador de registros fluentd. Asegúrate de que tu recopilador de registros esté en ejecución y a la escucha en el punto de conexión que especifiques en la configuración.

Agregue la siguiente sección a la configuración de la extensión:

"loggingSettings": {
   "logger": "fluentd",
   "endpoint": "unix:///var/run/azuremonitoragent/sometenant/default_fluent.socket",
   "format": "forward",
   "servicename": "akvvm_service"
}

Solucionar problemas

Use estas sugerencias para solucionar problemas de implementación.

Compruebe las preguntas más frecuentes

¿Hay un límite en el número de certificados observados?

N.º No, la extensión de VM de Key Vault no tiene un límite en cuanto al número de certificados observados (observedCertificates).

¿Cuál es la ubicación predeterminada donde se instalan los certificados?

Si no especifica certificateStoreLocation, la extensión escribe certificados en /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.

¿Cómo puedo forzar a la extensión a obtener un nuevo certificado?

Reinicia el servicio akvvm_service (nombre para mostrar Extensión de Key Vault para máquinas virtuales).

¿Cómo se usa una identidad diferente para un certificado específico?

Agregue un objeto authenticationOverride con el destino msiClientId a la entrada de ese certificado en observedCertificates. Los certificados sin una sustitución utilizan el de nivel superior authenticationSettings.

Consulta del estado de la extensión

Compruebe el estado de la implementación de la extensión en el portal de Azure o mediante PowerShell o el CLI de Azure.

Para ver el estado de implementación de las extensiones de una máquina virtual determinada, ejecute los comandos siguientes.

• Azure PowerShell:

  Get-AzVMExtension -ResourceGroupName <myResourceGroup> -VMName <myVM> -Name <myExtensionName>
  

• La CLI de Azure:

  az vm get-instance-view --resource-group <myResourceGroup> --name <myVM> --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.

Revisión de registros y configuración

Los registros de extensión de máquina virtual de Key Vault solo existen localmente en la máquina virtual. Revise los detalles del registro para obtener ayuda para solucionar problemas.

Instalación de certificados en Linux

La extensión de máquina virtual Key Vault para Linux instala certificados como archivos PEM. Cuando la extensión descarga un certificado de Key Vault, es:

1. Crea una carpeta de almacenamiento basada en la certificateStoreLocation configuración. Si no especifica esta configuración, la ubicación tiene como valor predeterminado /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.
2. Escribe la cadena de certificados (el certificado final, luego los intermedios y, por último, el raíz si está presente en Key Vault) en un archivo .pem de cadena completa con versión, y escribe la clave privada correspondiente en un archivo .keyid con versión.
3. Aplica las ACL POSIX a la clave privada en función de la acls especificada en la configuración, que concede acceso de lectura a los usuarios y grupos enumerados. Por lo demás, los archivos solo son accesibles para el propietario.
4. Crea o actualiza un vínculo simbólico estable (<vaultname>.<certname>.pem y <vaultname>.<certname>.keyid) que apunta a la versión más reciente del certificado. La vinculación siempre se produce.

Ubicación predeterminada del almacén de certificados

Si no especifica una ubicación, la extensión instala certificados en /var/lib/waagent/Microsoft.Azure.KeyVault.Store/. La extensión omite certificateStoreName en Linux.

Archivos de salida del certificado

Para el almacén mykv y el secreto server-tls, una sincronización correcta da como resultado:

/var/lib/waagent/Microsoft.Azure.KeyVault.Store/
├── mykv.server-tls.pem -> mykv.server-tls.<version>.pem.<timestamp>     # symlink to latest full chain
├── mykv.server-tls.keyid -> mykv.server-tls.<version>.keyid.<timestamp> # symlink to latest private key
├── mykv.server-tls.<version>.pem.<timestamp>                            # full chain PEM (mode 600)
├── mykv.server-tls.<version>.keyid.<timestamp>                          # private key (mode 600)
└── mykv.server-tls.luma                                                 # certificate management metadata (mode 644)

Configure las aplicaciones para que hagan referencia a la ruta del enlace simbólico estable (por ejemplo, /var/lib/waagent/Microsoft.Azure.KeyVault.Store/mykv.server-tls.pem), de modo que siempre lean la versión más reciente del certificado sin necesidad de reconfigurarlas cuando se renueve.

Control de acceso a certificados

De forma predeterminada, los archivos de clave privada y certificado solo son legibles por su propietario. Conceda acceso de lectura a usuarios y grupos adicionales mediante la acls matriz en la configuración del certificado:

"acls": [
   { "user": "app1", "group": "appGroup1" },
   { "user": "service1" }
]

Cada entrada puede especificar un usuario, un grupo o ambos. La aplicación de la lista de control de acceso (ACL) está siempre activada y, actualmente, concede acceso de lectura.

Renovación de certificados

Cuando los certificados se renuevan en Key Vault, la extensión realiza automáticamente las siguientes acciones en el siguiente sondeo:

1. Descarga la nueva versión del certificado.
2. Escribe los nuevos archivos versionados .keyid y .pem.
3. Actualiza el enlace simbólico estable para que apunte a la nueva versión, de modo que las rutas existentes de la aplicación sigan apuntando al certificado más reciente.

Obtener soporte técnico

Microsoft solo proporciona compatibilidad con la versión principal 3.0 y posteriores de la extensión de máquina virtual de Key Vault. Si usa la versión 1.0, actualice a la versión más reciente antes de solicitar soporte técnico.

Use estas otras opciones para ayudar a resolver problemas de implementación:

• Para obtener ayuda, póngase en contacto con los expertos Azure en Microsoft Q& A.

• Si no encuentra una respuesta en el sitio, puede publicar una pregunta para la entrada de Microsoft u otros miembros de la comunidad.

• También puede contactar con el soporte técnico de Microsoft. Para obtener información sobre el uso de Soporte técnico de Azure, vea How to create an Soporte técnico de Azure request.