Linux 用の Key Vault 仮想マシン拡張機能
Key Vault VM 拡張機能では、Azure キー コンテナーに保存されている証明書の自動更新が行われます。 具体的には、拡張機能では、キー コンテナーに格納されている確認済みの証明書のリストが監視されます。 変更が検出されると、拡張によって取得され、対応する証明書がインストールされます。 このドキュメントでは、Linux 用の Key Vault VM 拡張機能でサポートされているプラットフォーム、構成、デプロイ オプションについて詳しく説明します。
オペレーティング システム
Key Vault VM 拡張機能では、次の Linux ディストリビューションがサポートされています。
- Ubuntu 20.04、22.04
- Azure Linux
Note
Key Vault VM 拡張機能では、既定の場所、または VM 拡張機能設定 (バージョン 1/2) あるいは個々の証明書設定 (バージョン 3) の "certStoreLocation" プロパティによって指定された場所に証明書がダウンロードされます。 Key Valut VM 拡張機能によって、フォルダーのアクセス許可が 700 (drwx------) に更新され、読み取り、書き込み、および実行のアクセス許可がフォルダーの所有者にのみ付与されます
サポートされている証明書の内容の種類
- PKCS #12
- PEM
バージョン 3.0+ の更新
Linux 用 Key Vault VM 拡張機能のバージョン 3.0 以降では、次の機能のサポートが追加されています。
- ダウンロードした証明書の ACL アクセス許可を追加して、ユーザーとグループの読み取りアクセスを提供する
- 証明書のインストール場所の構成
- カスタム シンボリック名のサポート
- Fluentd を使用した VM 拡張機能ログ統合のサポート
前提条件
証明書を持つ 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 拡張機能のバージョンを新しいバージョンにアップグレードすることを選択できます。
新しいバージョンにアップグレードする場合は、最初に以前のバージョンを削除してから、新しいバージョンをインストールする必要があります。
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
既定で最新バージョンがインストールされるため、フラグ --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.: "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 | 日付 |
publisher |
Microsoft.Azure.KeyVault | string |
type |
KeyVaultForLinux | string |
typeHandlerVersion |
3.0 | INT |
pollingIntervalInS |
3600 | string |
certificateStoreName |
Linux では無視されます | string |
linkOnRenewal |
false | boolean |
requireInitialSync |
true | boolean |
aclEnabled |
true | boolean |
certificateStoreLocation |
/var/lib/waagent/Microsoft.Azure.KeyVault.Store | string |
observedCertificates |
[{...}, {...}] | 文字列配列 |
observedCertificates/url |
"https://myvault.vault.azure.net/secrets/mycertificate1" | string |
observedCertificates/certificateStoreLocation |
"/var/lib/waagent/Microsoft.Azure.KeyVault/app1" | string |
observedCertificates/customSymbolicLinkName (任意) |
"app1Cert1" | string |
observedCertificates/acls (任意) |
"{...}, {...}" | 文字列配列 |
authenticationSettings (任意) |
{...} | オブジェクト |
authenticationSettings/msiEndpoint |
http://169.254.169.254/metadata/identity | string |
authenticationSettings/msiClientId |
c7373ae5-91c2-4165-8ab6-7381d6e75619 | string |
loggingSettings (任意) |
{...} | オブジェクト |
loggingSettings/logger |
"fluentd" | string |
loggingSettings/endpoint |
"tcp://localhost:24224" | string |
loggingSettings/format |
"forward" | string |
loggingSettings/servicename |
"akvvm_service" | 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": "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">
}
}
}
}
拡張機能の依存関係の順序付け
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 拡張機能をデプロイするには、次の手順を実行します。
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 上の最新バージョンの証明書を取得します。
よく寄せられる質問
- 構成できる observedCertificates の数に制限はありますか? いいえ。Key Vault VM 拡張機能には、observedCertificates の数に制限はありません。
サポート
この記事についてさらにヘルプが必要な場合は、いつでも MSDN の Azure フォーラムと Stack Overflow フォーラムで Azure エキスパートに問い合わせることができます。 または、Azure サポート インシデントを送信できます。 その場合は、Azure サポートのサイトに移動して、[サポートの要求] をクリックします。 Azure サポートの使用方法の詳細については、「 Microsoft Azure サポートに関する FAQ」を参照してください。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示