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

2025-05-20

Key Vault VM 拡張機能では、Azure キーコンテナーに保存されている証明書の自動更新が行われます。具体的には、拡張機能では、キーコンテナーに格納されている確認済みの証明書のリストが監視されます。変更が検出されると、拡張によって取得され、対応する証明書がインストールされます。このドキュメントでは、Linux 用の Key Vault 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 Secrets User ロールと、Azure Virtual Machine Scale Sets マネージド ID。このロールでは、証明書のシークレットの部分を取得できます。詳細については、次の記事を参照してください。
仮想マシンスケールセットには、次の ID 設定が必要です。 "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }
AKV 拡張機能には、次の設定が必要です。"authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

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 は、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	日付
`publisher`	Microsoft.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`	"https://myvault.vault.azure.net/secrets/mycertificate1"	ひも
`observedCertificates/certificateStoreLocation`	"/var/lib/waagent/Microsoft.Azure.KeyVault/app1"	ひも
`observedCertificates/customSymbolicLinkName` (任意)	"app1Cert1"	ひも
`observedCertificates/acls` (任意)	"{...}, {...}"	文字列配列
`authenticationSettings` (任意)	{...}	オブジェクト
`authenticationSettings/msiEndpoint`	http://169.254.169.254/metadata/identity	ひも
`authenticationSettings/msiClientId`	00001111-aaaa-2222-bbbb-3333cccc4444	ひも
`loggingSettings` (任意)	{...}	オブジェクト
`loggingSettings/logger`	"fluentd"	ひも
`loggingSettings/endpoint`	"tcp://localhost:24224"	ひも
`loggingSettings/format`	"forward"	ひも
`loggingSettings/servicename`	"akvvm_service"	ひも

テンプレートのデプロイ

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 回再試行し、その間は Transitioning 状態のままです。再試行が使い果たされた場合、拡張機能は Error 状態を報告します。

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

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

注

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

Azure PowerShell でのデプロイ

警告

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

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

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

Azure Key Vault VM 拡張機能は、Azure PowerShell を使用してデプロイできます。 Key Vault VM 拡張機能の設定を 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 を使用してデプロイできます。 Key Vault VM 拡張機能の設定を 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 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 上のローカルに存在し、トラブルシューティングの際に最も役立ちます。オプションのログセクションを使用し、fluentd を介してログプロバイダーと統合できます

場所	説明
/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 上の最新バージョンの証明書を取得します。

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

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

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

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

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

証明書パス構造の例

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

/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) を使用して、常に最新の証明書バージョンにアクセスするように構成する必要があります。

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

/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 サポートの使用方法の詳細については、「 Microsoft Azure サポートに関する FAQ」を参照してください。