Руководство. Развертывание в кластере Service Fabric

Статья
06/08/2023

В этом учебнике описывается несколько способов настройки среды Jenkins, а также различные способы развертывания приложения в кластере Service Fabric после его сборки. Выполните приведенные общие инструкции, чтобы успешно настроить Jenkins, получить изменения из GitHub, выполнить сборку приложения и развернуть его в кластере.

Убедитесь, что у вас установлены необходимые компоненты.
Затем выполните действия, описанные в одном из следующих разделов, чтобы настроить Jenkins:
После настройки Jenkins выполните инструкции в разделе Создание и настройка задания Jenkins, чтобы настроить GitHub для активации Jenkins при внесении изменений в приложение и чтобы настроить конвейер заданий Jenkins на этапе сборки для получения изменений из GitHub и выполнения сборки приложения.
Наконец, настройте действие задания Jenkins после сборки для развертывания приложения в кластере Service Fabric. Существует два способа настройки Jenkins для развертывания приложения в кластере:
- Для сред разработки и тестирования используйте настройку развертывания с помощью конечной точки управления кластером. Это простейший метод развертывания, который можно настроить.
- Для рабочих сред используйте настройку развертывания с помощью учетных данных Azure. Корпорация Майкрософт рекомендует этот способ для рабочих сред, так как учетные данные Azure позволяют ограничить доступ задания Jenkins к ресурсам Azure.

Необходимые компоненты

Убедитесь, что компонент Git установлен в локальной среде. Соответствующую вашей операционной системе версию Git можно установить, скачав ее со страницы загрузок Git. Если вы не знакомы с Git, ознакомьтесь со сведениями, приведенными в этой документации.
В этой статье для выполнения сборки и развертывания приложения используется пример для начала работы с Service Fabric с сайта GitHub (https://github.com/Azure-Samples/service-fabric-java-getting-started). Можно разветвить этот репозиторий, чтобы продолжить изучение этого руководства, или, внеся некоторые изменения в инструкции, использовать собственный проект GitHub.

Установка подключаемого модуля Service Fabric в существующей среде Jenkins

Если вы добавляете подключаемый модуль Service Fabric в имеющуюся среду Jenkins, необходимо сделать следующее:

Интерфейс командной строки Service Fabric (sfctl). Установите интерфейс командной строки на уровне системы, а не на уровне пользователя, чтобы среда Jenkins могла выполнять команды интерфейса командной строки.
Для развертывания приложений Java установите Gradle и Open JDK 8.0.
Для развертывания приложений .NET Core 2.0 установите пакет SDK для .NET Core 2.0.

После установки необходимых компонентов для своей среды вы сможете выполнить поиск подключаемого модуля Azure Service Fabric на сайте marketplace Jenkins и установить его.

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

Настройка Jenkins в кластере Service Fabric

Jenkins можно настроить внутри или за пределами кластера Service Fabric. В следующих разделах показано, как его настроить внутри кластера при использовании учетной записи хранения Azure для сохранения состояния экземпляра контейнера.

Убедитесь, что у вас есть кластер Service Fabric под управлением Linux с установленным компонентом Docker. Компонент Docker уже установлен на кластерах Service Fabric, запущенных в Azure. Если вы используете кластер локально (среда разработки OneBox), проверка, если Docker установлен на компьютере с docker info помощью команды. Если он не установлен, установите его, выполнив следующие команды.
```
sudo apt-get install wget
wget -qO- https://get.docker.io/ | sh
```
Примечание.

Убедитесь, что в качестве пользовательской конечной точки в кластере задан порт 8081. При использовании локального кластера убедитесь, что на хост-компьютере открыт порт 8081 и ему назначен общедоступный IP-адрес.

Клонируйте приложение, выполнив следующие команды.

git clone https://github.com/suhuruli/jenkins-container-application.git
cd jenkins-container-application

Сохраните состояние контейнера Jenkins в общей папке:
1. Создайте учетную запись хранения Azure, например с именем sfjenkinsstorage1, в том же регионе, что и кластер.
2. Затем создайте общую папку для этой учетной записи хранения и присвойте ей имя, например sfjenkins.
3. Щелкните Подключить для общей папки. Запишите значения, которые отображаются в разделе Подключение из Linux. Они должны выглядеть приблизительно так:
```
sudo mount -t cifs //sfjenkinsstorage1.file.core.windows.net/sfjenkins [mount point] -o vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777
```
Примечание.

Для подключения файловых ресурсов cifs требуется установить пакет cifs-utils на узлах кластера.
Замените значения заполнителей в сценарии setupentrypoint.sh сведениями из учетной записи хранения Azure, приведенными на шаге 2.
```
vi JenkinsSF/JenkinsOnSF/Code/setupentrypoint.sh
```
- Замените [REMOTE_FILE_SHARE_LOCATION] значением //sfjenkinsstorage1.file.core.windows.net/sfjenkins из выходных данных подключения, полученных выше на шаге 2.
- Замените [FILE_SHARE_CONNECT_OPTIONS_STRING] значением vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777, полученным ранее на шаге 2.
Только для безопасного кластера

Для настройки развертывания приложений в безопасном кластере из службы Jenkins сертификат кластера должен быть доступен в контейнере Jenkins. В файле ApplicationManifest под тегом ContainerHostPolicies добавьте эту ссылку на сертификат и измените значение отпечатка, указав отпечаток сертификата кластера.
```
<CertificateRef Name="MyCert" X509FindValue="[Thumbprint]"/>
```
Кроме того, добавьте приведенные ниже строки под (корневым) тегом ApplicationManifest в файле ApplicationManifest.xml и измените значение отпечатка, указав отпечаток сертификата кластера.
```
<Certificates>
  <SecretsCertificate X509FindType="FindByThumbprint" X509FindValue="[Thumbprint]" />
</Certificates> 
```
Подключитесь к кластеру и установите приложение-контейнер.

Безопасный кластер
```
sfctl cluster select --endpoint https://PublicIPorFQDN:19080  --pem [Pem] --no-verify # cluster connect command
bash Scripts/install.sh
```
Предыдущая команда принимает сертификат в формате PEM. Если сертификат имеет формат PFX, можно использовать следующую команду, чтобы преобразовать его. Если PFX-файл не защищен паролем, укажите параметр passin следующим образом: -passin pass:.
```
openssl pkcs12 -in cert.pfx -out cert.pem -nodes -passin pass:<password>
```
Небезопасный кластер
```
sfctl cluster select --endpoint http://PublicIPorFQDN:19080 # cluster connect command
bash Scripts/install.sh
```
Контейнер Jenkins установится в кластер, и его можно будет отслеживать с помощью Service Fabric Explorer.

Примечание.

Скачивание образа Jenkins в кластер может занять несколько минут.
Откройте в браузере http://PublicIPorFQDN:8081. Это предоставит путь к начальному паролю администратора, необходимому для входа в систему.
Откройте Service Fabric Explorer, чтобы узнать, на каком узле выполняется контейнер Jenkins. Войдите на узел по протоколу SSH.
```
ssh user@PublicIPorFQDN -p [port]
```
Получите идентификатор экземпляра контейнера с помощью docker ps -a.
Войдите в контейнер по протоколу SSH и вставьте путь, предоставленный на портале Jenkins. Например, если на портале был указан путь PATH_TO_INITIAL_ADMIN_PASSWORD, выполните следующие команды.
```
docker exec -t -i [first-four-digits-of-container-ID] /bin/bash   # This takes you inside Docker shell
```
```
cat PATH_TO_INITIAL_ADMIN_PASSWORD # This displays the password value
```
На главной странице Jenkins щелкните параметре "Select plugins to install" (Выбор подключаемых модулей для установки), установите флажок None (Нет) и нажмите кнопку "Install" (Установить).
Создайте учетную запись пользователя или продолжите от имени администратора.

После настройки Jenkins перейдите к созданию и настройке задания Jenkins.

Настройка Jenkins за пределами кластера Service Fabric

Jenkins можно настроить внутри или за пределами кластера Service Fabric. В следующих разделах показано, как настроить Jenkins за пределами кластера.

Убедитесь, что на компьютере установлен компонент Docker, запустив docker info в терминале. Выходные данные указывают, запущена ли служба Docker.
Если компонент Docker не установлен, выполните следующую команду:
```
sudo apt-get install wget
wget -qO- https://get.docker.io/ | sh
```
Получите образ контейнера Jenkins для Service Fabric: docker pull rapatchi/jenkins:latest. Этот образ предварительно установлен в подключаемом модуле Jenkins Service Fabric.
Запустите образ контейнера: docker run -itd -p 8080:8080 rapatchi/jenkins:latest
Получите идентификатор экземпляра образа контейнера. Вы можете вывести список всех контейнеров Docker с помощью команды docker ps –a.
Войдите на портал Jenkins, сделав следующее.
1. Войдите в оболочку Jenkins со своего узла. Используйте первые четыре разряда идентификатора контейнера. Например, если идентификатор контейнера — 2d24a73b5964, то используйте 2d24.
```
docker exec -it [first-four-digits-of-container-ID] /bin/bash
```
2. В оболочке Jenkins получите пароль администратора для экземпляра контейнера.
```
cat /var/jenkins_home/secrets/initialAdminPassword
```
3. Чтобы войти в панель мониторинга Jenkins, откройте следующий URL-адрес в браузере: http://<HOST-IP>:8080. Введите пароль из предыдущего шага, чтобы получить доступ к Jenkins.
4. (Необязательно.) После первого входа вы можете создать собственную учетную запись пользователя и использовать ее для выполнения следующих действий или продолжить использовать учетную запись администратора. Если вы создадите пользователя, вам потребуется использовать его для последующих действий.
Настройте GitHub для работы с Jenkins, выполнив шаги, описанные в статье Generating a new SSH key and adding it to the ssh-agent (Создание ключа SSH и его добавление в агент SSH).
- Используйте инструкции, предоставленные в GitHub, чтобы создать ключ SSH и добавить его в учетную запись GitHub, в которой находится репозиторий.
- В оболочке Jenkins или Docker (а не на узле) выполните команды, перечисленные в приведенной выше статье.
- Чтобы войти в оболочку Jenkins с вашего узла, выполните следующую команду:
```
docker exec -t -i [first-four-digits-of-container-ID] /bin/bash
```

Убедитесь, что кластер или компьютер, где размещен образ контейнера Jenkins, имеет общедоступный IP-адрес, чтобы экземпляр Jenkins получал уведомления от GitHub.

После настройки Jenkins перейдите к следующему разделу, Создание и настройка задания Jenkins.

Создание и настройка задания Jenkins

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

На панели мониторинга Jenkins щелкните New Item (Создать элемент).
Введите имя элемента, например MyJob. Выберите проект в свободной форме и нажмите кнопку ОК.
Откроется страница настройки задания. (Чтобы получить конфигурацию из панели мониторинга Jenkins, выберите задание и нажмите кнопку Configure (Настройка).)
На вкладке General (Общие) установите флажок напротив проекта GitHub и укажите URL-адрес этого проекта. Это URL-адрес, где размещено приложение Service Fabric на Java, в которое необходимо интегрировать процесс непрерывной интеграции и доставки Jenkins (например, https://github.com/{your-github-account}/service-fabric-java-getting-started).
На вкладке Source Code Management (Управление исходным кодом) выберите Git. Укажите URL-адрес репозитория, где размещено приложение Service Fabric на Java, в которое необходимо интегрировать поток средств непрерывной интеграции и непрерывного развертывания Jenkins (например, https://github.com/{your-github-account}/service-fabric-java-getting-started). Также можно указать ветвь для выполнения сборки (например, /master).
Настройте репозиторий GitHub для обмена данными с Jenkins.
1. На странице репозитория GitHub выберите Settings (Параметры) >Integrations and Services (Интеграция и службы).
2. Выберите Add Service (Добавить службу), введите Jenkins и выберите Jenkins-Github plugin (Модуль Jenkins-Github).
3. Введите URL-адрес webhook для Jenkins (по умолчанию это должен быть http://<PublicIPorFQDN>:8081/github-webhook/). Добавьте или обновите службу.
4. В ваш экземпляр Jenkins будет отправлено событие проверки. Рядом с webhook в GitHub должен появиться зеленый флажок. Это означает, что проект успешно создан.
На вкладке Build Triggers (Триггеры сборки) в Jenkins выберите требуемый вариант сборки. Например, необходимо активировать выполнение сборки при каждой отправке изменений в репозиторий, поэтому выберите GitHub hook trigger for GITScm polling (Триггер обработчика GitHub для опроса GITScm). (Ранее был указан параметр Build when a change is pushed to GitHub (Выполнять сборку при отправке изменений в GitHub).)
На вкладке Build (Сборка) выполните одно из следующих действий, в зависимости от того, какое приложение вы создаете: Java или .NET Core.
- Для приложений Java. Из раскрывающегося списка Add build step (Добавление шага сборки) выберите Invoke Gradle Script (Вызов сценария Gradle). Щелкните Дополнительно. В расширенном меню укажите путь к корневому сценарию сборки своего приложения. Этот скрипт выбирает build.gradle по указанному пути и действует соответствующим образом. Для приложения ActorCounter это ${WORKSPACE}/reliable-services-actor-sample/Actors/ActorCounter.
- Для приложений .NET Core. Из раскрывающегося списка Add build step (Добавление шага сборки) выберите Execute Shell (Выполнение оболочки). В отобразившемся окне команд сначала необходимо перейти в каталог, в котором находится файл build.sh. После этого можно будет запустить скрипт build.sh для сборки приложения.
```
cd /var/jenkins_home/workspace/[Job Name]/[Path to build.sh]  
./build.sh
```
  Ниже приведен снимок экрана с примером команд, которые используются для сборки примера Counter Service с заданием Jenkins CounterServiceApplication.
Чтобы настроить Jenkins для развертывания приложения в кластере Service Fabric во время действий после сборки, необходимо расположение сертификата этого кластера в контейнере Jenkins. Выберите одно из приведенных ниже действий в зависимости от того, запущен ли контейнер Jenkins в кластере или за его пределами, и запишите расположение сертификата кластера.
- Для контейнера Jenkins вне кластера. Путь к сертификату можно найти, выводя значение переменной среды Certificates_JenkinsOnSF_Code_MyCert_PEM из контейнера.
```
echo $Certificates_JenkinsOnSF_Code_MyCert_PEM
```
- Для контейнера Jenkins за пределами кластера. Выполните следующие действия, чтобы скопировать сертификат кластера в контейнер.
  1. Сертификат должен быть в формате PEM. При отсутствии PEM-файла его можно создать из PFX-файла сертификата. Если PFX-файл не защищен паролем, выполните следующую команду на узле.
```
openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:
```
    Если PFX-файл защищен паролем, укажите его в параметре -passin. Например:
```
openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:<password>
```
  2. Чтобы получить идентификатор контейнера Jenkins, выполните команду docker ps на узле.
  3. Скопируйте PEM-файл в контейнер с помощью следующей команды Docker.
```
docker cp clustercert.pem [first-four-digits-of-container-ID]:/var/jenkins_home
```

Почти все готово! Не закрывайте задание Jenkins. Осталось только настроить действия после сборки для развертывания приложения в кластере Service Fabric.

Чтобы развернуть его в среде разработки или тестирования, выполните действия, описанные в разделе Настройка развертывания с использованием конечной точки управления кластером.
Чтобы развернуть его в рабочей среде, выполните действия, описанные в разделе Настройка развертывания с использованием учетных данных Azure.

Настройка развертывания с использованием конечной точки управления кластером

Для развертывания приложения в средах разработки и тестирования можно использовать конечную точку управления кластером. Чтобы настроить действие после сборки с использованием конечной точки управления кластером для развертывания приложения, требуется минимальная настройка. Если вы развертываете рабочую среду, перейдите к настройке развертывания с помощью учетных данных Azure для настройки субъекта-службы Microsoft Entra для использования во время развертывания.

В задании Jenkins выберите вкладку Post-build Actions (Действия после сборки).
В раскрывающемся списке Post-Build Actions (Действия после сборки) выберите Deploy Service Fabric Project (Развернуть проект Service Fabric).
В разделе Service Fabric Cluster Configuration (Конфигурация кластера Service Fabric) выберите переключатель Fill the Service Fabric Management Endpoint (Заполнить данные конечной точки управления Service Fabric).
Для параметра Management Host (Узел управления) введите конечную точку подключения для своего кластера, например {your-cluster}.eastus.cloudapp.azure.com.
Для параметров Client Key (Ключ клиента) и Client Cert (Сертификат клиента) укажите расположение PEM-файла в контейнере Jenkins, например /var/jenkins_home/clustercert.pem. (Вы скопировали расположение сертификата на заключительном шаге создания и настройки задания Jenkins.)
В разделе Application Configuration (Конфигурация приложения) настройте параметры Application Name (Имя приложения), Application Type (Тип приложения) и Path to Application Manifest (Путь к манифесту приложения) (относительный).
Щелкните Verify configuration(Проверить конфигурацию). При успешной проверки щелкните Save (Сохранить). Теперь конвейер заданий Jenkins полностью настроен. Перейдите к дальнейшим действиям для тестирования развертывания.

Настройка развертывания с использованием учетных данных Azure

В рабочих средах настоятельно рекомендуется настроить учетные данные Azure для развертывания приложения. В этом разделе показано, как настроить субъект-службу Microsoft Entra для развертывания приложения в действии после сборки. Можно назначить субъекты-службы ролям в вашем каталоге, чтобы ограничить разрешения для задания Jenkins.

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

Чтобы создать субъект-службу Microsoft Entra и назначить его разрешения в подписке Azure, выполните действия, описанные на портале для создания приложения и субъекта-службы Microsoft Entra. Обратите внимание на следующее.
- Выполняя инструкции в разделе, не забудьте скопировать и сохранить следующие значения: идентификатор приложения, ключ приложения, идентификатор каталога (идентификатор клиента) и идентификатор подписки. Они нужны для настройки учетных данных Azure в Jenkins.
- Если у вас нет необходимых разрешений для каталога, то вам потребуется обратиться к администратору, чтобы он предоставил их или создал субъект-службу для вас. Или вам потребуется настроить конечную точку управления для кластера в действиях после сборки для задания в Jenkins.
- В разделе "Создание приложения Microsoft Entra" можно ввести любой хорошо сформированный URL-адрес для URL-адреса входа.
- В разделе Назначение роли приложению можно назначить приложению роль Читатель для группы ресурсов кластера.
В задании Jenkins выберите вкладку Post-build Actions (Действия после сборки).
В раскрывающемся списке Post-Build Actions (Действия после сборки) выберите Deploy Service Fabric Project (Развернуть проект Service Fabric).
В разделе Service Fabric Cluster Configuration (Конфигурация кластера Service Fabric) щелкните Select the Service Fabric Cluster (Выбрать кластер Service Fabric). Нажмите кнопку Add (Добавить) рядом с разделом Azure Credentials (Учетные данные Azure). Щелкните Jenkins, чтобы выбрать поставщик учетных данных Jenkins.
В диалоговом окне поставщика учетных данных Jenkins из раскрывающегося списка Kind (Тип) выберите Microsoft Azure Service Principal (Субъект-служба Microsoft Azure).
Используйте значения, которые вы сохранили при настройке субъекта-службы на шаге 1, чтобы заполнить следующие поля.
- Client ID (Идентификатор клиента): идентификатор приложения.
- Client Secret (Секрет клиента): ключ приложения.
- Tenant ID (Идентификатор клиента): идентификатор каталога.
- Subscription ID (Идентификатор подписки): идентификатор подписки.
Введите описательный идентификатор, используемый для выбора учетных данных в Jenkins, и добавьте краткое описание. Затем щелкните Verify Service Principal (Проверить субъект-службу). Если проверка прошла, нажмите кнопку Add (Добавить).
На вкладке Service Fabric Cluster Configuration (Конфигурация кластера Service Fabric) убедитесь, что для параметра Azure Credentials (Учетные данные Azure) выбраны ваши новые учетные данные.
Из раскрывающегося списка Resource Group (Группа ресурсов) выберите группу ресурсов кластера, в которой необходимо развернуть приложение.
Из раскрывающегося списка Service Fabric выберите кластер, в котором необходимо развернуть приложение.
В полях Client Key (Ключ клиента) и Client Cert (Сертификат клиента) укажите расположение PEM-файла в контейнере Jenkins. Например, /var/jenkins_home/clustercert.pem.
В разделе Application Configuration (Конфигурация приложения) настройте параметры Application Name (Имя приложения), Application Type (Тип приложения) и Path to Application Manifest (Путь к манифесту приложения) (относительный).
Щелкните Verify configuration(Проверить конфигурацию). При успешной проверки щелкните Save (Сохранить). Теперь конвейер заданий Jenkins полностью настроен. Перейдите к дальнейшим действиям для тестирования развертывания.

Устранение неполадок подключаемого модуля Jenkins

Если вы столкнулись с ошибками, которые касаются подключаемых модулей Jenkins, сообщите о проблеме с конкретным компонентом на портале Jenkins JIRA.

Апробация идей

Теперь GitHub и Jenkins настроены, Попробуйте внести несколько изменений в проект reliable-services-actor-sample/Actors/ActorCounter в своей вилке репозитория, https://github.com/Azure-Samples/service-fabric-java-getting-started. Передайте эти изменения в удаленную ветвь master (или ветвь, настроенную для работы). Это запустит задание Jenkins MyJob, которое вы настроили. Оно получит изменения из GitHub, выполнит их сборку и развернет приложение в кластере, выбранном в действиях после сборки.

Следующие шаги

Jenkins в Azure

Поделиться через