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

  • Artículo

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. Microsoft publica la extensión de máquina virtual de Key Vault y es compatible con esta, actualmente en máquinas virtuales Linux. 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 estas distribuciones de Linux:

Nota

La extensión de máquina virtual Key Vault descarga los certificados en la ubicación predeterminada o en la ubicación proporcionada por la propiedad "certStoreLocation" en la configuración de la extensión de máquina virtual. La extensión de máquina virtual Key Vault actualiza el permiso de carpeta a 700 (drwx------), lo que solo concede el permiso de lectura, escritura y ejecución al propietario de la carpeta.

Tipos de contenido de certificado admitidos

  • PKCS #12
  • PEM

Prerrequisitos

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

  • VM/VMSS debe tener asignada una identidad administrada.

  • La directiva de acceso de Key Vault se debe establecer con los secretos get y los permisos list para la identidad administrada de VM/VMSS y recuperar la parte del certificado de un secreto. Consulte Autenticación en Key Vault y Asignación de una directiva de acceso de Key Vault.

  • VMSS debe tener el siguiente valor 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]" }

Extensión de máquina virtual de Key Vault

  • Los usuarios pueden optar por actualizar la versión de la extensión de VM del almacén de claves a V2.0 para utilizar la característica de descarga completa de la cadena de certificados. Los certificados de emisor (intermedio y raíz) se anexarán al certificado de hoja en el archivo PEM.

  • Si prefiere actualizar a v2.0, deberá eliminar primero v1.0 y después instalar v2.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 2.0

La marca--version 2.0 es opcional porque la versión más reciente se instalará de forma predeterminada.

  • Si la máquina virtual tiene certificados descargados por v1.0, al eliminar la extensión v1.0 AKVVM, NO se eliminarán los certificados descargados. Después de instalar v2.0, los certificados existentes NO se modificarán. 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 muestra el esquema para la extensión de máquina virtual de Key Vault. La extensión no requiere configuración protegida, ya que todas sus opciones se consideran información sin riesgo de seguridad. La extensión requiere una lista de secretos supervisados, frecuencia de sondeo y el almacén de certificados de destino. 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": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <It is ignored on Linux>,
          "linkOnRenewal": <Not available on Linux e.g.: false>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "requireInitialSync": <initial synchronization of certificates e..g: true>,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]>
        },
        "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".>
        }
       }
      }
    }

Nota

Las direcciones URL de los certificados observados deben tener el formato https://myVaultName.vault.azure.net/secrets/myCertName.

Esto se debe a que la ruta de acceso /secrets devuelve el certificado completo, incluida la clave privada, mientras que la ruta de acceso /certificates no. Se puede encontrar más información sobre los certificados aquí: Certificados de Key Vault

Importante

La propiedad "authenticationSettings" es necesaria para máquinas virtuales con identidades asignadas por el usuario. Incluso si quiere usar una identidad asignada por el sistema, esto sigue siendo necesario; de lo contrario, la extensión de máquina virtual no sabrá qué identidad usar. Sin esta sección, una máquina virtual con identidades asignadas por el usuario producirá un error en la extensión Key Vault y no podrá descargar certificados. Establezca msiClientId en la identidad que se autenticará en Key Vault.

Además, es necesario en el caso de las máquinas virtuales habilitadas para Azure Arc. Establezca msiEndpoint en http://localhost:40342/metadata/identity.

Valores de propiedad

Nombre Valor / ejemplo Tipo de datos
apiVersion 2022-07-01 date
publisher Microsoft.Azure.KeyVault string
type KeyVaultForLinux string
typeHandlerVersion 2.0 int
pollingIntervalInS 3600 string
certificateStoreName Se omite en Linux. string
linkOnRenewal false boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
requireInitialSync true boolean
observedCertificates ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"] matriz de cadenas
msiEndpoint http://169.254.169.254/metadata/identity string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string

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.

La configuración de JSON para una extensión de máquina virtual debe estar anidada dentro del fragmento de recursos de máquina virtual de la plantilla, en concreto en el objeto "resources": [] de la plantilla de máquina virtual y, en el caso de un conjunto de escalado de máquinas virtuales, en el objeto "virtualMachineProfile":"extensionProfile":{"extensions" :[].

Nota

La extensión de VM requeriría la asignación de la identidad administrada del sistema o del usuario para autenticarse en Key Vault. Consulte Autenticación en Key Vault y asignación de una directiva de acceso de 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": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
          "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <ingnored on linux>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: "https://myvault.vault.azure.net/secrets/mycertificate"
        }      
      }
      }
    }

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, la extensión informa de que se ha iniciado correctamente en cuanto se ha iniciado el sondeo. Sin embargo, se puede configurar para que espere hasta que se haya descargado correctamente la lista completa de certificados antes de informar de un inicio correcto. Si otras extensiones dependen de tener instalado el conjunto completo de certificados para iniciarse, la habilitación de esta opción permitirá a esa extensión declarar 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 volverá a intentar la descarga inicial de forma indefinida y permanecerá en un estado Transitioning.

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

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

[Nota] El uso de esta característica no es compatible con una plantilla de Resource Manager que crea una identidad asignada por el sistema y actualiza una directiva de acceso de Key Vault con esa identidad. Su utilización producirá un interbloqueo porque la directiva de acceso al almacén no se puede actualizar hasta que se hayan iniciado todas las extensiones. En su lugar, debe usar una identidad MSI asignada por el usuario única y establecer una ACL previamente en los almacenes con esa identidad antes de la implementación.

Implementación de Azure PowerShell

Advertencia

Los clientes de PowerShell suelen agregar \ a " en el archivo settings.json, lo cual producirá en akvvm_service el error: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object..

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:

        # Build settings
    $settings = '{"secretsManagementSettings": 
    { "pollingIntervalInS": "' + <pollingInterval> + 
    '", "certificateStoreName": "' + <certStoreName> + 
    '", "certificateStoreLocation": "' + <certStoreLoc> + 
    '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
    $extName =  "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"


    # Start the deployment
    Set-AzVmExtension -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -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 = '{"secretsManagementSettings": 
    { "pollingIntervalInS": "' + <pollingInterval> + 
    '", "certificateStoreName": "' + <certStoreName> + 
    '", "certificateStoreLocation": "' + <certStoreLoc> + 
    '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
    $extName = "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"

    # Add Extension to VMSS
    $vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
    Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -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:

       # Start the deployment
     az vm extension set -n "KeyVaultForLinux" `
     --publisher Microsoft.Azure.KeyVault `
     -g "<resourcegroup>" `
     --vm-name "<vmName>" `
     --version 2.0 `
     --enable-auto-upgrade true `
     --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

  • 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 2.0 `
      --enable-auto-upgrade true `
      --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

Tenga en cuenta las restricciones y los requisitos siguientes:

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 solo existen localmente en la máquina virtual y son los más informativos en lo que respecta a la solución de problemas.

Ubicación Descripción
/var/log/waagent.log Muestra cuándo se produjo una actualización de la extensión.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Examine los registros de extensión de máquina virtual de Key Vault para determinar el estado del servicio akvvm_service y la descarga del certificado. La ubicación de la descarga de los archivos PEM también se encuentra en estos archivos con una entrada llamada nombre del archivo de certificados. Si certificateStoreLocation no se especifica, tendrá como valor predeterminado /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<versión más reciente>/config/* La configuración y los archivos binarios del servicio de extensión de máquina virtual de Key Vault.

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.

Preguntas más frecuentes

  • ¿Hay un límite en el número de observedCertificates que se pueden configurar? No, la extensión de VM de Key Vault no tiene un límite para el número de observedCertificates.

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.