Автор: Александр Монахов, Леонтий Онищук, Виталий Гнусин — DevOps Engineers, DataArt, Анна Медведенко — Project Manager, DataArt

Наша DevOps-команда постаралась разобраться в тонкостях применения сервиса Blueprints. В статье мы расскажем о результатах нашего небольшого исследования: структуре и параметрах Blueprint, затрону тему артефактов и ресурсной группы в контексте использования сервиса. Думаю, материал может быть полезен, прежде всего, DevOps-инженерам, которые работают с инфраструктурой Azure и испытывают потребность в удобном инструменте создания и управления окружением. Но и программистам, заинтересованным в облачных технологиях, прочитать статью будет интересно: Blueprints — современное решение, позволяющее оптимизировать процесс разработки и поддержки программного обеспечения.

1. Что такое Blueprints?

Blueprints — сервис Azure Cloud, позволяющий в декларативном виде определять повторяемый набор ресурсов Azure Cloud, соответствующий стандартам и требованиям организации.

Blueprints позволяет разработчикам быстро и удобно разворачивать новое облачное окружение Azure с соблюдением всех требований безопасности и комплаенса.

2. Что можно сделать с помощью Blueprints?

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

• Role Assignments.

• Policy Assignments.

• Azure Resource Manager templates (ARM templates).

• Resource Groups.

В отличие от ARM-темплейтов, сервис Blueprints предназначен для конфигурирования окружения. Такая конфигурация обычно содержит набор из ресурсных групп, политик, ролей и, собственно, ARM-темплейтов. Blueprint содержит все эти артефакты вместе и поддерживает версионирование, что открывает возможность внедрения практик CI/CD.

Также, в отличие от ARM-темплейтов, при разворачивании ресурсов через Blueprint сохраняется связь между определением (что должно быть развернуто) и назначением (что было развернуто). Эта связь позволяет контролировать процесс разворачивания ресурсов.

 Каждый Blueprint может (но не обязан) содержать ARM-темплейт.

3. Blueprint as Code

3.1 Предварительные требования 

Для удобства работы с Blueprints в Azure DevOps на уровне организации можно установить расширение Azure Blueprints от Neil Peterson. 

Работа c Blueprints состоит из следующих этапов: 

• Подготовка Blueprint, его артефактов (см. ниже), а также файла с параметрами назначений (assign.json).

• Создание (publish) версии Blueprint в Azure Blueprints service.

• Назначение (assignment) версии Blueprint — в результате создается окружение, соответствующее артефактам Blueprint и параметрам из файла assign.json, или же существующее окружение обновляется и приводится в соответствие с ними.

3.2 Структура артефактов Blueprint 

Артефакты Blueprint описываются файлами JSON — каждый артефакт содержится в отдельном файле. 

В общем случае папка с Blueprints и артефактами выглядит так: 

Файл blueprint.json — основной, его назначение — определение самого Blueprint. При деплое Blueprint он вызывается первым, а все артефакты представляют собой его дочерние ресурсы. 

Файл assign.json обязателен при операции назначения Blueprint, он содержит значение переменных, которые используются в Blueprint в процессе Assignment (например, имена создающихся компонент, их SKU, регион, в котором будут созданы описанные компоненты, и т. д.). Обычно значения переменных или параметров в этом файле необходимо изменить. Для этого используется трансформация файла. 

3.3 Трансформация файла

Функция FileTransform может изменять содержимое XML или JSON-файлов. 

Пример: 

Файл assign.json, который используется в процессе назначение Blueprint. Нам необходимо изменить значения location, blueprintId, gOrganizationName и g_AzureRegion: 

{
    "identity": {
      "type": "SystemAssigned"
    },
    "location": "testLocation",
    "properties": {
      "blueprintId": "testBlueprintId",
      "resourceGroups": {},
      "parameters": {
        "g_Organization_Name": {
          "value": "testOrgName"
        },
        "g_AzureRegion": {
          "value": "testLocation"
        }
      }
    }
} 

В YAML-пайплайне указываем желаемые значение переменных, соблюдая структуру изменяемого файла: 

variables:
  location: 'westeurope'
  properties.blueprintId: "/subscriptions/$(SubscriptionId)/providers/Microsoft.Blueprint/blueprints/AM-BP-feature-init"
  properties.parameters.g_AzureRegion.value: $(location)
  properties.parameters.g_Organization_Name.value: "Integration"

 и выполняем трансформацию файла:

- task: FileTransform@1
  inputs:
    folderPath: '$(Agent.BuildDirectory)\blueprints'
    fileType: 'json'
    targetFiles: 'assign.json'

Можем посмотреть содержимое трансформированного файла:

- script: type "$(Agent.BuildDirectory)\blueprints\assign.json"

3.4 Типы артефактов 

Blueprint состоит из артефактов, причем поддерживаются следующие типы последних: 

• Ресурсные группы — применяются на уровне подписок. 

• ARM-темплейты — применяются на уровне подписок и ресурсных групп.

• Назначение политик — применяются на уровне подписок и ресурсных групп.

• Назначение ролей — применяются на уровне подписок и ресурсных групп.

Рассмотрим пример файла blueprint.json: 

{
    "properties": {
        "description": "This will be displayed in the essentials, so make it good",
        "targetScope": "subscription",
        "parameters": { 
            "principalIds": {
                "type": "string",
                "metadata": {
                    "displayName": "Display Name for Blueprint parameter",
                    "description": "This is a blueprint parameter that any artifact can reference. We'll display these descriptions for you in the info bubble",
                    "strongType": "PrincipalId"
                }
            },
            "genericBlueprintParameter": {
                "type": "string"
            }
        },
        "resourceGroups": {
            "SingleRG": {
                "description": "An optional description for your RG artifact. FYI location and name properties can be left out and we will assume they are assignment-time parameters",
                "location": "eastus"
            }
        }
    },
    "type": "Microsoft.Blueprint/blueprints" 
}

Мы видим два опциональных параметра parameters: principalIds и genericBlueprintParameter. 

Эти параметры могут быть использованы в любых дочерних артефактах. В этом случае мы определяем параметр ResourceGroup в файле blueprint.json, а не в отдельном файле. 

3.5 Параметры 

Практически все в Blueprint может быть параметризировано. Параметры определяются в файле blueprint.json и могут применяться в любых артефактах. 

Параметр может быть определен в простом виде: 

"parameters": { 
    "genericBlueprintParameter": {
        "type": "string"
    }
}

Типы параметров можно найти в этом разделе документации. 

Обращение к параметрам может происходить так же, как это делается в свойствах ARM-темплейтов (defaultValue, allowedValue и т. д.). Также мы можем вызвать параметры, определенные ранее:

"properties": {
    "genericBlueprintParameter": "[parameters('principalIds')]",
}

Также получить значение параметра можем через конструкцию вида:

${{ parameters.genericBlueprintParameter }}

3.6 Свойства Resource Group 

Мы определили свойства Resource Group в главном файле blueprint.json с такими параметрами:

• Месторасположение: "location": "eastus".

• Имя размещения для ResourceGroup: SingleRG.

Ресурсная группа еще не создана, это случится после назначения (assignment). 

По желанию мы можем указать имя ресурсной группы добавив "name": "myRgName" как дочерний параметр объекта SingleRG (подробнее посмотреть можно здесь).

3.7 Артефакты 

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

1. Kind, согласно которому, артефакт может быть: 

   a. template, 

   b. roleAssignment, 

   c. policyAssignment.

2. Type, который для артефактов всегда будет: Microsoft.Blueprint/blueprints/artifacts. 

3. Properties — основной раздел, в котором описываются все свойства артефакта. 

   Например: 

   a. dependsOn опционально может указывать на зависимость от других артефактов. Больше информации тут.  

   b. resourceGroup опционально может указывать на название ресурсной группы, где будут размещаться ресурсы. Если этот параметр не определен, для размещения ресурсов будет использоваться ресурсная группа, указанная в файле blueprint.json.  

Полная спецификация для каждого типа артефактов описана здесь: Policy Assignment, Role Assignment, Template. 

3.8 Работа с Blueprints в пайплайнах 

Для работы с Blueprints можно использовать: 

• powershell командлеты (модуль Az.Blueprint, подробнее см. здесь);

• таски, разработанные Neil Peterson (подробнее см. здесь, их мы и используем в этой статье).

3.8.1. Создание Blueprint

steps:
- task: nepeters.azure-blueprints.CreateBlueprint.CreateBlueprint@1
  displayName: 'Create Azure Blueprint'
  inputs:
    azureSubscription: 'nepeters-subscription'
    BlueprintName: 'blueprints-demo'
    BlueprintPath: ./create
    IncludeSubFolders: true
    PublishBlueprint: true
    ChangeNote: 'Added new artifacts.'

Результаты можно просмотреть на  Azure портале -> Blueprints -> Blueprint definitions. 

3.8.2. Назначение Blueprint

steps:
- task: nepeters.azure-blueprints.AssignBlueprint.AssignBlueprint@1
  displayName: 'Assign Azure Blueprint'
  inputs:
    azureSubscription: 'nepeters-internal'
    AssignmentName: 'prod-test-one'
    BlueprintName: 'prod-test-one'
    ParametersFile: 'assign/assign-blueprint.json'
    AlternateSubscription: true
    SubscriptionID: '00000000-0000-0000-0000-000000000000'
    Wait: true
    StopOnFailure: true

Результаты можно просмотреть на  Azure портале -> Blueprints -> Assigned blueprints. Эта секция особенно полезна для получения детальных логов при ошибках назначения Blueprint. 

Как видите, работа с Blueprints не намного сложнее работы с ARM-темплейтами, но дает намного больший функционал и позволяет контролировать окружения. Важный момент — возможность иерархического применения блюпринтов. Используя этот сервис Azure, вы можете не просто автоматически развернуть окружение, а управлять им с  с соблюдением всех требований безопасности и комплаенса.