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

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

注

診断を高速化するために VM アシストを試してください。 Windows の場合は VM assist、LinuxVM assist を実行することをお勧めします>。これらのスクリプトベースの診断ツールは、Azure VM ゲストエージェントと VM の全体的な正常性に影響する一般的な問題を特定するのに役立ちます。

仮想マシンでパフォーマンスの問題が発生している場合は、サポートに連絡する前に、これらのツールを実行してください。

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

Key Vault VM 拡張機能では、次の機能がサポートされます。

Ubuntu 22.04 以降
Azure Linux

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

PKCS #12
PEM

特徴

Linux バージョン 3.0 以降の Key Vault VM 拡張機能では、次の機能がサポートされています。

ダウンロードした証明書の ACL アクセス許可を追加して、ユーザーとグループに読み取りアクセスを提供する
証明書のインストール場所の構成
カスタムシンボリック名のサポート
Fluentd を使用した VM 拡張機能ログ統合のサポート

前提条件

証明書を使用してインスタンスをKey Vaultします。 Key Vault の作成を参照してください。
仮想マシン/仮想マシンスケールセットで割り当てられたマネージド ID 。
VM に対する Key Vault スコープレベルでの Key Vault シークレットユーザー ロールと、Azure Virtual Machine Scale Sets マネージド ID。このロールでは、証明書のシークレットの部分を取得できます。詳細については、次の記事を参照してください。
仮想マシンスケールセットには、次の ID 設定が必要です。
AKV 拡張機能には、次の設定が必要です。

Key Vault VM 拡張機能をアップグレードする

以前のバージョンからバージョン 3.0 以降にアップグレードする必要がある場合は、最初に以前のバージョンを削除してから、バージョン 3.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 3.0

VM に以前のバージョンによってダウンロードされた証明書がある場合、VM 拡張機能を削除しても、ダウンロードされた証明書は削除されません。新しいバージョンをインストールした後、既存の証明書は変更されません。証明書ファイルを削除するか、証明書をロールオーバーして、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": "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.: "00001111-aaaa-2222-bbbb-3333cccc4444".>
        }>
       }
      }
    }

注

確認された証明書の URL は、の形式である必要があります。

これは、パスは秘密キーを含む完全な証明書を返すのに対し、パスはそれを返さないためです。証明書の詳細については、Key Vault Certificates

重要

authenticationSettings プロパティは、VM または VM スケールセットで ユーザー割り当てマネージド ID を使用する場合、または Azure Arc 対応 VM を使用する場合にのみ必要です。システム割り当てマネージド ID の場合は、セクションを省略します。これを含めると、デプロイが失敗します。このセクションがない場合、ユーザー割り当て ID を持つ VM では、Key Vault拡張機能が失敗し、証明書をダウンロードできなくなります。 msiClientId を、Key Vaultに対して認証する ID に設定します。

また、Azure Arc 対応 VM に必要です。 MsiEndpoint をに設定します。

プロパティ値

名前	値/例	データ型
`apiVersion`	2022-07-01	date
`publisher`	マイクロソフト。Azure。KeyVault	文字列
`type`	KeyVaultForLinux	文字列
`typeHandlerVersion`	3.0	INT
`pollingIntervalInS`	3600	文字列
`certificateStoreName`	Linux では無視されます	文字列
`linkOnRenewal`	偽り	ブーリアン
`requireInitialSync`	ほんとう	ブーリアン
`aclEnabled`	ほんとう	ブーリアン
`certificateStoreLocation`	/var/lib/waagent/Microsoft/Azure/KeyVault/Store	文字列
`observedCertificates`	[{...}, {...}]	文字列配列
`observedCertificates/url`	";	文字列
`observedCertificates/certificateStoreLocation`	"/var/lib/waagent/Microsoft。Azure。KeyVault/app1"	文字列
(省略可)	"app1Cert1"	文字列
(省略可)	{...}, {...}	文字列配列
(省略可)	{...}	オブジェクト
`authenticationSettings/msiEndpoint`	http://169.254.169.254/metadata/identity	文字列
`authenticationSettings/msiClientId`	00001111-aaaa-2222-bbbb-3333cccc4444	文字列
(省略可)	{...}	オブジェクト
`loggingSettings/logger`	"fluentd"	文字列
`loggingSettings/endpoint`	"tcp://localhost:24224"	文字列
`loggingSettings/format`	"forward"	文字列
`loggingSettings/servicename`	"akvvm_service"	文字列

Template deployment

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

注

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": "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.: "00001111-aaaa-2222-bbbb-3333cccc4444">
          }
        } 
      }
    }

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

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

拡張機能は、バックオフ期間を長くして最初のダウンロードを最大 25 回再試行し、その間は状態のままです。再試行が使い果たされた場合、拡張機能は状態を報告します。

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

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

注

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

Azure PowerShellデプロイ

警告

多くの場合、PowerShell クライアントでは、エラーを伴って akvvm_service が失敗する原因となる settings.json で、がに追加されます。

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

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

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

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

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

仮想マシンに拡張機能をデプロイするには:

# 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

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

    # 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

Azure CLIデプロイ

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

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

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

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

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

仮想マシンに拡張機能をデプロイするには


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

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

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

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

Key Vaultの制限:
- デプロイ時に存在している必要があります
- VM の ID に関連付けられた Key Vault に、Key Vault シークレットユーザーロールを割り当てる必要があります。

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

拡張機能のデプロイの状態に関するデータは、Azure ポータルから、および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/*	Key Vault VM 拡張機能サービスログを調べて、akvvm_service サービスと証明書のダウンロードの状態を確認します。 PEM ファイルのダウンロード場所は、証明書ファイル名のエントリを持つファイル内で確認できます。 certificateStoreLocation が指定されていない場合、既定値は /var/lib/waagent/Microsoft になります。Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<最も新しいバージョン>/config/*	Key Vault VM 拡張機能サービスの構成とバイナリ。

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

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

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

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

certificateStoreLocation 設定に基づいてストレージフォルダーを作成します (指定しない場合、既定値は /var/lib/waagent/Microsoft.Azure.KeyVault.Store/)
Key Vaultに格納されている証明書チェーンと秘密キーをインストールします。 PEM ファイルは RFC 5246 セクション 7.4.2 の順序に従います。
- リーフ証明書 (エンドエンティティ証明書) が最初に提供されます
- 中間証明書は順番に従い、各証明書は前の証明書を直接認定します (Key Vaultに存在する場合)
- ルート証明書が存在する場合 (ただし、システムによって既に信頼されている場合は検証に必要ありません)
- リーフ証明書に対応する秘密キーは、ファイルの末尾に配置されます
最新バージョンの証明書を指すという名前のシンボリックリンクを自動的に作成する

この方法により、次のことが保証されます。

アプリケーションは、Key Vaultに格納されている証明書チェーンにアクセスできます
証明書チェーンは、RFC 標準に従って TLS ハンドシェイク用に適切に順序付けられています
秘密キーはサービスで使用できます
アプリケーションは、証明書の更新時に自動的に更新される安定したシンボリックリンクパスを参照できます
証明書のローテーションまたは更新時にアプリケーションの再構成は必要ありません

証明書パス構造の例

という名前のの証明書の場合、ディレクトリ構造は次のようになります。

/var/lib/waagent/Microsoft.Azure.KeyVault.Store/
├── exampleVault.myCertificate -> exampleVault.myCertificate.1234567890abcdef
├── exampleVault.myCertificate.1234567890abcdef    # Full chain PEM file (current version)
└── exampleVault.myCertificate.0987654321fedcba    # Previous version (if exists)

アプリケーションは、シンボリックリンクパス (/var/lib/waagent/Microsoft.Azure.KeyVault.Store/exampleVault.myCertificate) を使用して、常に最新の証明書バージョンにアクセスするように構成する必要があります。

カスタム証明書ストアの場所と設定を使用する場合、構造は次のパターンに従います。

/path/to/custom/store/
├── customLinkName -> exampleVault.myCertificate.1234567890abcdef
└── exampleVault.myCertificate.1234567890abcdef    # Full chain PEM file

よく寄せられる質問

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

サポート

この記事の任意の時点でさらにヘルプが必要な場合は、MSDN Azure および Stack Overflow フォーラムのAzureエキスパートにお問い合わせください。または、Azure サポートインシデントを提出することもできます。 Azure サポートサイトに移動し、[サポートを受ける] を選択します。 Azure Supportの使用方法については、Microsoft Azure サポート FAQ を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-06