Использование расширения настраиваемых скриптов Azure версии 2 на виртуальных машинах Linux

Расширение пользовательских скриптов версии 2 скачивает и запускает скрипты на виртуальных машинах Azure. Используйте это расширение для настройки после развертывания, установки программного обеспечения или любой другой задачи настройки или управления. Сценарии можно скачать из службы хранилища Azure или другого интернет-ресурса, доступного из Интернета, или передать в среду выполнения расширения.

Расширение Custom Script интегрируется с шаблонами Azure Resource Manager. Вы также можете запустить его с помощью Azure CLI, Azure PowerShell или REST API Azure Virtual Machines.

В этой статье описывается, как использовать расширение пользовательского скрипта из Azure CLI и как запустить расширение с помощью шаблона Azure Resource Manager. В этой статье также показаны шаги по устранению неполадок в системах Linux.

Существует две версии расширения пользовательских скриптов:

• Версия 1 — Microsoft.OSTCExtensions.CustomScriptForLinux
• Версия 2 — Microsoft.Azure.Extensions.CustomScript

Используйте версию 2 для новых и существующих развертываний. Новая версия заменит собой старую. Это так же просто, как смена названия или версии. Изменение конфигурации расширения не требуется.

Предпосылки

Поддерживаемые дистрибутивы Linux

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

Вы можете настроить расширение на использование ваших учетных данных для доступа к Хранилищу BLOB-объектов Azure. Скрипт может находиться в любом расположении при условии, что виртуальная машина может осуществлять маршрутизацию в конечную точку, например, GitHub или внутренний файловый сервер.

Подключение к Интернету

Чтобы загрузить скрипт из внешнего источника, например из GitHub или службы хранилища Azure, нужно открыть другой брандмауэр или порты группы безопасности сети (NSG). К примеру, если ваш скрипт находится в службе хранилища Azure, можете предоставить к нему доступ с помощью служебных тегов для хранилища Azure NSG.

Если ваш скрипт находится на локальном сервере, вам может потребоваться открыть другие порты брандмауэра или порты группы безопасности сети (NSG).

Советы

• Наибольшая частота сбоев для этого расширения обусловлена синтаксическими ошибками в скрипте. Проверьте, что скрипт запускается без ошибок. Добавьте больше возможностей ведения журнала в скрипт, чтобы упростить поиск ошибок.
• Пишите идемпотентные скрипты, чтобы их повторные запуски не вызывали изменения системы.
• Выполняемые скрипты не должны запрашивать ввод данных пользователем.
• Выполнение скрипта разрешено в течение 90 минут. Более длительный процесс приведёт к ошибке предоставления расширения.
• Не помещайте перезагрузки в скрипт. Перезапуск вызывает проблемы с другими устанавливаемыми расширениями, и расширение не будет работать после перезагрузки.
• Если у вас есть скрипт, вызывающий перезагрузку перед установкой приложений и запуском скриптов, назначьте время перезагрузки с помощью задания cron или таких инструментов, как расширения DSC, Chef или Puppet.
• Не запускайте скрипт, который вызывает остановку или обновление агента Linux для Azure. Это может привести к тому, что расширение останется в переходном состоянии и истечет время ожидания.
• Расширение выполняет скрипт только один раз. Если вы хотите запускать скрипт при каждом старте системы, можете использовать образ cloud-init и модуль Scripts Per Boot. Кроме того, можно использовать скрипт для создания модуля службы systemd.
• К виртуальной машине можно применить только одну версию расширения. Чтобы запустить второй пользовательский скрипт, можно применить к имеющемуся расширению новую конфигурацию. Кроме того, можно удалить расширение пользовательских скриптов и повторно применить его с измененным скриптом.
• Чтобы запланировать время выполнения скрипта, воспользуйтесь расширением что бы создать задание cron.
• Во время выполнения скрипта на портале Azure или в CLI вы увидите только переходное состояние расширения. Если требуются более частые обновления состояния выполняющегося скрипта, создайте собственное решение.
• Расширение пользовательских скриптов не предусматривает собственную поддержку прокси-серверов. Но вы можете использовать средство передачи файлов, которое поддерживает прокси-серверы в скрипте, такое как Curl.
• Учитывайте нестандартные расположения каталогов, которые могут использоваться вашими скриптами или командами. Для решения этой ситуации необходимо иметь в распоряжении логику.

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

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

Конфиденциальные данные можно хранить в защищенной конфигурации, которая шифруется и расшифровывается только на целевой виртуальной машине. Защищенную конфигурацию можно использовать для команд, которые содержат секретные данные, например пароли. Ниже приведен пример:

{
  "name": "config-app",
  "type": "Extensions",
  "location": "[resourceGroup().location]",
  "apiVersion": "2019-03-01",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', concat(variables('vmName'),copyindex()))]"
  ],
  "tags": {
    "displayName": "config-app"
  },
  "properties": {
    "publisher": "Microsoft.Azure.Extensions",
    "type": "CustomScript",
    "typeHandlerVersion": "2.1",
    "autoUpgradeMinorVersion": true,
    "settings": {
      "skipDos2Unix":false,
      "timestamp":123456789
    },
    "protectedSettings": {
       "commandToExecute": "<command-to-execute>",
       "script": "<base64-script-to-execute>",
       "storageAccountName": "<storage-account-name>",
       "storageAccountKey": "<storage-account-key>",
       "fileUris": ["https://.."],
       "managedIdentity" : "<managed-identity-identifier>"
    }
  }
}

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

Подробности о значениях свойств

Общедоступные параметры отправляются в виде открытого текста на виртуальную машину, в которой выполняется скрипт. Защищенные параметры шифруются с помощью ключа, известного только в Azure и виртуальной машине. Параметры сохраняются на виртуальной машине по мере их отправки. Это значит, что если параметры были зашифрованы, они сохранятся в таком виде и на виртуальной машине. Сертификат, используемый для расшифровки зашифрованных значений, хранится на виртуальной машине. При необходимости сертификат также используется для расшифровки параметров во время выполнения.

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

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

• commandToExecute
• script
• fileUris

Свойство skipDos2Unix

Предыдущая версия расширения Microsoft.OSTCExtensions.CustomScriptForLinux пользовательского скрипта автоматически преобразует файлы DOS в файлы UNIX, переводя \r\n в \n. Этот перевод по-прежнему присутствует и включен по умолчанию. Это преобразование применяется ко всем файлам, скачанным из fileUris, или к параметрам скрипта, основанного на любом из приведенных ниже критериев:

• Расширение .sh, .txt, .py или .pl. Параметр скрипта всегда соответствует этому критерию, так как предполагается, что сценарий выполняется с /bin/sh. Параметр скрипта сохраняется как script.sh на виртуальной машине.
• Файл начинается с #!.

Значение по умолчанию равно false, что означает преобразование dos2unix выполнено. Преобразование dos2unix можно пропустить, задав для параметра skipDos2Unix значение true:

{
  "fileUris": ["<url>"],
  "commandToExecute": "<command-to-execute>",
  "skipDos2Unix": true
}

Свойство сценарий

Расширение пользовательских скриптов поддерживает выполнение определяемого пользователем скрипта. Параметры скрипта объединяют commandToExecute и fileUris в один параметр. Вместо того чтобы настраивать файл для скачивания из службы хранилища Azure или GitHub Gist, можно зашифровать скрипт в качестве параметра. Скрипт можно использовать для замены commandToExecute и fileUris.

Есть некоторые требования:

• Скрипт должен быть представлен в кодировке Base64.
• Скрипт также можно при необходимости сжать в формате GZIP.
• Настройка скрипта может использоваться в публичных или защищенных настройках.
• Максимальный размер данных параметра script — 256 КБ. Если скрипт превышает этот размер, он не выполняется.

К примеру, следующий скрипт сохранен в файл /script.sh/:

#!/bin/sh
echo "Creating directories ..."
mkdir /data
chown user:user /data
mkdir /appdata
chown user:user /appdata

Вы должны создать правильную настройку скриптового расширения Custom Script Extension, используя выходные данные следующей команды.

cat script.sh | base64 -w0

{
  "script": "IyEvYmluL3NoCmVjaG8gIlVwZGF0aW5nIHBhY2thZ2VzIC4uLiIKYXB0IHVwZGF0ZQphcHQgdXBncmFkZSAteQo="
}

В большинстве случаев скрипт можно в дальнейшем при необходимости сжать в формат GZIP, чтобы еще больше уменьшить размер. Расширение пользовательских скриптов автоматически обнаруживает использование сжатия в формат GZIP.

cat script | gzip -9 | base64 -w 0

Для выполнения скрипта расширение для пользовательских сценариев использует следующий алгоритм:

1. Убедитесь, что длина значения скрипта не превышает 256 КБ.
2. Base64 декодирует значение скрипта.
3. Попробуйте распаковать декодированное из кодировки Base64 значение с помощью gunzip.
4. Запишите декодированное и по желанию распакованное значение на диск: /var/lib/waagent/custom-script/#/script.sh.
5. Запустите скрипт с помощью команды _/bin/sh -c /var/lib/waagent/custom-script/#/script.sh.

Свойство: управляемая идентификация

Расширение пользовательского скрипта версии 2.1 и более поздних версий поддерживает управляемые удостоверения для скачивания файлов из URL-адресов, предоставленных в параметре fileUris . Этот подход позволяет расширению Custom Script получать доступ к частным blob-объектам или контейнерам хранилища Azure без необходимости передавать секреты, такие как токены общей подписи (SAS) или ключи учетной записи хранилища.

Чтобы использовать эту функцию, добавьте удостоверение, назначаемое системой или удостоверение, назначаемое пользователем, на ВМ или в масштабируемый набор виртуальных машин, где должно выполняться расширение пользовательского скрипта. Затем предоставьте управляемому удостоверению доступ к контейнеру хранилища Azure или объекту BLOB.

Чтобы использовать назначаемое системой удостоверение на целевой виртуальной машине или масштабируемом наборе виртуальных машин, задайте managedidentity пустой объект JSON.

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.sh"],
  "commandToExecute": "sh script1.sh",
  "managedIdentity" : {}
}

Чтобы использовать назначенное пользователем удостоверение на целевой виртуальной машине или масштабируемом наборе виртуальных машин, настройте managedidentity с клиентским или объектным ID управляемого удостоверения.

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.sh"],
  "commandToExecute": "sh script1.sh",
  "managedIdentity" : { "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444" }
}

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.sh"],
  "commandToExecute": "sh script1.sh",
  "managedIdentity" : { "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" }
}

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

Вы можете развернуть расширения виртуальной машины Azure с помощью шаблонов диспетчера ресурсов Azure. Схема JSON, подробно описанная в предыдущем разделе, может использоваться в шаблоне Azure Resource Manager для запуска расширения пользовательского скрипта во время развертывания шаблона. Пример шаблона, который содержит расширение пользовательских скриптов, можно найти на сайте GitHub.

{
  "name": "config-app",
  "type": "extensions",
  "location": "[resourceGroup().location]",
  "apiVersion": "2019-03-01",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', concat(variables('vmName'),copyindex()))]"
  ],
  "tags": {
    "displayName": "config-app"
  },
  "properties": {
    "publisher": "Microsoft.Azure.Extensions",
    "type": "CustomScript",
    "typeHandlerVersion": "2.1",
    "autoUpgradeMinorVersion": true,
    "settings": {
      },
    "protectedSettings": {
      "commandToExecute": "sh hello.sh <param2>",
      "fileUris": ["https://github.com/MyProject/Archive/hello.sh"
      ]
    }
  }
}

Azure CLI (интерфейс командной строки Azure)

При использовании Azure CLI для запуска расширения пользовательского скрипта создайте один или несколько файлов конфигурации. Как минимум, файл конфигурации должен содержаться commandToExecute. Команда az vm extension set ссылается на файл конфигурации:

az vm extension set \
  --resource-group myResourceGroup \
  --vm-name myVM --name customScript \
  --publisher Microsoft.Azure.Extensions \
  --protected-settings ./script-config.json

Кроме того, можно указать параметры в команде в виде строки в формате JSON. Такой подход позволяет задать конфигурацию во время выполнения и без отдельного файла конфигурации.

az vm extension set \
  --resource-group exttest \
  --vm-name exttest \
  --name customScript \
  --publisher Microsoft.Azure.Extensions \
  --protected-settings '{"fileUris": ["https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"],"commandToExecute": "./config-music.sh"}'

Пример: общедоступная конфигурация с файлом сценария

В этом примере используется следующий файл скрипта с именем script-config.json:

{
  "fileUris": ["https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"],
  "commandToExecute": "./config-music.sh"
}

1. Создайте файл скрипта с помощью текстового редактора или с помощью следующей команды CLI:

   cat <<EOF > script-config.json
   {
     "fileUris": ["https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"],
     "commandToExecute": "./config-music.sh"
   }
   EOF
   

2. Выполните следующую команду:

   az vm extension set \
     --resource-group myResourceGroup \
     --vm-name myVM --name customScript \
     --publisher Microsoft.Azure.Extensions \
     --settings ./script-config.json
   

Пример: общедоступная конфигурация без файла сценария

В этом примере используется следующее содержимое в формате JSON:

{
  "commandToExecute": "apt-get -y update && apt-get install -y apache2"
}

Выполните следующую команду:

az vm extension set \
  --resource-group tim0329vmRG \
  --vm-name tim0329vm --name customScript \
  --publisher Microsoft.Azure.Extensions \
  --settings '{"commandToExecute": "apt-get -y update && apt-get install -y apache2"}'

Пример: открытые и защищенные файлы конфигурации

Используйте общедоступный файл конфигурации, чтобы указать универсальный код ресурса (URI) файла скрипта:

{
  "fileUris": ["https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"]
}

Используйте защищенный файл конфигурации, чтобы указать команду для выполнения:

{
  "commandToExecute": "./config-music.sh"
}

1. Создайте общедоступный файл конфигурации с помощью текстового редактора или с помощью следующей команды CLI:

   cat <<EOF > script-config.json
   {
     "fileUris": ["https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"]
   }
   EOF
   

2. Создайте защищенный файл конфигурации с помощью текстового редактора или с помощью следующей команды CLI:

   cat <<EOF > protected-config.json
   {
     "commandToExecute": "./config-music.sh"
   }
   EOF
   

3. Выполните следующую команду:

   az vm extension set \
     --resource-group myResourceGroup \
     --vm-name myVM \
     --name customScript \
     --publisher Microsoft.Azure.Extensions \
     --settings ./script-config.json \
     --protected-settings ./protected-config.json
   

Наборы масштабирования виртуальных машин

Если развернуть расширение пользовательского скрипта из портала Azure, у вас нет контроля за истечением срока действия токена SAS для доступа к скрипту в учетной записи хранилища. Начальное развертывание работает, но по истечении срока действия SAS-токена учетной записи хранения любая последующая операция масштабирования завершается ошибкой, потому что расширение для пользовательских скриптов больше не может получить доступ к учетной записи хранения.

Рекомендуется использовать PowerShell, Azure CLI или шаблон Azure Resource Manager при развертывании расширения пользовательского скрипта в масштабируемом наборе виртуальных машин. Таким образом, вы можете использовать управляемое удостоверение или напрямую управлять сроком действия маркера SAS для доступа к скрипту в вашей учетной записи хранения так долго, как вам нужно.

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

Когда расширение пользовательских сценариев выполняется, сценарий создается или загружается в каталог, который выглядит, как показано в следующем примере. Выходные данные команды также сохраняются в этот каталог в файлах stdout и stderr.

sudo ls -l /var/lib/waagent/custom-script/download/0/

Чтобы устранить неполадки, сначала проверьте журнал агента Linux и убедитесь, что расширение запущено:

sudo cat /var/log/waagent.log

Отслеживайте выполнение расширения. Выглядит примерно так:

2018/04/26 17:47:22.110231 INFO [Microsoft.Azure.Extensions.customScript-2.0.6] [Enable] current handler state is: notinstalled
2018/04/26 17:47:22.306407 INFO Event: name=Microsoft.Azure.Extensions.customScript, op=Download, message=Download succeeded, duration=167
2018/04/26 17:47:22.339958 INFO [Microsoft.Azure.Extensions.customScript-2.0.6] Initialize extension directory
2018/04/26 17:47:22.368293 INFO [Microsoft.Azure.Extensions.customScript-2.0.6] Update settings file: 0.settings
2018/04/26 17:47:22.394482 INFO [Microsoft.Azure.Extensions.customScript-2.0.6] Install extension [bin/custom-script-shim install]
2018/04/26 17:47:23.432774 INFO Event: name=Microsoft.Azure.Extensions.customScript, op=Install, message=Launch command succeeded: bin/custom-script-shim install, duration=1007
2018/04/26 17:47:23.476151 INFO [Microsoft.Azure.Extensions.customScript-2.0.6] Enable extension [bin/custom-script-shim enable]
2018/04/26 17:47:24.516444 INFO Event: name=Microsoft.Azure.Extensions.customScript, op=Enable, message=Launch command succeeded: bin/custom-sc

В приведенных выше выходных данных:

• Enable — означает момент запуска команды.
• Download — относится к скачиванию пакета расширения пользовательских скриптов из Azure, а не файлов сценария, указанных в fileUris.

Расширение сценариев Azure создает журнал, который можно найти здесь:

sudo cat /var/log/azure/custom-script/handler.log

Найдите отдельное исполнение. Выглядит примерно так:

time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event=start
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event=pre-check
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="comparing seqnum" path=mrseq
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="seqnum saved" path=mrseq
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="reading configuration"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="read configuration"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="validating json schema"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="json schema valid"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="parsing configuration json"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="parsed configuration json"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="validating configuration logically"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="validated configuration"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="creating output directory" path=/var/lib/waagent/custom-script/download/0
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="created output directory"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 files=1
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 file=0 event="download start"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 file=0 event="download complete" output=/var/lib/waagent/custom-script/download/0
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="executing command" output=/var/lib/waagent/custom-script/download/0
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="executing protected commandToExecute" output=/var/lib/waagent/custom-script/download/0
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="executed command" output=/var/lib/waagent/custom-script/download/0
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event=enabled
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event=end

Здесь вы можете увидеть:

• команда enable, запускающая этот журнал;
• Параметры, переданные в расширение.
• Расширение, скачающее файл и результат этого действия.
• выполняемая команда и результат выполнения.

Вы можете также получить состояние выполнения расширения пользовательских скриптов, включая фактически переданные аргументы как commandToExecute, с помощью Azure CLI.

az vm extension list -g myResourceGroup --vm-name myVM

Выходные данные выглядят так:

[
  {
    "autoUpgradeMinorVersion": true,
    "forceUpdateTag": null,
    "id": "/subscriptions/subscriptionid/resourceGroups/rgname/providers/Microsoft.Compute/virtualMachines/vmname/extensions/customscript",
    "resourceGroup": "rgname",
    "settings": {
      "commandToExecute": "sh script.sh > ",
      "fileUris": [
        "https://catalogartifact.azureedge.net/publicartifacts/scripts/script.sh",
        "https://catalogartifact.azureedge.net/publicartifacts/scripts/script.sh"
      ]
    },
    "tags": null,
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "typeHandlerVersion": "2.0",
    "virtualMachineExtensionType": "CustomScript"
  },
  {
    "autoUpgradeMinorVersion": true,
    "forceUpdateTag": null,
    "id": "/subscriptions/subscriptionid/resourceGroups/rgname/providers/Microsoft.Compute/virtualMachines/vmname/extensions/OmsAgentForLinux",
    "instanceView": null,
    "location": "eastus",
    "name": "OmsAgentForLinux",
    "protectedSettings": null,
    "provisioningState": "Succeeded",
    "publisher": "Microsoft.EnterpriseCloud.Monitoring",
    "resourceGroup": "rgname",
    "settings": {
      "workspaceId": "workspaceid"
    },
    "tags": null,
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "typeHandlerVersion": "1.0",
    "virtualMachineExtensionType": "OmsAgentForLinux"
  }
]

Проблемы синтаксиса Azure CLI

Azure CLI может выполняться в нескольких средах оболочки, но с небольшими вариантами формата. Если вы столкнулись с непредвиденными результатами команд Azure CLI, см. статью Как успешно использовать Azure CLI.

Дальнейшие действия

Смотрите код, текущие проблемы и версии в custom-script-extension-linux.