Sdílet prostřednictvím

Rozšíření virtuálního počítače služby Key Vault pro Linux

  • Článek

Rozšíření virtuálního počítače služby Key Vault poskytuje automatickou aktualizaci certifikátů uložených ve službě Azure Key Vault. Konkrétně rozšíření monitoruje seznam pozorovaných certifikátů uložených v trezorech klíčů. Rozšíření načte a nainstaluje odpovídající certifikáty po zjištění změny. Tento dokument podrobně popisuje podporované platformy, konfigurace a možnosti nasazení pro rozšíření virtuálního počítače služby Key Vault pro Linux.

Operační systém

Rozšíření virtuálního počítače se službou Key Vault podporuje tyto linuxové distribuce:

Poznámka:

Rozšíření virtuálního počítače služby Key Vault stáhne certifikáty ve výchozím umístění nebo do umístění, které poskytuje vlastnost certStoreLocation v nastavení rozšíření virtuálního počítače (verze 1/2) nebo individuální nastavení certifikátu (verze 3). Rozšíření virtuálního počítače služby Key Vault aktualizuje oprávnění ke složce na verzi 700 (drwx------), která umožňuje jen oprávnění ke čtení, zápisu a spuštění pro vlastníka složky.

Podporované typy obsahu certifikátu

  • PKCS č. 12
  • PEM

Aktualizace ve verzi 3.0 nebo novější

Verze 3.0 nebo novější rozšíření virtuálního počítače služby Key Vault pro Linux přidává podporu pro následující funkce:

  • Přidání oprávnění seznamu ACL pro stažené certifikáty pro zajištění přístupu pro čtení pro uživatele a skupiny
  • Konfigurace umístění instalace certifikátu
  • Podpora vlastních symbolických názvů
  • Podpora integrace protokolování rozšíření virtuálních počítačů prostřednictvím fluentdu

Požadavky

Verze rozšíření virtuálního počítače služby Key Vault

  • Uživatelé se můžou rozhodnout upgradovat stávající verzi rozšíření virtuálního počítače služby Key Vault na novější verzi.

  • Pokud chcete upgradovat na novější verzi, musíte nejprve odstranit předchozí verzi a pak nainstalovat novější verzi.

  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

Příznak --version 3.0 je volitelný, protože nejnovější verze je ve výchozím nastavení nainstalovaná.

  • Pokud má virtuální počítač certifikáty stažené podle předchozí verze, odstranění rozšíření virtuálního počítače neodstraní stažené certifikáty. Po instalaci novější verze se stávající certifikáty nezmění. Pokud chcete získat soubor PEM s úplným řetězem na virtuálním počítači, musíte odstranit soubory certifikátů nebo certifikát převést.

Schéma rozšíření

Následující KÓD JSON ukazuje schéma pro rozšíření virtuálního počítače služby Key Vault. Rozšíření nevyžaduje chráněná nastavení – všechna jeho nastavení se považují za informace bez dopadu na zabezpečení. Rozšíření vyžaduje seznam monitorovaných tajných kódů, frekvenci dotazování a cílové úložiště certifikátů. Konkrétně:

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

Poznámka:

Pozorované adresy URL certifikátů by měly být ve formuláři https://myVaultName.vault.azure.net/secrets/myCertName.

Je to proto, že /secrets cesta vrací úplný certifikát, včetně privátního klíče, zatímco /certificates cesta ne. Další informace o certifikátech najdete tady: Certifikáty služby Key Vault

Důležité

Vlastnost authenticationSettings se vyžaduje pro virtuální počítače s libovolnými identitami přiřazenými uživatelem. I když chcete použít identitu přiřazenou systémem, je stále potřeba, jinak rozšíření virtuálního počítače neví, kterou identitu použít. Bez této části způsobí selhání virtuálního počítače s identitami přiřazenými uživatelem rozšíření Key Vault a nemožnost stáhnout certifikáty. Nastavte msiClientId na identitu, která se ověří ve službě Key Vault.

Vyžaduje se také pro virtuální počítače s podporou Azure Arc. Nastavte msiEndpoint na http://localhost:40342/metadata/identity.

Hodnoty vlastností

Název Hodnota / příklad Datový typ
apiVersion 2022-07-01 datum
publisher Microsoft.Azure.KeyVault string
type KeyVaultForLinux string
typeHandlerVersion 3,0 int
pollingIntervalInS 3600 string
certificateStoreName V Linuxu se ignoruje. string
linkOnRenewal false (nepravda) boolean
requireInitialSync true boolean
aclEnabled true boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
observedCertificates [{...}, {...}] Řetězcové pole
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" string
observedCertificates/certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault/app1 string
observedCertificates/customSymbolicLinkName (volitelné) "app1Cert1" string
observedCertificates/acls (volitelné) "{...}, {...}" Řetězcové pole
authenticationSettings (volitelné) {...} objekt
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity string
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string
loggingSettings (volitelné) {...} objekt
loggingSettings/logger "fluentd" string
loggingSettings/endpoint "tcp://localhost:24224" string
loggingSettings/format "vpřed" string
loggingSettings/servicename "akvvm_service" string

Nasazení šablon

Rozšíření virtuálních počítačů Azure je možné nasadit pomocí šablon Azure Resource Manageru. Šablony jsou ideální pro nasazení jednoho nebo více virtuálních počítačů, které vyžadují aktualizaci certifikátů po nasazení. Rozšíření je možné nasadit na jednotlivé virtuální počítače nebo škálovací sady virtuálních počítačů. Schéma a konfigurace jsou společné pro oba typy šablon.

Konfigurace JSON pro rozšíření virtuálního počítače musí být vnořená uvnitř fragmentu prostředku virtuálního počítače šablony "resources": [] , konkrétně objektu pro šablonu virtuálního počítače a pro škálovací sadu virtuálních počítačů pod objektem "virtualMachineProfile":"extensionProfile":{"extensions" :[] .

Poznámka:

Rozšíření virtuálního počítače by vyžadovalo přiřazení systémové nebo uživatelem spravované identity k ověření ve službě Key Vault. Viz Postup ověření ve službě Key Vault a přiřazení zásad přístupu ke službě 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">
          }
        } 
      }
    }

Řazení závislostí rozšíření

Rozšíření virtuálního počítače služby Key Vault podporuje řazení rozšíření, pokud je nakonfigurované. Ve výchozím nastavení se sestavy rozšíření úspěšně spustí, jakmile se spustí dotazování. Můžete ho ale nakonfigurovat tak, aby čekal, až úspěšně stáhne úplný seznam certifikátů, a teprve potom nahlásí úspěšné spuštění. Pokud jiná rozšíření závisí na nainstalovaných certifikátech před jejich spuštěním, povolením tohoto nastavení umožníte těmto rozšířením deklarovat závislost na rozšíření Key Vault. Zabráníte tak spuštění těchto rozšíření, dokud nebudou nainstalované všechny certifikáty, na kterých závisí. Rozšíření bude opakovat počáteční stahování po neomezenou dobu a zůstane ve Transitioning stavu.

Pokud chcete zapnout závislost rozšíření, nastavte následující:

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

Poznámka:

Použití této funkce není kompatibilní se šablonou ARM, která vytvoří identitu přiřazenou systémem a aktualizuje zásadu přístupu ke službě Key Vault s touto identitou. Tím dojde k zablokování, protože zásady přístupu trezoru nelze aktualizovat, dokud nebudou spuštěna všechna rozšíření. Před nasazením byste měli místo toho použít identitu MSI přiřazenou jedním uživatelem a předsouvat seznam ACL trezorů s danou identitou.

Nasazení Azure PowerShellu

Upozorňující

Klienti PowerShellu se často přidávají \ do " settings.json, což způsobí selhání akvvm_service s chybou: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

Azure PowerShell je možné použít k nasazení rozšíření virtuálního počítače služby Key Vault do existujícího virtuálního počítače nebo škálovací sady virtuálních počítačů.

  • Nasazení rozšíření na virtuální počítač:

Rozšíření virtuálního počítače azure Key Vault je možné nasadit pomocí Azure PowerShellu. Uložte nastavení rozšíření virtuálního počítače služby Key Vault do souboru JSON (settings.json).

Následující fragmenty kódu JSON poskytují ukázková nastavení pro nasazení rozšíření virtuálního počítače služby Key Vault pomocí PowerShellu.

{
   "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"
   }      
}
  • Nasazení rozšíření na virtuální počítač:
# 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
  • Nasazení rozšíření ve škálovací sadě virtuálních počítačů:
    # 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

Nasazení v Azure CLI

Azure CLI se dá použít k nasazení rozšíření virtuálního počítače služby Key Vault do existujícího virtuálního počítače nebo škálovací sady virtuálních počítačů.

  • Nasazení rozšíření na virtuální počítač:

Rozšíření virtuálního počítače azure Key Vault je možné nasadit pomocí Azure CLI. Uložte nastavení rozšíření virtuálního počítače služby Key Vault do souboru JSON (settings.json).

Následující fragmenty kódu JSON poskytují ukázková nastavení pro nasazení rozšíření virtuálního počítače služby Key Vault pomocí Azure CLI.

{
   "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"
   }      
}
  • Nasazení rozšíření na virtuální počítač

    # 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"
  • Nasazení rozšíření ve škálovací sadě virtuálních počítačů:
    # 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"

Mějte na paměti následující omezení a požadavky:

  • Omezení služby Key Vault:
    • Musí existovat v době nasazení.
    • Role uživatele tajných klíčů služby Key Vault musí být přiřazená službě Key Vault pro identitu virtuálního počítače.

Řešení potíží a podpora

Data o stavu nasazení rozšíření je možné načíst z webu Azure Portal a pomocí Azure PowerShellu. Pokud chcete zobrazit stav nasazení rozšíření pro daný virtuální počítač, spusťte následující příkaz pomocí Azure PowerShellu.

Azure PowerShell

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

Azure CLI

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

Azure CLI může běžet v několika prostředích prostředí, ale s mírnými variacemi formátu. Pokud máte neočekávané výsledky s příkazy Azure CLI, přečtěte si, jak úspěšně používat Azure CLI.

Protokoly a konfigurace

Protokoly rozšíření virtuálního počítače služby Key Vault existují místně na virtuálním počítači a jsou nejinformativnější, pokud jde o řešení potíží. Volitelný oddíl protokolování můžete použít k integraci se zprostředkovatelem protokolování prostřednictvím fluentd

Umístění Popis
/var/log/waagent.log Ukazuje, kdy došlo k aktualizaci rozšíření.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Projděte si protokoly služby Rozšíření virtuálního počítače služby Key Vault a zjistěte stav služby akvvm_service a stažení certifikátu. Umístění stahování souborů PEM najdete v souborech s položkou s názvem název souboru certifikátu. Pokud parametr certificateStoreLocation není zadaný, použije se výchozí hodnota /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-nejnovější< verze>/config/* Konfigurace a binární soubory pro službu rozšíření virtuálního počítače služby Key Vault.

Symbolické odkazy nebo Symlinky jsou pokročilé klávesové zkratky. Abyste se vyhnuli monitorování složky a získání nejnovějšího certifikátu automaticky, můžete pomocí tohoto symlinku ([VaultName].[CertificateName]) získat nejnovější verzi certifikátu v Linuxu.

Nejčastější dotazy

  • Existuje limit počtu pozorovaných certifikátů, které můžete nakonfigurovat? Ne, rozšíření virtuálního počítače služby Key Vault nemá limit počtu pozorovaných certifikátů.

Technická podpora

Pokud potřebujete další pomoc v libovolném bodě tohoto článku, můžete kontaktovat odborníky na Azure na fórech MSDN Azure a Stack Overflow. Případně můžete podat incident podpora Azure. Přejděte na web podpora Azure a vyberte Získat podporu. Informace o používání podpory Azure najdete v nejčastějších dotazech k Microsoftu podpora Azure.