Настройка образа контейнера для выполнения развертываний

Создание пользовательского образа контейнера с помощью скрипта

Создание пользовательского образа контейнера позволяет настроить развертывания в соответствии с вашими требованиями. Вы можете создать и создать образ на основе стандартного образа ADE и отправить его в реестр контейнеров с помощью скрипта быстрого запуска, предоставленного корпорацией Майкрософт. Скрипт можно найти в репозитории сред развертывания. Чтобы использовать скрипт быстрого запуска, форкните репозиторий и запустите скрипт локально.

Скрипт создает образ контейнера и отправляет его в указанный Реестр контейнеров Azure (ACR) в хранилище "ade" с тегом "latest". Для выполнения этого скрипта необходимо ваше имя реестра и каталог для вашего пользовательского образа, установка Azure CLI и Docker Desktop, а также включение их в переменные PATH. Кроме того, у вас должны быть разрешения на отправку в указанный реестр.

Чтобы использовать скрипт быстрого запуска для быстрой сборки и отправки этого примера образа в Реестр контейнеров Azure, вам потребуется:

• Скопируйте этот репозиторий в ваш личный аккаунт.
• Убедитесь, что Azure CLI и приложение Docker Desktop установлены на вашем компьютере и входят в переменные PATH.
• Убедитесь, что у вас есть разрешения на отправку образов в выбранный Реестр контейнеров Azure.

Скрипт можно вызвать с помощью следующей команды в PowerShell:

.\quickstart-image-build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}'

Кроме того, если вы хотите отправить в определенный репозиторий и имя тега, можно выполнить следующее:

.\quickstart-image-build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}' -Repository '{YOUR_REPOSITORY}' -Tag '{YOUR_TAG}'

Чтобы использовать образ в развертываниях среды, необходимо добавить расположение изображения в файл манифеста , чтобы подключить образ к определению среды, и вам может потребоваться настроить разрешения для ACR, чтобы сделать настраиваемый образ доступным для ADE.

Создание пользовательского образа контейнера вручную

Создание пользовательского образа контейнера позволяет настроить развертывания в соответствии с вашими требованиями. Вы можете создавать пользовательские образы на основе стандартных образов ADE.

После завершения настройки образа можно создать образ и отправить его в реестр контейнеров вручную.

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

В этом примере вы узнаете, как создать образ Docker для использования развертываний ADE и доступа к интерфейсу командной строки ADE, основанный на одном из образов, созданных ADE.

Чтобы создать образ, настроенный для ADE, выполните следующие действия.

1. Создайте пользовательский образ на основе стандартного образа.
2. Установите нужные пакеты.
3. Настройка скриптов командной оболочки.
4. Создайте скрипты оболочки операций для развертывания файлов ARM или Bicep.

1. Создание пользовательского образа на основе стандартного образа

Создайте Dockerfile, включающий инструкцию FROM, указывающую на стандартный образ, размещенный в реестре артефактов Microsoft.

Ниже приведен пример инструкции FROM, ссылающейся на стандартный основной образ:

FROM mcr.microsoft.com/deployment-environments/runners/core:latest

Эта инструкция загружает последний опубликованный основной образ и использует его в качестве основы для пользовательского образа.

2. Установка обязательных пакетов

На этом этапе вы устанавливаете любые пакеты, которые требуются для вашего образа, включая Bicep. Пакет Bicep можно установить с помощью Azure CLI с помощью инструкции RUN, как показано в следующем примере:

RUN az bicep install

Стандартные образы ADE основаны на образе Azure CLI и предварительно установлены пакеты ADE CLI и JQ. Дополнительные сведения о Azure CLI и пакете JQ можно узнать.

Чтобы установить любые дополнительные пакеты, которые вам нужны в образе, используйте инструкцию RUN.

3. Настройка скриптов оболочки операций

В стандартных образах операции определяются и выполняются на основе имени операции. В настоящее время поддерживаются две операции: deploy и delete.

Чтобы настроить пользовательский образ для использования этой структуры, укажите папку на уровне вашего Dockerfile с названием scripts и укажите два файла: deploy.sh и delete.sh. Скрипт deploy запускается при создании или повторном развертывании среды, а скрипт delete запускается при удалении среды. Примеры скриптов оболочки можно просмотреть в репозитории в папке Runner-Images для образа ARM-Bicep .

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

COPY scripts/* /scripts/
RUN find /scripts/ -type f -iname "*.sh" -exec dos2unix '{}' '+'
RUN find /scripts/ -type f -iname "*.sh" -exec chmod +x {} \;

4. Создание скриптов оболочки операций для развертывания файлов ARM или Bicep

Чтобы обеспечить успешное развертывание инфраструктуры ARM или Bicep через ADE, необходимо:

1. Преобразование параметров ADE в допустимые для ARM параметры
2. Обработать связанные шаблоны, если они используются в развертывании
3. Используйте привилегированную управляемую идентификацию для развертывания

Во время точки входа основного образа все параметры, заданные для текущей среды, хранятся в переменной $ADE_OPERATION_PARAMETERS. Чтобы преобразовать их в допустимые параметры ARM, можно выполнить следующую команду с помощью JQ:

# format the parameters as arm parameters
deploymentParameters=$(echo "$ADE_OPERATION_PARAMETERS" | jq --compact-output '{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", "contentVersion": "1.0.0.0", "parameters": (to_entries | if length == 0 then {} else (map( { (.key): { "value": .value } } ) | add) end) }' )

Затем, чтобы разрешить любые связанные шаблоны, используемые в шаблоне ARM на основе JSON, можно декомпилировать основной файл шаблона, который декомпилирует все файлы локальной инфраструктуры и распределяет их по многим модулям Bicep. Затем перестройте эти модули обратно в один шаблон ARM с связанными шаблонами, внедренными в основной шаблон ARM в виде вложенных шаблонов. Этот шаг необходим только во время операции развертывания. Основной файл шаблона можно указать с помощью набора $ADE_TEMPLATE_FILE, который используется в качестве точки входа основного образа, и эту переменную следует переназначить с помощью перекомпилированного файла шаблона. См. следующий пример.

if [[ $ADE_TEMPLATE_FILE == *.json ]]; then

    hasRelativePath=$( cat $ADE_TEMPLATE_FILE | jq '[.. | objects | select(has("templateLink") and (.templateLink | has("relativePath")))] | any' )

    if [ "$hasRelativePath" = "true" ]; then
        echo "Resolving linked ARM templates"

        bicepTemplate="${ADE_TEMPLATE_FILE/.json/.bicep}"
        generatedTemplate="${ADE_TEMPLATE_FILE/.json/.generated.json}"

        az bicep decompile --file "$ADE_TEMPLATE_FILE"
        az bicep build --file "$bicepTemplate" --outfile "$generatedTemplate"

        # Correctly reassign ADE_TEMPLATE_FILE without the $ prefix during assignment
        ADE_TEMPLATE_FILE="$generatedTemplate"
    fi
fi

Чтобы предоставить развертыванию необходимые разрешения для выполнения развертывания и удаления ресурсов в подписке, используйте привилегированное управляемое удостоверение, связанное с типом среды проекта ADE. Если для развертывания требуются специальные разрешения, например определенные роли, назначьте эти роли удостоверениям типа среды проекта. Иногда управляемое удостоверение не сразу доступно при входе в контейнер; вы можете повторять попытку до успешного входа.

echo "Signing into Azure using MSI"
while true; do
    # managed identity isn't available immediately
    # we need to do retry after a short nap
    az login --identity --allow-no-subscriptions --only-show-errors --output none && {
        echo "Successfully signed into Azure"
        break
    } || sleep 5
done

Чтобы начать развертывание файлов ARM или Bicep, выполните az deployment group create команду. При выполнении этой команды в контейнере выберите имя развертывания, которое не переопределяет предыдущие развертывания, и используйте флаги --no-prompt true и --only-show-errors, чтобы убедиться, что развертывание не завершится сбоем или зависнет при ожидании ввода данных пользователем, как показано в следующем примере:

deploymentName=$(date +"%Y-%m-%d-%H%M%S")
az deployment group create --subscription $ADE_SUBSCRIPTION_ID \
    --resource-group "$ADE_RESOURCE_GROUP_NAME" \
    --name "$deploymentName" \
    --no-prompt true --no-wait \
    --template-file "$ADE_TEMPLATE_FILE" \
    --parameters "$deploymentParameters" \
    --only-show-errors

Чтобы удалить среду, выполните развертывание в полном режиме и укажите пустой шаблон ARM, который удаляет все ресурсы в указанной группе ресурсов ADE, как показано в следующем примере:

deploymentName=$(date +"%Y-%m-%d-%H%M%S")
az deployment group create --resource-group "$ADE_RESOURCE_GROUP_NAME" \
    --name "$deploymentName" \
    --no-prompt true --no-wait --mode Complete \
    --only-show-errors \
    --template-file "$DIR/empty.json"

Вы можете проверить состояние развертывания и детали, выполнив указанные ниже команды. ADE использует специальные функции для чтения и предоставления дополнительного контекста на основе данных о подготовке, которые можно найти в папке Runner-Images. Простая реализация может быть следующей:

if [ $? -eq 0 ]; then # deployment successfully created
    while true; do

        sleep 1

        ProvisioningState=$(az deployment group show --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName" --query "properties.provisioningState" -o tsv)
        ProvisioningDetails=$(az deployment operation group list --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName")

        echo "$ProvisioningDetails"

        if [[ "CANCELED|FAILED|SUCCEEDED" == *"${ProvisioningState^^}"* ]]; then

            echo -e "\nDeployment $deploymentName: $ProvisioningState"

            if [[ "CANCELED|FAILED" == *"${ProvisioningState^^}"* ]]; then
                exit 11
            else
                break
            fi
        fi
    done
fi

Наконец, чтобы просмотреть выходные данные развертывания и передать их в ADE, чтобы сделать их доступными через Azure CLI, можно выполнить следующие команды:

deploymentOutput=$(az deployment group show -g "$ADE_RESOURCE_GROUP_NAME" -n "$deploymentName" --query properties.outputs)
if [ -z "$deploymentOutput" ]; then
    deploymentOutput="{}"
fi
echo "{\"outputs\": $deploymentOutput}" > $ADE_OUTPUTS

Создание пользовательского образа

Вы можете создать образ с помощью интерфейса командной строки Docker. Убедитесь, что подсистема Docker установлена на компьютере. Затем перейдите в каталог Dockerfile и выполните следующую команду:

docker build . -t {YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}

Например, если вы хотите сохранить образ в репозитории в реестре с именем customImageи отправить с помощью версии тега 1.0.0, выполните следующие действия:

docker build . -t {YOUR_REGISTRY}.azurecr.io/customImage:1.0.0

Создание пользовательского образа контейнера с помощью скрипта

Создание пользовательского образа контейнера позволяет настроить развертывания в соответствии с вашими требованиями. Вы можете создать образ на основе стандартного образа ADE и отправить его в реестр контейнеров с помощью скрипта быстрого запуска, предоставленного корпорацией Майкрософт. Скрипт можно найти в репозитории Deployment Environments with Terraform. Чтобы использовать скрипт быстрого запуска, форкните репозиторий и запустите скрипт локально.

Чтобы использовать скрипт быстрого запуска для быстрой сборки и отправки этого примера образа в Реестр контейнеров Azure, вам потребуется:

• Скопируйте этот репозиторий в ваш личный аккаунт.
• Убедитесь, что Azure CLI и приложение Docker Desktop установлены на вашем компьютере и входят в переменные PATH.
• Убедитесь, что у вас есть разрешения на отправку образов в выбранный Реестр контейнеров Azure.

Скрипт создает образ контейнера и отправляет его в указанный Реестр контейнеров Azure (ACR) в хранилище "ade" с тегом "latest". Для выполнения этого скрипта необходимо ваше имя реестра и каталог для вашего пользовательского образа, установка Azure CLI и Docker Desktop, а также включение их в переменные PATH. Кроме того, у вас должны быть разрешения на отправку в указанный реестр. Скрипт можно вызвать с помощью следующей команды в PowerShell:

.\quickstart-image-build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}'

Кроме того, если вы хотите отправить в определенный репозиторий и имя тега, можно выполнить следующее:

.\quickstart-image-build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}' -Repository '{YOUR_REPOSITORY}' -Tag '{YOUR_TAG}'

Чтобы использовать образ в развертываниях среды, необходимо добавить расположение изображения в файл манифеста , чтобы подключить образ к определению среды, и вам может потребоваться настроить разрешения для ACR, чтобы сделать настраиваемый образ доступным для ADE.

Создание пользовательского образа контейнера с помощью рабочего процесса GitHub

Для начала можно использовать опубликованный рабочий процесс GitHub из репозитория "Leveraging ADE's Extensibility Model With Terraform".

Чтобы использовать рабочий процесс, вам потребуется:

• Форкните этот репозиторий в личную учетную запись.
• Разрешить GitHub Actions подключаться к Azure через федеративные учетные данные приложения Microsoft Entra ID через OIDC. Дополнительные сведения см. в разделе "Настройка OpenID Connect" в Azure.
• Настройте секреты репозитория, содержащие идентификатор приложения Microsoft Entra ID, заданный как AZURE_CLIENT_ID, идентификатор подписки, заданный как AZURE_SUBSCRIPTION_ID, и идентификатор клиента, заданный как AZURE_TENANT_ID
• Настройте переменные репозитория, содержащие ваше личное имя Azure Container Registry в качестве REGISTRY_NAME, предпочитаемое имя репозитория в качестве REPOSITORY_NAME и предпочитаемый тег в качестве TAG для созданного образа. Переменные можно изменить между рабочими процессами, чтобы отправить созданный образ в разные реестры, репозитории и теги.

Запустите рабочий процесс, перейдя на вкладку "Действия" в форкнутом репозитории и выбрав рабочий процесс, который вы хотите запустить. Затем можно выбрать кнопку "Запустить рабочий процесс", чтобы запустить рабочий процесс.

Чтобы использовать образ в развертываниях среды, необходимо добавить расположение изображения в файл манифеста , чтобы подключить образ к определению среды, и вам может потребоваться настроить разрешения для ACR, чтобы сделать настраиваемый образ доступным для ADE.

Создание пользовательского образа контейнера вручную

Создание пользовательского образа контейнера позволяет настроить развертывания в соответствии с вашими требованиями. Вы можете создавать пользовательские образы на основе стандартных образов ADE.

После завершения настройки образа необходимо создать образ и отправить его в реестр контейнеров.

Вы можете создать и отправить образ вручную или использовать скрипт, предоставленный корпорацией Майкрософт, для автоматизации процесса.

Опубликованная GitHub Action помогает создавать и отправлять образ в Реестр контейнеров Azure (ACR). Вы можете ссылаться на предоставленную ссылку на образ ACR в определении среды в ADE, чтобы развернуть или удалить среду с предоставленным изображением.

Чтобы создать образ, настроенный для ADE, выполните следующие действия.

1. Создайте пользовательский образ на основе рабочего процесса GitHub.
2. Установите нужные пакеты.
3. Настройка скриптов командной оболочки.
4. Создайте скрипты оболочки операций, использующие интерфейс командной строки Terraform.

1. Создайте пользовательский образ на основе рабочего процесса GitHub

Используйте опубликованный репозиторий, чтобы воспользоваться преимуществами рабочего процесса GitHub. Репозиторий содержит компоненты образов, совместимые с ADE, включая Dockerfile и скрипты оболочки для развертывания и удаления сред с помощью шаблонов Terraform IaC. Этот пример кода помогает создать собственный образ контейнера.

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

Вот пример этого процесса, установка версии 1.7.5 интерфейса командной строки Terraform:

RUN wget -O terraform.zip https://releases.hashicorp.com/terraform/1.7.5/terraform_1.7.5_linux_amd64.zip
RUN unzip terraform.zip && rm terraform.zip
RUN mv terraform /usr/bin/terraform

3. Настройка скриптов оболочки операций

В стандартных образах операции определяются и выполняются на основе имени операции. В настоящее время поддерживаются две операции: deploy и delete.

Чтобы настроить пользовательский образ для использования этой структуры, укажите папку на уровне вашего Dockerfile с названием scripts и укажите два файла: deploy.sh и delete.sh. Скрипт deploy запускается при создании или повторном развертывании среды, а скрипт delete запускается при удалении среды. Примеры скриптов оболочки можно просмотреть в репозитории в папке сценариев для Terraform.

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

COPY scripts/* /scripts/
RUN find /scripts/ -type f -iname "*.sh" -exec dos2unix '{}' '+'
RUN find /scripts/ -type f -iname "*.sh" -exec chmod +x {} \;

4. Создание скриптов оболочки операций, использующих интерфейс командной строки Terraform

Существует три шага для развертывания инфраструктуры с помощью Terraform:

1. terraform init — инициализирует интерфейс командной строки Terraform для выполнения действий в рабочем каталоге.
2. terraform plan — разрабатывает план на основе входящих файлов инфраструктуры Terraform и переменных, а также всех существующих файлов состояния и разрабатывает шаги, необходимые для создания или обновления инфраструктуры, указанной в файлах .tf .
3. terraform apply — применяет план для создания новой или обновления существующей инфраструктуры в Azure

В точке входа основного образа все существующие файлы состояния извлекаются в контейнер и каталог, сохраненный в переменной среды $ADE_STORAGE. Кроме того, все параметры, заданные для текущей среды, хранящейся в переменной $ADE_OPERATION_PARAMETERS. Чтобы получить доступ к существующему файлу состояния и задать переменные в файле .tfvars.json , выполните следующие команды:

set -e #set script to exit on error
EnvironmentState="$ADE_STORAGE/environment.tfstate"
EnvironmentPlan="/environment.tfplan"
EnvironmentVars="/environment.tfvars.json"

echo "$ADE_OPERATION_PARAMETERS" > $EnvironmentVars

Кроме того, чтобы использовать привилегии ADE для развертывания инфраструктуры в вашей подписке, скрипт должен использовать управляемое удостоверение при подготовке инфраструктуры с помощью провайдера Terraform AzureRM. Если для развертывания требуются специальные разрешения, например, для определенных ролей, назначьте эти разрешения идентификации типа среды проекта, которое используется для развертывания вашей среды. ADE задает соответствующие переменные среды, такие как идентификаторы клиента, арендатора и подписки в точке входа основного образа. Выполните следующие команды, чтобы убедиться, что поставщик использует управляемую идентификацию ADE:

export ARM_USE_MSI=true
export ARM_CLIENT_ID=$ADE_CLIENT_ID
export ARM_TENANT_ID=$ADE_TENANT_ID
export ARM_SUBSCRIPTION_ID=$ADE_SUBSCRIPTION_ID

Если в шаблоне есть другие переменные, которые не указаны в параметрах среды, задайте переменные среды с помощью префикса TF_VAR. Предоставляется список переменных среды ADE (Azure Deployment Environment), подробнее см. справочник по переменным среды развертывания Azure. Примером этих команд может быть;

export TF_VAR_resource_group_name=$ADE_RESOURCE_GROUP_NAME
export TF_VAR_ade_env_name=$ADE_ENVIRONMENT_NAME
export TF_VAR_env_name=$ADE_ENVIRONMENT_NAME
export TF_VAR_ade_subscription=$ADE_SUBSCRIPTION_ID
export TF_VAR_ade_location=$ADE_ENVIRONMENT_LOCATION
export TF_VAR_ade_environment_type=$ADE_ENVIRONMENT_TYPE

Теперь можно выполнить шаги, перечисленные ранее для инициализации интерфейса командной строки Terraform, создания плана подготовки инфраструктуры и применения плана во время скрипта развертывания:

terraform init
terraform plan -no-color -compact-warnings -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan

Во время скрипта удаления можно добавить destroy флаг в создание плана для удаления существующих ресурсов, как показано в следующем примере:

terraform init
terraform plan -no-color -compact-warnings -destroy -refresh=true -lock=true -state=$EnvironmentState -out=$EnvironmentPlan -var-file="$EnvironmentVars"
terraform apply -no-color -compact-warnings -auto-approve -lock=true -state=$EnvironmentState $EnvironmentPlan

Наконец, чтобы результаты вашего развертывания были загружены и доступны при доступе к вашей среде через Azure CLI, преобразуйте объект результатов из Terraform в ADE-соответствующий формат через пакет JQ. Задайте значение переменной среды $ADE_OUTPUTS, как показано в следующем примере:

tfOutputs=$(terraform output -state=$EnvironmentState -json)
# Convert Terraform output format to ADE format.
tfOutputs=$(jq 'walk(if type == "object" then 
            if .type == "bool" then .type = "boolean" 
            elif .type == "list" then .type = "array" 
            elif .type == "map" then .type = "object" 
            elif .type == "set" then .type = "array" 
            elif (.type | type) == "array" then 
                if .type[0] == "tuple" then .type = "array" 
                elif .type[0] == "object" then .type = "object" 
                elif .type[0] == "set" then .type = "array" 
                else . 
                end 
            else . 
            end 
        else . 
        end)' <<< "$tfOutputs")

echo "{\"outputs\": $tfOutputs}" > $ADE_OUTPUTS

Создание пользовательского образа

Вы можете создать образ с помощью интерфейса командной строки Docker. Убедитесь, что подсистема Docker установлена на компьютере. Затем перейдите в каталог Dockerfile и выполните следующую команду:

docker build . -t {YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}

Например, если вы хотите сохранить образ в репозитории в реестре с именем customImageи отправить с помощью версии тега 1.0.0, выполните следующие действия:

docker build . -t {YOUR_REGISTRY}.azurecr.io/customImage:1.0.0