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

Azure Key Vault仮想マシン (VM) 拡張機能は、Azure key vaultに格納されている証明書を自動的に更新します。 この拡張機能では、キー コンテナーに格納されている確認済みの証明書のリストが監視されます。 拡張機能は、変更を検出すると、対応する証明書を取得してインストールします。 この記事では、Linux 用の Key Vault VM 拡張機能でサポートされているプラットフォーム、構成、デプロイ オプションについて説明します。

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

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

• Ubuntu 24.04
• Azure Linux 3.0 および 4.0
• Red Hat Enterprise Linux (RHEL) 9

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

Key Vault VM 拡張機能では、次の証明書コンテンツ タイプがサポートされています。

• PKCS #12
• PEM

特徴

Linux バージョン 4.x 用の Key Vault VM 拡張機能:

• 各証明書の 2 つの最新バージョンをインストールします。
• 各証明書を分割ファイルとしてインストールします。フルチェーン .pem ファイルと、それぞれ最新バージョンを指す安定したシンボリック リンクを持つバージョン管理されたファイルとして書き込まれた個別の .keyid 秘密キー ファイルです。
• TLS サーバー認証拡張キー使用法 (EKU) を含む証明書をインストールする前に、証明書チェーンの検証を実行します。 検証はフェイルオープンです。一時的なネットワークの問題により検証を完了できない場合でも、証明書はインストールされます。 サーバー認証 EKU のない証明書は、このチェックの対象になりません。
• POSIX ACL を適用して、構成済みのユーザーとグループに秘密キーへの読み取りアクセス権を付与します。 ACL の適用は常にオンになっています。
• 証明書ごとの認証のオーバーライド (オプション) をサポートします。これにより、個々の監視対象の証明書が、拡張機能の既定値とは異なるマネージド ID でKey Vaultに対して認証されます。 詳細については、「 拡張スキーマ」を参照してください。
• Fluentd を使用した VM 拡張機能のログ統合をサポートします。 詳細については、「 Fluentd を使用したログ記録」を参照してください。

3.0 からのアップグレード

3.0 から更新する場合、次の機能が変更または削除されます。

一般的な破壊的変更:

• pollingIntervalInS は現在、5 分から 60 分の間に制限されています。 既定では、拡張機能は 1 時間に 1 回ポーリングします。
• requireInitialSync は削除されました。 拡張機能は、構成されているすべての証明書をインストールした場合にのみ成功を報告します。
• 証明書の特定のバージョンを構成できなくなりました。 監視対象の証明書 URL は、バージョンレスである必要があります。
• observedCertificatesが URL 文字列の一覧であるレガシ スキーマはサポートされなくなりました。 各エントリは、 url プロパティを持つオブジェクトである必要があります。

Linux 固有の破壊的変更:

• 証明書チェーンと秘密キーが個別のファイルに書き込まれるようになりました。 3.0 では、完全なチェーンと秘密キーが 1 つの PEM ファイルに結合されました。 4.x では、拡張機能は完全なチェーンを <vaultname>.<certname>.pem に書き込み、秘密キーを別の <vaultname>.<certname>.keyid ファイルに書き込みます。 この変更は重大です。1 つのファイル内のキーとチェーンを想定するアプリケーションは、 .pem ファイルからチェーンを読み取り、 .keyid ファイルから秘密キーを読み取る必要があります。 .luma ファイルはシンボリック リンクが更新された後に更新されるため、アプリケーションはこのメタデータ ファイルへの変更を監視する必要があります。
• customSymbolicLinkName は削除されました。 拡張機能では、常に既定のシンボリック リンク名 <vaultname>.<certname>が使用されます。
• aclEnabled は削除されました。 ACL 機能が常に有効になりました。
• certificateStoreName は Linux では無視され、影響はありません。

前提条件

Linux 用の Key Vault VM 拡張機能を使用するための次の前提条件を確認します。

• 証明書を含む Azure Key Vault インスタンス。 詳細については、Azure portal を使用したキー コンテナーの作成に関する記事を参照してください。

• マネージド ID が割り当てられた VM。

• Key Vault スコープ レベルの Key Vault シークレット ユーザー ロールを VM またはAzure Virtual Machine Scale Setsのマネージド ID に割り当てます。 このロールは、証明書のシークレット部分を取得します。 詳細については、次の記事を参照してください。

  • Azure Key Vaultでの認証
  • Azure Key Vault で Azure RBAC のシークレット、キー、および証明書のアクセス許可を使用する
  • Key Vault スコープ ロールの割り当て

• 次のidentity構成でVirtual Machine Scale Setsを構成します。

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

• 次のauthenticationSettings構成を使用して、Key Vault VM 拡張機能を構成します。

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

拡張機能のスキーマ

次の JSON は、Key Vault VM 拡張機能のスキーマを示しています。 スキーマ実装オプションを検討する前に、次の重要な注意事項を確認してください。

• 拡張機能では、設定を保護する必要がありません。 すべての設定は公開情報です。

• 観察された証明書 URL は、フォーム https://myVaultName.vault.azure.net/secrets/myCertNameを使用する必要があります。

  /secrets パスは秘密キーを含む完全な証明書を返しますが、/certificates パスは返さないため、このフォームが必要です。 証明書の詳細については、「Azure Key Vault のキー、シークレット、証明書の概要」を参照してください。 特定のバージョンの証明書を指定することはできません。

• URL ホストは、認識されたAzure Key Vaultホストである必要があります。

• authenticationSettings プロパティは、ユーザー割り当て ID を持つ VM と、Azure Arc対応 VM に必要です。

  システム割り当て ID を使用する場合は、このプロパティを省略します。 Azure Arc対応 VM の場合は、msiEndpointを 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">
         }
      }
   }
}

プロパティ値

JSON スキーマには、次のプロパティが含まれています。

Template deployment

Azure Resource Manager (ARM) テンプレートを使用した Azure VM 拡張機能のデプロイ テンプレートは、証明書のデプロイ後の更新を必要とする 1 つ以上の仮想マシンをデプロイする場合に最適です。 拡張機能は、個々の VM またはVirtual Machine Scale Sets インスタンスにデプロイできます。 スキーマと構成は、両方のテンプレートの種類に共通です。

キー コンテナー拡張機能の JSON 構成は、VM または Virtual Machine Scale Sets のテンプレート内で入れ子にされています。 VM リソース拡張機能の場合、構成は "resources": [] 仮想マシン オブジェクトの下で入れ子になります。 Virtual Machine Scale Sets インスタンス拡張機能の場合、構成は "virtualMachineProfile":"extensionProfile":{"extensions" :[] オブジェクトの下で入れ子になります。

次の JSON スニペットは、Key Vault VM 拡張機能の ARM テンプレートデプロイの設定例を示しています。

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

拡張機能の自動アップグレード

Key Vault VM 拡張機能では、Azureの仮想マシンとスケール セットの拡張機能の自動アップグレードがサポートされます。 Azure前の例のautoUpgradeMinorVersionプロパティとenableAutomaticUpgradeプロパティを true に設定すると、拡張機能は自動的に最新の状態に保たされます。

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

Key Vault VM 拡張機能では、拡張機能の依存関係の順序付けがサポートされています。 拡張機能は、すべての証明書をダウンロードしてインストールした後、正常な開始を報告します。

証明書を開始する前に証明書のインストールが必要な他の拡張機能を使用する場合は、拡張機能の依存関係の順序を使用して、Key Vault VM 拡張機能への依存関係を宣言できます。

起動時に、Key Vault VM 拡張機能は、バックオフ期間が長くなり、証明書のダウンロードとインストールが最大 25 回再試行され、その間は Transitioning 状態になります。 再試行が使い果たされた場合、拡張機能は エラー 状態を報告します。 すべての証明書が正常にインストールされると、Key Vault VM 拡張機能によって正常な開始が報告されます。

拡張機能間の依存関係の設定の詳細については、「Virtual Machine Scale Setsでの拡張機能のプロビジョニングのシーケンス」を参照してください。

Azure PowerShellデプロイ

Azure PowerShellを使用して、Azure Key Vault VM 拡張機能をデプロイします。 VM 拡張機能Key Vault設定を JSON ファイル (settings.json) に保存します。

次の JSON スニペットでは、PowerShell を使用して Key Vault VM 拡張機能をデプロイするための設定例を示します。

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

VM でデプロイする

# 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

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

Azure CLIデプロイ

Azure CLIを使用して、Azure Key Vault VM 拡張機能をデプロイします。 VM 拡張機能Key Vault設定を JSON ファイル (settings.json) に保存します。

次の JSON スニペットは、Azure CLIを使用して Key Vault VM 拡張機能をデプロイするための設定例を示しています。

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

VM でデプロイする

# 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"

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

Fluentd を使用したログ記録

Key Vault VM 拡張機能は、そのログを Fluentd ログ コレクターに転送できます。 ログ コレクターが実行され、設定で指定したエンドポイントでリッスンしていることを確認します。

拡張機能の設定に次のセクションを追加します。

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

トラブルシューティング

これらの推奨事項を使用して、デプロイの問題のトラブルシューティングを行います。

よく寄せられる質問を確認する

確認済み証明書の数に制限はありますか?

No. Key Vault VM 拡張機能には、確認済み証明書の数に制限はありません (observedCertificates)。

証明書がインストールされている既定の場所は何ですか?

certificateStoreLocationを指定しない場合、拡張機能は証明書を/var/lib/waagent/Microsoft.Azure.KeyVault.Store/に書き込みます。

拡張機能で新しい証明書を強制的にプルするにはどうすればよいですか?

akvvm_service サービス (VM 拡張機能Key Vault表示名) を再起動します。

特定の証明書に別の ID を使用するにはどうすればよいですか?

ターゲット msiClientIdを持つauthenticationOverride オブジェクトを、observedCertificatesの証明書のエントリに追加します。 オーバーライドのない証明書では、最上位レベルの authenticationSettingsが使用されます。

拡張機能の状態表示

Azure portal で、または PowerShell または Azure CLI を使用して、拡張機能のデプロイの状態を確認します。

特定の VM の拡張機能のデプロイ状態を確認するには、次のコマンドを実行します。

• Azure PowerShell:

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

• Azure CLI:

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

Azure CLIは、いくつかのシェル環境で実行できますが、わずかな形式のバリエーションがあります。 Azure CLIコマンドで予期しない結果が発生した場合は、「Azure CLIを正常に使用する方法を参照してください。

ログと構成を確認する

Key Vault VM 拡張機能ログは、VM 上にのみローカルで存在します。 トラブルシューティングに役立つログの詳細を確認します。

Linux での証明書のインストール

Linux 用の Key Vault VM 拡張機能は、PEM ファイルとして証明書をインストールします。 拡張機能がKey Vaultから証明書をダウンロードすると、次のようになります。

1. certificateStoreLocation設定に基づいてストレージ フォルダーを作成します。 この設定を指定しない場合、場所は既定で /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ になります。
2. 証明書チェーン (リーフ、中間、Key Vaultに存在する場合は root) をバージョン管理されたフルチェーン .pem ファイルに書き込み、対応する秘密キーをバージョン管理された.keyid ファイルに書き込みます。
3. 構成で指定された acls に基づいて、POSIX ACL を秘密キーに適用します。これによって、一覧に表示されているユーザーとグループへの読み取りアクセスが許可されます。 それ以外の場合、ファイルは所有者専用です。
4. 証明書の最新バージョンを指す安定したシンボリック リンク (<vaultname>.<certname>.pem と <vaultname>.<certname>.keyid) を作成または更新します。 リンクは常に行われます。

既定の証明書ストアの場所

場所を指定しない場合、拡張機能は /var/lib/waagent/Microsoft.Azure.KeyVault.Store/の下に証明書をインストールします。 拡張機能は Linux 上の certificateStoreName を無視します。

証明書の出力ファイル

ボールト mykv とシークレット server-tls では、同期が成功すると次のようになります。

/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)

安定したシンボリック リンク パス ( /var/lib/waagent/Microsoft.Azure.KeyVault.Store/mykv.server-tls.pem など) を参照するようにアプリケーションを構成し、更新時に再構成せずに常に最新の証明書バージョンを読み取るようにします。

証明書のアクセス制御

既定では、証明書ファイルと秘密キー ファイルは所有者のみが読み取り可能です。 証明書構成の acls 配列を使用して、追加のユーザーとグループに読み取りアクセス権を付与します。

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

各エントリでは、ユーザー、グループ、またはその両方を指定できます。 ACL の適用は常に有効になっており、現在、読み取りアクセス権が付与されています。

証明書の書き換え

Key Vaultで証明書が更新されると、拡張機能は次のポーリングで次のアクションを自動的に実行します。

1. 新しい証明書バージョンをダウンロードします。
2. 新しいバージョン付きの .pem ファイルと .keyid ファイルを書き込みます。
3. 既存のアプリケーション パスが引き続き最新の証明書に解決されるように、安定したシンボリック リンクを更新して新しいバージョンを指します。

サポートを受ける

Microsoftでは、Key Vault VM 拡張機能のメジャー バージョン 3.0 以降のみがサポートされます。 バージョン 1.0 を使用している場合は、サポートを要求する前に最新バージョンにアップグレードしてください。

デプロイの問題を解決するには、次の他のオプションを使用します。

• サポートについては、AzureのエキスパートにMicrosoft Q&Aでお問い合わせください。

• サイトに回答が見つからない場合は、質問を投稿して、Microsoft またはコミュニティの他のメンバーからの回答を得られます。

• Microsoft サポートにお問い合わせいただくこともできます。 Azure サポートの使用方法については、「Azure サポート要求を作成する方法」を参照>。