Расширение виртуальной машины Key Vault для Linux

Расширение виртуальной машины Key Vault обеспечивает автоматическое обновление сертификатов, хранящихся в хранилище ключей Azure. В частности, расширение отслеживает список сертификатов, наблюдаемых в хранилищах ключей. После обнаружения изменений расширение получает и устанавливает соответствующие сертификаты. В этом документе подробно описаны поддерживаемые платформы, конфигурации и параметры развертывания для расширения виртуальной машины Key Vault для Linux.

Операционная система

Расширение виртуальной машины Key Vault поддерживает следующее:

• Ubuntu 22.04 и более поздних версий
• Azure Linux

Поддерживаемые типы содержимого сертификатов

• PKCS #12
• PEM

Функции

Расширение виртуальной машины Key Vault для Linux версии 3.0+ поддерживает:

• Добавление разрешений ACL для скачанных сертификатов для предоставления доступа для чтения для пользователей и групп
• Конфигурация расположения установки сертификата
• Поддержка пользовательского символьного имени
• Поддержка интеграции журналирования расширения виртуальной машины с помощью Fluentd

Предпосылки

• Экземпляр хранилища ключей с сертификатом. См. Создание хранилища ключей

• управляемая идентификация назначена на виртуальных машинах или масштабируемых виртуальных машинных наборах.

• Роль пользователя секретов Key Vault на уровне области для управляемых удостоверений виртуальных машин и масштабируемых наборов виртуальных машин Azure. Эта роль извлекает часть секрета сертификата. Дополнительные сведения см. в следующих статьях:

  • Проверка подлинности в Azure Key Vault
  • Использование секрета, ключа и сертификата Azure RBAC с помощью Azure Key Vault
  • Назначение ролей области Key Vault

• Масштабируемые наборы виртуальных машин должны иметь следующий параметр удостоверения: "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }

• Расширение AKV должно иметь этот параметр: "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Обновление расширения виртуальной машины Key Vault

• Если вам нужно обновить более раннюю версию до версии 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

• Если у виртуальной машины есть сертификаты, скачанные предыдущей версией, удаление расширения виртуальной машины не удаляет скачанные сертификаты. После установки более новой версии существующие сертификаты не изменяются. Чтобы получить PEM-файл с полной цепочкой на виртуальной машине, необходимо удалить файлы сертификата или перевернуть сертификат.

Схема расширения

В следующем формате JSON представлена схема расширения виртуальной машины Key Vault. Все параметры указаны как обычные (незащищенные) параметры, поскольку ни один из них не считается конфиденциальным. Чтобы настроить расширение, необходимо указать список сертификатов для мониторинга, частоту опроса обновлений и путь назначения для хранения сертификатов. Конкретно:

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

Значения свойств

Развертывание шаблона

Расширения виртуальных машин Azure можно развернуть с использованием шаблонов Azure Resource Manager. Шаблоны идеально подходят для развертывания одной или нескольких виртуальных машин, требующих обновления сертификатов, выполняемого после развертывания. Расширение можно развертывать на отдельных виртуальных машинах или в масштабируемых наборах виртуальных машин. Для обоих типов шаблонов используются общие схема и конфигурация.

   {
      "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 поддерживает упорядочение расширений, если оно настроено. По умолчанию расширение сообщает об успешном запуске после начала опроса. Однако вы можете настроить его, чтобы дождаться успешного скачивания полного списка сертификатов, прежде чем сообщить об успешном запуске. Если другие расширения зависят от установленных сертификатов перед началом работы, включение этого параметра позволит этим расширениям объявить зависимость от расширения Key Vault. Это предотвратит запуск этих расширений до тех пор, пока не будут установлены все сертификаты, от которых они зависят.

Расширение повторит начальную загрузку до 25 раз с увеличением интервалов ожидания, в течение которых оно остается в Transitioning состоянии. Если повторные попытки исчерпаны, расширение зафиксирует состояние Error.

Чтобы включить зависимость расширения, установите следующее:

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

Развертывание с помощью Azure PowerShell

Azure PowerShell можно использовать для развертывания расширения виртуальной машины Key Vault на имеющейся виртуальной машине или в масштабируемых наборах виртуальных машин.

• Развертывание расширения на виртуальной машине:

Расширение виртуальной машины Azure Key Vault можно развернуть с помощью Azure PowerShell. Сохраните параметры расширения виртуальной машины Key Vault в JSON-файл (settings.json).

В следующих фрагментах JSON приведены примеры параметров для развертывания расширения виртуальной машины Key Vault с помощью PowerShell.

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

Для развертывания расширения виртуальной машины Key Vault на имеющейся виртуальной машине или в масштабируемом наборе виртуальных машин можно использовать Azure CLI.

• Развертывание расширения на виртуальной машине:

Расширение виртуальной машины Azure Key Vault можно развернуть с помощью Azure CLI. Сохраните параметры расширения виртуальной машины Key Vault в JSON-файл (settings.json).

В следующих фрагментах JSON приведены примеры параметров для развертывания расширения виртуальной машины Key Vault с помощью Azure CLI.

{
   "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:
  • оно должно существовать во время развертывания;
  • Роль пользователя секретов Key Vault должна быть назначена Key Vault для удостоверения виртуальной машины.

Устранение неполадок и поддержка

Данные о состоянии развертываний расширения можно получить на портале Azure, а также с помощью Azure PowerShell. Чтобы просмотреть состояние развертывания расширений для определенной виртуальной машины, выполните следующую команду в 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 существуют локально на виртуальной машине и наиболее информативны при устранении неполадок. Вы можете использовать дополнительный раздел ведения журнала для интеграции с поставщиком ведения журнала с помощью fluentd

Использование символьной ссылки

Символьные ссылки или симлинки — это продвинутые ярлыки. Чтобы избежать наблюдения за папкой и автоматического получения последнего сертификата, вы можете использовать эту символьную ссылку ([VaultName].[CertificateName]) для получения последней версии сертификата в Linux.

Установка сертификата в Linux

Расширение виртуальной машины Key Vault для Linux устанавливает сертификаты в виде PEM-файлов с полной цепочкой сертификатов. Когда сертификат загружается из Key Vault, расширение:

1. Создает папку хранилища на основе параметра certificateStoreLocation (по умолчанию используется /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ если не указано)
2. Устанавливает полную цепочку сертификатов и закрытый ключ в PEM-файле в следующем разделе RFC 5246 7.4.2 в указанном порядке:
   • Конечный сертификат (сертификат конечной сущности) идет первым
   • Промежуточные сертификаты следуют в порядке, где каждый сертификат напрямую подтверждает предыдущий.
   • Корневой сертификат, если он присутствует (хотя он не требуется для проверки, если система уже доверяет)
   • Закрытый ключ, соответствующий конечному сертификату, помещается в конец файла.
3. Автоматически создает символьную ссылку с именем [VaultName].[CertificateName] , указывающую на последнюю версию сертификата.

Такой подход гарантирует следующее:

• Приложения всегда имеют доступ к полной цепочке сертификатов, необходимой для проверки
• Цепочка сертификатов правильно упорядочена для TLS рукопожатий в соответствии со стандартами RFC
• Закрытый ключ доступен для использования службой
• Приложения могут ссылаться на стабильный путь символьной ссылки, который автоматически обновляется при продлении сертификатов.
• При смене или продлении сертификатов не требуется перенастройка приложения

Пример структуры пути к сертификату

Для сертификата с exampleVault.vault.azure.net именем myCertificateструктура каталогов будет выглядеть следующим образом:

/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

Часто задаваемые вопросы

• Существует ли ограничение на количество наблюдаемых сертификатов, которые можно настроить? Нет, расширение виртуальной машины Key Vault не имеет ограничения на количество наблюдаемых сертификатов.

Поддержка

Если в любой момент при изучении этой статьи вам потребуется дополнительная помощь, вы можете обратиться к экспертам по Azure на форумах MSDN Azure и Stack Overflow. Кроме того, можно зарегистрировать обращение в службу поддержки Azure. Перейдите на сайт поддержки Azure и щелкните "Получить поддержку". Дополнительные сведения об использовании службы поддержки Azure см. в статье Часто задаваемые вопросы о поддержке Microsoft Azure.