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. 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 de 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 (versión 1/2) o en la configuración de certificado individual (versión 3). 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

Novedades en la versión 3.0+

La versión 3.0+ de la extensión de máquina virtual de Key Vault para Linux agrega compatibilidad con las siguientes características:

  • 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

Extensión de máquina virtual de Key Vault

  • Los usuarios pueden elegir actualizar su versión de extensión de máquina virtual de Key Vault existente a una versión más reciente.

  • Si prefiere actualizar a una versión más reciente, primero tendría que eliminar la versión anterior y a continuación, instalar la versión más reciente.

  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

La marca --versión 3.0 es opcional porque la versión más reciente está instalada de manera predeterminada.

  • 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 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. Específicamente:

    {
      "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.: "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 sabe 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 3.0 int
pollingIntervalInS 3600 string
certificateStoreName Se omite en Linux string
linkOnRenewal false boolean
requireInitialSync true boolean
aclEnabled true boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
observedCertificates [{...}, {...}] matriz de cadenas
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" string
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" string
observedCertificates/customSymbolicLinkName (opcional) "app1Cert1" string
observedCertificates/acls (opcional) "{...}, {...}" matriz de cadenas
authenticationSettings (opcional) {...} objeto
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity string
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string
loggingSettings (opcional) {...} objeto
loggingSettings/logger "fluentd" string
loggingSettings/endpoint "tcp://localhost:24224" string
loggingSettings/format "adelante" string
loggingSettings/servicename "akvvm_service" 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": "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.: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
          }
        } 
      }
    }

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 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:

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

Location 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. Puede encontrar la ubicación de descarga de archivos PEM en archivos con una entrada denominada nombre de archivo de certificado. 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 certificados observados que puede 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.