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

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

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

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

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

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

• PKCS #12
• PEM

Функции

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

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

Предпосылки

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

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

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

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

• Наборы масштабирования виртуальных машин Azure должны иметь следующий параметр идентификации:

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

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

  "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 Key Vault 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 Resource Manager развернуть расширения для виртуальных машин Azure. Шаблоны идеально подходят при развертывании одной или нескольких виртуальных машин, требующих обновления сертификатов после развертывания. Расширение можно развернуть для отдельных виртуальных машин или наборов масштабирования виртуальных машин Azure. Для обоих типов шаблонов используются общие схема и конфигурация.

   {
      "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 or disables ACLs on defined certificates e.g.: true>,
          "observedCertificates": <An array of Key Vault 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 в существующей виртуальной машине или масштабируемом наборе виртуальных машин.

Сохраните параметры расширения виртуальной машины 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"
   }
}

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

# 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

Развертывание в масштабируемом наборе виртуальных машин с помощью Azure PowerShell

# 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 в существующей виртуальной машине или масштабируемом наборе виртуальных машин.

Сохраните параметры расширения виртуальной машины 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"
   }
}

Развертывание на виртуальной машине с помощью Azure CLI

# Start the deployment
az vm extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vm-name "<vmName>" \
  --version "3.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

Развертывание в масштабируемом наборе виртуальных машин с помощью Azure CLI

# Start the deployment
az vmss extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vmss-name "<vmssName>" \
  --version "3.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

Ознакомьтесь со следующими ограничениями и требованиями:

• Ограничения Key Vault:
  • Хранилище ключей должно существовать на момент развертывания.
  • Роль пользователя секретов Key Vault должна быть назначена Key Vault для удостоверения виртуальной машины.

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

Получение данных о состоянии развертываний расширений на портале Azure или с помощью Azure PowerShell или Azure CLI. Чтобы просмотреть состояние развертывания расширений для данной виртуальной машины, выполните следующие команды.

• 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. Устанавливает цепочку сертификатов и закрытый ключ в том виде, в котором они хранятся в Key Vault. PeM-файл следует за порядком RFC 5246 раздела 7.4.2 :
   • Конечный сертификат, или сертификат конечной сущности, идёт первым.
   • Промежуточные сертификаты следуют по порядку, при этом каждый сертификат напрямую удостоверяет подлинность предыдущего, если они присутствуют в Key Vault.
   • Корневой сертификат, если присутствует. Корневой сертификат не требуется для проверки, если система уже доверяет ей.
   • Расширение помещает закрытый ключ, соответствующий конечному сертификату в конце файла.
3. Автоматически создает символьную ссылку с именем [VaultName].[CertificateName] , указывающую на последнюю версию сертификата.

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

• Приложения имеют доступ к цепочке сертификатов, хранящейся в Key Vault.
• Цепочка сертификатов упорядочена для 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 не ограничивает количество наблюдаемых сертификатов (observedCertificates).

Получите поддержку

Microsoft предоставляет поддержку только для основной версии 3.0 и более поздних версий расширения виртуальной машины Key Vault. Если вы используете версию 1.0, обновите ее до последней версии, прежде чем запрашивать поддержку.

Ниже приведены некоторые другие варианты, которые помогут устранить проблемы с развертыванием.

• Чтобы получить помощь, обратитесь к экспертам Azure в Microsoft Q& A.
• Если вы не нашли ответ на сайте, задайте вопрос, чтобы получить ответы от Microsoft или других участников сообщества.
• Вы также можете связаться с служба поддержки Майкрософт. Сведения об использовании поддержки Azure см. в статье Как создать запрос в поддержку Azure.