Linux 用の Key Vault 仮想マシン拡張機能

[アーティクル]
02/20/2024

Key Vault VM 拡張機能では、Azure キーコンテナーに保存されている証明書の自動更新が行われます。具体的には、拡張機能では、キーコンテナーに格納されている確認済みの証明書のリストが監視されます。変更が検出されると、拡張によって取得され、対応する証明書がインストールされます。このドキュメントでは、Linux 用の Key Vault VM 拡張機能でサポートされているプラットフォーム、構成、デプロイオプションについて詳しく説明します。

オペレーティングシステム

Key Vault VM 拡張機能では、次の Linux ディストリビューションがサポートされています。

Ubuntu 20.04、22.04
Azure Linux

Note

Key Vault VM 拡張機能は、既定の場所または VM 拡張機能の設定の "certStoreLocation" プロパティによって指定される場所に証明書をダウンロードします。 Key Valut VM 拡張機能によって、フォルダーのアクセス許可が 700 (drwx------) に更新され、読み取り、書き込み、および実行のアクセス許可がフォルダーの所有者にのみ付与されます

サポートされている証明書の内容の種類

PKCS #12
PEM

前提条件

証明書を持つ Key Vault インスタンス。 Key Vault の作成に関するページを参照してください
VM/VMSS 上で割り当てられたマネージド ID
VM に対する Key Vault スコープレベルでの Key Vault Secrets User ロールと、Azure Virtual Machine Scale Sets マネージド ID。このロールでは、証明書のシークレットの部分を取得できます。詳細については、次の記事を参照してください。
VMSS には、次の ID 設定が必要です。"identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }
AKV 拡張機能には、次の設定が必要です。"authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Key Vault VM 拡張機能バージョン

ユーザーは、Key Vault VM 拡張機能のバージョンを V2.0 にアップグレードして、完全な証明書チェーンダウンロード機能を使用することを選択できます。発行者証明書 (中間およびルート) は、リーフ証明書と共に PEM ファイル内に含まれます。
v2.0 にアップグレードする場合は、まず v1.0 を削除してから、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

既定で最新バージョンがインストールされるため、フラグ "--version 2.0" は省略可能です。

VM に v1.0 によってダウンロードされた証明書がある場合、v1.0 AKVVM 拡張機能を削除しても、ダウンロードされた証明書は削除されません。 v2.0 をインストールしても、既存の証明書は変更されません。証明書ファイルを削除するか、証明書をロールオーバーして、VM 上のフルチェーンの PEM ファイルを取得する必要があります。

拡張機能のスキーマ

次の JSON は、Key Vault VM 拡張機能のスキーマを示しています。この拡張機能では、保護された設定は必要ありません。すべての設定がセキュリティに影響を与えない情報と見なされます。この拡張機能には、監視対象のシークレット、ポーリング頻度、および宛先の証明書ストアの一覧が必要です。具体的な内容は次のとおりです。

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

Note

確認された証明書の URL は、https://myVaultName.vault.azure.net/secrets/myCertName の形式である必要があります。

これは、パス /secrets は秘密キーを含む完全な証明書を返すのに対し、パス /certificates はそれを返さないためです。証明書について詳しくは、次の記事をご覧ください: 「Key Vault 証明書」

重要

"authenticationSettings" プロパティは、ユーザー割り当て ID を使用する VM の場合にのみ必須です。システム割り当て ID を使用する場合でもこれは必要で、これがないと VM 拡張機能はどの ID を使用するべきかを判断できません。このセクションがない場合、ユーザー割り当て ID を持つ VM では、Key Vault 拡張機能が失敗し、証明書をダウンロードできなくなります。 msiClientId を、Key Vault に対して認証される ID に設定します。

これも、Azure Arc 対応 VM で必要です。 MsiEndpoint を http://localhost:40342/metadata/identity に設定します。

プロパティ値

名前	値/例	データ型
apiVersion	2022-07-01	date
publisher	Microsoft.Azure.KeyVault	string
type	KeyVaultForLinux	string
typeHandlerVersion	2.0	INT
pollingIntervalInS	3600	string
certificateStoreName	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"]	文字列配列
msiEndpoint	http://169.254.169.254/metadata/identity	string
msiClientId	c7373ae5-91c2-4165-8ab6-7381d6e75619	string

テンプレートのデプロイ

Azure VM 拡張機能は、Azure Resource Manager テンプレートでデプロイできます。テンプレートは、デプロイ後の証明書の更新が必要な仮想マシンを 1 つ以上デプロイするときに最適です。拡張機能は、個々の VM または仮想マシンスケールセットにデプロイできます。スキーマと構成は、両方のテンプレートの種類に共通です。

仮想マシン拡張機能の JSON の構成は、テンプレートの仮想マシンリソースのフラグメント内に入れ子にする必要があります (具体的には、仮想マシンテンプレートの場合は "resources": [] オブジェクト、仮想マシンスケールセットの場合は "virtualMachineProfile":"extensionProfile":{"extensions" :[] オブジェクト)。

注意

VM 拡張機能では、Key Vault に対する認証のために、システムまたはユーザーのマネージド ID が割り当てられている必要があります。 Key Vault に対して認証を行う方法と 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"
        }
      }
      }
    }

拡張機能の依存関係の順序付け

Key Vault VM 拡張機能は、構成されている場合に拡張機能の順序付けをサポートします。既定では、拡張機能はポーリングが開始するとすぐに開始の成功を報告します。しかし、完全な証明書のリストのダウンロードが成功するのを待ってから、開始の成功を報告するように拡張機能を構成することができます。他の拡張機能が、起動のためにインストールされている証明書に依存している場合は、この設定を有効にすることで、それらの拡張機能が Key Vault 拡張機能を依存関係として宣言できるようになります。これにより、依存先であるすべての証明書がインストールされるまで、これらの拡張機能を起動できなくなります。拡張機能によって、最初のダウンロードが無期限に再試行され、Transitioning 状態のままとなります。

拡張機能の依存関係を有効にするには、次のように設定します。

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

Note

システム割り当て ID を作成し、その ID を使用して Key Vault アクセスポリシーを更新する ARM テンプレートに対しては、この機能を使用することはできません。それを行うと、すべての拡張機能が起動するまでコンテナーのアクセスポリシーが更新されなくなり、デッドロックが発生することになります。そうではなく、"単一ユーザー割り当て MSI ID" を使用し、その ID でコンテナーに事前 ACL を設定してからデプロイする必要があります。

Azure PowerShell でのデプロイ

警告

多くの場合、PowerShell クライアントでは、[CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object. エラーを伴って akvvm_service が失敗する原因となる settings.json で、\ が " に追加されます。

Azure PowerShell を使用すると、Key Vault VM 拡張機能を既存の仮想マシンまたは仮想マシンのスケールセットにデプロイすることができます。

VM 拡張機能をデプロイするには、次の手順を実行します。

    # 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

拡張機能を仮想マシンスケールセットにデプロイするには:


    # 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

Azure CLI でのデプロイ

Azure CLI を使用すると、Key Vault VM 拡張機能を既存の仮想マシンまたは仮想マシンスケールセットにデプロイすることができます。

VM 拡張機能をデプロイするには、次の手順を実行します。

   # 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> \"] }}'

拡張機能を仮想マシンスケールセットにデプロイするには:

      # 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> \"] }}'

次の制限/要件に注意してください。

Key Vault の制限:
- デプロイ時に存在している必要があります
- マネージド ID を使用して VM/VMSS ID に Key Vault アクセスポリシーが設定されている必要があります。 Key Vault に対して認証を行う方法に関するページと「Key Vault アクセスポリシーを割り当てる」を参照してください。

トラブルシューティングとサポート

拡張機能のデプロイ状態に関するデータを取得するには、Azure Portal または Azure PowerShell を使用します。特定の VM での拡張機能のデプロイ状態を確認するには、Azure PowerShell を使用して次のコマンドを実行します。

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 は、いくつかのシェル環境で実行できますが、形式には若干の差異があります。 Azure CLI コマンドで予期しない結果が発生した場合は、「Azure CLI を正しく使用する方法」を参照してください。

ログと構成

Key Vault VM 拡張機能のログは、VM 上のローカルにのみ存在し、トラブルシューティングの際に大変役に立ちます。

場所	説明
/var/log/waagent.log	拡張機能の更新が発生した時間を示します。
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/*	akvvm_service サービスと証明書のダウンロードの状態を確認するには、Key Vault VM 拡張機能のサービスログを調べます。 PEM ファイルのダウンロード場所は、証明書ファイル名のエントリを持つファイル内で確認できます。 certificateStoreLocation が指定されていない場合の既定値は /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ になります。
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<最新バージョン>/config/*	Key Vault VM 拡張機能サービスの構成とバイナリ。

シンボリックリンクの使用

シンボリックリンク (Symlink) は、高度なショートカットです。フォルダーの監視を回避し、最新の証明書を自動的に取得するには、このシンボリックリンク ([VaultName].[CertificateName]) を使用して、Linux 上の最新バージョンの証明書を取得します。

よく寄せられる質問

構成できる observedCertificates の数に制限はありますか? いいえ。Key Vault VM 拡張機能には、observedCertificates の数に制限はありません。

サポート

この記事についてさらにヘルプが必要な場合は、いつでも MSDN の Azure フォーラムと Stack Overflow フォーラムで Azure エキスパートに問い合わせることができます。または、Azure サポートインシデントを送信できます。その場合は、Azure サポートのサイトに移動して、[サポートの要求] をクリックします。 Azure サポートの使用方法の詳細については、「 Microsoft Azure サポートに関する FAQ」を参照してください。

Linux 用の Key Vault 仮想マシン拡張機能

オペレーティング システム

サポートされている証明書の内容の種類

前提条件

Key Vault VM 拡張機能バージョン

拡張機能のスキーマ

プロパティ値

テンプレートのデプロイ

拡張機能の依存関係の順序付け

Azure PowerShell でのデプロイ

Azure CLI でのデプロイ

トラブルシューティングとサポート

ログと構成

シンボリック リンクの使用

よく寄せられる質問

サポート

その他のリソース

オペレーティングシステム

シンボリックリンクの使用